Como escrever um CLAUDE.md que realmente melhora as respostas do Claude Code

Fala aí, beleza? O CLAUDE.md é o arquivo que VOCÊ escreve pro Claude Code ler no início de toda sessão, antes de ele encostar em qualquer linha do seu código

E é exatamente por isso que ele decide, na prática, a qualidade das respostas que você recebe 🙂

Ele é um arquivo markdown carregado no início de cada sessão, com o contexto persistente que o Claude não tem como inferir só lendo o repositório: qual comando roda os testes, por que a pasta X existe, aquele detalhe do ambiente que te ferrou uma vez

Só que tem um preço: esse arquivo entra no contexto e consome tokens

Ou seja, toda linha que não muda o comportamento do agente está pagando aluguel na sua janela de contexto, e a documentação oficial do Claude Code é bem direta nisso: arquivo inchado faz o Claude ignorar as instruções que realmente importam

Bora escrever um que funciona?

O que você precisa antes de começar:

Pouca coisa, e nada de PC da Nasa aqui

Você precisa do Claude Code instalado e aberto na raiz do projeto, porque é a partir do diretório de trabalho que ele monta a memória da sessão

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

E três comandos sustentam todo o resto deste tutorial:

• /init gera um CLAUDE.md inicial a partir da estrutura atual do projeto, pra depois ser refinado
• /memory lista e abre os arquivos de memória (incluindo CLAUDE.md e CLAUDE.local.md) nos escopos de usuário e de projeto, e se você selecionar um arquivo que ainda não existe, ele cria
• /context mostra em tempo real o que está ocupando a janela de contexto, incluindo quais arquivos CLAUDE.md e de auto memory foram carregados na sessão

Esse último é o mais subestimado dos três

É ele que transforma "acho que o Claude leu meu arquivo" em "o Claude leu, e ocupa tanto assim"

Como escrever um CLAUDE.md passo a passo

1. Rode /init e trate o resultado como rascunho. O comando lê a estrutura atual do projeto e te entrega um esqueleto pra refinar, não um arquivo final. O erro comum deste passo: aceitar a saída como está e sair usando, aí o arquivo vira uma descrição do repositório em vez de instrução de comportamento

2. Aplique o critério de conteúdo: escreva o que você teria que reexplicar. A régua oficial é pensar no que um colega novo de time precisaria saber pra produzir: comandos de build, convenções, layout do projeto, regras do tipo "sempre faça X". Se você repetiria isso em toda sessão, é linha de CLAUDE.md. Vale a pena olhar com calma o que colocar e o que cortar antes de encher o arquivo. O erro comum deste passo: escrever pro Claude aquilo que ele descobre sozinho lendo dois arquivos

3. Escreva instrução verificável, não instrução simpática. "Formate o código corretamente" não dá pra checar, e por isso não muda nada. "Use indentação de 2 espaços" dá. O erro comum deste passo: linha genérica que soa bonita na leitura e não tem como ser cumprida nem cobrada

4. Corte a lista do que não deve entrar. A orientação oficial manda tirar qualquer coisa que o Claude descobre lendo o código, convenções padrão da linguagem, documentação detalhada de API, informação que muda com frequência e explicação longa. O erro comum deste passo: colar doc de API dentro do arquivo achando que está ajudando, quando está só empurrando o resto pra fora do foco

5. Segure o arquivo abaixo de 200 linhas. Esse é o alvo recomendado por arquivo CLAUDE.md, e o motivo é bem prático: arquivo maior consome mais contexto e reduz a aderência às instruções. O erro comum deste passo: crescer o arquivo por acumulação, uma linha por frustração, e nunca revisitar

6. Confira com /context o que entrou de verdade na sessão. Ele mostra quais arquivos de memória foram carregados e o que está ocupando a janela. O erro comum deste passo: supor a carga em vez de olhar. Sem checar, você fica ajustando instrução que talvez nem esteja no contexto

Exemplos de instruções que mudam o comportamento na prática

Os blocos abaixo são ilustrativos de FORMATO

A ideia é você sentir a diferença entre a linha vaga e a linha que muda a resposta, e depois trocar o conteúdo pelo do seu projeto

1. Comando que ele não tem como adivinhar

# vago
Rode os testes antes de finalizar

# muda o comportamento
Testes: `npm run test:unit <arquivo>` durante o trabalho
Suite completa só antes de commitar: `npm run test`

2. Estilo que foge do padrão

# vago
Mantenha o código bem formatado

# muda o comportamento
Use indentação de 2 espaços
Aspas simples em TypeScript, sem ponto e vírgula no fim da linha

3. Etiqueta do repositório

# vago
Siga o padrão de commits do projeto

# muda o comportamento
Nunca commite direto na branch principal: crie branch antes
Mensagem de commit no imperativo, em português

4. Decisão de arquitetura

# vago
O projeto tem uma boa separação de camadas

# muda o comportamento
Acesso a banco mora só na camada de dados
Rota nunca monta query: chama função da camada de dados

5. Peculiaridade do ambiente

# vago
O ambiente local é um pouco diferente

# muda o comportamento
O Postgres local roda na porta 5434 (5432 está ocupada)
Subir tudo com `npm run dev:all` no começo da sessão

6. Pegadinha (a gotcha que já te mordeu)

# vago
Cuidado com os arquivos de configuração

# muda o comportamento
Migration já aplicada nunca é editada: crie uma nova

Esse tipo de linha é ouro, porque é o conhecimento que não está escrito em lugar nenhum do código

É o "já me ferrei uma vez por causa disso" virando regra

7. Instrução de compactação escrita no próprio CLAUDE.md

Dá pra customizar o comportamento de compactação por ali também, dizendo o que não pode se perder quando a conversa é compactada:

Ao compactar, preserve a lista completa de arquivos modificados
e os comandos de teste usados até aqui

Sacou o padrão? Toda linha boa responde "o que muda na próxima resposta do agente por causa disso"

Onde cada instrução deve morar: arquivo do projeto, rules ou skill

Agora a parte que quase ninguém organiza direito

O Claude Code lê os CLAUDE.md do diretório de trabalho pra cima até a raiz, e descobre os arquivos de subpastas conforme acessa arquivos daqueles diretórios

Então os pais carregam na abertura da sessão, e as subpastas carregam sob demanda

Na ordem de leitura, o arquivo do diretório mais acima aparece antes no contexto, e dentro de cada diretório o CLAUDE.local.md é acrescentado depois do CLAUDE.md:

foo/CLAUDE.md          <- entra antes
foo/CLAUDE.local.md
foo/bar/CLAUDE.md      <- entra depois

Isso importa quando duas instruções conversam entre si, beleza?

E o que é seu, não do time?

Instrução de escopo pessoal fica na memória de usuário: ~/.claude/CLAUDE.md e ~/.claude/rules/

Assim sua mania não vira regra do repositório inteiro

Projeto grande pede quebra por tópico

Em vez de um arquivão, dá pra criar arquivos markdown dentro de .claude/rules/ no projeto, com descoberta recursiva dos .md e um tópico por arquivo

E tem o pulo do gato: regra pode ser limitada a arquivos específicos pelo campo paths no frontmatter YAML, e só entra no contexto quando o Claude trabalha com arquivos que casam com o padrão

---
paths:
  - "apps/web/**/*.tsx"
---

Componente novo sempre em Server Component por padrão

Regra que não casou com o glob simplesmente não é carregada

É contexto que você não paga 😀

Quando a instrução NÃO é caso de CLAUDE.md

Se a entrada é um procedimento de vários passos, ou só importa pra uma parte do código, a orientação é mover: procedimento longo vira skill, regra localizada vira path-scoped rule

O mesmo raciocínio vale pra tarefa grande, onde o combinado detalhado não mora na memória do projeto e sim em uma spec antes de implementar

O erro comum aqui: achar que import com @caminho economiza contexto

Não economiza

Ele organiza o arquivo, mas os arquivos importados carregam junto na abertura da sessão do mesmo jeito

CLAUDE.md e auto memory: dois mecanismos diferentes

Esse ponto confunde muita gente, então vamos separar

Além do CLAUDE.md que VOCÊ escreve, o Claude Code tem a auto memory, em que o próprio Claude salva notas a partir das suas correções e preferências

Ela vem ligada por padrão, e o toggle grava autoMemoryEnabled em ~/.claude/settings.json (o toggle também aparece no /memory)

Do MEMORY.md, carregam no início de cada conversa as primeiras 200 linhas ou os primeiros 25KB, o que vier primeiro

O que passa disso não entra na abertura da sessão

E qual o caso de uso prático dessa distinção?

Não duplicar

Se uma preferência sua já foi capturada pela auto memory a partir de uma correção que você fez, repetir a mesma coisa no CLAUDE.md só gasta contexto duas vezes

O CLAUDE.md é o contrato do projeto

A auto memory é o caderninho do que você já corrigiu

Como podar o arquivo e manter ele afiado

CLAUDE.md não é documento que se escreve uma vez e esquece, ele é mantido

E manter, aqui, quer dizer cortar 🙂

1. Passe o olho procurando linha redundante. Se o Claude já faz aquilo certo sem a instrução, a orientação é apagar a linha, sem dó

2. Converta em hook a regra que precisa de garantia. Quando não pode falhar de jeito nenhum, instrução em texto é o lugar errado: vira hook

3. Cheque o tamanho de novo. O alvo continua sendo menos de 200 linhas por arquivo CLAUDE.md, e quem cresceu passa por revisão ou vira arquivo por tópico em .claude/rules/

4. Use /context como termômetro. Ele mostra quanto os arquivos de memória estão custando na janela, então dá pra medir o efeito da poda em vez de confiar no feeling

O erro comum dessa rotina: só adicionar

Cada vez que o agente erra, a tentação é escrever mais uma linha, e em três semanas o arquivo está com o dobro do tamanho e metade da eficácia…

Conclusão

A régua do CLAUDE.md cabe em uma frase: escreva só o que precisaria ser reexplicado toda sessão, em instrução curta e verificável

O resto é peso morto no contexto

Seu próximo passo é bem concreto: roda /init hoje pra ter o esqueleto, poda até caber abaixo de 200 linhas, confere com /context o que entrou de verdade e move procedimento de vários passos pra uma skill

Depois disso, o arquivo deixa de ser um README disfarçado e passa a mudar a resposta do agente na prática

até o próximo post! 😀