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ã.

O que este material faz

O CLAUDE.md é o arquivo que o Claude Code lê antes de qualquer coisa, em toda
sessão. Este guia é sobre escrever um que muda o comportamento em vez de
virar decoração que consome contexto.

O que ele cobre:

• As quatro seções que pagam por si — comandos, arquitetura, convenções e
  armadilhas — e por que documentação genérica de stack não entra em nenhuma.
• A diferença entre regra e desabafo. "Escreva código limpo" não muda nada.
  "Nunca git add -A; só a allowlist da sessão" muda.
• O teste do custo. Todo parágrafo ocupa contexto em toda sessão. O guia dá
  o critério pra decidir o que fica e o que sai.
• Onde escrever a armadilha, que é a parte de maior retorno: o bug que já
  custou caro uma vez vira uma linha que impede a segunda.
• Quando dividir em CLAUDE.md por diretório, e quando isso só espalha.

O que vem no pacote

• O guia (GUIA.md), curto e direto ao ponto.
• Um modelo comentado pra copiar e preencher, com o que vai em cada seção.
• Uma checklist de revisão: o que ler no seu CLAUDE.md atual pra saber o que
  está sobrando.

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 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. É de graça: pega, usa, e se prestar você volta.