test-driven-development

Visão geral

O que esta skill faz

A skill test-driven-development codifica um fluxo de trabalho rigoroso de Test-Driven Development (TDD): você sempre escreve um teste falhando antes de qualquer código de produção e segue de forma disciplinada o ciclo Red-Green-Refactor.

Em vez de uma orientação vaga do tipo “escreva alguns testes em algum momento”, esta skill define regras rígidas:

• Nenhum código de produção sem antes ter um teste falhando
• Sempre verificar que o teste falha pelo motivo correto
• Escrever apenas o mínimo de código necessário para fazer os testes passarem
• Refatorar somente quando tudo estiver verde

Ela também aponta para um guia dedicado de testing-anti-patterns que ajuda você a evitar testes frágeis e enganosos.

Para quem ela é

Use a skill test-driven-development se você é:

• Um desenvolvedor que quer um fluxo de trabalho confiável para features, correções de bugs e refatorações
• Um time padronizando em TDD e que precisa de regras claras que todos possam seguir
• Um coach ou líder técnico que deseja reforçar hábitos consistentes de automação de testes

Ela é especialmente útil em bases de código em JavaScript e TypeScript, mas os princípios se aplicam a qualquer linguagem e framework de testes.

Problemas que esta skill resolve

Esta skill foi criada para atacar problemas comuns do dia a dia de desenvolvimento:

• Escrever código primeiro e adicionar testes depois, ou nunca
• Dificuldade em saber se os testes realmente verificam o comportamento
• Medo de refatorar porque os testes são fracos ou inexistentes
• Uso excessivo ou inadequado de mocks que testam comportamento falso em vez de comportamento real

Ao seguir o fluxo de trabalho test-driven-development, você:

• Obtém feedback rápido a partir de testes falhando
• Mantém um registro claro do comportamento desejado
• Torna a refatoração mais segura, pois o comportamento está travado pelos testes
• Evita testes frágeis que só validam mocks ou detalhes de implementação

Quando usar (e quando não usar)

A skill original recomenda explicitamente usar TDD para:

• Novas features
• Correções de bugs
• Trabalhos de refatoração
• Qualquer mudança de comportamento

E destaca exceções que devem ser discutidas com uma pessoa, como:

• Protótipos descartáveis
• Código gerado
• Arquivos de configuração

Se você está “apenas explorando” ou fazendo um spike rápido que pretende descartar, esta skill de test-driven-development rigorosa pode ser mais pesada do que você precisa. Para features de produção, porém, ela foi criada para ser o fluxo de trabalho padrão, não um extra opcional.

Como usar

Instalação

Para instalar a skill test-driven-development do repositório obra/superpowers, execute:

npx skills add https://github.com/obra/superpowers --skill test-driven-development

Esse comando traz a definição da skill test-driven-development e arquivos de suporte para o seu ambiente Agent Skills. Depois de instalada, você pode abrir os arquivos da skill para ver as regras detalhadas e os exemplos de antipadrões.

Alguns arquivos importantes referenciados por esta skill incluem:

• SKILL.md – as regras centrais de TDD, incluindo a Iron Law e Red-Green-Refactor
• testing-anti-patterns.md – um guia focado no que não fazer em testes

Princípio central: The Iron Law

No coração desta skill está o que a fonte chama de Iron Law:

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Na prática, isso significa:

• Se você escreveu código de produção antes de um teste, deve deletar esse código e começar de novo
• Você não mantém o código como “referência” nem o adapta enquanto escreve testes
• Você não espia o código deletado ao reimplementar guiado pelos testes

Essa regra rígida garante que cada linha de código de produção seja impulsionada por um teste real.

Fluxo de TDD passo a passo

Com a skill test-driven-development instalada, use-a como seu fluxo padrão:

1. Escreva um teste falhando (RED)

• Identifique um único comportamento (feature, correção de bug ou resultado de uma refatoração)
• Escreva um novo teste que expresse o comportamento esperado
• Rode os testes e confirme que esse novo teste falha

Você não concluiu a etapa RED até:

• Ver o teste falhar
• Confirmar que ele está falhando pelo motivo correto (a asserção certa, o erro certo)

Se a falha é incorreta (por exemplo, o teste quebra na configuração ou falha por outro motivo), corrija o teste e rode novamente até que ele falhe de forma significativa.

2. Adicione o mínimo de código para passar (GREEN)

• Implemente apenas o código mais simples possível para fazer o teste falhando passar
• Evite design prematuro, abstrações desnecessárias ou lógica extra
• Rode a suíte de testes e verifique que o novo teste agora está verde e que os testes existentes continuam passando

A orientação da skill enfatiza que esta etapa é intencionalmente estreita: seu objetivo não é “terminar a feature”, mas atender ao teste.

3. Refatore com segurança (REFACTOR)

Com tudo verde:

• Limpe o código de produção: remova duplicações, simplifique a lógica, torne nomes mais claros
• Limpe os testes: deixe-os mais legíveis, extraia helpers se necessário
• Continue rodando os testes com frequência para garantir que o comportamento não mudou

Isso preserva o comportamento enquanto melhora o design, com o suporte da sua suíte de testes.

4. Repita o ciclo

Para cada pequeno comportamento ou caso de borda:

• Adicione outro teste (RED)
• Faça-o passar (GREEN)
• Refatore conforme necessário (REFACTOR)

O papel da skill test-driven-development é manter você nesse loop e dificultar racionalizações para pular etapas.

Integração com sua stack

Os exemplos do repositório são escritos com foco em JavaScript e TypeScript, mas você pode aplicar as regras de TDD independentemente da sua stack:

• Em projetos JavaScript/TypeScript (por exemplo, usando Jest, Vitest ou Mocha):

  • Sempre crie ou modifique testes (por exemplo, em *.test.ts ou *.spec.ts) antes de editar arquivos de produção
  • Use o ciclo Red-Green-Refactor em torno de cada mudança no código de aplicação

• Em outras linguagens (por exemplo, Python, Java, Go, C#):

  • Mapeie os mesmos passos para o seu framework de testes (pytest, JUnit, Go test, xUnit etc.)
  • A regra rígida “no production code without a failing test” continua valendo

A skill em si não prende você a um framework específico; ela codifica regras de fluxo de trabalho, não dependências de biblioteca.

Usando o guia de testing anti-patterns

O arquivo testing-anti-patterns.md incluído funciona como um complemento à skill test-driven-development. Carregue ou consulte esse guia sempre que você:

• Estiver escrevendo ou alterando testes
• Estiver adicionando mocks ou stubs
• Estiver tentado a adicionar hooks de teste em classes ou módulos de produção

Alguns princípios-chave desse guia incluem:

• Nunca testar comportamento de mock – testes devem verificar comportamento real, não apenas que um mock existe
• Nunca adicionar métodos apenas para testes em classes de produção – mantenha as APIs de produção limpas
• Nunca usar mocks sem entender as dependências – excesso de mocks leva a uma confiança falsa

Os exemplos de antipadrões usam testes no estilo TypeScript para mostrar testes ruins vs. bons, que você pode adaptar ao seu próprio framework de testes.

Adaptando o fluxo ao seu time

Depois de instalar, você pode adaptar as regras da skill test-driven-development à realidade do seu time, preservando a intenção central:

• Alinhe quais tipos de mudanças devem seguir TDD estrito (por exemplo, todos os módulos de produção, lógica de domínio, fluxos críticos)
• Combine os poucos casos de exceção (por exemplo, spikes rápidos ou código gerado), mas mantenha-os explícitos
• Incorpore a Iron Law na sua checklist de code review:
  • “Onde está o teste falhando que guiou esta alteração?”
  • “O teste foi escrito primeiro?”

Isso ajuda a usar a skill como um padrão de time, não apenas um hábito individual.

FAQ

A skill test-driven-development é específica de algum framework?

Não. A skill test-driven-development define um fluxo de trabalho e regras, não um framework de testes específico. Os exemplos do repositório usam JavaScript e TypeScript, mas você pode aplicar o mesmo ciclo Red-Green-Refactor em qualquer linguagem.

Eu realmente preciso deletar o código que escrevi sem testes?

De acordo com a Iron Law em SKILL.md, sim. Se você escreveu código de produção antes de um teste falhando, a regra é deletar e recomeçar a partir dos testes. A ideia é eliminar a tentação de tratar testes como algo secundário.

Quando esta skill não é uma boa opção?

A orientação original lista algumas possíveis exceções, como protótipos descartáveis, código gerado ou arquivos de configuração. Para spikes experimentais de curta duração, um TDD rigoroso pode ser mais pesado do que o necessário. Para features de produção, correções de bugs e refatorações, esta skill foi pensada para ser o padrão.

Como esta skill ajuda em debug e refatoração?

Ao corrigir um bug ou refatorar:

• Primeiro, escreva um teste falhando que reproduza o bug ou descreva o comportamento desejado
• Depois altere o código até o teste passar
• Por fim, refatore com confiança, porque os testes garantem o comportamento

Isso torna o debug mais sistemático e a refatoração mais segura.

Posso usar isso com código legado existente que não tem testes?

Sim, mas provavelmente você vai aplicar de forma incremental:

• Quando tocar em uma área legada, primeiro adicione um teste que capture o comportamento atual ou desejado
• Veja esse teste falhar (se você estiver mudando o comportamento) e depois faça-o passar
• Use o ciclo Red-Green-Refactor para, aos poucos, colocar aquela parte da base de código sob testes

Com o tempo, cada vez mais do seu código legado ficará protegido por testes.

Por onde começar depois da instalação?

Depois de rodar o comando de instalação, abra:

• SKILL.md para ver as regras centrais de test-driven-development e a descrição do Red-Green-Refactor
• testing-anti-patterns.md para ver erros comuns a evitar na escrita de testes

Use esses dois arquivos como referência para o seu fluxo de trabalho diário de desenvolvimento.