Como pedir um teste no Claude Code que falha antes da correção?

Teste que passa não prova nada, teste que falha antes e passa depois prova a correção

Fala aí, beleza? Se você pediu um teste no Claude Code pra cobrir um bug e ele voltou verde já na primeira rodada, respira: tem uma chance boa desse teste não estar provando coisa nenhuma

Quando o pedido é "escreve teste pra esse arquivo", o modelo olha o código que EXISTE e escreve asserções que batem com ele

Se o código atual está errado, o teste aprende o erro junto e passa feliz 🙂

É primo do problema de teste que só confirma o código atual, só que aqui a gente ataca o outro lado: o teste precisa ficar VERMELHO antes de qualquer correção, senão ele não separa o certo do errado

Neste post: como descrever o comportamento esperado no prompt, o fluxo de TDD que a própria documentação recomenda, o checklist do que conferir antes de aceitar o teste e o que fazer quando o Claude resolve mexer no teste em vez de corrigir o código

O que você precisa antes de começar

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

Três coisas, e nenhuma delas é ferramenta nova

• Um comportamento esperado que caiba em uma frase: algo como "ao receber data vazia, a função devolve erro de validação e não uma data zerada"
• Um projeto com suíte de testes que roda: se rodar a suíte já é uma aventura, o passo de "confirmar que falha" não significa nada
• Um critério de qualidade que você vai exigir: a Anthropic orienta declarar isso dentro do próprio prompt, do tipo "testes que continuariam passando se eu refatorasse a implementação interna mantendo o mesmo comportamento público"

Repara que o gargalo não é técnico, é de descrição

Quem não sabe dizer o que espera vai receber de volta um espelho do código atual, e olha lá

Onde deixar as regras que você não quer repetir:

O CLAUDE.md é um arquivo markdown na raiz do projeto, lido pelo Claude Code no começo de toda sessão

É o lugar das instruções persistentes: padrões de código, decisões de arquitetura, checklists de revisão

E "persistente" significa o quê aqui? Que você escreve a regra uma vez em vez de colar o mesmo parágrafo em cada prompt 😀

Tem também o comando /memory, que abre a memória pra você navegar, editar ou apagar o que ficou salvo em markdown

Uma dica de bastidor: só promova uma regra pro CLAUDE.md DEPOIS que ela funcionou solta no prompt, senão o arquivo vira um depósito de achismo que ninguém revisa

Passo a passo: o fluxo de TDD com o Claude Code

A documentação oficial de boas práticas descreve esse fluxo, e a Anthropic apresenta ele como um dos favoritos internos pra mudanças que são facilmente verificáveis com testes de unidade, integração ou ponta a ponta

Bora ver na prática?

1. Descreva o comportamento esperado, não o código atual

A documentação de prompting da Anthropic é bem direta nisso: exemplos são uma das formas mais confiáveis de direcionar a saída, e eles devem ser diversos e cobrir casos de borda pra o modelo não pegar um padrão que você não quis ensinar

Então o prompt começa por uma tabelinha mental de entrada e saída, não por um caminho de arquivo

Comportamento esperado de parseVencimento(texto):
- "2026-08-26" devolve um objeto de data valido
- "" devolve erro de validacao
- "26/08/2026" devolve erro de validacao
- "2026-02-30" (data inexistente) devolve erro de validacao

A implementacao atual NAO e a fonte da verdade, ela tem um bug em pelo menos um desses casos

O erro comum deste passo: pedir cobertura

"Cobre esse módulo com testes" é um pedido sobre quantidade, e quantidade se resolve escrevendo asserções que copiam o comportamento presente

2. Peça os testes primeiro, com TDD e sem mock implementations

O exemplo de prompt que a Anthropic mostra no artigo de engenharia sobre Claude Code pede escrever os testes primeiro, com abordagem de TDD e sem mock implementations

Faz sentido: se o comportamento que está sendo testado é justamente o que ainda não existe, mockar ele é trapacear no próprio jogo

Escreva os testes primeiro, com abordagem de TDD, sem mock implementations
Cubra os quatro casos acima, incluindo os de borda
Ainda NAO escreva a implementacao

O erro comum deste passo: deixar a implementação nascer junto com o teste

Quando os dois saem no mesmo turno, o teste passa porque foi escrito pra passar, e você fica sem saber se ele detectaria a quebra

3. Mande rodar e confirmar que os testes falham

Esse é o passo que a maioria pula, e é o único que transforma o teste em prova

O fluxo oficial manda rodar, confirmar a falha e instruir explicitamente o Claude a não escrever código de implementação nessa etapa

Rode a suite e me mostre a saida
Confirme que os novos testes FALHAM e por qual motivo cada um falha
Nao escreva implementacao ainda

O erro comum deste passo: aceitar o verde na primeira rodada

Se o teste já nasceu passando, ou o bug não é o que você pensou, ou o teste não está tocando o comportamento que você descreveu

4. Commite os testes quando eles estiverem bons

O fluxo oficial recomenda pedir pro Claude commitar os testes assim que você estiver satisfeito com eles, antes de pedir a implementação

Parece burocracia, mas é a sua rede de segurança: com os testes commitados, qualquer mudança neles aparece no diff

O erro comum deste passo: commitar teste que você ainda não leu

Revisa antes, porque a partir daqui esse arquivo vira o contrato

5. Peça o código que passa, sem alterar os testes

Agora sim a implementação, e o prompt precisa dizer com todas as letras que os testes são intocáveis

A orientação oficial é pedir o código que passa nos testes sem modificar os testes, e seguir iterando (rodar, ajustar, rodar) até tudo ficar verde

Agora escreva o codigo que passa nesses testes
Nao modifique os testes
Itere: rode a suite, ajuste a implementacao, rode de novo, ate todos passarem

O erro comum deste passo: deixar a instrução implícita

"Faz passar" é ambíguo, e a forma mais barata de fazer passar é sempre mexer na asserção

6. Peça verificação com subagentes independentes contra overfitting

A documentação sugere pedir, nessa etapa, que subagentes independentes verifiquem se a implementação não está se ajustando demais aos testes

É o clássico código que acerta os quatro casos que você escreveu e erra o quinto que você não escreveu

Use subagentes independentes para verificar se a implementacao
nao esta apenas se ajustando aos testes (overfitting)
Aponte casos nao cobertos que quebrariam esse codigo

O erro comum deste passo: tratar suíte verde como fim da conversa

Verde diz que os casos escritos passam, não que o comportamento está certo

O que conferir no teste antes de aceitar

Checklist curto, roda em dois minutos e evita muita dor depois

1. O teste falha com a mensagem certa e pelo motivo certo: falha por erro de import, arquivo não encontrado ou setup quebrado não conta como vermelho útil
2. A asserção descreve o comportamento público: se o teste checa nome de variável interna ou ordem de chamada privada, ele vai quebrar na primeira faxina honesta
3. Existe caso de borda além do caminho feliz: entrada vazia, formato inválido, valor inexistente, aquilo que a doc de prompting chama de exemplos diversos
4. O teste continuaria passando depois de uma refatoração interna que mantém o mesmo comportamento público: esse é o critério de qualidade que a Anthropic orienta declarar dentro do prompt, e ele vale como pergunta de aceitação também
5. Nada foi resolvido com mock no lugar do comportamento real: se o mock devolve exatamente a resposta esperada, o teste está testando o mock

Se um item falhar, volta pro passo 1 e refaz a descrição do comportamento, não o teste na mão

E quando o Claude mexe no teste em vez de corrigir o código?

O sintoma é aquele alívio suspeito: a suíte fecha verde, você abre o diff e a asserção está mais frouxa, ou o arquivo de teste inteiro foi reescrito

Não é impressão sua, não

Existe uma issue aberta no repositório oficial anthropics/claude-code relatando exatamente isso: o Claude Code manipulando os testes em vez de seguir as instruções

A causa prática é de incentivo: o objetivo que você deu foi "deixar verde", e mexer no teste é o caminho mais curto pra deixar verde

A solução são as três travas que já apareceram no fluxo, agora com nome:

• Commitar os testes antes de pedir a implementação: com o commit feito, qualquer alteração no arquivo de teste aparece no git diff e você não precisa confiar na sua memória
• Instrução explícita de não modificar os testes no prompt do código, junto com o pedido de iterar até todos passarem
• Subagentes independentes checando overfitting, pra pegar a versão sofisticada do problema: o teste continua igual, mas a implementação foi moldada só pros casos dele

A prevenção é tirar isso do improviso: essas regras são exatamente o tipo de instrução persistente que vive no CLAUDE.md da raiz do projeto, lido no início de cada sessão

Algo bem curto já resolve

## Testes
- Teste novo precisa falhar antes da correcao, com a saida da falha no chat
- Nao alterar testes existentes para fazer a suite passar
- Testes commitados antes da implementacao

Tome cuidado com um detalhe: regra em arquivo não é mágica

Continua sendo você quem lê o diff antes do merge 😀

Quando esse fluxo compensa (e quando é exagero)

A Anthropic apresenta esse fluxo de TDD como um dos favoritos internos pra mudanças que são facilmente verificáveis com testes de unidade, integração ou ponta a ponta

Ou seja: quanto mais claro o "como eu sei que ficou certo", mais o fluxo paga o próprio custo

O contraponto honesto é esse último grupo

Quando o resultado esperado não é verificável por teste, a descrição do comportamento vira o gargalo e o fluxo só adiciona cerimônia

A linha do meio é a refatoração: ali o teste existe justamente pra travar o comportamento antes de qualquer mudança, e vale combinar esse fluxo com um pedido bem delimitado na hora de pedir refatoração ao Claude Code

Conclusão

Recapitulando o que importa: teste que passa de primeira não prova nada, teste que falha antes e passa depois prova a correção

O caminho pra chegar lá tem pouca ferramenta e muita descrição: comportamento esperado com exemplos diversos e casos de borda, testes primeiro com TDD e sem mock implementations, falha confirmada antes de qualquer implementação, commit dos testes, código que passa sem alterar os testes e uma verificação independente contra overfitting

Próximo passo concreto: pega UM bug pequeno hoje

Escreve no prompt o comportamento esperado (não o código atual), exige ver a falha antes da implementação, roda o checklist de aceitação e move pro CLAUDE.md do projeto as regras que funcionaram

É um bug só, mas é o primeiro teste seu que realmente prova alguma coisa

até o próximo post!