Claude Code ignora o CLAUDE.md? Por que acontece e como fazer ele seguir as regras

Fala aí, beleza? Você escreve a regra no CLAUDE.md, o Claude responde que entendeu perfeitamente, e três mensagens depois ele faz exatamente o contrário

A sensação é de estar conversando com alguém que balança a cabeça e não escuta nada, haha

A boa notícia: isso é comum e tem causas técnicas identificáveis. Carregamento (a regra nunca entrou na sessão), compactação (ela entrou e saiu no meio do caminho), tamanho (o arquivo virou ruído) e conflito entre níveis de memória

E tem ainda um quinto caso, que não é do arquivo: a regra chega certinha na sessão e o modelo acaba seguindo outro sinal concorrente. Isso também tem registro público no repositório oficial, e eu falo dele lá no fim

Bora destrinchar cada uma e, principalmente, como escrever a regra num formato que ele respeita

Antes de culpar o modelo: como conferir se a regra está sendo lida

Sintoma: você não faz ideia se o problema é o modelo ignorar a instrução ou se ela simplesmente nunca chegou até ele

Causa: nem tudo que está no disco está no contexto da sessão. São coisas diferentes, e essa confusão faz muita gente reescrever o CLAUDE.md inteiro pra resolver um problema que era de carregamento

Solução: antes de mexer em qualquer linha, rode dois comandos dentro da sessão

/context
/memory

O /context mostra o que está preenchendo a janela de contexto naquele momento

O /memory abre os arquivos de memória pra você navegar e editar sem sair da sessão. Dá também pra simplesmente pedir ao Claude que adicione a instrução ao CLAUDE.md

E guarde isso: o Claude Code lê os arquivos CLAUDE.md no início de toda sessão, como instruções persistentes de projeto, pessoais ou da organização. Se a sua regra mora no CLAUDE.md da raiz, ela entrou. Se mora em outro lugar, aí a conversa muda (é a próxima seção)

Como prevenir: faça essa checagem ANTES de sair reescrevendo o arquivo. Diagnóstico primeiro, cirurgia depois 😀

Causa 1: a regra existe, mas nunca foi carregada naquela sessão

Sintoma: a regra está escrita, você abre o arquivo e lê ela com seus próprios olhos, e mesmo assim ela não vale nada na prática

Causa: nem todo arquivo de memória entra na abertura da sessão

Um CLAUDE.md aninhado em subpasta não é carregado quando a sessão começa: ele entra quando o Claude lê um arquivo daquele subdiretório. Se você inicia a sessão de packages/api/, aí sim carregam o packages/api/CLAUDE.md e o CLAUDE.md da raiz

O mesmo vale para as regras modulares em .claude/rules/. Com o campo paths no frontmatter YAML, a regra só carrega quando o Claude trabalha com arquivos que batem no padrão glob

---
paths: src/api/**/*.ts
---

# Regras da API
- Toda rota nova precisa de teste de contrato

E tem um detalhe que pega muita gente: regras com paths disparam quando o Claude LÊ um arquivo que bate no padrão, não a cada uso de ferramenta

Ou seja, se ele nunca abriu um arquivo daquela pasta na sessão, a regra nunca existiu pra ele

Solução: sobe a regra crítica pro CLAUDE.md da raiz. Ou usa regra sem paths dentro de .claude/rules/, porque regra sem paths carrega sempre

Como prevenir: reserve paths pra regra específica de área do código (convenção de componente, padrão de migration, esse tipo de coisa). Inegociável de projeto não pode depender de gatilho

Causa 2: a compactação levou a regra embora no meio da sessão longa

Sintoma: clássico. Ele seguia a regra direitinho no começo, você ficou horas na mesma sessão e, do nada, ele começou a ignorar

Você não mudou nada, e mesmo assim o comportamento mudou

Causa: o Claude Code compacta a conversa automaticamente ao se aproximar do limite de contexto

E a compactação não trata todos os arquivos igual

O CLAUDE.md da raiz SOBREVIVE: depois da compactação ele é relido do disco e reinjetado na sessão

Já os CLAUDE.md aninhados e as regras com paths não são reinjetados automaticamente. Eles só voltam quando o Claude lê de novo um arquivo que os dispara

Então aquela regra da pasta src/api que estava valendo às 14h pode simplesmente não existir mais às 17h, mesmo com o arquivo intacto no disco

Solução: algumas saídas, da mais simples pra mais fina

• Coloque o inegociável no CLAUDE.md da raiz, que é o único que volta sozinho
• Reabra um arquivo da área pra redisparar a regra aninhada
• Ajuste o limiar da auto-compactação pela variável CLAUDE_CODE_AUTO_COMPACT_WINDOW
• Rode o /compact manual com instrução focada, tipo /compact focus on the auth bug fix

Como prevenir: trate sessão longa como sessão que perde contexto por padrão. Não é bug, é o funcionamento normal da janela

Causa 3: o arquivo cresceu e virou ruído

Sintoma: quanto mais regra você adiciona, MENOS ele obedece

Parece contraintuitivo, né? Mas faz todo sentido

Causa: a documentação oficial de memória do Claude Code aponta um alvo bem claro: menos de 200 linhas por arquivo CLAUDE.md

O motivo é direto: arquivo maior consome mais contexto e reduz a aderência

E a recomendação é de instruções específicas, concisas e bem estruturadas, porque quanto mais específica e concisa a instrução, mais consistentemente o Claude segue ela

O que a maioria dos CLAUDE.md tem, na prática, é um manual de onboarding com parágrafo explicativo, justificativa e três exemplos por regra. Isso não é regra, é redação escolar

Solução: corta o arquivo

• Agrupe com cabeçalhos markdown e bullets
• Referencie arquivos específicos e aponte padrões de exemplo em vez de descrever no abstrato
• Quebre o resto em .claude/rules/ ou traga por import

O import usa aquela sintaxe simples dentro do próprio CLAUDE.md

@docs/padroes-de-teste.md

Como prevenir: revise o tamanho toda vez que adicionar regra nova. Regra nova entrando geralmente significa regra velha saindo

Causa 4: suas regras estão brigando entre si

Sintoma: existem duas instruções válidas no seu setup e ele escolhe justamente a que você não queria

Causa: os níveis de memória (organização, projeto, usuário) são ADITIVOS, e não existe regra dura de precedência entre eles

Ou seja: quando as instruções conflitam, o resultado depende de como o Claude interpreta a situação

Não adianta gritar mais alto no arquivo de projeto esperando que ele vença o arquivo pessoal, porque essa hierarquia rígida não existe

E tem mais uma camada que muita gente esquece: organizações podem instalar um CLAUDE.md gerenciado, que não pode ser excluído pelas configurações individuais e vale para toda sessão na máquina

Os caminhos variam por sistema operacional

Sistema	Caminho do CLAUDE.md gerenciado
macOS	/Library/Application Support/ClaudeCode/CLAUDE.md
Linux e WSL	/etc/claude-code/CLAUDE.md
Windows	C:\Program Files\ClaudeCode\CLAUDE.md

Também dá pra distribuir pela chave claudeMd no managed-settings.json

Solução: elimine a duplicata em vez de reforçar a regra

Vá nos três lugares e veja se você não escreveu a mesma coisa de dois jeitos diferentes: o repo do projeto, o ~/.claude (no Windows, %USERPROFILE%\.claude) e o gerenciado

Como prevenir: uma regra, um lugar. Sempre

Como reescrever a regra em formato que o Claude respeita

Agora a parte prática. Pega uma regra sua que ele vive ignorando e passa ela por esses seis passos

1. Transforme em frase curta e imperativa. Comando, não explicação. "Use pnpm, nunca npm" funciona; um parágrafo contando a história de por que o time migrou de gerenciador de pacotes não funciona. O erro comum deste passo: regra explicativa e longa demais, que dilui o comando dentro do contexto
2. Declare o escopo: quando vale e quando NÃO vale. Escopo implícito é convite pra interpretação, e interpretação é exatamente o que você quer evitar aqui. O erro comum deste passo: deixar o "quando" na sua cabeça em vez de no arquivo
3. Aponte o arquivo ou o padrão de exemplo. A doc recomenda referenciar arquivos específicos e apontar padrões de exemplo. É a diferença entre "siga nosso padrão de service" e "siga o padrão de src/services/user.service.ts". O erro comum deste passo: descrever o padrão no abstrato e esperar que ele adivinhe qual arquivo é o modelo
4. Agrupe com cabeçalho e bullets. Bloco temático com título markdown e lista, sem texto corrido. O erro comum deste passo: jogar tudo numa lista gigante sem seção, o que deixa o arquivo impossível de podar depois
5. Decida onde a regra mora. Raiz pro inegociável, .claude/rules/ com paths pro que é de área específica, .claude/rules/ sem paths pro que precisa valer sempre, import com @ pra documentação maior. O erro comum deste passo: enterrar o inegociável num arquivo que depende de gatilho de leitura
6. Valide na sessão seguinte com /context e /memory. Abre uma sessão nova e confere se a regra realmente entrou, antes de confiar nela num trabalho sério. O erro comum deste passo: validar na mesma sessão em que você editou o arquivo

Um exemplo do formato final, bem enxuto

## Banco de dados
- Nunca rode migration destrutiva sem pedir confirmação
- Escopo: qualquer arquivo em `db/migrations/`
- Siga o padrão de `db/migrations/2026_01_create_users.ts`

Repare que a regra virou comando, escopo e exemplo. Três linhas

Esse mesmo formato serve muito bem pra domar comportamento, e não só estilo de código: é assim que você consegue fazer ele perguntar antes de codar em vez de sair escrevendo arquivo por conta própria

Onde colocar cada tipo de regra (e quando usar hook em vez de arquivo)

Mapa prático pra parar de chutar onde a regra deve morar

Tipo de regra	Onde colocar	Por quê
Inegociável do projeto	CLAUDE.md na raiz do repo	é lido no início da sessão e reinjetado depois da compactação
Regra de área do código	.claude/rules/ com paths e glob	carrega quando ele lê um arquivo que bate no padrão
Regra que precisa valer sempre	.claude/rules/ sem paths	regra sem paths carrega sempre
Preferência pessoal sua	~/.claude (Windows: %USERPROFILE%\.claude)	escopo global, vale nos seus projetos
Padrão obrigatório da empresa	CLAUDE.md gerenciado ou chave claudeMd no managed-settings.json	não pode ser excluído por configuração individual

Detalhe massa das regras modulares: subpastas como .claude/rules/frontend/react.md são descobertas automaticamente. Dá pra organizar por domínio sem ficar registrando nada em lugar nenhum

Um bom caso pra regra de raiz é o que envolve risco de perder trabalho: instruções sobre apagar código com segurança não podem depender de gatilho de leitura pra existir na sessão

E quando o arquivo não basta?

Aí entram os hooks, que são a camada que não depende da interpretação do modelo sobre o que é relevante

O hook UserPromptSubmit roda quando você envia um prompt, antes do Claude processar, e permite injetar contexto adicional. Ele não substitui o seu prompt: ele adiciona

A injeção pode ser pelo campo additionalContext, dentro de hookSpecificOutput no JSON de saída, ou por stdout em texto puro

{
  "hookSpecificOutput": {
    "additionalContext": "Nunca rode migration destrutiva sem confirmar"
  }
}

O conteúdo entra como system reminder iniciado pelo nome do hook, e o timeout padrão é de 30 segundos

Já os hooks SessionStart rodam de novo ao retomar a sessão, com source igual a resume, ou fork quando se usa --fork-session. É o lugar certo pra reinjetar contexto quando você volta pro trabalho de ontem

E tem a auto memory, que vem ligada por padrão, com arquivos por projeto em ~/.claude/projects/<project>/memory/

Se você quiser desligar, o toggle fica dentro do /memory e grava autoMemoryEnabled em ~/.claude/settings.json. Também dá pela variável de ambiente

CLAUDE_CODE_DISABLE_AUTO_MEMORY=1

E quando a regra está certa e ele ignora mesmo assim?

Sintoma: você fez tudo certo. Regra curta, escopo declarado, arquivo na raiz, checado com /context

E a instrução explícita ainda foi violada

Causa: aqui já não é o arquivo, é o modelo escolhendo entre dois sinais que competem dentro da mesma sessão. E tem registro público disso no repositório oficial

O issue #27032, aberto por chrispicht em 20/02/2026 e fechado como not planned, relata violação de duas regras explícitas do CLAUDE.md mesmo com os arquivos lidos no início da sessão, e cita ter seguido a sugestão do system prompt em vez da regra do CLAUDE.md

Repare que esse caso não é carregamento, nem compactação, nem tamanho, nem conflito entre níveis de memória. O arquivo estava lá, lido e inteiro

Tem também o issue #15443, com o mesmo padrão de reclamação, cujo título já diz tudo: Claude ignores explicit CLAUDE.md instructions while claiming to understand them

Ou seja: não é impressão sua e não é falta de jeito pra escrever prompt

Solução: reduza a superfície de conflito

Menos regra, mais curta, mais explícita, e o que for realmente crítico reforçado por hook em vez de só por arquivo

Como prevenir: não dependa de uma única camada pro que é crítico. Arquivo pra regra do dia a dia, hook pro que não pode falhar 🙂

Conclusão

Na maior parte dos casos em que o Claude Code passa por cima do CLAUDE.md, o problema está do lado do arquivo

É carregamento (a regra nunca entrou), compactação (ela saiu no meio da sessão), tamanho (o arquivo virou ruído) ou conflito entre níveis que são aditivos e sem precedência rígida

E sobra uma fatia em que o arquivo está impecável e o modelo segue outro sinal mesmo assim, que é onde o hook entra pra segurar o que não pode falhar

O próximo passo é bem concreto: na sua próxima sessão, roda /context e /memory antes de qualquer coisa

Depois corta o CLAUDE.md da raiz pra caber no alvo de menos de 200 linhas, e move o resto pra .claude/rules/

Só isso já resolve a maior parte dos casos

Até o próximo post!

Perguntas frequentes

Existe algum registro oficial de que o Claude Code ignora o CLAUDE.md mesmo depois de ler o arquivo?

Sim, há dois issues públicos no repositório oficial. O #27032, aberto por chrispicht em 20/02/2026 e fechado como not planned, relata o modelo violando duas regras explícitas do CLAUDE.md mesmo tendo lido o arquivo no início da sessão, seguindo a sugestão do system prompt em vez da regra escrita. O #15443 registra o mesmo padrão, com o Claude afirmando entender a instrução e ignorando ela na prática.

O CLAUDE.md da organização tem prioridade sobre o do meu projeto?

Não existe prioridade rígida: os níveis de organização, projeto e usuário são aditivos, e conflito entre eles é resolvido pela interpretação do modelo, não por uma hierarquia fixa. A diferença é que o CLAUDE.md gerenciado pela organização (por exemplo em /etc/claude-code/CLAUDE.md no Linux e WSL, ou via claudeMd no managed-settings.json) não pode ser excluído pelas configurações individuais e vale em toda sessão na máquina.

Dá para forçar uma regra usando hooks em vez de confiar só no CLAUDE.md?

Dá sim. O hook UserPromptSubmit roda antes do Claude processar o prompt e permite injetar contexto adicional a cada mensagem enviada, com timeout padrão de 30 segundos. Já o SessionStart dispara de novo quando a sessão é retomada (resume) ou bifurcada (fork), o que ajuda a reforçar uma instrução que se perdeu depois de uma compactação.

O que é a auto memory do Claude Code e ela pode interferir nas minhas regras do CLAUDE.md?

Auto memory é um recurso ligado por padrão, que guarda arquivos de memória por projeto em ~/.claude/projects/<project>/memory/. Dá para desligar direto no /memory, o que grava autoMemoryEnabled em ~/.claude/settings.json, ou via variável de ambiente CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Onde fica o CLAUDE.md global que vale para todos os meus projetos?

O escopo de projeto fica no repositório, com .claude/ e CLAUDE.md na raiz. O escopo global fica em ~/.claude/ no diretório home, e no Windows esse caminho resolve para %USERPROFILE%\.claude.

Dá para dividir o CLAUDE.md em outro arquivo pra não passar de 200 linhas?

Sim, o CLAUDE.md aceita importar outros arquivos com a sintaxe @caminho/para/arquivo. É a forma mais direta de manter o arquivo principal abaixo das 200 linhas recomendadas sem perder conteúdo, jogando o resto para um arquivo separado ou para .claude/rules/.