TDD com IA: escrevendo testes no Claude Code com vermelho-verde-refatorar (2026)

O que é TDD com IA?

TDD (Desenvolvimento Orientado a Testes) é uma forma de escrever código em que você escreve o teste primeiro — deixa ele falhar — depois escreve apenas o código suficiente para fazê-lo passar e, por fim, limpa (refatora) sem deixar o teste vermelho de novo. Esse é o TDD "clássico", e ele existe há anos. "TDD com IA" simplesmente significa que você deixa o Claude Code (ou um assistente de IA parecido) fazer as duas tarefas: escrever os testes e escrever a implementação que os satisfaz, enquanto você continua no comando de definir os requisitos e verificar o resultado.

A diferença central em relação a "pedir para a IA programar e depois mandar ela adicionar testes" é a ordem. No TDD, o teste que você escreve primeiro é uma especificação executável: ele descreve a entrada, a saída e os casos extremos exatos antes de existir uma única linha de código real. Aí o Claude Code escreve código para deixar aquele teste verde, em vez de escrever o que bem entender e corrigir a própria lição de casa.

Se você ainda não se sente à vontade trabalhando em um processo lado a lado com a IA, leia primeiro o que é vibe coding e como ele difere de um fluxo de trabalho disciplinado para ver onde o TDD se encaixa no quadro geral. O TDD é uma das disciplinas que impedem o vibe coding de virar uma pilha de código que ninguém consegue controlar.

Por que o TDD combina tão bem com o Claude Code?

O Claude Code brilha quando a "definição de pronto" é algo executável e autoverificável — e um teste é exatamente isso. Quando você diz "faça essa função funcionar corretamente", a IA precisa adivinhar o que você quer dizer. Quando você diz "faça esses 8 testes passarem", ela tem um alvo binário claro: vermelho ou verde, sem zona cinzenta onde ela possa "supor que terminou".

Três motivos fazem essa dupla funcionar:

• Um teste é uma especificação e uma rede de segurança ao mesmo tempo. Ele descreve o requisito e, ao mesmo tempo, captura a quebra no instante em que a IA muda outra coisa por engano. Em uma base de código que a IA edita o tempo todo, é essa rede de segurança que evita o "conserta uma coisa, quebra outras três".
• Um ciclo de feedback bem curto. Escreve o teste -> roda -> lê o erro -> corrige até ficar verde. O Claude Code consegue rodar os testes no terminal e ler a saída real, então ele itera por várias rodadas sem você copiar e colar os erros na mão.
• Uma proteção contra a IA passar batido pelo requisito. Esse é o ponto que pouca gente fala em voz alta: escrever o teste primeiro obriga você (e a IA) a cravar o requisito antes de programar. Muitos bugs do tipo "tecnicamente correto, mas com a intenção errada" desaparecem quando o requisito é congelado em um teste.

A própria Anthropic lista o TDD como um fluxo de trabalho recomendado ao usar o Claude Code em boas práticas do Claude Code (Anthropic, 2025): escreva os testes, confirme que eles falham e depois escreva código até passarem. Isso não é um truque que alguém inventou — é como a própria fabricante da ferramenta sugere usá-la.

O ciclo vermelho-verde-refatorar com o Claude Code

Todo o TDD cabe em três passos, repetidos para cada pequena fatia de uma funcionalidade. Com o Claude Code, cada passo corresponde a um prompt e a uma expectativa de saída bem clara.

Passo 1 - Vermelho: escreva um teste que falha (ainda sem código)

Você pede ao Claude para escrever um teste para o comportamento desejado, e apenas o teste. Ao rodá-lo, ele tem que ficar vermelho, porque a implementação ainda não existe.

Write a unit test for validate_email(email) in src/validators.py using pytest.
Cover these cases: valid email, missing @, missing domain, empty string, None.
The test MUST fail because the function does not exist yet. Do NOT write any code for validate_email.

Esperado: um arquivo test_validators.py com um punhado de casos, e rodar pytest reporta um ImportError ou testes vermelhos. Vermelho aqui é o certo — prova que o teste realmente verifica algo que ainda não existe.

Passo 2 - Verde: escreva o mínimo de código para passar

Só agora você deixa a IA escrever a implementação, e reforça o "mínimo" para ela não emendar funcionalidades extras.

Write the MINIMAL implementation of validate_email so every test in
test_validators.py passes. Run `pytest -q` and paste the real results back to me.
Do not add features beyond what the tests cover.

Esperado: código na medida certa, e a saída do pytest vira verde. Faça a IA colar a saída real da execução; não confie em um mero "passa".

Passo 3 - Refatorar: limpe o código e mantenha o verde

Uma vez verde, você tem uma rede de segurança para limpar tudo à vontade.

Refactor validate_email for readability (extract the regex into a constant, use clear names).
Do NOT change behavior. Re-run `pytest -q` after editing to prove it is still green.

Esperado: código mais limpo, testes ainda totalmente verdes. Se um teste ficar vermelho durante uma refatoração, isso é um sinal de que você acabou de mudar o comportamento sem querer — conserte na hora.

Uma sessão real test-first com o Claude Code (passo a passo)

Essa é a teoria; aqui vai uma sessão real com uma funcionalidade pequena: uma função parse_price("1.299.000d") que retorna o inteiro 1299000. É lógica pura, com entrada/saída claras — terreno ideal para TDD.

Passo 1 - peça um teste vermelho. Eu abro o Claude Code na pasta do projeto e digito:

Write pytest for parse_price(s) in src/pricing.py:
- "1.299.000d" -> 1299000
- "50.000 d" -> 50000
- "0d" -> 0
- a string with no digits -> raise ValueError
Write only the test. The function does not exist yet, so the test must fail.

Passo 2 - peça o mínimo de código para ficar verde. Depois de confirmar que os testes estão vermelhos como esperado:

Write the minimal implementation of parse_price so all 4 tests pass.
Run `pytest -q` and paste the output. Do not handle cases outside the tests.

O Claude escreve uma função que remove os caracteres não numéricos, faz o cast para int e lança ValueError quando está vazio. Ele mesmo roda os testes e devolve um resultado verde.

Passo 3 - refatore. Eu digo ao Claude para extrair a lógica de extração de dígitos para um helper e adicionar uma docstring, e para rodar os testes de novo para provar que o comportamento não mudou. Continuam 4 verdes. A sessão inteira leva alguns minutos, e o ponto-chave é que eu nunca precisei aceitar o "está pronto" na fé — cada afirmação vinha com a saída real do pytest anexada.

Como FORÇAR o Claude Code a escrever os testes PRIMEIRO (para ele não programar antes)

Essa é a maior dor de cabeça e o motivo de muitas equipes largarem o TDD depois de alguns dias: o Claude Code, como a maioria dos assistentes de IA, tende a pular direto para a implementação e só pendurar testes para inglês ver. Ele foi treinado para "resolver o problema", e, para ele, escrever código parece mais resolver o problema do que escrever um teste. Três mecanismos forçam a barra de forma eficaz:

1. Prompts separados por fase. Não junte "escreva a função X e um teste para ela" em uma frase só — isso é um convite para a IA programar antes. Separe com firmeza: o passo Vermelho diz apenas "escreva um teste que FALHA para X, NÃO escreva código ainda", e você só passa para o Verde quando o teste estiver vermelho. Colocar "não escreva código ainda" em maiúsculas ou negrito melhora bastante a obediência.

2. Uma regra test-first no CLAUDE.md. Essa é a abordagem mais duradoura — escreva a regra uma vez e aplique em toda sessão. Adicione este bloco ao arquivo CLAUDE.md do seu projeto:

## TDD rules (mandatory)
- Always write tests BEFORE the implementation for any new logic/function.
- Order: (1) write a failing test, (2) run `pytest -q` to confirm red,
 (3) write the minimal code to pass, (4) refactor while staying green.
- Do NOT write any implementation during the Red step.
- Do NOT edit tests just to make existing code pass.
- After every change, run the REAL tests and paste the output; never claim "it passes" on faith.

Se você nunca configurou esse arquivo, veja o guia para escrever um CLAUDE.md sólido (forçando o test-first) — é o interruptor liga/desliga da disciplina no projeto inteiro.

3. Um portão de fase com um subagent. A jogada avançada: use um subagent dedicado a escrever testes e não mostre a ele o plano de implementação. Quando o "escritor de testes" não sabe como o código vai ficar, os testes se atêm ao comportamento desejado, e não ao código que você pretende escrever — o que evita testes moldados sob medida para "ficar verde". A forma de organizar vários agentes por fase está no fluxo brainstorm -> plan -> cook -> ship.

Erros comuns no TDD com IA (antipadrões)

O TDD com IA falha de formas bem previsíveis. Identifique-as cedo para você não se enganar achando que está "fazendo TDD":

Desses, a lacuna de verificação é a mais perigosa porque é silenciosa. Quando você empaca em um teste que fica vermelho ou a IA começa a andar em círculos, não deixe ela "ficar verde" afrouxando o teste — mude para uma depuração metódica (veja depurando com IA) e confira a qualidade da mudança com uma rodada de revisão de código com IA antes de fazer o commit.

Automatizando o TDD: hooks e skills que impõem o portão de fase

A disciplina manual escorrega fácil. Duas maneiras de automatizar para que o portão de fase não dependa da sua memória:

Hooks que rodam os testes automaticamente. O Claude Code oferece suporte a hooks que rodam depois de cada edição de arquivo. Você configura um hook para rodar pytest -q (ou npm test, vitest run) depois de cada edição; se um teste ficar vermelho, o hook sinaliza na hora, então a IA precisa corrigir antes de seguir em frente. Isso transforma "lembrar de rodar os testes" em "não dá para esquecer de rodar os testes".

Skills/subagents com o processo embutido. Em vez de reescrever a convenção test-first para cada projeto, você pode usar um kit pronto.

Acelere com um kit pronto: Se você prefere não construir os hooks e as convenções do zero, o kit AgentKit para Claude Code (20% de desconto pelo link) (agentkit.best, a CLI ak — não confunda com o AgentKit da OpenAI) vem com mais de 60 skills e mais de 30 workflows para engenheiros, incluindo um workflow de revisão de código. Você pode combiná-los com o seu loop vermelho-verde-refatorar para ter um portão de fase e uma revisão automáticos, sem a configuração manual. Detalhes na análise do Engineer Kit. O Engineer Kit custa atualmente US$ 99 (o site não menciona nenhuma cobrança recorrente).

Quer você mesmo construa, quer use um kit, o princípio não muda: quem tem que rodar os testes e relatar o resultado é a máquina — não a IA se autodeclarando pronta.

Quando você deve e quando NÃO deve usar TDD com IA

TDD com IA não é bala de prata. Seja realista sobre onde ele brilha e onde ele atrapalha:

Use quando: lógica de negócio, funções puras (entrada -> saída clara), processamento de dados, APIs de backend e, especialmente, correção de bugs — escrever um teste que reproduz o bug (vermelho) e depois corrigi-lo até ficar verde é o fluxo de correção de bug mais organizado que existe. É também onde o TDD mais compensa quando você usa o Claude Code para construir uma API de backend, porque o contrato de um endpoint é fácil de congelar em um teste.

Menos indicado quando: na fase de exploração/protótipo, em que os requisitos ainda estão nebulosos (os testes que você escrever vão ser apagados a toda hora), na estilização de UI e no aspecto visual (testes são caros e não capturam "ficou bonito/feio"), ou em um script descartável. Quando o requisito ainda está vago, forçar o test-first só te atrasa — prototipe à vontade e, depois de travar o comportamento, volte e envolva com testes as partes que valem a pena manter.

Perguntas frequentes (FAQ)

O TDD com IA substitui o TDD manual?

Ele não substitui o princípio, só quem digita. Você ainda tem que decidir o que o teste verifica e julgar se ele é significativo; a IA cuida de escrever e rodar. A disciplina do vermelho-verde-refatorar continua sendo sua.

Os testes que o Claude escreve são corretos e completos?

Geralmente corretos nos casos básicos, mas ele costuma deixar passar casos extremos (vazio, null, negativos, unicode, erros de rede). Leia os testes que a IA escreveu e peça para ela adicionar casos extremos antes de confiar neles. O teste é a especificação, então cabe a você aprovar a especificação.

Qual framework - pytest, Jest ou Vitest?

Use o que o seu projeto já usa; o Claude Code é fluente em pytest (Python), Jest e Vitest (JS/TS). O que importa é nomear o framework explicitamente no seu prompt ou no CLAUDE.md para a IA não escolher um ao acaso.

Preciso saber escrever testes antes de fazer TDD com IA?

Você deve saber o básico. Não precisa ser craque em escrever testes, mas precisa do suficiente para ler e julgar os testes que a IA escreve — senão você vai dar aval a testes sem sentido. Encare o TDD como uma forma de subir de nível nas suas próprias habilidades de teste enquanto trabalha.

Os testes escritos por IA são confiáveis o bastante para barrar regressões?

Eles são confiáveis sob duas condições: você revisou os testes e os testes foram de fato executados (não a IA se autodeclarando aprovada). Adicione uma camada lint -> unit -> e2e para cobrir a tendência da IA de relatar "pronto" cedo demais.

Posso aplicar TDD com IA em um projeto legado?

Pode, mas em uma ordem diferente: para código legado, você primeiro escreve "testes de caracterização" que travam o comportamento atual e depois refatora com segurança. Para funcionalidades novinhas adicionadas a um projeto antigo, continua sendo test-first como de costume.

Conclusão e próximos passos

TDD com IA se resume a um loop: escreva um teste vermelho -> deixe o Claude Code deixá-lo verde -> refatore mantendo o verde, e sempre faça a máquina rodar os testes de verdade em vez de confiar na palavra da IA. A chave não é uma ferramenta mais poderosa, é conseguir forçar a IA a escrever os testes primeiro com prompts separados por fase e uma regra no CLAUDE.md. Próximo passo: conecte o TDD a um processo completo com o fluxo brainstorm -> plan -> cook -> ship e reforce a base do seu processo com vibe coding feito do jeito certo.