CLAUDE.md: anatomia de um arquivo que funciona

O CLAUDE.md não é arquivo de configuração. Ele é contexto entregue como mensagem de usuário, logo depois do system prompt — e é exatamente por isso que o agente às vezes o ignora.

Essa frase está na documentação oficial e quase nunca aparece nos tutoriais. As consequências são práticas: instrução vaga compete com o resto da conversa, instrução contraditória é resolvida na sorte, e o que precisa de garantia não pertence ao CLAUDE.md.

Este guia é a anatomia do arquivo: onde ele mora, como os escopos se combinam, por que 200 linhas é o teto certo, e o que fazer com o que sobra. O que acontece com esse conteúdo quando a sessão fica longa está em por que seu agente esquece.

É contexto. Não é enforcement.

A documentação é explícita: "Claude trata os dois como contexto, não como configuração aplicada. Para bloquear uma ação independentemente do que o Claude decidir, use um hook PreToolUse" (Claude Code Docs, acesso em 19/08/2026).

Na seção de troubleshooting a explicação fica mecânica: o conteúdo é entregue como mensagem de usuário depois do system prompt, não como parte dele. O agente lê e tenta seguir, mas não há garantia de conformidade estrita — especialmente com instrução vaga ou conflitante.

Isso resolve a discussão mais comum sobre o arquivo. Quando alguém diz "o Claude ignorou meu CLAUDE.md", quase sempre uma destas três é a causa:

1. O arquivo não carregou de fato (escopo errado, veja abaixo)
2. A instrução é vaga demais para ser seguida de forma verificável
3. Duas instruções se contradizem, e o agente escolheu uma arbitrariamente

E há uma quarta situação, que não é bug: a instrução precisava ser um hook. Se algo tem que rodar sempre, num ponto fixo do ciclo (antes de todo commit, depois de toda edição), escreva como hook. Hooks executam como comando de shell em evento de ciclo de vida e valem independentemente do que o agente decidir.

Não existe um CLAUDE.md. Existem até quatro carregados ao mesmo tempo, na ordem do mais amplo para o mais específico.

A política gerenciada não pode ser excluída por configuração individual. Os outros três, sim.

O detalhe que muda o comportamento: os arquivos se concatenam, não se sobrescrevem. O Claude Code sobe a árvore de diretórios a partir do seu diretório atual e junta tudo o que encontra. Rodando em foo/bar/, ele carrega foo/CLAUDE.md e foo/bar/CLAUDE.md — nessa ordem, da raiz para baixo, então o que está mais perto de onde você lançou a sessão é lido por último. Dentro de cada diretório, o CLAUDE.local.md vem depois do CLAUDE.md.

Arquivos em subdiretórios abaixo do diretório atual têm comportamento diferente: não carregam no lançamento, e sim quando o agente lê um arquivo daquela pasta.

Em monorepo, isso vira problema rápido — você herda o CLAUDE.md de outros times sem pedir. A saída é claudeMdExcludes no settings.local.json:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/outro-time/.claude/rules/**"
  ]
}

Porque o arquivo entra inteiro no contexto de toda sessão, e a aderência cai conforme ele cresce.

A recomendação oficial é direta: alvo abaixo de 200 linhas por arquivo, porque arquivos mais longos consomem mais contexto e reduzem a aderência. Vale notar a assimetria: o MEMORY.md da memória automática é truncado nas primeiras 200 linhas ou 25 KB, mas o CLAUDE.md é carregado por inteiro, independentemente do tamanho. Ninguém corta por você.

Quando passa do teto, existem três destinos, e escolher errado é o erro mais comum:

A regra que uso para decidir: isso é verdade em toda tarefa deste projeto? Convenção de nomenclatura, sim. Procedimento de migração de banco, não — isso é skill.

Há uma medição pública que sustenta esse critério e vale contra o instinto de esvaziar o arquivo. Ao documentar o que muda na migração para o Next.js 16, a Vercel afirma que conhecimento de framework deve vir de docs sempre carregados, não de skills, porque em benchmark próprio contexto sempre disponível superou recuperação sob demanda. Enxugar o CLAUDE.md é sobre remover o que o agente deriva sozinho — não sobre mover para skill tudo que ele precisa em toda tarefa.

O /doctor faz essa poda semi-automaticamente num CLAUDE.md versionado. Ele corta o que o agente consegue derivar do próprio código (layout de diretórios, lista de dependências, visão geral de arquitetura) e preserva armadilhas, justificativas e convenções que divergem do padrão da ferramenta. É a distinção certa: o arquivo não é para descrever o projeto, é para dizer o que o projeto tem de diferente.

Organizam. Não economizam contexto.

A sintaxe é @caminho/do/arquivo, e funciona em qualquer lugar do texto:

Veja @README para a visão geral e @package.json para os comandos npm.

# Instruções adicionais
- fluxo de git @docs/git-instructions.md

Quatro regras que valem conhecer:

Caminho relativo resolve a partir do arquivo que importa, não do diretório de trabalho. Confundir isso quebra o import em silêncio.

A recursão vai até quatro saltos. Arquivo importado pode importar outro.

Crase escapa o import. Escrever `@README` entre crases mantém o texto literal — o parser pula code spans e blocos de código. Sem isso, mencionar um caminho no texto importaria o arquivo.

Import não reduz contexto. Esta é a que mais decepciona. Quebrar um CLAUDE.md de 400 linhas em cinco imports de 80 organiza a leitura para humanos e carrega exatamente os mesmos tokens no lançamento. Para reduzir contexto de verdade, o caminho é .claude/rules/ com paths, ou skill.

Há uma proteção que pega quem trabalha em projeto compartilhado: import de arquivo de projeto que resolve para fora do diretório de trabalho dispara um diálogo de aprovação na primeira vez. Se você recusar, os imports ficam desativados e o diálogo não volta. Imports em escopo de usuário não passam por isso, porque são arquivos que você mesmo escreveu.

E se o repositório já usa AGENTS.md para outros agentes: o Claude Code não lê AGENTS.md. Crie um CLAUDE.md que o importe.

@AGENTS.md

## Claude Code
Use plan mode para mudanças em `src/billing/`.

Symlink também funciona, mas no Windows exige privilégio de administrador ou Modo Desenvolvedor — no Windows, prefira o import.

É a única forma de escrever mais instrução sem pagar mais contexto em toda sessão.

A estrutura é um arquivo por assunto, descobertos recursivamente:

seu-projeto/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── code-style.md
│       ├── testing.md
│       └── frontend/
│           └── componentes.md

Regra sem frontmatter paths carrega no lançamento, com a mesma prioridade do .claude/CLAUDE.md. Ou seja: sem paths, você só moveu o problema de arquivo.

O ganho está no escopo por caminho:

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

# Regras de API

- Todo endpoint valida a entrada
- Use o formato padrão de resposta de erro

Essa regra só entra no contexto quando o agente lê um arquivo que casa com o glob. Não é a cada uso de ferramenta — é na leitura.

Expansão de chaves multiplica padrões: src/*.{ts,tsx} vira dois, e {a,b}/{c,d}/*.{ts,tsx} vira oito. A lista paths inteira divide um orçamento de 1.000 padrões expandidos e 4 MiB; padrão sem chaves não conta. Estourou o orçamento, o Claude Code usa o padrão sem expandir — e aí as chaves literais não casam com arquivo nenhum.

Uma pegadinha de sintaxe: o glob trata [ como início de expressão de colchete. photos [2024/** é inválido e não casa com nada, embora os outros padrões da mesma regra continuem valendo. Para colchete literal, escape: photos \[2024/**.

Regras de usuário em ~/.claude/rules/ valem em todo projeto da máquina e carregam antes das de projeto, o que dá prioridade maior às do projeto. E o diretório aceita symlink, então dá para manter um conjunto compartilhado e linkar em vários repositórios.

Concreta o bastante para ser verificável. Os exemplos da documentação mostram o padrão:

O teste é simples: dá para verificar se foi cumprido olhando o resultado? Se não dá, o agente também não consegue.

Três hábitos que fazem o resto do trabalho:

Estrutura com heading e bullet. O agente varre estrutura do mesmo jeito que um leitor: seção organizada é mais fácil de seguir que parágrafo denso.

Revisão periódica por contradição. Se duas regras se contradizem, o agente escolhe uma arbitrariamente. Vale reler o CLAUDE.md do projeto, os aninhados em subpastas e o .claude/rules/ de vez em quando, procurando conflito e conteúdo vencido.

Comentário HTML para nota de humano. Comentários de bloco são removidos antes de o conteúdo entrar no contexto. Ou seja, dá para deixar recado para quem mantém o arquivo sem gastar um token:

<!-- Esta seção existe por causa do incidente de 12/03. Não remover
     sem falar com o time de infra. -->
- Nunca rode migração direto em produção.

Comentários dentro de bloco de código são preservados, e o arquivo aberto pela ferramenta de leitura mostra tudo.

A ordem de diagnóstico, do mais provável ao menos.

1. O arquivo carregou? /context lista o que entrou na sessão sob Memory files. Esse e os outros comandos citados aqui estão na referência completa de comandos do Claude Code. Se o seu arquivo não está ali, o agente não o vê — e nenhum ajuste de redação resolve. /memory abre os arquivos para edição.

2. A instrução é verificável? Volte à tabela acima.

3. Existe contradição? Entre escopos, entre CLAUDE.md aninhados, ou com .claude/rules/.

4. Sumiu depois do /compact? O CLAUDE.md da raiz do projeto sobrevive à compactação: o agente relê do disco e reinjeta. Já os CLAUDE.md aninhados em subpastas e as regras com paths: não são reinjetados automaticamente — eles voltam na próxima vez que o agente ler um arquivo daquela pasta ou que case com o padrão. Se a instrução sumiu, ou ela só existia na conversa, ou está num aninhado que ainda não recarregou.

5. Precisa de log? O hook InstructionsLoaded registra exatamente quais arquivos de instrução carregaram, quando e por quê. É a ferramenta certa para depurar regra com paths e carregamento sob demanda.

Cabe em menos de 200 linhas e cobre o que importa.

# Projeto

<!-- Manter abaixo de 200 linhas. O que crescer vira .claude/rules/ ou skill. -->

## Stack
- Next.js 16 (App Router), TypeScript estrito, Tailwind
- Banco: Postgres via Prisma
- Deploy: push na main dispara build

## Comandos
- `npm run dev` — desenvolvimento
- `npm test` — rodar antes de commitar
- `npm run lint` — obrigatório antes de PR

## Convenções
- Indentação de 2 espaços
- Componentes em `src/components/`, um por arquivo
- Handlers de API em `src/api/handlers/`
- Nome de arquivo em kebab-case, componente em PascalCase

## O que diverge do padrão
- Não usamos barrel files: import direto do arquivo
- Datas sempre em UTC no banco, conversão só na borda de exibição
- `any` é proibido; use `unknown` e refine

## Armadilhas conhecidas
<!-- Esta lista veio de erro real. Não enxugar sem contexto. -->
- O middleware virou `proxy.ts` no Next 16 — código antigo ainda cita middleware
- O seed do banco apaga tudo. Nunca rodar com DATABASE_URL de staging

Note o que não está ali: descrição de arquitetura, lista de dependências, layout de diretórios. Tudo isso o agente deriva lendo o código — é justamente o que o /doctor corta. O que fica é o que ele não conseguiria adivinhar: o que diverge do padrão e o que já deu errado.

O CLAUDE.md é a primeira das cinco camadas de um setup que aguenta produção — e a que sustenta as outras quatro. O mecanismo por trás disso está em por que seu agente esquece.

Qual a diferença entre CLAUDE.md e memória automática?

Você escreve o CLAUDE.md; o agente escreve a memória automática. O primeiro guarda instrução e regra, a segunda guarda aprendizado e padrão que ele descobriu sozinho. Os dois carregam em toda sessão, mas a memória automática mora em ~/.claude/projects/<projeto>/memory/ e só o índice MEMORY.md entra no início — os arquivos de tópico são lidos sob demanda.

Devo usar /init ou escrever na mão?

/init primeiro. Ele analisa o código e gera um arquivo inicial com comandos de build, instruções de teste e convenções que encontrou. Se já existe CLAUDE.md, ele sugere melhorias em vez de sobrescrever. Depois refine com o que o agente não teria como descobrir — as armadilhas e as decisões.

Quebrar em imports reduz o custo de contexto?

Não. Arquivo importado carrega no lançamento igual. Imports servem para organizar. Para reduzir contexto, use .claude/rules/ com paths — essas regras só entram quando o agente lê um arquivo que casa com o padrão.

O que fazer com instrução que precisa valer sempre?

Se precisa de garantia, não é CLAUDE.md. Instrução que deve rodar num ponto fixo do ciclo vira hook. Bloqueio de ferramenta, comando ou caminho vira permissions.deny nas configurações. O CLAUDE.md orienta comportamento; ele não é camada de aplicação.

• Anthropic — Claude Code Docs: How Claude remembers your project. Acesso em 19/08/2026.
• Anthropic — Claude Code Docs: Automate actions with hooks. Acesso em 20/08/2026.
• Anthropic — Claude Code Docs: Skills. Acesso em 19/08/2026.
• Anthropic — Claude Code Docs: Manage costs effectively. Acesso em 19/08/2026.
• Anthropic — Claude Code Docs: Settings. Acesso em 20/08/2026.

Verificado em 19 de agosto de 2026.

Gatilho de reavaliação: revisar quando (a) mudar o alvo recomendado de 200 linhas, (b) CLAUDE_CODE_NEW_INIT sair de trás da variável de ambiente e virar padrão do /init, ou (c) a ordem de precedência entre escopos ou o comportamento de reinjeção pós-/compact mudarem.