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

Ao trabalhar com Claude Code em repositórios complexos, o agente inevitavelmente encontra particularidades pouco óbvias: definições TypeScript desatualizadas, dependências ocultas de runtime ou comportamentos específicos de bundler. Corrigir o mesmo erro repetidas vezes no chat desperdiça contexto e tempo. Por outro lado, despejar transcrições de sessão de muitas páginas nas instruções cria ruído no prompt e reduz a atenção do modelo.

Um padrão prático é manter um MISTAKES.md leve na raiz do repositório. Ele registra somente incidentes reproduzíveis, causas verificadas e ações preventivas, que depois são promovidos para testes do projeto, regras de linter e configuração persistente.

---

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

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

Dimensão	Transcrição de sessão	Log de incidentes MISTAKES.md
Volume	Milhares de linhas de chamadas de ferramentas e etapas intermediárias	5–10 linhas estruturadas por incidente
Objetivo	Depuração e auditoria de uma execução	Base de referência para evitar recorrência futura
Segredos	Pode capturar variáveis de ambiente ou tokens brutos	Estritamente proibido: nenhuma credencial ou segredo
Vida útil	Artefato efêmero	Documentação persistente até automatização

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.

---

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.