Como escrever um prompt no Claude Code que ele consegue verificar sozinho antes de dizer que terminou

O jeito mais comum de um agente te frustrar não é errando o código, é dizendo que corrigiu sem ter verificado nada

Isso não é impressão minha: afirmar sucesso sem verificar é o modo de falha mais citado nas boas práticas oficiais do Claude Code

E a diferença aqui não está no modelo, está em COMO o pedido foi escrito

Sem uma checagem que o próprio agente possa rodar, o único sinal disponível é "parece pronto", e quem vira o laço de verificação é você, abrindo o terminal, rodando o teste, voltando pra conversa e explicando o que quebrou

Agora, quando o pedido carrega uma checagem que devolve passa ou falha, o laço fecha sozinho: o Claude faz o trabalho, roda a checagem, lê o resultado e itera até passar

A doc oficial é bem direta nisso, chega a dizer que se você for adotar só uma prática, adote a verificação

Bora montar esse pedido na prática?

O que você precisa antes de escrever o pedido

Nada de PC da Nasa aqui, é lista curta e verificável:

• Claude Code instalado e rodando no diretório do projeto, não numa pasta qualquer
• Um comando de checagem que JÁ funciona na sua máquina, e que devolve saída legível: pode ser a suíte de testes, o build ou o linter. Se ele não roda pra você, também não vai rodar pro agente
• Um CLAUDE.md no projeto, que é o arquivo markdown que o Claude lê automaticamente no início de toda sessão naquele diretório

Não tem o CLAUDE.md ainda? O comando /init faz o Claude explorar o projeto e rascunhar esse arquivo cobrindo comandos de build, comandos de teste, visão da estrutura e convenções detectadas

É o atalho mais barato pra sair do zero, e você revisa depois o que ele escreveu

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Como escrever o pedido passo a passo

1. Descreva a tarefa com precisão

A doc coloca de um jeito que eu gosto: o Claude infere intenção, mas não lê mentes, e quanto mais precisa a instrução, menos correção depois

Compare o vago com o específico:

   ruim: arruma o login

   bom: o login falha quando o email tem maiúscula
   normaliza o email pra minúsculo antes de comparar no banco
   não muda a rota nem o formato da resposta

Erro comum deste passo: escrever o sintoma e achar que o resto "tá óbvio". Óbvio pra você, que abriu o arquivo

2. Anexe o critério de aceite, com o comando exato

Aqui é a virada do post: sai o "faça X" e entra o "faça X e prove que funciona rodando Y"

O Y tem nome, não é "teste aí":

   normaliza o email pra minúsculo antes de comparar no banco

   critério de aceite: npm test -- auth passa inteiro
   não considere a tarefa concluída enquanto esse comando falhar

Troque npm test pelo comando que roda de verdade no seu projeto, beleza? O que importa é que seja um comando que devolva passa ou falha sozinho

Erro comum deste passo: pedir "verifique se funciona" sem nomear NADA rodável. Isso não é critério, é torcida

3. Peça evidência, não a afirmação de sucesso

A recomendação oficial é justamente essa: em vez de aceitar o "pronto, corrigido", peça a saída do teste, o comando que rodou e o que ele devolveu, ou o screenshot do resultado

   quando terminar, me mostre:
   o comando que você rodou
   a saída dele, colada, não resumida

Erro comum deste passo: aceitar resumo do tipo "todos os testes passaram". Saída colada é evidência, resumo é opinião

4. Comece pelo modo de plano quando houver incerteza

A doc separa pesquisa e planejamento da implementação exatamente pra evitar resolver o problema errado, com o Claude lendo arquivos e respondendo perguntas sem alterar nada

O critério oficial de quando usar é bem prático: vale a pena quando você tem dúvida sobre a abordagem, quando a mudança toca vários arquivos ou quando o código é desconhecido

E o contrário também é regra: se dá pra descrever o diff em uma frase, pula o plano e vai

Erro comum deste passo: planejar mudança de uma linha e transformar 30 segundos em 10 minutos

5. Se o critério ainda não existe, escreva os testes primeiro

Essa é a razão pela qual a abordagem TDD aparece recomendada: os testes dão ao Claude critérios claros de validação pra perseguir, e apanham problemas guiando a iteração até a solução funcionar

Sem teste, você está pedindo pro agente adivinhar o que é "funcionando"

Vale lembrar que dá pra delegar a escrita dos testes também, desde que você confira na mão o que ele considerou como caso válido

Erro comum deste passo: deixar o mesmo agente escrever o teste E o código na mesma tacada sem você olhar o teste. Aí ele ajusta o critério até passar 😅

Que checagem usar em cada tipo de tarefa

O catálogo oficial de sinais é mais largo do que "rodar teste"

Serve qualquer coisa que devolva um sinal legível na conversa: suíte de testes, código de saída de um build, linter, script que compara a saída com um fixture, ou screenshot do navegador comparado com o design

Traduzindo pra situação real:

O ponto de todos eles é o mesmo: o agente precisa CONSEGUIR ler o resultado dentro da conversa

Se a única forma de saber que deu certo é você abrir a tela e olhar, o laço continua sendo você

O que mudou no meu fluxo quando o pedido passou a carregar a prova

No vídeo abaixo eu instalo o GSD no Claude Code e passo pelo fluxo inteiro, e ele funciona bem como estudo de caso disso aqui

A instalação eu fiz por fora do Claude Code, direto no terminal, com o comando tirado da documentação oficial do projeto, que eu li antes de gravar

Na hora de instalar dá pra escolher pra qual ferramenta de IA vai, e eu fui de instalação global, notando que nada é ativado até você pedir

Pra confirmar que ficou tudo certo, abri o Claude Code e digitei a barra com o nome do framework, e a lista de comandos apareceu

Um detalhe de bastidor: eu iniciei pulando as permissões, porque aprovar cada arquivo criado deixaria a fase de planejamento arrastada demais

Aí começa a parte que interessa pro assunto deste post

Eu comecei um projeto do zero e passei por uma ENTREVISTA antes de qualquer linha de código: a ferramenta pergunta o que você quer construir e vai desdobrando a sua resposta em perguntas mais específicas

Dá pra responder escolhendo uma das opções prontas ou pedir pra explicar com as suas próprias palavras, e eu usei a segunda quando quis detalhar

Respondi em português e a conversa seguiu em português, o que já ajuda bastante

O que eu mais fiz na entrevista foi RESTRINGIR escopo de propósito: defini que um prompt salvo seria só o texto por enquanto, que a conta seria obrigatória e cortei itens que não entrariam na primeira versão

Quando não soube definir a stack, pedi recomendação e deixei a pesquisa da ferramenta apontar a escolha, em vez de chutar

Depois da entrevista ainda tem uma fase de discussão, pra resolver o que ficou mal esclarecido e capturar decisões antes de planejar

E o planejamento é rigoroso, às vezes até sofrido, com um ciclo que verifica os requisitos e repete até o plano ser aprovado

Parece burocracia? Parece

Mas é exatamente o mesmo princípio do critério de aceite: em vez de a IA adivinhar, ela ganha algo pra conferir contra

Eu inclusive defendo que esse rigor é especialmente bom pra quem entende pouco de programação, porque força o detalhe no planejamento

Onde eu ainda precisei entrar no meio: a verificação final não é obrigatoriamente o passo seguinte à execução, dá pra voltar ao planejamento e abrir novas tarefas antes de fechar, e foi o que fiz

No fim da primeira fase a ferramenta gerou uma pasta de planejamento com as informações que eu tinha respondido

E fica a recomendação que eu dei lá: leia a documentação oficial do projeto, que é a fonte mais fiel, em vez de ficar só no que eu mostrei

No vídeo você vê a entrevista rodando na tela, as respostas cortando escopo e o plano sendo verificado antes de virar código

Como travar a verificação no projeto (CLAUDE.md e hook de Stop)

Repetir o critério em TODO prompt cansa, e é onde a gente esquece

Dá pra deixar isso combinado no projeto:

1. Registre o comando de checagem no CLAUDE.md

Como esse arquivo é lido automaticamente no início de toda sessão naquele diretório, o comando de teste e de build entram no contexto sem você digitar de novo

Se você rodou /init, esses comandos provavelmente já estão lá, é só conferir se batem com a realidade

Erro comum deste passo: deixar no CLAUDE.md um comando que mudou de nome faz meses. Contexto errado é pior que contexto nenhum

2. Configure um hook de Stop

Esse é o pulo do gato: um hook de Stop pode rodar a sua checagem como script e BLOQUEAR o encerramento do turno até que ela passe

Ou seja, o agente não consegue te devolver um "terminei" enquanto o teste estiver vermelho

Combinado com a ideia de deixar o agente rodando tarefas sozinho, é o que dá pra chamar de guardrail de verdade

Erro comum deste passo: apontar o hook pra um script que só existe na sua máquina, fora do repositório

3. Saiba onde a configuração mora

Hooks são configurados adicionando um bloco hooks a um arquivo de settings: .claude/settings.json pros hooks do projeto e ~/.claude/settings.json pros globais

A configuração tem três níveis: o evento (como PreToolUse ou Stop), um grupo matcher que filtra quando dispara, e um ou mais handlers que rodam quando casa

Alguns eventos usam os campos de topo decision e reason no retorno pra bloquear ou dar feedback, e é por aí que o "não deixa fechar" acontece

Se quiser a referência exata, a documentação de hooks é o lugar

Erro comum deste passo: tentar cadastrar pelo menu /hooks, que é somente leitura. Pra adicionar, alterar ou remover, você edita o JSON de settings direto ou pede pro próprio Claude fazer a alteração

O que remover do prompt se você usa o Claude Opus 5

Essa parte pega muita gente que copiou prompt antigo e nunca mais mexeu

O Claude Opus 5 verifica o próprio trabalho sem ser instruído, e a orientação oficial é REMOVER as instruções explícitas de verificação herdadas de prompts de modelos anteriores

Motivo: elas causam verificação excessiva e gastam tokens sem ganho de qualidade

Então some com coisas assim:

confira sua resposta
reverifique antes de responder
revise tudo de novo antes de finalizar

Rechecagem que o modelo já executa sozinho se soma ao comportamento próprio dele e vira custo sem ganho

Mas atenção pra não jogar o bebê fora com a água: o critério de aceite RODÁVEL é outra coisa

"passa o npm test -- auth antes de considerar concluído" não é redundância, é um sinal externo, medido fora da cabeça do modelo

O que sai é o pedido genérico de "pensa de novo"

O que fica é o comando que decide

Próximo passo

O resumo cabe em uma linha: o pedido que se verifica sozinho é o pedido que NOMEIA a prova

Sem isso, sobra "parece pronto", e você continua sendo o CI do seu próprio projeto 😅

Próximo passo bem concreto, pra fazer hoje: escolhe UMA tarefa pequena do projeto que você já tem aberto

Escreve o pedido com a descrição precisa, com o comando de checagem embutido e com o pedido de evidência da rodada

Depois compara com o jeito que você pedia antes

Se fizer sentido, você registra o comando no CLAUDE.md e nem precisa repetir na próxima

faça o teste! até o próximo post!