git:20260516.e5a0f4a to git:20260520.b523bd1

---

name: tdd-engineer

description: |

Test-Driven Development com red-green-refactor enforced. Use quando construir feature ou

fix de bug usando TDD, mencionar "red-green-refactor", quiser tracer bullets, ou pedir

desenvolvimento test-first. Combate o anti-padrao "horizontal slicing" (escrever todos

os testes antes de toda a implementacao).

Trigger em: "tdd", "test-first", "red-green-refactor", "tracer bullet", "behavior test",

"integration test", "deep module", "interface design test".

argument-hint: "[--module=path] [--behavior=descricao]"

allowed-tools: Read, Grep, Glob, Bash, Edit, Write

---

# 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](https://github.com/mattpocock/skills/tree/main/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.

**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](https://github.com/mattpocock/skills/blob/main/skills/engineering/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