test-driven-development

Visão geral da skill test-driven-development

O que a skill test-driven-development realmente faz

A skill test-driven-development dá ao agente de IA um fluxo rígido de TDD para desenvolvimento de funcionalidades, correções de bugs e mudanças de comportamento: escrever um teste primeiro, confirmar que ele falha pelo motivo certo, escrever o mínimo de código de produção para passar e só então refatorar com segurança. O valor central não é “escrever testes também”, e sim impor a sequência para que a implementação seja guiada por comportamento executável.

Para quem essa skill é mais indicada

A test-driven-development skill é ideal para desenvolvedores que usam IA em trabalho real de repositório, onde correção e confiabilidade importam: funcionalidades de aplicação, lógica de serviços, correções de bugs, refatorações e prevenção de regressões. Ela é especialmente útil quando você quer impedir que o modelo pule direto para a implementação e, em vez disso, produza passos menores e verificáveis.

O trabalho real que ela resolve

A maioria dos usuários instala test-driven-development porque prompts genéricos de programação costumam criar código primeiro e adaptar testes depois. Esta skill muda esse comportamento. Ela ajuda você a obter implementações ancoradas em testes que falham primeiro, deixando o agente mais fácil de revisar e menos propenso a inventar comportamentos não validados.

O que diferencia esta skill de um prompt genérico de “escreva testes”

O diferencial está na “lei de ferro” da skill: nenhum código de produção sem antes existir um teste falhando. Isso é muito mais rígido do que um prompting comum. A skill também enfatiza verificar se a falha inicial é a falha correta, e não apenas qualquer resultado em vermelho — um guardrail prático que muitos resumos superficiais sobre TDD deixam passar.

Limites importantes antes de instalar

Esta é uma skill de processo, não um toolkit de testes específico de framework. Ela não vai definir sozinha toda a arquitetura de testes do seu projeto e também não inclui scripts auxiliares nem referências extensas além de SKILL.md e testing-anti-patterns.md. Se você precisa de orientação profunda sobre configuração de Jest, Pytest, JUnit ou Playwright, esta skill funciona melhor como camada de workflow do que como manual completo de testes.

Como usar a skill test-driven-development

Instale a skill test-driven-development

Instale a partir do repositório com:

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

Se o seu ambiente oferece descoberta local de skills, confirme que a skill aparece como test-driven-development e está disponível para o agente antes de começar o trabalho de feature.

Leia estes arquivos primeiro

Para este fluxo de test-driven-development install e uso, comece por:

• skills/test-driven-development/SKILL.md
• skills/test-driven-development/testing-anti-patterns.md

Leia SKILL.md primeiro para entender o workflow e as restrições. Em seguida, leia testing-anti-patterns.md se sua tarefa envolver mocks, isolamento, testes de UI ou qualquer tentação de criar seams voltados só para teste dentro do código de produção.

Entenda o mínimo de contexto que a skill precisa

A skill funciona melhor quando você informa:

• a funcionalidade, bug ou mudança de comportamento
• os arquivos relevantes ou os limites do módulo
• o framework de testes já usado no repositório
• o comportamento desejado, visível para usuário ou sistema
• quaisquer restrições de formato de API, compatibilidade retroativa ou performance

Sem esse contexto, o agente ainda consegue aplicar TDD de forma mecânica, mas pode escolher o nível de teste errado ou criar testes artificiais, mais adequados à ferramenta do que ao codebase.

Transforme um pedido vago em um prompt pronto para TDD

Prompt fraco:

Add support for password reset.

Prompt mais forte:

Use the test-driven-development skill. We need password reset in the existing Node/Express app. Write the first failing integration or service-level test before any production code. Verify the failure is for missing reset behavior, not setup issues. Then implement the minimum code to pass. Keep the current route style, use Jest, and avoid changing unrelated auth flows.

A versão mais forte dá ao agente contexto suficiente para escolher o teste inicial correto e seguir o ciclo red-green-refactor.

Use a skill como um workflow em etapas, não como uma geração única

Um padrão prático de test-driven-development usage é:

1. Peça apenas o primeiro teste falhando.
2. Revise se a falha aponta para o comportamento pretendido.
3. Peça a implementação mínima para fazê-lo passar.
4. Peça refatoração só depois do green.
5. Repita para a próxima pequena fatia de comportamento.

Isso produz resultados melhores do que pedir a feature inteira de uma vez, porque a skill foi feita para incrementos pequenos e validados.

Verifique corretamente a fase “red”

Um detalhe importante neste test-driven-development guide é que um teste falhando, por si só, não basta. A falha precisa provar que o teste está mirando o comportamento ausente correto. Se o teste falha por erro de import, fixture quebrada ou setup não relacionado, o ciclo ainda nem começou de verdade.

Ao escrever o prompt, peça explicitamente que o agente diga por que o teste falha e por que essa é a falha correta.

Escolha o teste inicial certo

O melhor primeiro teste geralmente mira a menor mudança de comportamento que já seja externamente relevante. Bons candidatos incluem:

• a reprodução de um bug
• uma regra de negócio
• uma mudança na resposta de um endpoint
• o comportamento de um método de domínio
• uma interação de UI com impacto claro para o usuário

Pontos de partida ruins incluem cenários enormes de ponta a ponta, cobertura ampla por snapshot ou testes que travam detalhes internos de implementação cedo demais.

Aplique a orientação sobre anti-patterns quando surgirem mocks

O arquivo de apoio testing-anti-patterns.md importa muito se o agente começar a exagerar no uso de mocks. A skill alerta com força para o risco de testar comportamento de mocks em vez de comportamento real. Isso é especialmente relevante para test-driven-development for Test Automation, em que agentes de IA frequentemente criam assertions sobre placeholders mockados porque isso é mais fácil de satisfazer do que validar saídas reais.

Se um teste estiver verificando que um mock foi renderizado, que um mock foi chamado de forma trivial, ou se foi preciso adicionar um método só para teste no código de produção, pare e redefina o escopo do teste.

Peça ao agente para preservar a lei de ferro

Se o modelo já tiver rascunhado a implementação, a orientação da própria skill é rígida: apague o código de produção e recomece a partir de um teste falhando. Na prática, você não precisa dramatizar, mas deve instruir o agente a ignorar a implementação especulativa anterior e regenerar a solução a partir da sequência test-first.

Formulação útil:

Do not continue from implementation-first code. Restart with a failing test and derive the implementation from that test.

Adapte a skill à stack de testes do seu repositório

A skill é centrada em processo, então você deve ancorá-la na sua stack:

• pytest para serviços em Python
• Jest ou Vitest para lógica em JS/TS
• RSpec para Ruby
• JUnit para Java
• Playwright ou similar apenas quando o comportamento realmente pertence ao nível de navegador

Se o seu repositório já tem uma pirâmide de testes bem definida, diga ao agente onde esta mudança deve entrar. Caso contrário, o modelo pode acabar escolhendo o estilo de teste mais visível, e não o mais barato e útil.

Exemplo de prompt para trabalho real em repositório

Um bom prompt de test-driven-development skill se parece com isto:

Use the test-driven-development skill for a bug fix. In billing/invoice_service.py, invoices with zero-amount adjustments should remain payable if tax is still due. Start by writing the smallest failing pytest that reproduces the current bug. Confirm the failure is caused by the missing business rule, not fixture issues. Then implement the minimum fix, run or describe the expected green result, and suggest any safe refactor only after the test passes.

Esse prompt fornece comportamento, localização, framework e critérios de revisão.

FAQ da skill test-driven-development

Vale a pena instalar test-driven-development mesmo se eu já conheço TDD?

Sim, se o seu principal problema é fazer agentes de IA realmente seguirem TDD em vez de apenas falarem sobre isso. A test-driven-development skill é útil menos como material educativo e mais como restrição comportamental para o modelo.

Ela é amigável para iniciantes?

Em grande parte, sim. O workflow é simples e explícito. A parte mais difícil para quem está começando é escolher o teste inicial certo e o nível de teste adequado. Se você é novo em testes, use esta skill primeiro em correções pequenas de bugs, não em features novas e amplas.

Quando test-driven-development não é uma boa escolha?

Ela é menos adequada para protótipos descartáveis, código gerado automaticamente ou mudanças puramente de configuração, a menos que o risco de erro seja alto e a revisão humana ainda exija disciplina test-first. A orientação da fonte trata explicitamente esses casos como exceções que devem ser discutidas com um parceiro humano.

Em que isso difere de prompting comum?

Prompts comuns costumam dizer “implemente X e adicione testes”. Esta skill muda a ordem do trabalho e trata essa ordem como inegociável. Esse sequenciamento é o valor real, porque reduz implementações alucinadas e melhora a revisabilidade.

Esta skill também cobre setup de framework?

Não em profundidade. test-driven-development install é simples, mas a skill em si não traz documentação extensa de setup específico por framework. Ela assume que você consegue apontar o agente para sua stack de testes atual ou para as convenções já existentes no repositório.

Posso usar test-driven-development para refatoração?

Sim. Ela funciona muito bem para refatorações quando o comportamento precisa permanecer estável. O padrão prático é primeiro travar o comportamento atual com testes e depois refatorar com a proteção dos testes em green.

Isso é bom para testes de UI e end-to-end?

Às vezes, mas com cuidado. Em trabalho de UI, o arquivo de anti-patterns é especialmente importante porque a IA pode desviar para assertions sobre presença de mocks ou artefatos de implementação. Comece pelo menor comportamento real de usuário que você consiga verificar.

Como melhorar a skill test-driven-development

Dê comportamento, não ideias de solução

Para obter um test-driven-development usage melhor, descreva o comportamento esperado e as restrições, em vez de ditar a implementação. TDD funciona melhor quando o teste define os resultados e o código emerge dessas verificações.

Entrada melhor:
Users should see an error when uploading files over 10MB.

Entrada pior:
Add a fileSizeValidator class and call it from the controller.

A primeira deixa espaço para uma implementação mínima mais limpa.

Especifique o nível de teste desejado

Muitos resultados fracos vêm de um escopo de teste mal escolhido. Diga ao agente se você quer:

• lógica de negócio em nível unitário
• integração em torno de um serviço ou API
• comportamento em nível de navegador

Essa escolha costuma importar mais do que qualquer outro detalhe do prompt.

Force incrementos menores

Uma falha comum é pedir coisa demais em um único ciclo. Se o modelo escrever uma suíte ampla de testes e uma implementação grande ao mesmo tempo, reduza o escopo:

Pick one failing test that captures the first slice of behavior. Do not implement the whole feature yet.

Isso preserva o loop de test-driven-development.

Exija explicação sobre por que o primeiro teste está correto

Peça ao agente que justifique:

• por que esse teste é a menor fatia útil
• qual falha exata é esperada
• por que essa falha prova que o comportamento está ausente

Isso melhora a qualidade porque torna explícitas suposições escondidas antes de a implementação começar.

Observe anti-patterns desde cedo

As quedas de qualidade mais comuns são:

• testar mocks em vez de comportamento
• introduzir métodos voltados só para teste no código de produção
• escrever testes que já passam e chamar isso de TDD
• escolher assertions presas a detalhes de implementação
• pular a etapa de refatoração depois do green

Se você identificar um desses casos, interrompa o ciclo e peça um primeiro teste corrigido em vez de remendar o problema.

Informe explicitamente as convenções do repositório

A skill funciona melhor quando você informa:

• convenções de nomenclatura para testes
• onde os testes ficam
• padrões de fixture
• política de mocking
• estilo de assertion preferido

Como o repositório inclui apenas material de apoio leve, essas convenções locais melhoram materialmente a qualidade da saída.

Itere depois da primeira resposta

Após o resultado inicial, não peça apenas “mais”. Faça perguntas objetivas de continuação:

• Can you make the failing test narrower?
• Is this failure due to setup or missing behavior?
• Can we remove this mock and test real behavior instead?
• What is the minimum code needed to pass?
• What refactor is now safe with tests green?

Esta é a forma de maior alavancagem para melhorar a test-driven-development skill na prática: manter o agente dentro do ciclo em vez de deixá-lo se adiantar.

Combine com julgamento humano nas exceções

A skill é intencionalmente rígida. Isso é uma força, mas também pode ser aplicado em excesso. Se a tarefa for uma mudança puramente de configuração, atualização de código gerado ou protótipo descartável, questione se TDD completo realmente vale o custo. Os melhores resultados vêm de usar a skill onde a sequência test-first melhora a qualidade das decisões, e não apenas onde ela pode ser aplicada.