Arquivo CLAUDE.md: como escrever, boas práticas e 3 modelos

CLAUDE.md e a memória do Claude Code

Toda sessão do Claude Code começa com a memória zerada. Duas coisas levam conhecimento de uma sessão para a próxima: arquivos CLAUDE.md que você escreve e notas de auto memory que o Claude escreve para si mesmo.

Quando você diz "lembre que eu emito notas fiscais em euros", o Claude salva isso na auto memory, e avisos como "Saved 2 memories" aparecem quando isso acontece. Para colocar uma regra no CLAUDE.md, diga "adicione isto ao CLAUDE.md".

A auto memory vem ligada por padrão e fica em ~/.claude/projects/<project>/memory/: um índice MEMORY.md com uma linha por nota, mais um arquivo pequeno para cada nota. Rode /memory para ler, editar ou desligar.

O Claude lê o CLAUDE.md toda vez?

Sim, automaticamente, no início de toda conversa, inclusive na nova que você ganha depois de um /clear. O Claude Code passa o arquivo ao Claude como uma mensagem logo depois das próprias instruções embutidas, então o Claude lê e tenta seguir, mas nada o obriga. Para bloquear algo de qualquer jeito, use uma regra de permissão, que aparece mais adiante.

Onde fica o arquivo CLAUDE.md: o lugar de cada arquivo

~ significa a sua pasta de usuário (%USERPROFILE% no Windows), e ./ significa a pasta principal do seu projeto.

No Mac, o arquivo global é /Users/seunome/.claude/CLAUDE.md; o Finder esconde pastas que começam com ponto, então aperte Cmd+Shift+. para vê-las. Veja como fica no disco o projeto de uma pequena empresa, com o modelo de dono de negócio mais abaixo salvo como CLAUDE.md:

O Claude Code carrega o CLAUDE.md da pasta em que você o inicia e de todas as pastas acima dela, e os arquivos se somam em vez de se substituírem. Um CLAUDE.md dentro de uma subpasta só carrega quando o Claude começa a trabalhar com arquivos daquela subpasta.

Como o arquivo mais específico é lido por último, uma regra do projeto fica mais perto do trabalho. Mesmo assim, evite contradizer seu arquivo pessoal, porque quando duas regras entram em conflito o Claude pode seguir qualquer uma delas.

Como criar um arquivo CLAUDE.md

1. Abra a pasta do projeto no Claude Code. No terminal, entre na pasta e rode claude; no app desktop, use a aba Code e Select folder.
2. Rode /init. O Claude olha a pasta e escreve um CLAUDE.md inicial. Se já existir um, ele sugere melhorias em vez de sobrescrever, e aproveita regras que você escreveu para o Cursor ou o GitHub Copilot.
3. Ou deixe o Claude te entrevistar. Para uma pasta ainda quase vazia, o prompt abaixo dá resultados melhores que o /init.
4. Edite. O /memory lista seus arquivos CLAUDE.md e abre um deles no seu editor, ou você pode simplesmente dizer "adicione esta regra ao CLAUDE.md".
5. Recarregue. O arquivo é lido no início da sessão, então rode /clear ou comece uma nova sessão depois de editar; a página de prompt caching da Anthropic explica por que edições no meio da sessão esperam.
6. Confira se carregou. Rode /context e procure o arquivo em Memory files.

Rodamos o /init no pequeno projeto de landing page do nosso guia de vibe coding. Ele leu os dois arquivos, mostrou o CLAUDE.md para aprovação (a imagem no topo deste guia) e depois resumiu o que tinha registrado:

Quero um CLAUDE.md para esta pasta. Me faça até 8 perguntas, uma de cada vez, sobre o meu negócio, para quem é o trabalho, meu tom de voz, as regras que eu sempre quero seguidas e o que "pronto" significa para mim. Depois escreva um CLAUDE.md com menos de 60 linhas e títulos claros, e me mostre antes de salvar.

Boas práticas do CLAUDE.md: o que colocar e o que deixar de fora

Trate o CLAUDE.md como o lugar das coisas que você teria que explicar de novo. Um bom sinal para uma nova linha é o Claude cometer o mesmo erro duas vezes, ou você digitar a mesma correção da semana passada.

Qual deve ser o tamanho de um arquivo CLAUDE.md?

Menos de 200 linhas, e bem menos de 100 para a maioria das pastas de negócio. O Claude Code avisa na inicialização, e no /status, quando um arquivo passa do tamanho recomendado ou quando todos os seus arquivos de instruções juntos ficam grandes demais, e ele ignora qualquer arquivo sozinho acima de 4 MiB. Cada linha carrega em toda sessão, então um arquivo enxuto também faz o seu plano render mais, como explica o guia de limites de uso do Claude Code.

Puxe outros arquivos com imports @

Se as suas regras já estão em outro arquivo, importe em vez de copiar. Uma linha como @brand/voice.md carrega aquele arquivo na inicialização, e o caminho é lido a partir da pasta em que o CLAUDE.md está. Arquivos importados podem importar outros, até quatro níveis de profundidade.

• Espaços num caminho precisam de uma barra invertida antes de cada um: @Brand\ Kit/voice.md.
• Para mencionar um caminho sem importar, coloque entre crases.
• Arquivos fora do projeto, como @~/.claude/my-rules.md, disparam uma janela de aprovação única naquele projeto.

Imports deixam tudo organizado, mas não deixam o arquivo mais leve, porque arquivos importados também carregam na inicialização.

Três modelos de CLAUDE.md para copiar

Estes exemplos de CLAUDE.md foram escritos para quem não programa. Cada um tem de 21 a 25 linhas, cerca de um oitavo do teto de 200 linhas da Anthropic, então sobra espaço para as suas próprias regras. Troque tudo o que está entre colchetes, apague o que não se aplica e enxugue de novo depois de uma semana de uso real.

Modelo 1: dono de negócio

Salve como ~/.claude/CLAUDE.md para valer em tudo, ou como CLAUDE.md na pasta que você usa para o trabalho administrativo.

# Sobre mim e o meu negócio
- Eu tenho a [NOME DO NEGÓCIO], um(a) [TIPO DE NEGÓCIO] em [CIDADE OU MERCADO].
- Os clientes são [QUEM SÃO]. Principais produtos ou serviços: [LISTA].
- Não sou desenvolvedor. Explique qualquer coisa técnica em uma frase simples.

# Como trabalhar comigo
- Me faça perguntas antes de começar qualquer coisa que leve mais do que alguns passos.
- Me mostre um plano curto antes de mudar mais de 3 arquivos.
- Responda em [IDIOMA], em parágrafos curtos, sem jargão.

# Regras que sempre valem
- Nunca envie e-mails, mensagens ou pagamentos. Prepare rascunhos para eu enviar.
- Nunca apague arquivos. Mova o que quiser remover para uma pasta chamada _trash.
- Nunca invente números, preços ou fatos. Se faltar algo, me pergunte.
- A moeda é [MOEDA]. As datas são escritas [FORMATO DE DATA].

# Arquivos e pastas
- Documentos recebidos ficam em /inbox. Trabalho pronto vai para /output.
- Nomeie os arquivos como AAAA-MM-DD_assunto.

# Quando terminar uma tarefa
- Liste o que você mudou, o que não conseguiu fazer e qualquer coisa de que não teve certeza.

# Ao compactar
- Mantenha a lista de arquivos alterados e as perguntas em aberto.

A última seção segue uma dica da página de boas práticas da Anthropic: uma instrução "ao compactar" diz ao Claude o que manter quando ele resume uma conversa longa.

Modelo 2: profissional de marketing

Salve como CLAUDE.md na sua pasta de marketing. Para fluxos completos de marketing que usam esse arquivo, veja Claude Code para marketing.

# Marca
- Marca: [NOME DA MARCA]. Vendemos [OFERTA] para [PÚBLICO].
- Voz: [TRÊS ADJETIVOS]. Soamos como [EXEMPLO], nunca como [ANTIEXEMPLO].
- Palavras que nunca usamos: [LISTA].
- Ortografia: português do [BRASIL OU PORTUGAL].

# Fatos e afirmações
- Use só os fatos de /brand/facts.md e dos arquivos que eu te passar.
- Toda estatística precisa de um link de fonte. Se não encontrar, deixe o número de fora.
- Não cite concorrentes a menos que eu peça.

# Canais e formatos
- LinkedIn: menos de [NÚMERO] palavras, uma ideia por post.
- E-mail: assunto com menos de [NÚMERO] caracteres, uma chamada para ação.
- Legendas do Instagram: o gancho vai na primeira linha, menos de [NÚMERO] palavras no total.

# Arquivos
- Briefings ficam em /briefs. Rascunhos vão para /drafts, um arquivo por peça, nomeado canal_assunto_data.

# Antes de dizer que terminou
- Confira cada afirmação com os arquivos de origem e liste o que não tiver respaldo.

Modelo 3: projeto de site

Salve como CLAUDE.md na pasta principal do site. O guia de como criar um site com IA mostra um projeto completo que combina bem com ele.

# Projeto
- Site da [NOME DO NEGÓCIO]: [PARA QUE SERVE O SITE].
- A única ação que queremos dos visitantes: [POR EXEMPLO, AGENDAR UMA CONVERSA].
- Feito com [STACK, POR EXEMPLO HTML E CSS PUROS]. Hospedado em [HOSPEDAGEM].

# Comandos
- Pré-visualizar localmente: [COMANDO]
- Checar antes de publicar: [COMANDO]

# Regras de design
- Cores: [CÓDIGOS HEX]. Fontes: [FONTES]. Mantenha bastante espaço em branco.
- Mobile primeiro: confira cada mudança na largura de celular antes de dizer que está pronta.
- Toda imagem precisa de texto alternativo. Botões dizem o que acontece depois ("Agendar conversa", não "Enviar").

# Regras de conteúdo
- Use só os textos de /content e fatos que eu confirmar. Nada de avaliações, números ou logos inventados.
- Toda página precisa do próprio título e da própria meta description.

# Não faça
- Não adicione bibliotecas, plugins ou serviços novos sem me perguntar.
- Não mude configurações de domínio, DNS ou hospedagem.

# Pronto significa
- O comando de checagem passa, a página funciona na largura de celular e você lista o que mudou.

Vale copiar o CLAUDE.md do Karpathy?

O arquivo que as pessoas chamam de "CLAUDE.md do Karpathy" é um arquivo da comunidade montado a partir dos posts de Andrej Karpathy sobre os erros que as ferramentas de código com IA cometem; ele mesmo não publicou o arquivo. São 65 linhas em quatro seções (pense antes de programar, simplicidade primeiro, mudanças cirúrgicas, execução guiada por objetivos), e o repositório no GitHub tinha cerca de 221.000 estrelas em outubro de 2026.

Se você programa, ele é uma boa base para colar acima das regras do seu próprio projeto. Se não programa, duas ideias dele valem para você: perguntar quando algo não está claro em vez de chutar, e combinar como o sucesso vai ser conferido antes de começar. Os modelos 1 e 3 já cobrem as duas em linguagem simples, com "me faça perguntas antes de começar" e a seção "Pronto significa".

Quando o CLAUDE.md não basta

O guia de como criar uma skill do Claude mostra como transformar um procedimento em skill. Para regras deny, o guia de permissões da Anthropic tem a sintaxe, e nossa cola do Claude Code inclui um arquivo de configurações inicial.

CLAUDE.md vs AGENTS.md

O AGENTS.md é a mesma ideia para outras ferramentas de código, como o Codex da OpenAI. Desde a versão 2.1.277, o Claude Code lê um AGENTS.md sozinho, mas só quando não há CLAUDE.md nem CLAUDE.local.md na sua pasta ou acima dela.

Para manter um único conjunto de regras para todas as ferramentas, coloque @AGENTS.md na primeira linha do seu CLAUDE.md e acrescente abaixo as regras só do Claude. Para o Claude ler os dois arquivos sem import, abra o /config e defina Project instructions como claude-md-and-agents-md.

CLAUDE.md não funciona? Soluções para os problemas comuns

Se uma regra precisa valer todas as vezes, passe para uma regra de permissão ou um hook em vez de escrevê-la mais alto.

O que fazer agora

Abra a pasta de projeto que você mais usa, rode /init ou o prompt de entrevista, e mantenha o resultado abaixo de 60 linhas na primeira semana. Cada vez que corrigir o Claude, pergunte se essa correção pertence ao arquivo, e remova o que o Claude já faz sozinho. O tutorial de Claude Code para iniciantes mostra o CLAUDE.md funcionando num projeto real, e o treinamento de Claude Code da ai school tem uma aula completa sobre o arquivo CLAUDE.md, seguida de uma sobre skills e MCP.