felvieira/tdd-engineer

TDD Engineer — Red-Green-Refactor Enforced

Skill que forca o ciclo TDD correto: 1 teste → 1 implementacao → repete. Combate o anti-padrao "escrevo 5 testes, depois 5 implementacoes" — que produz testes ruins (testam shape, nao behavior).

Adaptado de mattpocock/skills/engineering/tdd e integrado ao kit (skill 05 QA + policies/vertical-slices.md).

Governanca Global

Esta skill segue GLOBAL.md, policies/execution.md, policies/quality-gates.md, policies/vertical-slices.md, policies/source-driven.md, policies/writing-clarity.md e policies/verification-before-completion.md (cada passo red→green→refactor exige output verificável da mudança de estado).

Filosofia

Tests should verify behavior through public interfaces, not implementation details. Code can change entirely; tests shouldn't.

Bom teste e integration-style: exercita codigo real atraves de API publica. Descreve o que o sistema faz, nao como. Le como spec — "user can checkout with valid cart" diz exatamente que capacidade existe. Sobrevive a refactor.

Pattern: Approved Fixtures (v2.5.0+)

Inspirado em Birgitta Böckeler (Thoughtworks) — "behaviour harness" é o gap mais difícil da indústria. Approved fixtures é uma das poucas técnicas que aumentam confiança em testes AI-gerados o suficiente pra reduzir supervisão. Ver docs/inspiration/harness-engineering.md.

Conceito

Em vez de o LLM escrever asserções, ele:

1. Roda a feature com inputs de teste
2. Captura o output produzido
3. Você revisa o output uma vez e aprova (commit do "fixture")
4. Testes futuros comparam contra o fixture aprovado

Vantagem: humano revisa dados (concretos, fáceis), não asserções (abstratas, fáceis de errar). Diferente de snapshot testing comum porque o fixture é explicitamente aprovado, não auto-gerado e auto-comparado.

Quando usar

Encaixa bem:

• Output complexo (relatório financeiro, recomendação ML, formatação)
• Transformações de dados (parser → AST, pipeline ETL)
• Renderização (markdown → HTML, JSON → CSV)
• Email/notification rendering

Não encaixa:

• Comportamento dependente de tempo, random, ambiente externo
• Side effects (writes, network calls) — use mock/stub
• Lógica trivial (overhead > ganho)

Workflow

Round 1 — geração inicial
1. Descreve behavior: "função gera relatório mensal"
2. LLM cria teste estrutural:
   - setup input
   - chama função
   - persiste output em fixtures/<feature>.approved.txt
   - assert: output === readFile(fixture)
3. LLM roda → falha (fixture não existe)
4. LLM cria fixture com output atual
5. PARA — passa pro humano

Round 2 — review humano
6. Abrir fixtures/<feature>.approved.txt
7. Verificar se output é semanticamente correto
8. Aprovar (commit) ou rejeitar (descrita erro)

Round 3 — em diante
9. Mudanças que alteram output: fixture quebra
10. LLM mostra diff: "fixture mudou de X pra Y"
11. Aprovar diff (commit) ou tratar como regressão

Anti-padrões

• ❌ Auto-aprovar snapshots sem review (vira sticker)
• ❌ Usar pra lógica trivial (overhead > ganho)
• ❌ Fixtures gigantes (>1KB) — quebra review
• ❌ Fixtures binários — usar perceptual hash
• ❌ Múltiplos asserts no mesmo teste

Integração

• Skill 05 (QA) sugere approved fixtures pra features candidatas
• Subagent test-engineer usa pattern por padrão pra business logic
• /spec flagga: "output complexo → considere approved fixtures"

Tools

• JS/TS: approvals-js
• Python: approvaltests
• Java: approvaltests-java

Referência

• Approval Tests — site canônico
• Llewellyn Falco — autor original do approach

Mau teste acopla a implementacao: mocka colaboradores internos, testa metodo privado, verifica via DB direto. Sinal de alerta: teste quebra ao refactorar sem mudar comportamento. Se renomear funcao interna quebra teste, o teste estava testando implementacao.

Quando Usar

• nova feature com complexidade nao trivial
• bug fix em codigo critico (TDD garante regressao)
• refactor de modulo nao testado (escrever testes pegando o comportamento atual antes de mexer)
• design de modulo novo onde interface ainda nao esta clara (TDD revela interface boa)
• equipe nova precisando convencao de testabilidade

Quando NAO Usar

• script throwaway (data migration uma vez, scaffolding)
• spike exploratorio (descobrir se algo e possivel)
• bug trivial em area amplamente coberta (basta adicionar teste de regressao)
• UI puramente visual (snapshot test pode bastar)

Entradas Esperadas

• spec ou criterio de aceitacao da feature (skill 01 PO ou issue do tracker)
• modulo alvo (path) ou descricao do comportamento
• (opcional) lista de comportamentos prioritarios fornecida pelo usuario
• (opcional) plano de deepening da skill 38 (Architecture Deepener)
• glossario de dominio do projeto (CONTEXT.md ou docs/glossary.md)
• ADRs relevantes (docs/adr/)

Saidas Esperadas

• todos os comportamentos priorizados em verde
• N novos arquivos de teste em tests/ ou __tests__/ (path conforme convencao do projeto)
• relatorio curto: comportamentos cobertos, comportamentos NAO cobertos (escalados para skill 05 QA)
• nenhum teste mocka colaborador interno
• nenhum teste verifica metodo privado
• testes leem como spec ("user can X when Y")
• (se houver refactor pos-GREEN) lista de modulos deepened para skill 38 validar

Anti-Padrao: Horizontal Slicing

NAO escrever todos os testes primeiro, depois toda a implementacao. Isso e horizontal slicing — tratar RED como "escrever todos os testes" e GREEN como "escrever todo o codigo".

Produz testes ruins:

• testes em massa testam comportamento imaginado, nao real
• voce acaba testando shape (estrutura de dados, assinatura) em vez de comportamento user-facing
• testes ficam insensiveis a mudancas reais — passam quando comportamento quebra, falham quando comportamento esta ok
• voce ultrapassa seus farois — commit a estrutura de teste antes de entender a implementacao

ERRADO (horizontal):
  RED:   test1, test2, test3, test4, test5
  GREEN: impl1, impl2, impl3, impl4, impl5

CERTO (vertical):
  RED→GREEN: test1→impl1
  RED→GREEN: test2→impl2
  RED→GREEN: test3→impl3
  ...

Esta diretriz ecoa policies/vertical-slices.md — fatia vertical, nao horizontal.

Workflow

Fase 1 — Planning

Ao explorar codebase, usar glossario de dominio do projeto para que nomes de teste e vocabulario de interface batam com a linguagem do projeto. Respeitar ADRs na area tocada.

Antes de escrever qualquer codigo:

• [ ] Confirmar com usuario quais mudancas de interface sao necessarias
• [ ] Confirmar com usuario quais comportamentos testar (priorizar)
• [ ] Identificar oportunidades de deep modules (interface pequena, implementacao profunda — ver skill 38)
• [ ] Desenhar interfaces para testabilidade
• [ ] Listar comportamentos a testar (NAO passos de implementacao)
• [ ] Obter aprovacao do usuario no plano

Pergunta-chave: "Como deve ser a interface publica? Quais comportamentos sao mais importantes testar?"

Voce nao pode testar tudo. Confirmar com usuario quais comportamentos importam mais. Foco em paths criticos e logica complexa, nao todo edge case possivel.

Fase 2 — Tracer Bullet

Escrever UM teste que confirma UMA coisa sobre o sistema:

RED:   Escrever teste para o primeiro comportamento → teste falha
GREEN: Escrever codigo minimo para passar → teste passa

Esse e o tracer bullet — prova que o caminho funciona end-to-end.

Fase 3 — Loop Incremental

Para cada comportamento restante:

RED:   Escrever proximo teste → falha
GREEN: Codigo minimo para passar → passa

Regras:

• um teste por vez
• so codigo suficiente para passar o teste atual
• nao antecipe testes futuros
• mantenha testes focados em comportamento observavel

Fase 4 — Refactor

Apos todos os testes passarem, procurar oportunidades de refactor:

• [ ] Extrair duplicacao
• [ ] Aprofundar modulos (mover complexidade atras de interface simples — coordenar com skill 38)
• [ ] Aplicar SOLID onde natural
• [ ] Considerar o que o codigo novo revela sobre codigo existente
• [ ] Rodar testes apos cada passo de refactor

Nunca refactore enquanto RED. Chegue ao GREEN primeiro.

Checklist Por Ciclo

[ ] Teste descreve comportamento, nao implementacao
[ ] Teste usa apenas interface publica
[ ] Teste sobreviveria a refactor interno
[ ] Codigo e minimo para esse teste
[ ] Nenhuma feature especulativa adicionada

Anti-Rationalization Table

Pensamentos que indicam STOP — voce esta racionalizando:

| Pensamento | Realidade | |---|---| | "Vou escrever os 5 testes agora porque ja sei o que precisa" | Horizontal slicing. Volte ao tracer bullet. | | "Esse teste vai precisar de mock do DB pra rodar" | Provavelmente esta testando implementacao. Reescreva pra usar interface publica. | | "Adicionar funcionalidade extra agora porque ja estou aqui" | Nao antecipe. Codigo minimo para o teste atual. | | "Refactor enquanto vermelho — vai ficar mais limpo" | Nao. GREEN primeiro, refactor depois. | | "O teste passou na primeira tentativa, sem ter visto vermelho" | Voce pode estar testando algo que ja existia. Garanta que o teste falha sem o codigo novo. | | "Vou testar metodo privado pra cobrir tudo" | Metodo privado nao e contrato. Teste comportamento via interface publica. | | "Vou querer esse teste depois entao escrevo agora" | Especulativo. Escreva quando precisar. | | "Esse cenario e improvavel" | Se e improvavel, nao teste. Se e critico, escreva o teste agora. | | "Vou pular TDD nesta feature porque e simples" | "Simples" muitas vezes vira complexo. Comece TDD, abandone se ficar obvio que nao agrega. |

Heuristicas de Boa Interface (para testabilidade)

• Deep module: interface pequena, comportamento rico. Test count baixo + cobertura alta.
• Argumentos primitivos > objetos complexos: facilita setup de teste sem mocks elaborados.
• Funcao pura > stateful: input → output testavel sem fixture.
• Side effect declarado > escondido: facilita asserir que aconteceu.
• Erro e retorno > excecao: simplifica matrix de teste (sem try/catch).

Coordenar com skill 38 (Architecture Deepener) para identificar modulos shallow que merecem deepening antes de escrever teste.

Integracao com Vertical Slices

TDD opera dentro de uma vertical slice. Sequencia:

1. /to-issues quebra feature em vertical slices
2. Cada worker pega 1 slice
3. Dentro do slice: TDD red-green-refactor por comportamento
4. Slice completa quando todos os comportamentos prioritarios estao verdes

NAO tentar TDD cross-slice — comportamento de slice X nao deve depender de teste de slice Y.

Evidencia de Conclusao

• todos os comportamentos priorizados verdes
• nenhum teste foi escrito antes de ver o respectivo RED
• refactor passada apos GREEN final, todos os testes ainda verdes
• nenhum teste mocka colaborador interno
• nenhum teste verifica metodo privado
• testes leem como spec ("user can X when Y")

Handoff

Apos conclusao:

• caminho dos testes adicionados
• contagem (N novos testes, M cobertura aumentada)
• modulos que ganharam deepening (se aplicavel) → skill 38 valida
• proxima: skill 11 (Reviewer) valida que testes nao mockam implementacao

Integracao com Pipeline

• PO (skill 01): criterios de aceitacao alimentam lista de comportamentos prioritarios
• Backend (03) + Frontend (04): implementacao do GREEN
• QA Engineer (05): complementa com edge cases nao priorizados em TDD
• Reviewer (11): valida disciplina TDD (sem mock interno, sem teste de privado)
• Architecture Deepener (38): coordena para identificar deep modules antes do RED
• /build: pode ativar TDD se task descrita como "TDD" ou "test-first"

Material Adicional

Para deep dives consultar:

• docs/skill-guides/tdd-deep-modules.md (a criar conforme demanda) — adaptacao de tdd/deep-modules.md
• docs/skill-guides/tdd-interface-design.md — interface design para testabilidade
• docs/skill-guides/tdd-mocking.md — quando mockar (raramente) e como
• docs/skill-guides/tdd-refactoring.md — refactor checklist apos GREEN