✅ Código que Funciona: TDD + Diagnose

Agente é um péssimo verificador do próprio trabalho. Ele lê o código que acabou de gerar, vê que "parece certo", e declara vitória. Sem teste rodando, "parece certo" é só uma opinião — e a opinião do agente está enviesada pelo código que ele mesmo escreveu.

TDD resolve isso virando o jogo: o teste vem primeiro, falha primeiro, e só depois o código é escrito pra fazer o teste passar. O agente não tem como se enganar — ou o teste fica verde, ou não fica.

O comando /tdd coloca o agente num loop disciplinado de três etapas. Cada etapa tem um objetivo único — não pular, não combinar, não otimizar antes da hora.

# você
/tdd implementa função slugify(texto) — minúsculas, espaço vira "-",
remove acentos, remove caracteres especiais

# agente
🔴 Red: escrevi 4 testes em test_slugify.py
  - "Olá Mundo" → "ola-mundo"
  - "  Espaço extra  " → "espaco-extra"
  - "Já!!" → "ja"
  - "" → ""
rodando pytest... 4 failed (módulo slugify não existe) ✓ esperado

🟢 Green: criando slugify.py com unicodedata + re.sub
rodando pytest... 4 passed ✓

♻️ Refactor: extraindo etapas em funções nomeadas
  _strip_accents(s), _to_kebab(s)
rodando pytest após cada mudança... 4 passed ✓
pronto.

Quando uma feature toca várias camadas (UI, API, DB), tem dois jeitos de atacar: horizontalmente (faz toda a DB, depois toda a API, depois toda a UI) ou verticalmente (uma feature de ponta a ponta, depois a próxima). Com agente, vertical sempre ganha.

Vertical slice = você consegue rodar e ver funcionando ao final de cada slice. Horizontal = você só descobre que tudo está errado quando junta tudo no final.

VERTICAL (recomendado)              HORIZONTAL (evitar)
┌──────┬──────┬──────┐               ┌──────────────────┐
│  UI  │  UI  │  UI  │               │       UI         │  ← slice 3
├──────┼──────┼──────┤               ├──────────────────┤
│ API  │ API  │ API  │               │       API        │  ← slice 2
├──────┼──────┼──────┤               ├──────────────────┤
│  DB  │  DB  │  DB  │               │       DB         │  ← slice 1
└──────┴──────┴──────┘               └──────────────────┘
 feat1  feat2  feat3                   tudo de uma vez

cada slice roda           só roda no fim de tudo
end-to-end                (e geralmente quebra)

TDD resolve bem o trabalho novo. Mas bugs em código existente — especialmente os intermitentes, os que só acontecem em produção, os que ninguém entende — pedem outra abordagem. O /diagnose é um loop de seis etapas pensado pra isso.

O erro mais caro em debug é pular a etapa de reprodução. O agente lê o stack trace, vê um nome familiar, e sai escrevendo um fix. Às vezes funciona — mas quando não funciona, ninguém percebe, porque ninguém montou o cenário pra verificar.

Bug que voltou é o mais frustrante de todos — porque ele já foi consertado uma vez. A regra é simples: todo bug consertado vira um teste de regressão. Se você não tem teste pro caso, ele vai voltar.

O melhor momento de escrever esse teste é exatamente quando você acabou de consertar o bug — o cenário está fresco, você sabe exatamente o que falhava, e a reprodução já existe (você usou ela no /diagnose).

# Bug reportado em produção: "comentário com emoji 🎉 quebrava a API"
# Causa encontrada via /diagnose: encoding latin-1 num middleware antigo
# Fix aplicado: trocar pra utf-8
# Teste de regressão (commit junto com o fix):

def test_comentario_com_emoji_nao_quebra_api():
    """Regression: bug #482 — emoji no body causava UnicodeDecodeError."""
    payload = {"texto": "Show de bola 🎉🚀"}

    response = client.post("/api/comentarios", json=payload)

    assert response.status_code == 201
    assert response.json()["texto"] == "Show de bola 🎉🚀"

# Anote no docstring: número do bug, causa raiz. Quando o teste falhar
# de novo em 6 meses, quem ler vai entender o porquê de existir.

Os dois loops não competem — colaboram. /tdd é pra trabalho novo onde você sabe o que quer. /diagnose é pra entender por que algo existente não está fazendo o que devia. Bugs complexos quase sempre passam por ambos.

Pegue um bug aberto no seu projeto — qualquer um, de preferência um que você tem evitado porque "é estranho". Rode /diagnose e anote cada etapa num documento. No final, você vai ter o bug resolvido E um material de revisão pra entender como agentes lidam com bugs.