O CLAUDE.md que faz o agente acertar

O problema

Você pede uma mudança pequena. O agente refatora três arquivos que ninguém mandou tocar, inventa uma abstração para um caso só, usa a biblioteca que o projeto abandonou no ano passado e commita direto na branch principal.

Você corrige. Na sessão seguinte, ele faz tudo de novo.

Não é burrice do modelo: é que as regras do seu projeto existem só na sua cabeça. O agente chega em cada sessão sem memória, lê o código e conclui o que dá pra concluir. Tudo que não está escrito, ele adivinha, e adivinha de novo amanhã.

E há um segundo custo, que aparece depois. Quando as regras finalmente são escritas, o arquivo cresce até virar um calhamaço que ninguém lê inteiro, e que o agente carrega em toda sessão. Você passa a pagar contexto (e tokens) por página de texto que não muda decisão nenhuma. O agente ficou mais lento, mais caro, e continua errando.

Os dois problemas têm a mesma raiz: ninguém decidiu o que merece estar escrito e o que não.

O que este material faz

Ele dá o critério pra essa decisão, e a estrutura que sustenta o projeto quando ele cresce.

• O que escrever, e o que deixar de fora porque o agente descobre sozinho, com uma régua concreta pra aplicar linha por linha, em vez de bom senso.
• Como escrever pra que a regra mude comportamento em vez de virar decoração cara.
• O que fazer quando um arquivo só não dá mais conta: a organização que mantém o repositório navegável em vez de virar arqueologia a cada tarefa, e que faz o agente gastar o contexto dele no problema em vez de procurar onde as coisas estão.
• Como impedir o retrabalho antes dele acontecer, colocando a decisão de produto num lugar onde o agente a lê, em vez de deixá-la aparecer no meio do código.
• Como auditar o que você já tem: o que está sobrando, o que está faltando, e o sinal de que passou do ponto.

As regras de comportamento do modelo vêm adaptadas das observações do Andrej Karpathy sobre onde as LLMs erram ao programar, prontas pra colar, e é a parte que muda mais comportamento por linha escrita.

O que vem no pacote

Quatro arquivos em Markdown:

1. O guia: o material principal.
2. Modelo comentado: o esqueleto pra copiar e preencher, seção por seção, com o que entra em cada uma e o que só entra quando o projeto chegar lá.
3. Como organizar o projeto: o que fazer quando o arquivo estoura, e a estrutura que aguenta escala.
4. Checklist de revisão: pra passar no que você já tem.

Nada pra instalar. Nenhuma dependência. É texto.

O que ele NÃO é

Não é curso de Claude Code, não ensina a usar a ferramenta e não cobre skills, hooks nem MCP. Não é template pronto pra colar sem ler: metade do valor está em decidir o que do SEU projeto merece uma linha, e colar tudo sem apagar nada produz exatamente o arquivo caro que o guia manda evitar. Não serve em repositório novo, sem decisões tomadas: não há o que escrever. E não promete que o agente vai acertar sempre: promete que ele para de errar do mesmo jeito toda vez.

Pra quem é

Quem já usa agente pra escrever código num projeto de verdade e cansou de repetir a mesma correção. E quem chegou no ponto em que o projeto ficou grande demais pra caber numa explicação. É de graça: pega, usa, e se prestar você volta.