MISTAKES.md e Claude Code: transformar erro recorrente em regra

1. MISTAKES.md versus transcrição de sessão

Não confunda um log de incidentes com uma transcrição bruta do terminal:

MISTAKES.md precisa ficar conciso para que Claude Code o absorva no início da sessão sem consumir tokens de contexto em excesso.

---

2. Anatomia de um registro de incidente

Cada entrada possui quatro campos obrigatórios:

1. Incident: o que quebrou exatamente e em quais condições—código de erro, comando e ferramenta.
2. Impact: efeito posterior, como build quebrado, migração corrompida ou suíte de testes abortada.
3. Root Cause: origem técnica confirmada; se não comprovada, marque explicitamente [Hypothesis].
4. Prevention: regra ou verificação concreta para impedir repetição.

Exemplo de registro

ERR-014: migração PostgreSQL falhou em DROP COLUMN sem CASCADE

• Incident: Claude Code executou ALTER TABLE orders DROP COLUMN customer_ref; na migração 0042.
• Impact: o deploy de staging falhou por causa da view dependente v_active_orders.
• Root Cause: views que referenciam tabelas base exigem recriação explícita com cascade ou atualização prévia.
• Prevention: toda migração DDL de remoção de coluna deve verificar views dependentes por pg_depend antes da execução.

> [!IMPORTANT]
> **Política de zero segredos:** nunca faça commit de strings reais de conexão de banco, chaves privadas, tokens ou trechos de `.env` em `MISTAKES.md`. Gerencie as chaves API do Claude Code por variáveis de ambiente locais.

Para uma configuração confiável do Claude Code com provider de API, use sua própria chave API e siga o [guia de integração Claude Code da BetterToken](https://docs.bettertoken.ai/ai-tools/claude-code).

---

3. Limiar de promoção: do log ao teste ou regra

Nem todo erro isolado merece regra permanente. Promova entradas a barreiras automatizadas usando um limiar claro:

Incidente ocorreu
  │
  ├─> Primeira vez: registrar entrada de 4 campos em MISTAKES.md
  │
  └─> Segunda vez (recorrência):
        │
        ├─> Pode ser verificado mecanicamente?
        │     └─> SIM: adicionar teste unitário, regra ESLint ou hook pre-commit
        │
        └─> NÃO: adicionar instrução negativa estrita em CLAUDE.md / AGENTS.md

1. Primeira ocorrência: acrescente registro conciso ao MISTAKES.md.
2. Segunda ocorrência: se o problema pode ser detectado deterministicamente, escreva teste ou regra de linter. Barreiras automáticas superam prompts textuais.
3. Verificações não mecânicas: formule regra negativa explícita em CLAUDE.md, por exemplo “Nunca execute jest sem --runInBand no CI”.
4. Arquivamento: quando teste ou hook for implantado, arquive ou remova a entrada do MISTAKES.md para evitar crescimento do arquivo.

---

4. Verificação na próxima tarefa

Para confirmar que a nova proteção funciona:

1. inicie uma sessão nova do Claude Code;
2. forneça um prompt que antes provocava a falha;
3. verifique se o agente respeita a regra ou é interrompido pelo hook pre-commit;
4. se o agente contornar instruções de texto, transforme a restrição em wrapper estrito de comando ou verificação automática.

Esse ciclo de feedback transforma falhas aleatórias de desenvolvimento em uma base de engenharia robusta e autoaperfeiçoável.