Como dar ao seu agente de programação de IA uma "definição de pronto" clara

Quando um colega humano pega um ticket vago, ele preenche as lacunas com bom senso e faz perguntas. Um agente de programação de IA não faz nenhuma das duas coisas. Ele lê o seu pedido, escreve o código, roda as verificações que consegue e declara a funcionalidade pronta — muitas vezes sem uma única pergunta de esclarecimento. Como diz um guia, quando você entrega requisitos imprecisos a um agente, "a folga não é absorvida — ela é construída."

Isso torna a sua definição de pronto a coisa de maior alavancagem que você pode escrever. Este guia mostra como escrever uma sobre a qual um agente consiga de fato agir.

Critérios de aceitação vs. definição de pronto

Duas ideias relacionadas, que vale a pena manter separadas:

• Critérios de aceitação são específicos da funcionalidade: o que este trabalho em particular deve fazer para ser considerado correto.
• Definição de pronto é válida para todo o projeto: os portões de qualidade que toda mudança precisa passar antes de ir para produção — testes, revisão, documentação, nenhum segredo comitado.

Pense nos critérios de aceitação como "construímos a coisa certa" e na definição de pronto como "construímos de acordo com o nosso padrão". Seu agente precisa dos dois. (A Atlassian tem uma boa introdução sobre a distinção.)

Torne-o testável, não aspiracional

O teste de um bom critério: um script — ou o próprio agente — poderia verificar se ele é verdadeiro? "O formulário de login deveria parecer rápido" é inverificável. Reescreva como algo com uma fronteira clara:

• Enviar credenciais válidas redireciona para /dashboard em até 500ms
• Enviar uma senha errada mostra um erro inline e não navega para fora
• Enviar um campo vazio é bloqueado no lado do cliente antes de qualquer requisição de rede
• Logins com falha têm limite de taxa de 5 tentativas por minuto por IP

Cada linha é algo que o agente pode construir e confirmar. O conselho de Addy Osmani sobre escrever uma boa especificação para agentes de IA é focar no o quê e no porquê, não no como linha a linha — descreva a intenção e as restrições, e deixe o agente escolher a implementação.

Um exemplo concreto

Compare estes dois prompts para a mesma tarefa.

Vago:

Adicione uma forma de os usuários redefinirem a senha.

Com uma definição de pronto:

Adicione um fluxo de redefinição de senha. Pronto significa:

• Um endpoint POST /auth/reset-request aceita um e-mail e sempre retorna 200 (nunca revele se o e-mail existe)
• Um token assinado, de uso único, válido por 1 hora, é enviado por e-mail via o mailer existente em src/lib/mail.ts
• POST /auth/reset-confirm valida o token, aplica a política de senha atual e invalida o token após o uso
• Os testes cobrem: redefinição válida, token expirado, token reutilizado, e-mail desconhecido
• Nenhuma nova dependência sem sinalizá-la primeiro

A segunda versão não é mais longa por ser burocrática — é mais longa porque toda ambiguidade que o agente iria adivinhar já está decidida. As escolhas sensíveis à segurança (não vazar a existência da conta, expirar tokens, uso único) são justamente aquelas em que você menos quer que um agente improvise.

Conecte o "pronto" ao loop do agente

O verdadeiro poder de uma definição de pronto testável é que ela fecha o loop de feedback do agente. Um ciclo agêntico de codificar → testar → corrigir → repetir só converge se houver um alvo claro a atingir. Quando seus critérios se mapeiam para testes reais, o agente consegue rodá-los, ver as falhas e corrigir o próprio trabalho antes de devolvê-lo a você.

Então não apenas descreva o "pronto" — dê ao agente uma forma de verificá-lo:

• Aponte-o para o comando de teste (npm test, pytest) e diga que a funcionalidade não está pronta até que eles passem.
• Para coisas difíceis de afirmar em código — legibilidade, seguir um padrão existente — use uma passada de LLM como juiz (LLM-as-a-judge): um segundo prompt que revisa a saída em relação ao seu padrão de qualidade. A Anthropic e outros consideraram isso eficaz para verificações subjetivas.
• Mantenha a segurança e a regra de "nenhum código placeholder/mock" na sua definição de pronto de todo o projeto, para que ela se aplique a todas as mudanças, não apenas àquelas que você lembra de mencionar.

Coloque onde o agente vai ver

Escreva a sua definição de pronto de todo o projeto uma única vez, em um arquivo que o agente lê automaticamente — um AGENTS.md ou CLAUDE.md na raiz do repositório. Os critérios de aceitação específicos da funcionalidade ficam no próprio prompt da tarefa. Assim, "o nosso padrão" está sempre no contexto, e você só precisa detalhar o que é único no trabalho de hoje.

A mudança é sutil, mas é o jogo inteiro: com um agente capaz, os seus critérios de aceitação deixam de ser um bilhete para um colega e tornam-se a especificação contra a qual o código é construído. Escreva-os assim.