O prompt não é a especificação

Vejo sempre o mesmo artefato nas features de IA que reviso: um system prompt enorme, editado com carinho ao longo de meses, que todo mundo trata como a definição da feature. Pergunte o que ela deve fazer num caso de borda e alguém abre o prompt e lê uma frase dele. Isso não é spec. É um detalhe de implementação que por acaso está escrito em português.

O que uma spec faz que o prompt não faz

Uma spec responde perguntas que o modelo nunca vê. Quais inputs são válidos e o que acontece com os inválidos. O que a saída precisa conter, em que formato, e o que é proibido. O que a feature precisa se recusar a fazer. Quais são os modos de falha aceitáveis e como eles aparecem para o usuário. Como é um resultado bom, com exemplos, e como é um ruim, com exemplos. Quem responde quando dá errado. Um prompt pode sugerir parte disso, mas o modelo é livre para ignorar, e o próximo modelo vai ignorar partes diferentes. A spec é aquilo contra o que você testa. O prompt é uma tentativa de satisfazê-la.

O prompt é detalhe de implementação

Trate o prompt como trata uma query SQL ou uma regex: versionado, revisado, testado e substituível. Quando o provedor lança um modelo novo, o prompt que funcionava vira hipótese. Se a sua única definição de correto mora dentro dele, você não tem nada para comparar com o comportamento novo. Times que mantêm a spec fora do prompt trocam de modelo numa tarde. Times que não mantêm passam duas semanas discutindo se o tom novo é regressão.

Onde a spec mora de verdade

Nas features que entrego, a spec são três coisas concretas. Primeiro, um schema para a saída, garantido em código, não pedido com educação. Segundo, um conjunto de evals: algumas centenas de inputs com saídas esperadas ou regras de avaliação, cobrindo o caminho feliz, o caminho chato e o caminho adversarial. Terceiro, um documento curto com os invariantes em linguagem simples: este assistente nunca cita um preço que não recuperou, este extrator nunca devolve uma data que não viu na fonte. O prompt deriva desses três. Quando prompt e spec discordam, a spec ganha e o prompt é corrigido.

Como escrevo a spec de uma feature com LLM

Começo pelas falhas, do mesmo jeito que projeto qualquer sistema. Qual é a pior saída plausível? Um assistente de suporte que inventa uma política de reembolso. Um resumidor que descarta justamente a frase com a contraindicação. Um classificador confiantemente errado na classe rara que mais importa. Cada uma vira uma regra e alguns casos de eval antes de eu escrever uma linha de prompt. Depois escrevo o caminho feliz, que é fácil e é onde a maioria dos times começa e para. A spec está pronta quando um colega conseguiria construir a feature em outro modelo, só com a spec, e passar nos mesmos evals.

O sinal

O sinal de que um time confundiu prompt com spec é simples. Peça para mostrarem a última regressão. Se a resposta é um diff do prompt e uma thread no Slack sobre sensação, não existe spec. Se a resposta é um caso de eval falhando, com nome, existe. O segundo time não é mais inteligente. Ele só decidiu cedo que prompt é código e que correto é algo que se escreve em outro lugar.