Guia

Como escrever um arquivo CLAUDE.md para o Claude Code

Toda sessão do Claude Code começa com o contexto vazio, então você acaba repetindo os mesmos comandos de build e as mesmas regras da casa. Um arquivo CLAUDE.md resolve isso. Este guia mostra onde ele fica, o que colocar nele e como conferir se o Claude está mesmo lendo o arquivo.

Atualizado em 30 de outubro de 2026

Resposta rápida: o CLAUDE.md é um arquivo Markdown simples que o Claude Code carrega no início de toda sessão. Coloque o do projeto em ./CLAUDE.md (ou ./.claude/CLAUDE.md), rode /init para o Claude escrever um rascunho a partir do seu código e depois enxugue o arquivo até ficar só com os comandos, as convenções e as regras que o Claude não consegue adivinhar, de preferência com menos de 200 linhas.

Os locais e comandos abaixo foram conferidos na documentação do Claude Code da Anthropic em outubro de 2026. Se algo não aparecer na sua versão, rode claude update.

Onde ficam os arquivos CLAUDE.md

Você pode ter vários arquivos, cada um com um alcance diferente. O Claude Code junta todos em vez de deixar um substituir o outro; os mais específicos são lidos por último.

Arquivo	Vale para	Conteúdo típico
`~/.claude/CLAUDE.md`	Você, em todos os projetos	Preferências pessoais de estilo e de ferramentas
`./CLAUDE.md` ou `./.claude/CLAUDE.md`	Todo mundo no projeto (faça commit dele)	Comandos de build e de teste, arquitetura, convenções
`./CLAUDE.local.md`	Só você, neste projeto	Suas URLs de sandbox, dados de teste; adicione-o ao `.gitignore`
Arquivo de política gerenciada (definido pela TI)	Todo mundo na organização	Padrões da empresa e lembretes de compliance

Os arquivos da pasta onde você inicia o Claude e de todas as pastas acima dela são carregados na inicialização. Um CLAUDE.md dentro de uma subpasta é carregado depois, quando o Claude lê ou edita um arquivo nessa subpasta.

Crie o arquivo com /init

Abra um terminal na pasta raiz do projeto e inicie o claude.
Digite /init. O Claude percorre o código e escreve um CLAUDE.md inicial com os comandos de build, as instruções de teste e as convenções que encontrar. Se já existir um CLAUDE.md, ele sugere melhorias em vez de sobrescrevê-lo.
Leia o rascunho e apague o que for óbvio ou estiver errado.
Acrescente o que o Claude não consegue descobrir pelo código: decisões, particularidades do ambiente, regras do tipo "nunca faça X".
Faça commit do arquivo para que os colegas recebam as mesmas instruções.

Para editar depois, rode /memory. Ele lista os locais do CLAUDE.md e do CLAUDE.local.md nos escopos de usuário e de projeto, inclusive os que ainda não existem, e abre no seu editor o arquivo que você escolher. Você também pode simplesmente dizer adicione isto ao CLAUDE.md.

O que colocar nele

Um teste simples: se você já precisou dizer algo ao Claude duas vezes, isso vai para o arquivo. Momentos típicos para acrescentar uma linha: o Claude repete um erro, uma revisão de código pega algo que ele deveria saber, ou você digita a mesma correção que digitou na sessão anterior.

Comandos: como fazer build, testar, rodar o lint e executar o projeto.
Estrutura: onde fica o código principal, por exemplo os handlers da API estão em src/api/handlers/.
Convenções: nomes, formatação, regras de branch e de commit.
Lições aprendidas: coisas que fariam um colega novo tropeçar.

Escreva regras que dê para conferir. Rode npm test antes de fazer commit funciona melhor do que teste suas mudanças. Agrupe as linhas sob títulos e tópicos e remova instruções que se contradizem, porque o Claude pode seguir qualquer uma delas. Procedimentos de vários passos ou regras que só importam para uma parte do código ficam melhor em uma skill ou em uma regra limitada a certos caminhos.

Mantenha o arquivo curto e organizado

Tamanho: procure ficar abaixo de 200 linhas por arquivo. Arquivos mais longos ocupam mais contexto e são seguidos com menos consistência.
Importações: escreva @README ou @docs/git-instructions.md para incluir outro arquivo. Os caminhos são relativos ao CLAUDE.md, e as importações podem se aninhar em até quatro níveis. Os arquivos importados continuam ocupando contexto, então isso ajuda na organização, não no tamanho. Na primeira vez que um projeto importa um arquivo de fora da pasta, o Claude Code pede a sua aprovação.
Pasta de regras: coloque arquivos por tema, como testing.md, em .claude/rules/. Adicione um campo paths no topo (por exemplo src/api/**/*.ts) e a regra só é carregada quando o Claude trabalha em arquivos correspondentes.
Revisão: nas versões recentes, /doctor prompt-audit pede ao Claude que procure instruções desatualizadas ou conflitantes e proponha edições, sem mudar nada até você concordar.

CLAUDE.md x memória automática

O Claude Code também guarda anotações próprias, chamadas de memória automática (auto memory). Você escreve o CLAUDE.md; o Claude escreve a memória automática a partir das suas correções e preferências. Ela fica por repositório em ~/.claude/projects/<project>/memory/, com um índice MEMORY.md cujas primeiras 200 linhas (ou 25KB) são carregadas em cada sessão. Ela fica no seu computador e não é compartilhada pelo git. Quando você diz lembre-se de sempre usar pnpm, isso vai para a memória automática; ligue ou desligue o recurso com a chave em /memory. Use o CLAUDE.md para tudo o que o time inteiro deve receber.

Bom saber

O Claude Code vem com os planos Pro e Max, na mesma assinatura dos apps do Claude; membros de Team e Enterprise têm um artigo de ajuda separado.
O CLAUDE.md orienta o comportamento, mas não o impõe. Bloqueie comandos ou arquivos com regras de permissão nas configurações.
O CLAUDE.md da raiz do projeto é lido de novo do disco depois de /compact, então as regras que estão nele sobrevivem a sessões longas, enquanto regras que você só digitou no chat podem se perder. Os arquivos de subpastas e as regras limitadas a caminhos voltam quando o Claude mexe de novo em arquivos correspondentes.
Os arquivos em pastas adicionadas com --add-dir não são carregados, a menos que você defina CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1.

Se não funcionar

O Claude ignora uma instrução. Rode /context e procure em Memory files (arquivos de memória). Se o arquivo não estiver na lista, o Claude não o enxerga: confira o nome do arquivo e se você iniciou o Claude na pasta certa.
As regras são seguidas só às vezes. Deixe-as mais específicas, elimine conflitos com outros arquivos CLAUDE.md ou de regras e encurte o arquivo.
Uma importação não carrega. Um caminho com espaços precisa de uma barra invertida antes de cada espaço, um caminho entre aspas não é importado, e um caminho entre crases fica literal. Importações de fora do projeto precisam da sua aprovação, uma única vez.
O CLAUDE.md de uma subpasta parece não existir. Ele só é carregado depois que o Claude mexe em um arquivo dessa subpasta.

Guarde decisões e pendências fora do arquivo

O CLAUDE.md é para regras duradouras, não para as tarefas abertas desta semana. O plugin do Workbranch para o Claude Code cuida dessa parte: rode /workbranch:save e o Claude organiza as tarefas, decisões e dúvidas em aberto da sessão em um projeto do Workbranch, e quando uma sessão começa em uma pasta vinculada a um projeto do Workbranch, o plugin mostra o que ainda está pendente ali. Há um teste grátis de 3 dias em app.workbranch.ai.

Fontes

How Claude remembers your project (Claude Code Docs, conferido em 2026-10-30)
Commands (Claude Code Docs, conferido em 2026-10-30)
Use Claude Code with your Pro or Max plan (Central de Ajuda do Claude, conferido em 2026-10-30)

Perguntas frequentes

O Claude é obrigado a seguir o CLAUDE.md?

Não. A Anthropic o descreve como contexto, não como configuração imposta. Para algo que nunca pode acontecer, como um comando que precisa ser bloqueado, use uma regra de negação de permissão ou um hook PreToolUse.

Posso deixar no CLAUDE.md anotações que o Claude não lê?

Sim. Comentários HTML em bloco são removidos antes de o arquivo ser enviado ao Claude, então você pode deixar notas para quem mantém o projeto sem gastar contexto com elas.

Meu repositório já tem um AGENTS.md. Preciso dos dois?

Não. Se não houver um CLAUDE.md na pasta ou acima dela, as versões recentes do Claude Code leem o AGENTS.md no lugar. Se você tiver os dois, só o CLAUDE.md é lido, a menos que você importe o AGENTS.md a partir dele ou mude a configuração Project instructions em /config.