Guia do CLAUDE.md: o que é & como escrever um (com template, 2026)

Jasmine (uma dev que usa o Claude Code todo dia e escreve & ajusta arquivos CLAUDE.md em projetos reais).

O que é o CLAUDE.md?

Se você já se irritou porque o Claude Code vive "esquecendo" que o seu projeto usa pnpm em vez de npm, ou porque ele cria um arquivo novinho em vez de editar o que já existe, então o CLAUDE.md é exatamente o que estava faltando.

O CLAUDE.md é um arquivo Markdown colocado na raiz do seu projeto que o Claude Code carrega no contexto automaticamente no instante em que uma sessão começa, funcionando como instruções de sistema duradouras para todo o projeto. Em outras palavras, em vez de redigitar "este projeto usa TypeScript, rode os testes com o comando X, não mexa no diretório Y" toda vez que você abre uma nova sessão, você escreve essas convenções uma única vez no CLAUDE.md. O agente o lê como leria um briefing de um colega de equipe que já conhece a base de código.

A distinção-chave: o CLAUDE.md não é um prompt que você precisa lembrar de colar toda vez, e não é documentação para leitores humanos. É contexto para o agente — escrito para ser curto, imperativo e focado no que ajuda o Claude a tomar a decisão certa. Quanto mais específico e certeiro, menos o agente se perde. Se você ainda nem sabe o que é o Claude Code, leia primeiro o que é o Claude Code e depois volte aqui.

Outra forma de imaginar: quando você integra uma pessoa desenvolvedora nova, não quer reexplicar tudo toda manhã. Você escreve uma página de onboarding, ela lê e passa a atuar por conta própria. O CLAUDE.md é essa página de onboarding — só que para o agente, e ela é relida automaticamente em toda sessão. É por isso também que vale a pena investir no arquivo: escreva-o bem uma vez e o benefício se acumula ao longo das centenas de sessões que vêm depois. Segundo o guia de boas práticas da Anthropic, refinar o CLAUDE.md aos poucos com o tempo (tratando-o como um prompt vivo) funciona visivelmente melhor do que tentar escrevê-lo perfeito de primeira.

Como o CLAUDE.md funciona? (por que o agente o segue)

O mecanismo é genuinamente simples: quando você abre uma sessão dentro do diretório de um projeto, o Claude Code procura arquivos CLAUDE.md e os carrega no começo do contexto, antes do seu primeiríssimo prompt. Várias camadas carregam de uma vez:

• Raiz do projeto - ./CLAUDE.md, convenções compartilhadas para todo o repositório (carregadas para todo mundo que trabalha no projeto).
• Seu arquivo pessoal - ~/.claude/CLAUDE.md, suas próprias preferências aplicadas em todos os seus projetos.
• Diretórios pai/filho - o Claude Code sobe pela árvore de diretórios e também lê um CLAUDE.md dentro de um subdiretório quando está trabalhando ali, então convenções específicas de um módulo podem ficar bem ao lado desse módulo.

Como esse conteúdo fica no começo do contexto, ele está sujeito ao viés de primazia (primacy bias) — o modelo tende a "escutar" mais o que aparece cedo. É por isso que você deve colocar as suas restrições mais importantes (os limites de "NÃO faça") no topo do arquivo, em vez de enterrá-las no meio de um parágrafo longo.

Uma ressalva honesta: o CLAUDE.md cria um contexto do Claude Code forte, mas não é uma lei inquebrável. Quando o contexto lota ou o arquivo fica longo demais, o sinal se dilui e o agente ainda pode deixar coisas passarem. A forma mais rápida de verificar se o agente realmente o leu é perguntar diretamente: "de acordo com o CLAUDE.md, qual é o comando para rodar os testes?" — se ele responder certo, a sua memória de projeto chegou ao contexto.

Os 3 tipos de CLAUDE.md & onde eles ficam

Muita gente supõe que existe só um arquivo. Na real, são três escopos, e saber onde cada um fica evita que você amontoe tudo em um único arquivo:

Quanto ao CLAUDE.local.md, é um arquivo privado e não versionado para anotações pessoais por projeto — URLs de sandbox ou dados de teste locais que só você precisa. Segundo a documentação oficial no momento em que escrevo (2026-08-20), o arquivo ainda tem suporte total, não foi descontinuado como alguns guias mais antigos afirmam — ele carrega junto com o CLAUDE.md e é tratado da mesma forma; você só precisa adicioná-lo ao .gitignore. Se você trabalha em vários worktrees do mesmo projeto e quer compartilhar anotações pessoais entre eles, a documentação sugere importar a partir do seu diretório home, algo como @~/.claude/my-project-instructions.md, em vez de duplicar o conteúdo em cada worktree — reverifique essa sintaxe antes de depender dela, já que pode mudar entre versões. Se você quer a resposta curta para "onde eu coloco o CLAUDE.md": convenções do time na raiz do repo, preferências pessoais no arquivo de usuário, anotações não versionadas no CLAUDE.local.md, exceções específicas de módulo no subdiretório.

O que colocar no CLAUDE.md? (6 seções essenciais)

Esta é a pergunta mais importante — e a maioria dos arquivos fracos falha porque enche de coisa errada. Ordenadas por ROI, do maior para o menor, as seis seções que valem a pena são:

1. Comandos (maior ROI). Como testar, buildar, rodar o lint e subir o dev. O agente erra os comandos com mais frequência, então é aqui que você economiza mais tempo. Exemplo: pnpm test, pnpm build, pnpm lint.
2. Tech stack + versões. Linguagem, framework, gerenciador de pacotes, banco. Exemplo: "Next.js 15 (App Router), TypeScript strict, pnpm, PostgreSQL + Prisma". Evita que o agente recorra a APIs desatualizadas.
3. Estrutura de diretórios - uma linha por item. Exemplo: "app/ rotas; components/ UI; lib/ helpers compartilhados". O suficiente para o agente saber onde um arquivo novo deve ficar.
4. Convenções de código. Nomenclatura, ordem dos imports, tratamento de erros, estilo de teste. Aponte as coisas fáceis de errar; não copie o seu guia de estilo inteiro.
5. Os limites de "NÃO faça". Esta é a seção que faz a maior diferença, e ela pertence perto do topo. Exemplo: "NÃO crie um arquivo novo quando dá para editar um existente", "NÃO faça commit sem pedirem", "NÃO mexa na pasta migrations/ já aplicada".
6. Importe @path para docs detalhados. Em vez de colar um documento longo inline, aponte para ele: @docs/architecture.md. Isso mantém o arquivo principal enxuto e ainda dá ao agente um caminho para os detalhes quando preciso (divulgação progressiva). Algumas coisas que a galera erra: caminhos relativos são resolvidos em relação ao arquivo que faz a importação, não ao seu cwd; imports aninham até 4 níveis de profundidade - qualquer coisa mais funda é ignorada; para citar um caminho literalmente sem disparar uma importação, envolva-o em crases, por exemplo `@README`.

A regra de filtragem: se uma linha não ajuda o agente a tomar uma decisão diferente, corte. O CLAUDE.md não é um README. Um README explica o projeto para leitores humanos; o CLAUDE.md diz ao agente como se comportar. Dois propósitos diferentes — não misture os dois, ou o arquivo incha com conteúdo que o agente nunca usa de fato na hora de decidir o que fazer.

O template padrão de CLAUDE.md (copiar e colar)

Abaixo está um template completo e funcional para um projeto típico Next.js + TypeScript. É exatamente isso que a maioria dos guias deixa de fora: um arquivo que você cola e usa na hora, e depois apara para o seu próprio projeto.

Copie este template e ajuste ao seu projeto: troque a tech stack, os comandos e a estrutura de diretórios para bater com o seu. Mantenha a seção "NÃO faça" no topo.

# CLAUDE.md

Web app for managing clinic appointment scheduling. Priority: correct business logic > coding speed.

## Do NOT (read first)
- Do NOT create a new file if you can edit an existing one.
- Do NOT commit/push unless explicitly asked.
- Do NOT edit files in `prisma/migrations/` that already ran - create a new migration.
- Do NOT use `any` in TypeScript. Do NOT disable lint to get past errors.

## Tech stack
- Next.js 15 (App Router) + TypeScript (strict)
- pnpm (do NOT use npm/yarn)
- PostgreSQL + Prisma
- Tailwind CSS + shadcn/ui
- Vitest (unit) + Playwright (e2e)

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test` # single file: `pnpm test path/to/file`
- Build: `pnpm build`
- Lint: `pnpm lint`
- DB: `pnpm prisma migrate dev`

## Directory structure
- `app/` - routes (App Router)
- `components/` - reusable UI
- `lib/` - shared helpers, no JSX
- `server/` - server-side logic, DB queries
- `prisma/` - schema + migrations

## Code conventions
- Components: PascalCase; functions/variables: camelCase; constants: UPPER_SNAKE.
- Prefer named exports; absolute imports via the `@/` alias.
- Error handling: throw `AppError` (see `lib/errors.ts`), never swallow errors silently.
- Every new feature ships with a test.

## Workflow
- Before calling anything done: run `pnpm lint` and `pnpm test`, fix all errors.
- Large changes: describe a short plan before editing many files.

## Detailed docs (import when needed)
@docs/architecture.md
@docs/api-conventions.md

Faça & Não faça - exemplos errado → certo

A diferença entre um arquivo que o agente obedece e um que ele ignora costuma estar no jeito de escrever, não no tamanho. Alguns pares reais de antes/depois:

A regra de ouro: escreva do jeito que você faria um briefing para uma dev nova e esperta que ainda não sabe nada do projeto - específico, imperativo, curto. Toda linha vaga ("escreva código limpo", "siga as boas práticas") é quase inútil porque o agente não consegue medi-la. Troque "escreva código limpo" por "funções com no máximo 40 linhas, divida quando passar disso"; troque "trate os erros com cuidado" por "dê throw em AppError, sem try/catch vazio". O que é mensurável é o que o agente consegue seguir. Para ver o conjunto completo de comandos do Claude Code que você talvez queira referenciar no arquivo, confira o guia rápido de comandos do Claude Code.

Mantenha o CLAUDE.md enxuto & eficiente em tokens

Existe um equívoco comum: quanto maior o arquivo, mais o agente "entende" o projeto. É o contrário. O CLAUDE.md consome a janela de contexto de toda sessão e, à medida que incha, cada linha importante se perde entre dezenas de linhas ruidosas - o sinal afina e o agente fica mais propenso a deixar passar justo o que você mais precisava. Isso não é só intuição: veja se os arquivos de contexto AGENTS.md/CLAUDE.md realmente funcionam para as evidências por trás disso.

Experiência prática: mire em torno de ~200 linhas, com um teto de mais ou menos 300-500 linhas para projetos grandes. Passar bem disso é sinal de que você deveria separar as coisas. Como manter o CLAUDE.md otimizado:

• Divulgação progressiva via imports. Mantenha o arquivo principal como um "índice de decisões"; empurre os detalhes longos (arquitetura, convenções de API) para arquivos separados e aponte para eles com @docs/....
• Corte tudo que não muda o comportamento. Histórico do projeto, textos de marketing, explicações prolixas - jogue tudo fora.
• Una duplicatas. Se você já disse "use pnpm" na tech stack, não precisa repetir em outros três lugares.
• Priorize por ROI. Comandos e limites no topo; material "bom saber" no fim ou movido para um import.

Divida regras por caminho com .claude/rules/

Conforme o projeto cresce, amontoar toda convenção em um único CLAUDE.md cada vez mais longo deixa de funcionar. Em vez disso, o Claude Code deixa você dividir as instruções em vários arquivos pequenos dentro de .claude/rules/, cada um dono de uma fatia:

.claude/rules/
├── code-style.md
├── testing.md
└── security.md

Cada arquivo de regra pode carregar frontmatter YAML para limitar quando ele é carregado, usando o campo paths::

---
paths:
  - "src/api/**/*.ts"
---
Validate all input with Zod before writing to the DB.

Uma regra sem paths: (sem escopo) carrega em toda sessão na mesma prioridade que o ./CLAUDE.md. Uma regra com paths: só carrega quando o Claude abre um arquivo que casa com o glob - é exatamente por isso que ela economiza contexto: você não paga tokens por convenções de rota de API enquanto edita CSS. O ~/.claude/rules/ é pessoal, aplica-se a cada um dos seus projetos e carrega antes das regras de nível de projeto.

Isso se conecta à estratégia mais ampla de gestão de tokens - veja Gerenciando Contexto & Memória no Claude Code para onde o .claude/rules/ se encaixa no quadro maior de orçamento de tokens.

Dicas rápidas: /init e a tecla #

Você não precisa escrever o CLAUDE.md do zero. Duas ferramentas embutidas deixam isso muito mais rápido:

• /init - rode este comando no seu projeto e o Claude Code vai escanear o repo e gerar um CLAUDE.md inicial para você (chutando a tech stack, os comandos e a estrutura). Não pegue como está - trate como um rascunho e depois apare até as seis seções essenciais acima.
• A tecla # - enquanto trabalha, digite # seguido de uma nota, e o Claude Code vai se oferecer para salvá-la no CLAUDE.md (você escolhe o arquivo do projeto ou o do usuário). É assim que você adiciona memória de projeto no meio da sessão, no instante em que percebe uma convenção que vale registrar - sem parar para abrir um editor.

Se você está só começando, o fluxo mais enxuto é: rodar /init → aparar o arquivo até o template acima → usar a tecla # para ir construindo com o tempo. Os 10 passos para começar com o Claude Code percorrem esse fluxo inteiro.

Padrões de CLAUDE.md prontos de um kit (AgentKit)

Escrever um bom CLAUDE.md por conta própria leva algumas rodadas de tentativa e erro. Se você quer um atalho, alguns kits como o bundle do AgentKit (já vem com convenções padrão de CLAUDE.md) empacotam convenções de CLAUDE.md junto com regras/skills num padrão consistente, então você não começa de uma página em branco. Não substitui declarar os comandos e limites do seu próprio projeto, mas poupa você da montagem inicial e das convenções que se repetem entre projetos - você pode experimentar o AgentKit (20% de desconto pelo link) para ver a estrutura de exemplo deles e ficar com as partes que combinam com você.

Perguntas frequentes (FAQ)

O nome de arquivo CLAUDE.md diferencia maiúsculas de minúsculas?

Sim. Nomeie exatamente como CLAUDE.md, com a parte do nome toda em maiúsculas. Em sistemas que diferenciam maiúsculas de minúsculas (Linux, comum em CI), um nome errado como claude.md pode fazer o Claude Code não reconhecer o arquivo.

Devo versionar o CLAUDE.md no git?

Sim, o arquivo da raiz do projeto - é uma convenção compartilhada, então versione e o time inteiro trabalha a partir do mesmo contexto. Já o ~/.claude/CLAUDE.md é pessoal e não pertence ao repositório. Anotações pessoais por projeto devem ficar no arquivo de usuário ou em um import, não em um commit.

E se o Claude não seguir o CLAUDE.md?

Costuma ser uma de três causas: o arquivo está longo demais e o sinal se dilui, uma regra importante está enterrada no meio, ou o contexto já está cheio. Correções: encurte o arquivo, mova as restrições de "NÃO faça" para o topo e verifique perguntando ao agente sobre uma regra específica para ver se ele responde certo.

O CLAUDE.md funciona com o Cursor ou outras ferramentas?

O CLAUDE.md é uma convenção do Claude Code. Outras ferramentas usam os próprios arquivos de contexto (por exemplo AGENTS.md ou o arquivo de regras daquela ferramenta). O conteúdo que você escreve costuma ser reaproveitável, mas o nome do arquivo e o mecanismo de carregamento diferem de ferramenta para ferramenta.

Qual deve ser o tamanho do CLAUDE.md?

Mire em torno de 200 linhas, com um teto de 300-500 linhas para projetos grandes. Priorize a qualidade do sinal em vez da contagem de linhas: mantenha só o que muda as decisões do agente e empurre o resto para arquivos importados.

Como o arquivo de projeto é diferente do ~/.claude/CLAUDE.md?

O arquivo de projeto (./CLAUDE.md) guarda convenções que valem para todo o repositório e o time, e é versionado no git. O arquivo de usuário (~/.claude/CLAUDE.md) guarda as suas preferências pessoais, aplica-se a todos os seus projetos e fica fora do repositório. O Claude Code carrega os dois de uma vez quando ambos existem.

Conclusão + próximos passos

O CLAUDE.md é o investimento de menor esforço e maior retorno que você pode fazer com o Claude Code: escreva uma vez e o agente segue as suas convenções em toda sessão. Copie o template acima, apare para o seu projeto, ponha as restrições de "NÃO faça" no topo e mantenha o arquivo enxuto. Se você está só começando, leia os 10 passos para iniciantes; se quer consultas rápidas de comandos, mantenha o guia rápido de comandos do Claude Code ao lado do teclado.