Desenvolvimento Orientado a Testes (TDD)
Escreva o teste que falha primeiro. Veja-o falhar. Escreva o código mínimo para passar. Refatore. Um teste que passa imediatamente não prova nada — você nunca o viu detectar um bug.
Lei de ferro: Nenhum código de produção sem um teste que falha primeiro. Se você escreveu código antes do teste, apague-o e comece de novo. "Manter como referência" é teste-depois em disfarce — apagar significa apagar.
Quando usar
- Implementando qualquer nova funcionalidade ou comportamento
- Corrigindo um bug (reproduza-o com um teste primeiro — o Padrão Prove-It)
- Refatorando ou alterando comportamento existente
- Aciona em "tdd", "test-driven", "red green refactor", "测试驱动开发", "红绿重构", "测试驱动"
Não use para: gerar testes para código já escrito (use test-generation);
protótipos descartáveis ou configuração pura (implemente diretamente).
Exceções (confirme com o usuário): protótipos descartáveis, código gerado, alterações de configuração pura sem impacto comportamental.
Passos
0. Descubra a stack primeiro
O ciclo é universal; os comandos não são. Antes do primeiro teste, descubra como
este repositório testa: leia package.json / pyproject.toml / Cargo.toml /
pom.xml / go.mod, verifique ./gradlew, Makefile, workflows de CI e
convenções de nomenclatura de arquivos de teste existentes. Nunca presuma npm test — use o comando do próprio repositório
para cada verificação RED, GREEN e final.
1. RED — escreva um teste que falha
Um comportamento, um teste, uma fatia vertical (bala traçadora que responde ao que o último ciclo te ensinou). Escreva o teste que você gostaria que existisse — ele descreve a API desejada, não a implementação. Nomeie-o como uma especificação ("rejeita email vazio", não "teste1").
Concorde a costura (interface pública sob teste) antes de escrever. Nenhum teste em uma costura não confirmada — concordar as costuras de antemão coloca o esforço de teste em caminhos críticos em vez de em cada caso extremo. Use código real sobre mocks; se você precisar dobrar uma dependência, use o double mais simples que funciona (Real > Fake > Stub > Mock — veja referências/test-strategy.md). Mocks isolam fronteiras, não a coisa sendo testada.
2. Verifique RED — veja-o falhar
Execute o comando de teste focado. Confirme:
- Ele falha (não erros — erros significam corrigir a configuração e reexecutar)
- Ele falha pelo motivo certo (funcionalidade ausente, não um erro de digitação)
- Um teste que passa imediatamente significa que você está testando comportamento existente — corrija o teste
3. GREEN — escreva código mínimo
O código mais simples que passa no teste. Sem funcionalidades especulativas, sem
"flexibilidade", sem refatorar código adjacente. YAGNI. Não adicione métodos apenas para teste
(destroy(), reset()) em classes de produção — coloque a limpeza em utilitários de teste.
4. Verifique GREEN — veja-o passar
Execute o comando de teste focado, depois a suíte completa. Confirme:
- O novo teste passa
- Nenhum outro teste quebrou (se quebrou, corrija agora — não pule)
- A saída está limpa (sem avisos, sem testes ignorados)
5. REFACTOR — limpe
Apenas enquanto verde: extraia helpers, melhore nomes, remova duplicação. Execute testes após cada etapa de refatoração. Não adicione comportamento. Refatoração pertence ao estágio de revisão, não ao ciclo de implementação vermelho → verde.
6. Commit
Faça commit do teste e da implementação juntos como uma fatia vertical. Então comece o próximo teste que falha.
Correções de bugs — o Padrão Prove-It
Não comece corrigindo. Escreva um teste que reproduza o bug (RED confirma que ele existe), então corrija (GREEN prova que a correção funciona). O teste permanece como uma guarda de regressão. Nunca corrija um bug sem um teste de reprodução.
Verifique
- Todo novo comportamento tem um teste que falhou primeiro
- A suíte completa passa com o comando de teste do próprio repositório
- Correções de bugs incluem um teste de reprodução que falhou antes da correção
- Nomes de teste descrevem comportamento, não implementação
- Nenhum teste ignorado ou desativado; nenhum método apenas para teste em código de produção
Referências
- ${CLAUDE_PLUGIN_ROOT}/references/engineering-principles.md — disciplina que toda habilidade compartilha
- references/test-strategy.md — pirâmide de teste, hierarquia de test-double (Real > Fake > Stub > Mock), DAMP sobre DRY
- references/testing-anti-patterns.md — mau uso de mock, métodos apenas para teste, mocks parciais, funções de portão
- references/mocking.md — quando mockar, projetando para capacidade de mock
- references/good-tests.md — exemplos de bons vs maus testes, testes tautológicos