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.

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.

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