O que colocar no CLAUDE.md para o Claude Code parar de errar as convenções do projeto

Fala aí, beleza? Se toda sessão nova você corrige a MESMA coisa (o padrão de commit que ele ignora, o comando de teste que ele chuta, a pasta que ele não devia ter tocado), o problema não é o modelo, é a instrução que sumiu junto com a conversa anterior

O CLAUDE.md existe justamente pra isso: é um arquivo markdown, escrito em texto puro por quem mantém o projeto, com instruções que o Claude lê no começo de cada sessão

Aí vem a parte que quase ninguém fala: na maioria dos casos o arquivo JÁ existe

O que está errado é o que foi escrito dentro dele

Neste post eu vou separar três coisas: que tipo de instrução realmente muda o comportamento do agente, o que só ocupa contexto à toa e como verificar se o arquivo carregou mesmo na sessão 🙂

Antes de escrever: onde o arquivo vive e quem lê

Antes de sair digitando regra, vale entender onde o arquivo mora, porque isso define o alcance dele

São duas camadas possíveis:

• No projeto: CLAUDE.md ou .claude/CLAUDE.md
• No nível do usuário: ~/.claude/CLAUDE.md

Na prática a divisão é simples: regra que vale pro repositório inteiro (e pro time) vai no projeto, preferência sua de trabalho vai no arquivo de usuário

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

Se você conhece a ideia de config global versus config local do Git, é bem semelhante: o mais específico é o que descreve aquele projeto, o global descreve você

E três comandos vão aparecer nos passos, então já te apresento:

• /init gera um CLAUDE.md de partida no repositório
• /memory lista e abre os arquivos de memória de dentro da sessão (ele lista CLAUDE.md, CLAUDE.local.md e outros locais; se você seleciona um que ainda não existe, ele é criado antes de abrir no editor)
• /context mostra quais arquivos de memória realmente carregaram na sessão atual

Guarda esse último, ele é o detector de mentira do post inteiro

Passo a passo: montar um CLAUDE.md que o agente realmente segue

1. Gere a base com /init e refine com /memory

Não comece do zero em editor nenhum

Roda o /init no repositório pra ter um esqueleto, e depois abre o arquivo pelo /memory pra ir refinando sem sair da sessão

/init
/memory

O erro comum deste passo: aceitar o que o /init gerou como se fosse a verdade final e nunca mais voltar ali

O arquivo gerado é ponto de partida, não entrega

2. Escreva os comandos do projeto, porque é o que o agente mais chuta

Build, teste e lint são o primeiro item da recomendação oficial do que colocar no arquivo, e por um motivo bem prático: quando o agente não sabe, ele inventa um comando plausível

Escreva do jeito que você roda, com o gerenciador de pacotes certo:

## Comandos
- Testes: `npm run test`
- Lint: `npm run lint`
- Build: `npm run build`
- Nunca rodar o build só pra checar tipo, usar o lint

O erro comum deste passo: escrever "rode os testes antes de finalizar" sem dizer QUAL comando

Instrução sem o comando literal é convite pro chute

3. Registre convenções e layout em linhas específicas e concisas

A documentação é direta nisso: quanto mais específicas e concisas as instruções, mais consistentemente o Claude as segue

Então nada de parágrafo filosófico sobre qualidade de código

Linha curta, fato verificável:

## Convenções
- Componentes em `components/`, um por arquivo, export nomeado
- Toda query nova passa pelo repositório em `db/`, nunca SQL solto na rota
- Mensagem de commit no imperativo, sem escopo entre parênteses

Esse bloco de layout é o que evita o agente reinventar uma pasta que já existe

Se a sua dúvida é como explicar a arquitetura do projeto pro agente sem transformar o arquivo num livro, tem um comparativo aqui no blog só sobre isso

O erro comum deste passo: descrever a árvore de diretórios INTEIRA

O agente lê código, ele não precisa de um tree colado no arquivo, precisa de onde a coisa DEVE nascer

4. Escreva as regras "sempre faça X" e o que não mexer

Essa é a parte que resolve a dor de repetir correção

O critério oficial pra decidir o que entra é ótimo: escreva o que você teria que reexplicar

Se uma pessoa nova no time precisaria daquele contexto pra produzir, entra

## Regras
- Sempre atualizar o teste junto com a mudança de comportamento
- Nunca editar arquivos em `migrations/` já aplicadas, criar uma nova
- Nunca commitar sem rodar o lint

O erro comum deste passo: escrever a regra como desabafo ("pare de mexer nas migrations!") em vez de instrução

O agente segue instrução, não indireta 😀

5. Corte o que passar de menos de 200 linhas

O teto recomendado é de menos de 200 linhas por CLAUDE.md

E o motivo não é estético: arquivo maior consome mais contexto e reduz a aderência às instruções

Ou seja, quanto mais você escreve, MENOS ele obedece

Dói, mas é assim

O erro comum deste passo: tratar o arquivo como documentação do projeto

Documentação é pro humano, o CLAUDE.md é a lista do que você cansou de repetir

Se bater a dúvida na hora da tesoura, tem um guia aqui no blog sobre o que cortar do CLAUDE.md

6. Confira com /context quais arquivos carregaram de verdade

Esse passo é o que separa "escrevi a regra" de "a regra está valendo"

/context

O /context revela os arquivos de memória carregados na sessão

Se o seu arquivo não aparece ali, não adianta discutir com o agente, ele nunca leu aquilo

O erro comum deste passo: pular ele

Metade das brigas com o agente é sobre uma instrução que ele literalmente não recebeu

O que sai do CLAUDE.md e vira outra coisa

Cortar não é apagar

A maior parte do que você tira do arquivo tem um destino melhor, e é isso que deixa o CLAUDE.md curto sem perder a regra

Procedimento de várias etapas ou regra que só importa pra uma parte do código: a recomendação é mover pra uma skill ou pra uma regra com escopo de caminho

A regra com escopo usa frontmatter YAML com o campo paths, que aceita glob:

---
paths: "src/**/*.{ts,tsx}"
---

Neste diretório, todo componente novo entra com teste ao lado

E se a regra NÃO tem o campo paths? Aí ela carrega sempre e vale pra todos os arquivos

Quando essas regras com caminho disparam? Quando o Claude lê arquivos que casam com o padrão, e não a cada uso de ferramenta

O CLAUDE.md aninhado em subpasta segue a mesma lógica: ele e as regras com frontmatter paths recarregam conforme o agente lê os arquivos aos quais se aplicam

É carga sob demanda, e é por isso que quebrar o arquivo gigante em regras por caminho funciona

Agora o aviso que salva contexto: import com @caminho não economiza nada

Dividir o arquivo em imports ajuda na organização, sim, mas não reduz o contexto, porque os arquivos importados carregam no lançamento

Se você só picotou o arquivo de 400 linhas em quatro de 100 e importou todos, você não cortou nada, só ficou com a sensação de ter cortado

E tem ainda o que nem precisa entrar

O Claude Code tem dois sistemas de memória complementares: o CLAUDE.md (o que VOCÊ escreve) e a auto memory (notas que o próprio Claude salva a partir das suas correções e preferências)

A auto memory pula qualquer coisa que os seus arquivos CLAUDE.md já digam, e também o que dá pra derivar do código (arquitetura, caminhos de arquivo, correções de bug)

Ela guarda quatro tipos de nota: user (papel, especialidade e preferências de trabalho), feedback (correções que você dá e abordagens que confirma), project (trabalho em curso, prazos e decisões que não dá pra deduzir do código ou do git) e reference (onde achar informação fora do projeto)

Vem ligada por padrão, e o toggle fica dentro do /memory, gravando autoMemoryEnabled em ~/.claude/settings.json

Quer bisbilhotar o que ele salvou sozinho? Roda /memory e seleciona a pasta de auto memory

Dá também pra apontar um diretório próprio pela configuração autoMemoryDirectory

O agente continua errando mesmo com o CLAUDE.md escrito

São três cenários que aparecem sempre, e eu vou passar por cada um com a causa provável, a solução e como prevenir:

• a regra está escrita no arquivo e ele ignora
• o arquivo nem chegou a carregar na sessão
• a regra com paths não pega no seu ambiente

Bora um por um

Sintoma 1: a regra está lá, e ele ignora

Causa provável: arquivo longo demais e instrução vaga demais

Lembra que arquivo maior consome mais contexto e reduz a aderência, e que instrução específica e concisa é seguida com mais consistência? Os dois efeitos batem juntos aqui

Solução: encurtar e especificar

Troca "mantenha o padrão do projeto" por "todo componente novo em components/, export nomeado"

Como prevenir: uma linha por regra, e o detalhe grande vai pra skill ou pra regra com paths

Sintoma 2: o arquivo nem carregou

Causa provável: você está corrigindo um arquivo que a sessão nunca leu

Solução: /context primeiro, discussão depois

Se o arquivo não aparece na lista, cheque o claudeMdExcludes, que permite excluir arquivos CLAUDE.md do carregamento

Tome cuidado com um detalhe: ele pode ser configurado em qualquer camada de settings (usuário, projeto, local ou managed policy) e os arrays fazem merge entre as camadas

Ou seja, a exclusão pode estar vindo de uma camada que você nem abriu hoje

A exceção: CLAUDE.md de managed policy não pode ser excluído

Como prevenir: rodar /context logo depois de mexer em qualquer arquivo de memória

Sintoma 3: a regra com paths não pega no seu ambiente

Causa provável: o caminho até o arquivo passa por um symlink pro diretório do projeto

A correspondência de paths passou a funcionar também quando o Claude chega ao arquivo por um caminho com symlink a partir da versão 2.1.198

Solução: conferir a versão antes de reescrever o glob dez vezes achando que o padrão está errado

Como prevenir: quando uma regra com paths não dispara, primeiro pergunta por qual caminho o agente chegou naquele arquivo

O que aprendi comparando agentes com o mesmo arquivo de instruções

Esse post nasceu de um teste que eu fiz com outro agente de terminal, um bem minimalista, no vídeo abaixo

E foi ali que a ficha caiu sobre o que o arquivo de instruções realmente faz

Antes de pedir UMA linha de código, eu escrevi o arquivo de instruções do projeto

Coloquei a stack escolhida, as convenções e o fluxo esperado da aplicação

Na parte da stack eu fui específico de propósito, listando exatamente as decisões que eu não queria ver quebradas: o framework, a biblioteca de gráficos, qual API pública seria consumida e por qual provedor de IA a análise passaria

E descrevi o fluxo do produto na ordem (a pessoa digita um nome de usuário, o sistema busca no GitHub, analisa e renderiza o resultado), pra ele entender a sequência das coisas antes de sair criando arquivo

Aí veio o pulo do gato: o primeiro prompt PROIBIA código

Eu pedi que ele lesse o arquivo de convenções, seguisse elas e apenas confirmasse, sem gerar nada ainda

E cobrei uma confirmação em uma frase do que ele tinha entendido do projeto

Essa frase é a checagem: se o resumo vem genérico, ele não leu

Duas coisas quebraram no caminho, e são as mesmas que quebram no Claude Code:

Primeiro, eu errei o nome do arquivo na primeira tentativa

Criei o certo em seguida e ficou claro que o agente só segue o arquivo que ele REALMENTE lê, não o que você acha que escreveu (por isso o /context está no passo a passo)

Segundo, arquivo importante criado com a sessão já aberta não entra sozinho no contexto

Tive que recarregar o contexto pra ele contemplar o arquivo novo, e fechar e abrir a sessão teria o mesmo efeito

Depois da base pronta eu pedi uma funcionalidade isolada e mandei ele PARAR antes de integrar

Criei uma página de teste descartável que só chamava a função e imprimia o retorno cru na tela

O servidor de desenvolvimento subiu na porta 3005, porque as anteriores estavam ocupadas, abri e… retorno vazio, mesmo com usuário existente 😛

Colei o resultado de volta pro agente, pedi a correção e resolveu

Se eu tivesse confiado que estava funcionando, ia descobrir o erro lá na frente, com a aplicação inteira já dependendo daquela parte quebrada

Uma coisa que eu gostei bastante no teste: ver todo o processo no terminal, sem etapa escondida e sem instrução injetada que eu não pedi

No vídeo você vê o arquivo de instruções sendo escrito antes do primeiro prompt, a confirmação de leitura sendo cobrada e o teste isolado voltando vazio

E a moral que vale igual pro CLAUDE.md: o valor do arquivo não é volume de texto

É a instrução que você cansaria de repetir, escrita uma vez, no lugar que o agente lê antes de começar

Próximo passo: uma linha por correção que você repetiu esta semana

Fecha o post e faz isso agora, leva uns dez minutos

Roda /memory, abre o CLAUDE.md do projeto e anota em UMA linha cada correção que você repetiu essa semana

Uma entrada por linha, sem parágrafo, sem justificativa

O detalhe grande vai pra arquivo de tópico, ou vira skill, ou vira regra com paths

Entrada velha que não descreve mais o projeto você funde com outra ou descarta, porque arquivo mais curto gera melhor aderência

E lembra que você não está sozinho nessa: o CLAUDE.md e a auto memory são sistemas complementares, e os dois carregam no início de cada conversa

Você escreve o que quer garantir, ele anota o que você corrige

Bora testar? Faz o exercício da semana, roda /context na próxima sessão e vê se a briga diminuiu

até o próximo post!