CLAUDE.md muito grande: por que ele pesa no contexto de toda sessão (e o que tirar de lá)

Fala aí, beleza? Aquele teu CLAUDE.md que começou com cinco linhas hoje tem seção, subseção, histórico de decisão e um parágrafo explicando por que vocês escolheram aquele ORM em 2024

E ele parece de graça, né? É só um markdown na raiz do projeto, não aparece na conversa, não pede permissão, não faz barulho

Só que ele não é de graça

O CLAUDE.md é um arquivo de instruções persistentes que o Claude lê no INÍCIO de toda sessão, segundo a documentação oficial de memory. Ou seja: cada linha que tu escreve ali compete por espaço com o trabalho de verdade, em toda sessão, pra sempre

Bora ver como esse carregamento funciona de fato, como medir o peso real e qual critério usar pra decidir o que fica e o que sai…

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

O que já está carregado antes da sua primeira mensagem

Antes de você digitar qualquer coisa, quatro coisas já entraram no contexto: o CLAUDE.md, a auto memory, os nomes das ferramentas MCP e as descrições das skills

Essa é a parte que pega a maioria: a conta começa antes do "oi"

De onde vêm os arquivos:

O Claude Code carrega no lançamento todo CLAUDE.md do diretório de trabalho E de cada diretório pai

Se liga nisso, porque é onde mora a surpresa: você abre o Claude numa subpasta de um monorepo e herda arquivo de instrução que talvez nem seja seu

Os locais possíveis, por escopo:

• Projeto: ./CLAUDE.md ou ./.claude/CLAUDE.md
• Usuário: ~/.claude/CLAUDE.md
• Organização: managed policy

O que NÃO carrega no lançamento:

Nem tudo entra de cara, e essa distinção é o coração do post

E tem um limite explícito na auto memory que vale conhecer: carregam as primeiras 200 linhas do MEMORY.md ou os primeiros 25KB, o que vier primeiro

O que passa disso simplesmente não carrega

Repara que o limite é do MEMORY.md, não dos arquivos de tópico separados: esses ficam quietos até alguém pedir 🙂

Como medir o peso real do seu CLAUDE.md

Achismo aqui não ajuda, então bora pro que dá pra verificar na sua máquina agora

1. Rode /context pra ver o consumo por categoria

/context

Ele mostra a quebra do contexto: system prompt, ferramentas do sistema, ferramentas MCP, subagents, memory files, skills e mensagens da conversa. E mostra QUAIS arquivos CLAUDE.md e de auto memory foram carregados

O erro comum deste passo: olhar só o tamanho do arquivo principal e esquecer dos herdados dos diretórios pais. O /context te dá a lista real do que entrou, não a sua lembrança do que você escreveu

2. Rode /memory pra ver os arquivos de memória da sessão

/memory

Ele lista CLAUDE.md, CLAUDE.local.md e arquivos de rules carregados, permite abrir esses arquivos, ligar ou desligar a auto memory e abrir a pasta da auto memory

No Claude Code os arquivos de auto memory ficam em ~/.claude/projects/<project>/memory/, e ela vem ligada por padrão. O toggle dentro do /memory grava autoMemoryEnabled no ~/.claude/settings.json, e a variável de ambiente CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 desliga

O erro comum deste passo: achar que desligar a auto memory resolve o inchaço do CLAUDE.md. São coisas diferentes, com limites diferentes

3. Confira os imports antes de comemorar

Se o seu CLAUDE.md usa imports @caminho, o arquivo principal ficou lindo e enxuto na tela

Só que os arquivos importados também carregam e entram na janela de contexto no lançamento

O erro comum deste passo: contar linhas do arquivo principal e dar o caso por encerrado. Some tudo, ou melhor: confie no /context

Três sintomas de CLAUDE.md inchado (e o que fazer)

Sintoma 1: o Claude ignora justamente a instrução que importa

Você escreveu a regra. Está lá, em negrito, com CAIXA ALTA e tudo. E ele passa por cima

Causa: arquivo inchado dilui as regras. A doc de boas práticas é direta ao dizer que arquivos inchados fazem o Claude ignorar as instruções que importam

Solução: corte linha a linha pelo critério oficial. Para cada linha, pergunte: "remover isso faria o Claude errar?"

Se a resposta é não, corta. Sem dó

Se você quer um roteiro mais longo pra essa faxina, tem um guia sobre o que cortar do CLAUDE.md aqui no blog

Sintoma 2: quebrei o arquivo em imports e nada mudou

Esse é o mais frustrante, porque parece que você fez a lição de casa

Causa: imports @caminho organizam, mas NÃO reduzem contexto. Os arquivos importados carregam no lançamento do mesmo jeito

É tipo arrumar a bagunça em gavetas: a casa fica bonita, o peso do caminhão de mudança é o mesmo 😀

Solução: mover o que dá pra rules escopadas por caminho, que é exatamente a recomendação oficial pra quando as instruções crescem muito

Sintoma 3: editei o CLAUDE.md no meio da sessão e ele continua no comportamento antigo

Você corrigiu a regra, salvou, mandou a próxima mensagem e o Claude segue igualzinho

Causa: CLAUDE.md de projeto e de usuário são lidos uma vez no início da sessão e mantidos. A edição no meio do caminho não invalida o cache nem passa a valer na hora

Solução: o conteúdo novo entra no próximo /clear, /compact ou reinício

Prevenção: tratar o arquivo como configuração de boot, não como bloco de notas do dia. Se é coisa pra AGORA, fala na conversa mesmo

Para onde vai o que sai do CLAUDE.md

Cortar não é jogar fora, é mudar de endereço. Cada tipo de instrução tem um destino melhor

Regra que só vale pra certos arquivos: rules escopadas por caminho

Regras modulares ficam em .claude/rules/ e podem ser escopadas por caminho

A regra com frontmatter YAML paths: (globs) carrega só quando um arquivo correspondente entra no contexto:

---
paths:
  - "src/**/*.tsx"
---

Aqui vai a instrução que só vale pros componentes

Tome cuidado com um detalhe: regra SEM paths: carrega no início da sessão, igual ao CLAUDE.md. Ou seja, criar .claude/rules/ e não escopar nada não economiza nada

Procedimento longo que você usa de vez em quando: skill

Skills usam divulgação progressiva: no início da sessão só nome e descrição de cada skill instalada entram no contexto

O conteúdo completo só carrega quando a skill é usada e, uma vez carregado, permanece no contexto nos turnos seguintes

Dá até pra tirar a descrição da jogada, marcando a skill como invocação manual apenas:

disable-model-invocation: true

A dúvida de onde colocar cada coisa aparece direto, e ela tem resposta caso a caso: já falamos sobre regra de design em skill ou CLAUDE.md por aqui

Conhecimento acumulado: arquivos de tópico da auto memory

Aquele histórico de "por que fizemos assim" é conhecimento, não instrução de boot

O limite de 200 linhas ou 25KB vale só pro MEMORY.md. Arquivos de tópico separados são lidos sob demanda pelas ferramentas normais de arquivo, então eles não pesam no startup

Arquivo herdado que não é seu: claudeMdExcludes

E quando o CLAUDE.md que te atrapalha veio de um diretório pai que você não controla?

A configuração claudeMdExcludes impede que CLAUDE.md específicos carreguem:

{
  "claudeMdExcludes": ["**/legacy/CLAUDE.md"]
}

Ela aceita caminhos ou globs casados contra caminhos absolutos, e padrões relativos começam com **/

Pode ser definida nos escopos user, project, local ou managed, e os arrays se SOMAM entre escopos

Uma ressalva importante: CLAUDE.md de managed policy não pode ser excluído

A nova régua: o que merece ficar no CLAUDE.md

O critério de decisão cabe numa pergunta, e é a pergunta oficial: para cada linha, "remover isso faria o Claude errar?"

Se não faria, corta

Como teto de referência, a recomendação de boas práticas é menos de 200 linhas por arquivo CLAUDE.md. Arquivos maiores consomem mais contexto e reduzem a aderência às instruções

E não confunde os dois duzentos: esse aqui é recomendação de TAMANHO do arquivo CLAUDE.md, enquanto o outro lá de cima é o limite de carga do MEMORY.md. Coincidência de número mesmo

O custo principal não é dinheiro:

Aqui vale desarmar uma ideia que circula por aí, a de que cada linha do arquivo sai a preço cheio em toda mensagem

O prompt caching muda essa conta: a escrita no cache custa 1,25x o preço base de input e a LEITURA do cache custa 0,1x o preço base de input

O Claude Code reaproveita a camada do system prompt e recarrega o contexto do projeto do disco, com acerto de cache condicionado a uma coisa: CLAUDE.md e memória não terem mudado desde o início da sessão

Então o preço em dinheiro não é o vilão

O vilão é ATENÇÃO e espaço de contexto: instrução demais compete com o código que você quer que ele leia, e ainda faz ele ignorar o que importa

Dois detalhes que mexem na rotina:

O CLAUDE.md da raiz do projeto sobrevive à compactação: depois do /compact, o Claude relê o arquivo do disco e reinjeta na sessão

Massa, né? Isso significa que a regra da raiz não some no meio de uma sessão longa

O outro detalhe: o CLAUDE.local.md é ignorado quando local fica de fora das fontes de configuração

Já me ferrei com esse tipo de coisa: a instrução existe, o arquivo está lá, e ela simplesmente não está valendo

Comece pelo diagnóstico, não pela faxina

A virada de chave é parar de tratar o CLAUDE.md como documentação do projeto

Ele não é o README

Ele é o briefing que abre TODA sessão, lido antes da sua primeira mensagem, disputando espaço com o trabalho de verdade

O próximo passo é concreto e leva poucos minutos:

1. Rode /context e /memory pra ver o que está carregado hoje, incluindo os arquivos herdados dos diretórios pais
2. Passe a pergunta do corte em cada linha: "remover isso faria o Claude errar?"
3. Mova o que sobrar pro endereço certo: rules escopadas por caminho, skills ou arquivos de tópico consultados sob demanda

Faça o teste e compara o /context antes e depois, é o tipo de coisa que só convence quando tu vê no teu próprio projeto 😀

até o próximo post!