Como escrever um bom CLAUDE.md pro seu projeto (o que colocar e o que cortar)

Fala aí, beleza? Tu escreve a convenção, avisa no chat, repete na terceira mensagem, e na sessão seguinte a IA volta a fazer do jeito errado 😅

É pra isso que existe o CLAUDE.md: um arquivo markdown que o Claude Code carrega no início de cada sessão, com instruções persistentes de projeto, de fluxo pessoal ou da organização

E aqui vai a parte que quase ninguém fala: a maioria dos arquivos ruins não peca por falta, peca por EXCESSO

Arquivo inchado faz o Claude ignorar justamente as instruções que importam, e isso está na documentação oficial, não é achismo de internet

Bora montar um que funciona?

Antes de começar: onde o arquivo mora e o que já existe

Antes de sair escrevendo, vale saber em qual gaveta tu vai mexer

O arquivo de projeto fica na raiz do repositório ou dentro de .claude/, e o de escopo global fica em ~/.claude/

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

Tá no Windows? O ~/.claude resolve pra %USERPROFILE%\.claude

Se liga nisso: se a tua empresa implanta um CLAUDE.md de política gerenciada (managed policy), ele não pode ser excluído, as instruções da organização sempre valem

Ou seja, se tem regra corporativa em vigor, não adianta brigar com ela no arquivo do teu projeto, tu só vai perder tempo

Como escrever seu CLAUDE.md passo a passo

O caminho é curto, o difícil é a disciplina de cortar

1. Rode /init pra gerar o arquivo inicial

Ele analisa a base de código pra detectar sistemas de build, frameworks de teste e padrões de código, e escreve o CLAUDE.md com comandos e convenções

/init

Existe também um fluxo interativo opcional, que passa por skills, hooks e arquivos de memória pessoal, ativado por variável de ambiente:

CLAUDE_CODE_NEW_INIT=1

O erro comum deste passo: aceitar o que saiu do /init como versão final

O gerado é rascunho, não é entrega

2. Corte linha a linha com a régua oficial

A pergunta pra cada linha é uma só: remover isso faria o Claude errar?

Se a resposta é não, corta, sem dó

A recomendação oficial é manter cada arquivo abaixo de 200 linhas

O erro comum deste passo: transformar o CLAUDE.md em documentação do projeto

Documentação é pro humano, o CLAUDE.md é instrução operacional

3. Escreva instruções específicas e concisas

Quanto mais específica e concisa a instrução, mais consistentemente ela é seguida

E só entra o que se aplica de forma ampla, regra que vale em um canto só do repo tem outro lugar (já já eu falo dele)

O erro comum deste passo: instrução vaga do tipo "escreva código limpo", que não muda absolutamente nada no resultado

4. Refine com /memory

O /memory edita os arquivos de memória CLAUDE.md, liga ou desliga a memória automática e mostra as entradas dela

/memory

Ele também lista os locais dos arquivos de memória (CLAUDE.md, CLAUDE.local.md e outros) nos escopos de usuário e de projeto, inclusive os que ainda nem existem

O erro comum deste passo: editar o arquivo errado e jurar que a regra não funciona

Abre o /memory e confere o caminho antes de reclamar 😀

5. Confira o que carregou de verdade com /context

/context

Olha a lista em Memory files

O que não aparece ali simplesmente não está valendo naquela sessão, por mais bonito que esteja escrito no teu arquivo

O que colocar (e o que cortar) no CLAUDE.md

Essa é a parte que separa arquivo útil de arquivo enfeite

A régua mental é simples: entra o contexto que o Claude NÃO consegue inferir lendo o código

Entra no arquivo:

• comandos bash do projeto
• estilo de código
• regras de fluxo de trabalho
• etiqueta do repositório (nomeação de branch, merge x rebase)
• setup do ambiente de desenvolvimento
• comportamentos inesperados e avisos específicos do projeto

Aquele detalhe que só quem apanhou sabe? Esse é ouro puro no CLAUDE.md

É o tipo de coisa que a IA nunca vai adivinhar lendo os arquivos, porque não está escrita em lugar nenhum

Se o teu projeto sobe num servidor próprio, o comando de subir o ambiente entra aqui do mesmo jeito (a escolha do VPS pro projeto é outra conversa, e não pertence a este arquivo)

Sai do arquivo:

• conhecimento de domínio que só serve às vezes
• fluxo que tu roda uma vez por mês
• passo a passo específico de uma tarefa pontual

Tudo isso deve virar skill, não linha de CLAUDE.md

O porquê é bem direto: skills carregam sob demanda, sem inchar toda conversa

Já o CLAUDE.md entra inteiro, toda vez, em toda sessão

É como bagagem de mão: cada item que tu joga lá dentro tu carrega em TODA viagem, mesmo naquela que dura duas horas

Projeto grande: dividir em dois níveis e importar sem inchar

Em base grande, um arquivo só não dá conta e vira aquela colcha de retalhos

1. Monte o CLAUDE.md raiz com o que vale em todo lugar

Padrões de código, convenção de commit, layout do repositório

2. Crie um CLAUDE.md por subdiretório com as convenções daquela área

As regras do pacote de front ficam no pacote de front, e ponto

3. Entenda quando cada um carrega

No lançamento, o Claude Code carrega todo CLAUDE.md do diretório de trabalho e de cada diretório pai

Já o arquivo de cada subdiretório abaixo do diretório de trabalho carrega sob demanda: o Claude Code descobre esses arquivos sozinho e inclui quando lê arquivos daquela pasta, sem tu habilitar nada

Isso é exatamente o que faz a divisão em dois níveis valer a pena: o contexto da área só entra quando a área é tocada

4. Use import quando fizer sentido

Um CLAUDE.md pode importar outros arquivos com a sintaxe de arroba mais caminho:

@docs/convencoes-de-commit.md
@/caminho/absoluto/regras.md

Caminho relativo e absoluto são aceitos

Detalhe importante: o relativo resolve a partir do arquivo que contém a importação, não do teu diretório de trabalho

E a leitura de imports ignora trechos dentro de código inline e blocos de código cercados, então exemplo em bloco de código não vira import por acidente

Arquivos importados podem importar outros de forma recursiva, com profundidade máxima de quatro saltos

5. Não caia na armadilha do import mágico

Aqui vai o alerta duro: o conteúdo importado é expandido e carregado em contexto no lançamento, junto do CLAUDE.md que o referencia

Traduzindo: importar NÃO economiza contexto

Quebrar 600 linhas em seis arquivos de 100 e importar todos te dá as mesmas 600 linhas, só que espalhadas e mais difíceis de auditar

Quer economizar de verdade? Corta, ou manda pra skill

6. Não confunda import com o @ do prompt

O arroba mais caminho digitado no prompt é outra coisa: serve pra puxar um arquivo direto pro contexto naquela mensagem

São recursos distintos, um mora no arquivo e o outro é digitado por tu na hora

E já que falamos de comando: comando de barra só é reconhecido no começo da mensagem, não adianta jogar no meio do texto

7. Diretório adicional é outra história (não confunda com subdiretório)

Se liga na diferença, porque ela confunde muita gente

No item 3 o assunto é subdiretório abaixo do teu diretório de trabalho: esse o Claude Code descobre e inclui sozinho, sob demanda, quando lê arquivos daquela pasta

Diretório adicional é outra categoria, e a regra dele é o contrário: por padrão, arquivos CLAUDE.md de diretórios adicionais não são carregados

Existe variável de ambiente pra habilitar esse carregamento:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD

Resumindo: subdiretório da árvore do projeto entra sozinho, diretório adicional só entra se tu habilitar

O Claude está ignorando uma regra que está escrita: o que fazer

Cena clássica: tu tem a regra escrita, apontando bem clarinho pro comportamento certo, e ele faz do outro jeito assim mesmo

Sintoma: existe regra contra aquilo no arquivo e ele insiste

Causa provável (e essa é a leitura oficial): o arquivo está longo demais e a regra se perdeu no meio

Solução, na ordem:

1. aplique o corte pra ficar abaixo de 200 linhas, usando o critério "remover isso faria o Claude errar?"
2. mova o que só serve de vez em quando pra uma skill
3. rode /context e confira na seção Memory files quais arquivos de memória carregaram mesmo

Prevenção: revisa o arquivo toda vez que ele engordar, mantém uma regra por linha e escreve específico

Regra genérica no meio de arquivo gordo é a receita pronta pra ser ignorada

E se a regra da organização venceu a minha?

Acontece, e nem sempre é bug

Configurações gerenciadas pela organização têm precedência sobre tudo

Flags de CLI como --permission-mode ou --settings sobrescrevem o settings.json na sessão, e algumas variáveis de ambiente têm precedência sobre a configuração equivalente

Então a ordem que tu precisa ter na cabeça é: gerenciado pela organização, depois flags de CLI, depois settings.json

Se a política gerenciada diz uma coisa, é ela que vale, sem exclusão possível

Memória automática: o que ela grava e quando desligar

Muita gente confunde as duas coisas, então bora separar

A memória automática vem ligada por padrão e é o Claude anotando sozinho, entre sessões, o que ELE decide que vale guardar

Comandos de build, achados de depuração, notas de arquitetura, preferências de estilo, hábitos de fluxo, por aí vai

Ou seja: o CLAUDE.md é o que TU escreve, a memória automática é o que ele escreve

Os arquivos ficam em ~/.claude/projects/<projeto>/memory/ e dá pra navegar por eles pelo /memory

É markdown puro, então tu pode ler, editar ou apagar na boa, sem mistério nenhum

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

Quer desligar? O próprio /memory alterna, e a preferência fica gravada na chave autoMemoryEnabled do ~/.claude/settings.json

Minha sugestão: antes de desligar, abre a pasta e lê o que ele andou anotando

Às vezes o problema não é a memória automática, é o teu CLAUDE.md que virou romance 😛

Conclusão

O bom CLAUDE.md é o MENOR arquivo que ainda impede o erro

Não é o mais completo, não é o mais organizado, não é o que documenta o projeto inteiro

É o que sobrevive à leitura e continua sendo seguido na quinquagésima sessão

Próximo passo, e dá pra fazer agora em cinco minutos: abre o teu arquivo atual, roda /context pra ver o que realmente carrega e passa a régua linha a linha

Tudo que passa no teste "remover isso não causaria erro" sai fora

O resto tu mantém curto, específico e no escopo certo

Quem quiser conferir a fonte de tudo isso, a documentação de memória do Claude Code tem os detalhes de escopo, imports e memória automática

Bora limpar esse arquivo? Até o próximo post! =)