tdd

Visão geral da skill tdd

A skill tdd é um guia focado em desenvolvimento orientado a testes com um ciclo rigoroso de red-green-refactor, e não um prompt genérico de “escreva alguns testes”. Ela é mais indicada para desenvolvedores que querem ajuda da IA para criar funcionalidades ou corrigir bugs mantendo os testes ligados ao comportamento por meio de interfaces públicas, e não a detalhes de implementação.

Para que serve o tdd

Use tdd for Test Driven Development quando você quiser que o modelo:

• planeje uma funcionalidade em pequenos cortes verticais
• escreva um teste falhando por vez
• implemente só o código necessário para passar
• refatore com segurança depois do green
• evite testes frágeis que quebram em refactors inofensivos

Quem tira mais valor da skill tdd

A skill tdd funciona melhor se você já tiver:

• uma base de código com testes executáveis
• uma API pública, endpoint, comando ou fluxo de usuário claro para atacar
• permissão para alterar tanto os testes quanto o código de produção
• preferência por testes em estilo de integração em vez de mocking pesado

Ela é especialmente útil para serviços backend, bibliotecas, lógica de domínio e fluxos de aplicação em que o comportamento pode ser exercitado por uma interface real.

O que diferencia esta skill tdd

O principal diferencial está na postura opinativa sobre qualidade de testes:

• testar comportamento, não internals
• preferir testes em estilo de integração
• usar mock apenas nos limites do sistema
• evitar “fatiamento horizontal”, em que você escreve todos os testes primeiro e todo o código depois
• usar TDD para moldar interfaces melhores, e não apenas para aumentar cobertura

Isso torna o uso de tdd mais disciplinado do que um prompt comum pedindo para uma IA “escrever testes e implementação”.

O que pode dificultar a adoção

Essa skill encaixa pior se o seu ambiente não consegue rodar testes, se a base de código não tem pontos de entrada públicos estáveis ou se o time prefere principalmente testes unitários com muito snapshot ou muito mock. Ela também parte do princípio de que você aceita iterar em passos pequenos, em vez de gerar uma funcionalidade inteira de uma vez.

Como usar a skill tdd

Instale o tdd no seu ambiente de skills

Se você estiver usando o sistema de Skills do repositório, um padrão comum de instalação é:

npx skills add mattpocock/skills --skill tdd

Depois, invoque tdd ao pedir ao modelo que implemente ou corrija um comportamento usando um fluxo test-first.

Leia estes arquivos primeiro antes de usar tdd com mais intensidade

O caminho mais rápido para entender esta skill é:

1. SKILL.md
2. tests.md
3. mocking.md
4. interface-design.md
5. refactoring.md
6. deep-modules.md

Essa ordem importa. SKILL.md traz a filosofia operacional, enquanto os arquivos de apoio explicam na prática o que significam “bons testes” e “bom design”.

Entenda o fluxo central que o tdd espera

A skill foi construída em torno de um loop enxuto:

1. escolher um comportamento pequeno
2. escrever um teste falhando por uma interface pública
3. implementar o código mínimo para passar
4. refatorar mantendo os testes verdes
5. repetir com o próximo menor recorte

Se você pedir uma funcionalidade inteira de uma vez, perde a maior parte do valor do uso de tdd.

Comece por um comportamento, não por uma ideia de implementação

Entrada forte:

• “Add checkout support for expired cards. Public entrypoint is checkout(cart, paymentMethod). Existing test file is checkout.test.ts. Keep using integration-style tests.”

Entrada fraca:

• “Create classes for payment orchestration and add unit tests for each method.”

O primeiro prompt dá à skill um alvo comportamental. O segundo empurra o modelo para especulação sobre design interno e testes frágeis.

Dê à skill a interface pública e o comando de teste

Para ter bons resultados de instalação e execução de tdd, inclua:

• a função, rota, comando CLI ou ação de UI sob teste
• onde os testes ficam
• o test runner e o comando
• restrições relevantes, como DB, HTTP ou serviços externos
• o que pode e o que não pode ser mockado

Um template de prompt prático:

Use the tdd skill.

Goal: Add [behavior].
Public interface: [function/route/command].
Test location: [path].
Run tests with: [command].
Boundaries to mock: [external API, clock, filesystem].
Do not mock: [internal modules/classes].
Work in red-green-refactor steps and explain each step briefly.

Use cortes verticais, não cortes horizontais

Uma das lições práticas mais importantes deste repositório é evitar escrever todos os testes em bloco logo de início. Aqui, um bom uso de tdd significa:

• escolher um cenário real
• fazê-lo passar
• deixar esse resultado orientar o próximo cenário

Isso reduz abstrações imaginadas e normalmente produz uma API com formato melhor.

Prefira testes em estilo de integração no tdd

O repositório favorece fortemente testes que exercitam caminhos reais do código por APIs públicas. Na prática, isso significa:

• chamar funções exportadas em vez de helpers privados
• acionar handlers de rota pela interface suportada
• verificar resultados observáveis, não a ordem interna das chamadas
• nomear testes pela capacidade entregue, como “user can checkout with valid cart”

Se um refactor muda os internals, mas o comportamento continua igual, um bom teste normalmente deve continuar verde.

Faça mock apenas nos limites do sistema

A skill tdd não é anti-mock; ela é contra mockar a sua própria implementação. Faça mock de:

• gateways de pagamento
• provedores de email
• tempo/aleatoriedade
• em alguns casos, banco de dados ou filesystem, dependendo da configuração de testes

Não faça mock de:

• seus próprios módulos
• colaboradores internos
• métodos privados
• wrappers finos sob seu controle

Só essa diretriz já muda a qualidade da saída mais do que a maioria dos ajustes de prompt.

Modele o código para ser testável antes de escrever código demais

Os arquivos de apoio destacam um ponto importante: interfaces melhores tornam TDD mais fácil. Peça ao modelo para favorecer código que:

• receba dependências em vez de criá-las internamente
• retorne resultados em vez de mutar estado oculto
• mantenha pequena a superfície pública

Se o design atual dificulta os testes, diga ao modelo para primeiro propor uma interface pública menor e mais testável.

Um exemplo forte de prompt para tdd

Use the tdd skill to add password reset token expiry.

Context:
- Node + TypeScript
- Public API: `requestPasswordReset(email)` and `resetPassword(token, newPassword)`
- Tests: `src/auth/password-reset.test.ts`
- Run with: `pnpm test password-reset`
- Mock only email sending and time
- Do not mock repository code or internal services

Please:
1. choose the smallest failing behavior first
2. write integration-style tests through public APIs
3. implement minimum code to pass
4. refactor after green
5. avoid asserting internal call counts unless at an external boundary

Esse exemplo funciona porque dá à skill um alvo, uma política de limites e um caminho real de execução.

Observe os principais sinais de qualidade na saída

Um bom resultado de guia tdd com esta skill normalmente inclui:

• testes nomeados em torno de comportamento visível para o usuário
• um cenário pequeno por vez
• implementação mínima em cada etapa
• notas de refatoração depois do green
• pouca ou nenhuma dependência da estrutura privada

Um resultado ruim normalmente inclui:

• muitos mocks para código interno
• assertions sobre ordem de chamadas
• suítes enormes de teste já no primeiro passo
• abstrações especulativas antes de qualquer comportamento passar

FAQ da skill tdd

O tdd serve só para funcionalidades novas?

Não. A skill tdd também funciona muito bem para correção de bugs. Em muitas bases maduras, o melhor primeiro passo é um teste de regressão que falha e reproduz o bug por meio da interface pública, seguido de uma correção mínima e então limpeza do código.

Esta skill tdd é amigável para iniciantes?

Sim, desde que você já saiba rodar os testes do seu projeto. A orientação é opinativa, mas simples: teste comportamento, mantenha recortes pequenos e evite assertions sobre detalhes de implementação. Iniciantes absolutos ainda podem precisar de ajuda para entender a arquitetura do projeto e o ferramental de testes.

Em que o tdd difere de pedir para uma IA escrever testes?

Prompts comuns costumam gerar testes orientados à cobertura ou com mock em excesso. A skill tdd empurra o modelo na direção de:

• especificações comportamentais
• refactors mais seguros
• interfaces mais limpas
• passos iterativos menores

Isso muda tanto os testes quanto o design de produção.

Quando eu não devo usar tdd?

Evite ou limite tdd for Test Driven Development quando:

• o comportamento ainda não pode ser exercitado de forma significativa
• o ambiente é difícil demais de rodar durante a iteração
• você está fazendo spikes exploratórios e descartáveis
• a tarefa é principalmente mecânica, como renomeações ou atualização de dependências

Você ainda pode voltar ao TDD quando o ponto de entrada público estiver mais claro.

O tdd exige apenas testes de integração?

Não necessariamente, mas o viés dele é para testes em estilo de integração por interfaces reais. O objetivo não é maximizar o tamanho do teste; é testar comportamento em um ponto de contato estável. Testes pequenos e focados continuam válidos se permanecerem na interface pública e evitarem acoplamento interno.

Quais linguagens ou frameworks combinam com esta skill?

As ideias são amplamente independentes de linguagem. Os exemplos tendem a TypeScript e JavaScript, mas os princípios de design se aplicam a Python, Java, Go, Ruby e ecossistemas parecidos sempre que você consegue definir interfaces públicas claras e limites de teste.

Como melhorar a skill tdd

Dê ao tdd um primeiro recorte menor

A forma mais fácil de melhorar os resultados de tdd é reduzir o primeiro passo. Em vez de “build user invitations”, comece com “user with valid email can request an invitation”. Recortes menores reduzem arquitetura alucinada e produzem testes mais limpos.

Forneça regras explícitas de limites

Muitas saídas ruins vêm de uma política de mocking pouco clara. Diga ao modelo exatamente:

• quais sistemas externos podem ser mockados
• quais módulos internos devem continuar reais
• se existe um test DB disponível
• se o tempo deve ser injetado ou congelado

Isso ajuda a skill a permanecer alinhada à filosofia do repositório.

Peça nomes de teste pela interface pública

Se você quer testes melhores, peça nomes que descrevam resultados:

• bom: user can checkout with valid cart
• mais fraco: checkout calls payment service

Essa única instrução muitas vezes já evita o desvio para detalhes de implementação.

Faça o red-green-refactor ficar visível

Se a primeira resposta vier como um bloco completo de implementação, peça ao modelo para reorganizá-la:

• mostrar o primeiro teste falhando
• mostrar o código mínimo para passar
• explicar a refatoração separadamente
• parar depois de um recorte, se necessário

A skill tdd funciona melhor quando o loop está visível, e não apenas implícito.

Melhore o design quando os testes parecerem estranhos

Se o modelo tiver dificuldade para escrever testes limpos, o problema costuma ser o design da interface, não a sintaxe de testes. Peça que ele revise na direção de:

• injeção de dependências
• entradas e saídas explícitas
• superfícies públicas menores
• menos efeitos colaterais

É aqui que interface-design.md e deep-modules.md ficam especialmente valiosos.

Use a refatoração como uma etapa separada de qualidade

Depois de alguns recortes verdes, peça explicitamente uma revisão de refatoração usando os sinais do repositório:

• duplicação
• métodos longos
• módulos rasos
• feature envy
• primitive obsession

Isso evita que o uso de tdd pare em “os testes passam” e melhora a manutenção sem mudar comportamento.

Corrija cedo os modos de falha mais comuns

Se a qualidade da saída cair, estas costumam ser as causas:

• código demais gerado antes do primeiro teste falhando
• colaboradores internos fortemente mockados
• testes verificam detalhes de implementação
• o pedido de funcionalidade é grande demais para um único ciclo
• a interface pública está pouco clara ou muda a cada etapa

Quando isso acontecer, reinicie com um comportamento, um ponto de entrada, um teste falhando.

Use os arquivos do repositório como apoio de decisão

Para melhores resultados, mapeie seu problema para os docs de apoio:

• tests.md quando o estilo de teste estiver fraco
• mocking.md quando as decisões de limites estiverem pouco claras
• interface-design.md quando os pontos de entrada estiverem ruins
• refactoring.md depois do green
• deep-modules.md quando o formato da API estiver ficando amplo demais

Esse caminho de leitura entrega mais valor do que passar rapidamente só por SKILL.md.

Itere apertando as restrições, não repetindo o mesmo prompt

Se a primeira saída for mediana, não diga apenas “try again”. Melhore a próxima rodada com restrições concretas:

• atacar apenas um comportamento
• preservar a API pública atual
• não mockar módulos internos
• preferir um test DB a mocks de repositório
• parar após o primeiro ciclo red-green-refactor

Esse tipo de iteração melhora a qualidade do guia tdd de forma muito mais consistente do que simplesmente pedir mais detalhes.