Pular para o conteúdo principal

CLAUDE.md e arquivos de memória

Iniciante

Se você fizer uma coisa para melhorar o Claude Code, faça esta. O CLAUDE.md é um arquivo de texto simples que o Claude lê no início de cada sessão — o briefing permanente do seu projeto.

What you'll learn
  • Por que o CLAUDE.md é a configuração de maior alavancagem do Claude Code
  • Como a hierarquia de memória é carregada, da política gerenciada até o CLAUDE.local.md
  • Como a memória automática difere do CLAUDE.md que você escreve
  • Como gerar um arquivo inicial com /init e enxugá-lo
  • O que vai no CLAUDE.md — e o que deixar de fora
  • Como as @imports permitem referenciar documentos sem duplicá-los

Por que é a configuração de maior alavancagem​

Sem ele, você reexplica seu projeto a cada sessão ("usamos pnpm, os testes ficam em __tests__, não mexa em /generated…"). Com ele, o Claude já sabe. Boas instruções aqui melhoram todas as interações futuras de uma só vez.

A hierarquia de memória​

O Claude Code carrega a memória de vários locais e os mescla na ordem de carregamento, do escopo mais amplo primeiro — então uma instrução de projeto entra no contexto depois de uma instrução de usuário:

  • Política gerenciada — instruções em nível de organização que sua equipe de TI/DevOps distribui. O caminho varia por sistema operacional: /Library/Application Support/ClaudeCode/CLAUDE.md no macOS, /etc/claude-code/CLAUDE.md no Linux e no WSL, C:\Program Files\ClaudeCode\CLAUDE.md no Windows.
  • Instruções de usuário (~/.claude/CLAUDE.md) — suas preferências pessoais em todos os projetos.
  • Instruções de projeto (./CLAUDE.md ou ./.claude/CLAUDE.md, versionadas) — como este repositório funciona. Compartilhadas com sua equipe. Se o seu repositório usa AGENTS.md, ele pode ser carregado em vez destes arquivos ou junto com eles.
  • Instruções locais (./CLAUDE.local.md) — anotações específicas do projeto só para você, como a URL de um sandbox. Adicione-o ao .gitignore.

Arquivos na hierarquia de diretórios acima do seu diretório de trabalho são carregados na inicialização; arquivos em subdiretórios são carregados sob demanda, quando o Claude mexe em algo naquela área.

Pro tip
  • Um arquivo só já não basta? Divida as instruções em .claude/rules/*.md — um tópico por arquivo, descobertos recursivamente. Regras sem o frontmatter paths são carregadas na inicialização com a mesma prioridade do .claude/CLAUDE.md; adicione o frontmatter paths para carregar uma regra apenas quando o Claude trabalhar em arquivos correspondentes, o que economiza contexto.
Conheça suas camadas de memória
Pressione Enter ou Espaço para virar o cartão. Use as setas esquerda e direita para navegar entre os cartões.Termo exibido.
1 / 6

A outra metade: a memória automática​

O CLAUDE.md é a metade da memória que você escreve. O Claude Code também mantém a memória automática — anotações que o próprio Claude escreve a partir das suas correções e preferências, armazenadas por repositório e carregadas em cada sessão junto com os seus arquivos CLAUDE.md.

Arquivos CLAUDE.mdMemória automática
Quem escreveVocêO Claude
O que contémInstruções e regrasAprendizados e padrões
EscopoProjeto, usuário ou organizaçãoPor repositório, compartilhada entre worktrees

As duas são contexto, não imposição: o Claude as trata como orientação que pode ponderar, não como configuração que precisa obedecer. Para bloquear uma ação de forma definitiva, independentemente do que o Claude decidir, use um hook PreToolUse.

Watch out
  • A memória automática carrega apenas as primeiras 200 linhas ou 25 KB — um MEMORY.md inflado é truncado silenciosamente. Veja Auditoria de Orçamento de Contexto para o detalhamento completo do custo de inicialização.

Gere um ponto de partida​

Guided walkthrough1 of 3
  1. O Claude inspeciona o código e esboça um CLAUDE.md para você automaticamente.

Gerar um rascunho de CLAUDE.md

/init

Pegue um modelo pronto em Modelos de CLAUDE.md.

O que colocar nele​

  • O que é o projeto, em duas frases.
  • A stack tecnológica e como executar / testar / fazer lint.
  • Convenções que o Claude não consegue inferir (nomenclatura, estrutura, estilo de commit).
  • Proteções: "execute os testes antes de declarar concluído", "nunca edite /vendor", "nunca faça commit de segredos".

O que NÃO colocar nele​

Watch out
  • O Claude segue o CLAUDE.md literalmente — instruções desatualizadas, vagas ou idealizadas prejudicam ativamente.
  • Descreva como o projeto realmente funciona hoje; curto e verdadeiro vence longo e aspiracional.
  • Evite documentos gigantes colados (use @imports em vez disso), segredos e regras que você não segue de fato.
  • Revise-o periodicamente para que continue preciso à medida que o projeto evolui.

Importações​

Traga documentos existentes em vez de duplicá-los — por exemplo, referencie seu guia de estilo com uma importação @path/to/file para que haja uma única fonte da verdade. Caminhos relativos e absolutos funcionam; os relativos são resolvidos a partir do arquivo que contém a importação, e não do seu diretório de trabalho. Arquivos importados podem importar outros, até uma profundidade máxima de quatro saltos.

Duas armadilhas de sintaxe que vale conhecer antes de cair nelas:

  • Espaços exigem barras invertidas. @Design\ Docs/api-conventions.md funciona; sem a barra invertida o caminho para no primeiro espaço. Envolvê-lo em aspas não importa o arquivo de jeito nenhum.
  • Backticks cancelam a importação. A análise de importações ignora trechos de código e blocos cercados, então `@README` permanece texto literal, enquanto @README sozinho importa o arquivo. É assim que você menciona um caminho sem carregá-lo.

Veja a documentação oficial de memória para a referência completa.

Pro tip
  • Uma única fonte da verdade: referencie um arquivo com @imports em vez de colar o conteúdo dele no CLAUDE.md.
  • Se um documento já existe, faça um link para ele — não o copie. Cópias ficam desatualizadas.

Teste seus conhecimentos​

Teste seus conhecimentos

0/6
  1. Qual arquivo o Claude Code lê no início de cada sessão como o briefing permanente do seu projeto?
  2. O que executar /init faz em um projeto?
  3. Qual é a maneira recomendada de incluir um documento grande já existente, como um guia de estilo?
  4. Onde ficam as anotações pessoais e específicas do projeto — aquelas que você não quer versionar?
  5. Quem escreve a memória automática?
  6. Um CLAUDE.md em um subdiretório é carregado quando?
Key takeaways
  • O CLAUDE.md é a configuração de maior alavancagem: melhora todas as sessões futuras de uma só vez.
  • A memória carrega do escopo mais amplo primeiro: política gerenciada, depois usuário (~/.claude/CLAUDE.md), projeto (./CLAUDE.md ou ./.claude/CLAUDE.md) e por fim local (./CLAUDE.local.md). Arquivos em subdiretórios são carregados sob demanda.
  • A memória automática é a outra metade — as anotações do próprio Claude, por repositório, carregadas em cada sessão. As duas são contexto, não imposição: use um hook para bloquear algo de forma definitiva.
  • Um arquivo só já não basta? Divida-o em .claude/rules/*.md e delimite as regras com o frontmatter paths.
  • Comece com /init, depois enxugue o rascunho para o que é de fato verdadeiro.
  • Mantenha-o curto e verdadeiro — use @imports (máximo de quatro saltos) para documentos grandes e nunca faça commit de segredos.

Próximos passos​