Por que o Claude ignora o seu CLAUDE.md

Tem um detalhe que quase ninguém sabe e que explica a frustração inteira: o CLAUDE.md chega como uma mensagem de usuário depois do system prompt, não como parte dele. Está na documentação da Anthropic, e eles são diretos sobre a consequência — o Claude "lê e tenta seguir, mas não existe garantia de obediência".

Então quando você escreve "NUNCA dê push na main" em maiúsculo e ele dá push na main, isso não é bug. Você colocou um pedido dentro de um documento que, por definição, é contexto — não é imposição. Todo time que eu vi penando com o Claude Code está brigando com essa mesma confusão.

Contexto x imposição — escolha a camada certa

A documentação faz uma separação limpa que vale decorar, porque ela te diz em qual arquivo cada regra mora:

• Orientação de comportamento — estilo de código, convenções, arquitetura, "prefira X a Y" → CLAUDE.md.
• Bloqueio técnico — barrar um comando, um caminho, uma ferramenta → permissions.deny no settings.json.
• Tem que acontecer num momento exato — antes de cada commit, depois de cada edição → um hook.

A doc não deixa margem: as regras de settings são aplicadas pelo cliente independentemente do que o Claude decidir fazer. O CLAUDE.md não é uma camada de imposição. Se furar uma regra custa dinheiro ou dado, essa regra não deveria estar no CLAUDE.md.

O orçamento de 200 linhas

O CLAUDE.md entra no context window no início de toda sessão, gastando token antes de você digitar qualquer coisa. A doc dá um alvo: menos de 200 linhas por arquivo, porque arquivos mais longos consomem mais contexto e reduzem a adesão.

Essa segunda parte é a interessante. Um CLAUDE.md gigante não é só mais caro — ele é menos obedecido. O que inverte a lógica de como quase todo mundo escreve esse arquivo. O instinto é documentar tudo; o instinto certo é brigar por cada linha.

Duas coisas que não resolvem um arquivo inflado:

• import com @path. Ótimo para organizar, inútil para contexto. Os arquivos importados são expandidos e carregados no início de qualquer forma (até quatro níveis de profundidade). Você mudou os token de lugar, não economizou.
• Espalhar em vários CLAUDE.md subindo a árvore de pastas. Todos os arquivos encontrados são concatenados, não substituídos. Agora você tem mais contexto e mais chance de duas regras se contradizerem — e quando isso acontece, a doc avisa que o Claude pode escolher uma delas arbitrariamente.

O que funciona de verdade é .claude/rules/ com paths no frontmatter. Uma regra restrita a src/api/**/*.ts só entra em contexto quando o Claude realmente mexe num arquivo de API. Aí sim é economia, não arrumação.

O template

Quatro seções, e uma regra dura: cada linha tem que ser verificável.

# <projeto> — uma linha sobre o que é isso e para quem

## Stack
Node 22 / pnpm 11 / Next.js 14 App Router / Postgres via Prisma.
O gerenciador de pacotes é pnpm — nunca npm.

## Comandos
- Teste: `pnpm --filter web test`
- Lint: `pnpm lint`
- Migração: `pnpm db:migrate`

## Estrutura
- `apps/web/` — frontend Next.js
- `packages/shared/` — schemas zod, o contrato entre as apps
- `db/` — schema Prisma + migrações

## Convenções
- Importe o client compartilhado de `@repo/db`, nunca de `@prisma/client` direto.
- Indentação de 2 espaços.
- Toda rota nova de API precisa de um schema zod em `packages/shared/`.

## Limites
- Não toque em `db/prisma/migrations/` sem perguntar.
- Não edite arquivos gerados (`*.gen.ts`).

A doc dá o teste de especificidade, e ele é bom: "use indentação de 2 espaços" ganha de "formate o código corretamente". "Os handlers de API ficam em src/api/handlers/" ganha de "mantenha os arquivos organizados". Se uma linha não pode ser conferida, ela não vai ser seguida — e está te custando token para ser ignorada.

A parte que rende juros

Esse é o hábito que separa um CLAUDE.md que apodrece de um que fica mais afiado a cada semana. A doc nomeia o gatilho exato: acrescente algo ao CLAUDE.md quando o Claude comete o mesmo erro pela segunda vez, quando uma revisão de código pega algo que ele deveria saber sobre aquele repositório, ou quando você digita a mesma correção que digitou na sessão passada.

Não no primeiro erro — no segundo. O primeiro pode ser acaso. O segundo é uma linha que falta no seu arquivo.

Minha regra de bolso: quando eu corrijo o Claude duas vezes na mesma coisa, eu paro e pergunto em qual dos três arquivos aquilo mora. É um fato sobre o repositório? CLAUDE.md. É um procedimento com passos? Uma skill — o corpo dela só carrega quando é usada, então não custa nada até você precisar. É algo que nunca pode acontecer? Regra de deny. Acertar esse roteamento é a maior parte do que as pessoas querem dizer com "pra ele o Claude Code simplesmente funciona".

Vale saber: o Claude também guarda anotações próprias agora. A memória automática escreve em ~/.claude/projects/<projeto>/memory/, e só as primeiras 200 linhas ou 25KB do índice MEMORY.md entram em cada sessão. É markdown puro — vai ler o que ele vem anotando sobre o seu repositório. No meu, ele tinha aprendido coisas sobre o meu build que eu nunca escrevi em lugar nenhum.

Faça isso hoje

Abra o repositório em que você mais trabalha e rode /context. Olhe em Memory files e confirme que o seu CLAUDE.md realmente carregou — se ele não aparecer nessa lista, o Claude nunca viu esse arquivo, e você passou semanas depurando um texto que ninguém leu. Depois conte as linhas. Passou de 200, corte. E aí pegue aquela regra que você escreveu em maiúsculo e mova pra permissions.deny, onde ela vai valer de verdade.

Fontes

• Claude Code docs — How Claude remembers your project
• Claude Code docs — Settings