O CLAUDE.md é o arquivo com mais alavancagem do seu repositório: o Claude Code o lê no início de cada sessão, antes de olhar uma única linha do seu código. Bem escrito, ele poupa ao agente vinte minutos de redescobrir suas convenções em cada tarefa. Mal escrito, queima tokens, dilui a atenção e pode direcionar o modelo para o lado errado.
A maioria dos CLAUDE.md é mal escrita, e de um jeito bem específico: documentam o que o agente poderia descobrir sozinho e omitem o que ele jamais conseguiria inferir. Este guia cobre como o arquivo é carregado, a única regra que decide o que merece uma linha, um exemplo completo que você pode adaptar, o que deixar de fora (com a pesquisa por trás de cada corte) e como mantê-lo honesto ao longo do tempo. Se quiser ir direto ao resultado, nosso gerador gratuito de CLAUDE.md produz um rascunho sólido em uns dois minutos, sem cadastro.
O que é um CLAUDE.md e como o Claude Code o carrega
CLAUDE.md é um arquivo Markdown simples que o Claude Code incorpora automaticamente ao contexto quando uma sessão começa. Não há esquema nem frontmatter: o que você escrever vira instrução permanente para o agente. O que o torna poderoso é a hierarquia de carregamento:
- Memória de projeto (
./CLAUDE.mdna raiz do repo) é a principal: compartilhada com o time, versionada no git. O Claude Code também percorre a árvore de diretórios para cima, então em um monorepo carregam tanto o CLAUDE.md raiz quanto o do pacote, e CLAUDE.md de subdiretórios carregam sob demanda quando o agente trabalha com arquivos ali. - Memória de usuário (
~/.claude/CLAUDE.md) vale para todos os projetos da sua máquina. Preferências pessoais ficam aqui (seu estilo de commit, suas regras de "nunca mate meus processos"), não no arquivo do repo, onde seriam ruído para o resto do time. - Imports permitem dividir um arquivo grande: uma linha como
@docs/deploy-checklist.mdembute outro arquivo no carregamento (até cinco níveis de profundidade). Use-os para conteúdo que só algumas sessões precisam.
Dois detalhes de fluxo de trabalho que valem a pena conhecer: apertar # em uma sessão permite adicionar uma memória ao arquivo escolhido sem sair da tarefa, e /init gera um CLAUDE.md inicial escaneando o repo. Trate a saída do /init como um primeiro rascunho para podar sem dó, não como um arquivo pronto; abaixo você verá o porquê.
A regra de ouro: escreva só o que o agente não consegue inferir
Este é o modelo mental que conserta 90% dos CLAUDE.md ruins: o agente consegue ler o seu código. Ele pode listar diretórios, abrir o package.json, buscar com grep e rodar sua suíte de testes. Tudo que for descobrível por esse caminho é desperdício do seu orçamento de contexto, porque você está pagando tokens para contar ao modelo algo que ele encontraria de qualquer jeito.
O que o agente não consegue inferir, por melhor que fique, é tudo que vive fora do código:
- Os motivos. Por que o acesso ao banco passa pela camada de repositórios, não só o fato de que passa. Um modelo que conhece a razão aplica a regra a casos que você nunca escreveu.
- As armadilhas. A suíte de testes que falha só fora de UTC. A rota que quebra em silêncio no runtime edge. A migração que você nunca deve regenerar a partir de um template. São cicatrizes, e cicatrizes são exatamente o que falta a uma sessão nova.
- Convenções que diferem dos padrões. O agente assume o comportamento padrão das ferramentas. Se o seu projeto desvia (só exports nomeados, um helper de erros próprio, um diretório fora do padrão que não deve receber arquivos novos), diga, e diga por quê.
- Comandos com flags não óbvias. Não
npm install, mas o fato de que seus testes precisam deTZ=UTC, ou quepnpm testroda em modo watch e o CI precisa depnpm vitest run.
Antes de cada linha que escrever, pergunte: o Claude conseguiria descobrir isso lendo o repo? Se sim, apague a linha. Se não, mantenha, e anexe a razão.
Um exemplo completo
Este é um CLAUDE.md realista para um projeto típico de Next.js + TypeScript + Prisma. Repare que quase toda linha é um comando com seu detalhe, um desvio dos padrões ou uma armadilha com a razão anexada:
# CLAUDE.md
Guidance for Claude Code in this repository.
## Commands
- `pnpm dev`: dev server on :3000. Use this, not `next dev` directly,
because the script also runs env validation.
- `pnpm test`: Vitest in watch mode. For a one-shot run (CI, hooks)
use `pnpm vitest run`.
- `pnpm db:migrate`: applies Prisma migrations to the local Postgres.
Start it first with `docker compose up -d db`.
- `pnpm lint:fix` before committing; CI blocks on lint errors.
## Architecture notes
- App Router only. `pages/` still exists for two legacy webhook
endpoints; do not add new files there.
- All DB access goes through `src/server/repositories/`. Route
handlers never import Prisma directly, because the repository
functions carry the row-level tenancy filter.
- Feature flags come from `src/lib/flags.ts` and are cached for 30s,
so tests must stub `getFlag`, not the network call.
## Conventions that differ from defaults
- Named exports everywhere; default exports break `pnpm generate:api`.
- Use `invariant()` from `src/lib/invariant.ts` instead of throwing
raw errors: the global handler maps it to a 400 with a safe message.
- Dates are stored in UTC and formatted only in components via
`formatInTz`. Never format dates in server code; that caused the
double-booking bug in #482.
## Pitfalls
- `pnpm test` needs `TZ=UTC` (set in `.env.test`); without it the
booking specs fail only on machines outside UTC.
- The Stripe webhook route must stay on the Node runtime
(`export const runtime = "nodejs"`): the edge runtime cannot
verify webhook signatures.
São umas 40 linhas, e uma sessão que as carrega começa com tudo que um colega sênior contaria a alguém novo no primeiro dia, e nada mais.
O que deixar de fora, com a evidência
Cada corte abaixo remonta a um estudo publicado ou a uma doc oficial; a lista completa está no nosso artigo sobre as regras do linter de arquivos de contexto.
O boilerplate cru do /init. O benchmark de AGENTS.md da ETH Zurich (138 tarefas, quatro agentes incluindo o Claude Code) constatou que arquivos de contexto autogerados reduziram o sucesso do agente em cerca de 2-3% enquanto elevavam o custo em mais de 20%. Eles reafirmam o que o agente pode descobrir, então você paga os tokens duas vezes: uma para carregá-los e outra para o agente verificá-los.
Árvores de diretórios. No mesmo benchmark, os agentes ignoraram os despejos de estrutura de pastas enquanto pagavam cerca de 14-22% a mais de tokens de raciocínio por eles. O próprio /doctor do Claude Code agora corta os layouts de diretórios. O agente vai rodar ls; deixe.
Linguagem impositiva. "IMPORTANT: You MUST ALWAYS…" foi escrita para corrigir a sub-ativação em modelos de 2024. Os modelos atuais se sobre-ativam com ela: a própria orientação da Anthropic agora manda reescrever "CRITICAL: You MUST use this tool when…" como um simples "Use this tool when…". Um arquivo com oito ou mais marcadores em MAIÚSCULAS não tem mais ênfase nenhuma, porque tudo está enfatizado.
Prosa vaga de qualidade. "Write clean code", "follow best practices", "be helpful". O estudo do GitHub sobre mais de 2.500 arquivos de instruções para agentes constatou que a vagueza é o modo de falha número um: os agentes agem sobre instruções específicas e verificáveis e pulam a prosa evasiva. Se uma regra de estilo importa, ancore-a em um comando (ruff check --select D), ou apague.
Tudo que passar da linha 200. As docs de memória da Anthropic agora dão uma meta explícita: mantenha o CLAUDE.md abaixo de cerca de 200 linhas, porque arquivos mais longos reduzem a aderência de forma mensurável. Também há um limite rígido de 40.000 caracteres. Se estourou o orçamento, mova o detalhe para arquivos importados com @ ou apague as partes descobríveis; não brigue por aderência com mais letras maiúsculas.
Mantendo o arquivo vivo
Um CLAUDE.md é configuração viva, não documentação que você escreve uma vez. Três hábitos o mantêm útil:
- Atualize no momento do atrito. Quando o agente fizer algo errado que uma frase teria prevenido, adicione a frase na hora (
#transforma isso em uma operação de cinco segundos). É assim que a seção de armadilhas acumula cicatrizes reais em vez de hipóteses. - Revise a cada salto de modelo. Instruções são calibradas para uma geração de modelos. A linguagem impositiva que ajudava o Claude 3 prejudica os modelos atuais; um arquivo que ninguém relê desde 2024 provavelmente está direcionando o agente errado hoje. Coloque uma revisão do CLAUDE.md no seu checklist de cada atualização maior de modelo.
- Pode com a mesma agressividade com que adiciona. Regras se acumulam; orçamentos de contexto não. Se uma convenção virou o padrão, ou uma armadilha foi corrigida, remova a linha.
Se o seu time também usa Cursor, Copilot ou Codex, não mantenha quatro arquivos divergentes à mão: escreva o modelo uma vez e exporte uma configuração para cada agente, CLAUDE.md incluído.
Valide antes de commitar
Quase todas as regras deste artigo podem ser verificadas mecanicamente. Cole seu arquivo no linter de CLAUDE.md gratuito, ou rode offline:
npx promptarch lint CLAUDE.md
Ele dá uma nota de 0 a 100 ao arquivo contra ~30 regras respaldadas por pesquisa: o orçamento de 200 linhas, a linguagem impositiva, o boilerplate gerado, os despejos de árvore de diretórios, as diretivas contraditórias e verificações de segurança (chaves vazadas, injeção com Unicode invisível) que a maioria dos revisores nunca pensa em procurar. Roda totalmente offline e não precisa de conta.
Comece com um rascunho, não com um arquivo em branco
Duas formas gratuitas de começar agora:
- Gere: o gerador gratuito de CLAUDE.md pergunta pelo seu stack, suas convenções e suas restrições, e produz um rascunho estruturado. Sem cadastro para o primeiro.
- Valide: já tem um CLAUDE.md? Passe-o pelo linter e veja o que um ano de mudanças de modelos fez com as suas instruções. Também grátis.
De qualquer forma, os dois minutos investidos ganham de cada sessão em que o agente precisa redescobrir seu projeto do zero.