Ir para o conteúdo
Promovaweb

CLAUDE.md e memória do Claude Code

StayCloudVPS Agêntica

Uma VPS para os seus agentes trabalharem dia e noite

Instale o SetupVibe Desktop numa VPS da StayCloud em São Paulo, com acesso root e disco NVMe. Deixe Claude Code, Codex e OpenCode rodando no tmux ou no Herdr e feche o notebook sem interromper nada.

Montar minha VPS Agêntica

Link de parceiro da Promovaweb.

Black Friday até 30/11

30%off

nos 2 primeiros meses do plano mensal da VPS

  • Backup diário grátis para sempre
  • Servidores em São Paulo no datacenter da Ascenty
  • Datacenter Tier III manutenção sem parada
  • Acesso root com disco SSD NVMe
  • Réplica do backup em Ashburn, nos EUA

O CLAUDE.md é um arquivo Markdown que você escreve com as convenções do projeto e que o Claude Code carrega no começo de toda sessão. A auto memory é o outro lado: notas que o próprio agente grava durante o trabalho com as suas correções e preferências, também lidas quando uma sessão nova começa.

Sumário da página

  1. Cada sessão começa do zero
  2. Onde o CLAUDE.md pode ficar
  3. Instruções que o agente consegue seguir
  4. AGENTS.md e outros agentes
  5. A memória que o agente grava sozinho
  6. O que fica de fora

Cada sessão começa do zero

Toda sessão nova do Claude Code abre com a janela de contexto vazia. Ontem você explicou que os testes rodam com npm run test:unit e que os handlers da API ficam em src/api/handlers/. Essa conversa não chega à sessão de hoje. Sem um registro escrito, você repete as mesmas instruções e o agente volta a procurar as mesmas pastas.

O Claude Code resolve isso com dois sistemas que se completam. O CLAUDE.md é escrito por você e guarda instruções e convenções. A auto memory é escrita pelo Claude e guarda aprendizados. Os dois carregam no início de cada conversa. A documentação deixa claro que ambos entram como informação para o modelo, não como configuração imposta. Para barrar uma ação de qualquer jeito, o caminho é uma entrada deny nas permissões ou um hook PreToolUse.

Onde o CLAUDE.md pode ficar

O arquivo existe em quatro escopos, carregados do mais amplo para o mais específico. A instrução do projeto aparece depois da instrução pessoal, então é lida por último.

  • /etc/claude-code/CLAUDE.mdPolítica da organização no Linux e no WSL, distribuída pela área de TI.
  • ~/.claude/CLAUDE.mdSuas preferências pessoais, válidas em todos os projetos.
  • projeto/Raiz do repositório.
  • CLAUDE.mdConvenções do projeto, versionadas no Git. Também aceito em .claude/CLAUDE.md.
  • CLAUDE.local.mdAjustes pessoais daquele projeto, fora do Git.
  • .claude/rules/Instruções por assunto, que podem valer só para alguns caminhos.
Os quatro lugares do CLAUDE.md, do escopo mais amplo ao mais específico, como descritos na documentação de memória da Anthropic.

No macOS, a política da organização fica em /Library/Application Support/ClaudeCode/CLAUDE.md. No Windows, em C:\Program Files\ClaudeCode\CLAUDE.md. O comando /init gera um CLAUDE.md inicial a partir da leitura do projeto. O /memory abre os arquivos carregados para você conferir e editar.

O agente lê o CLAUDE.md e o CLAUDE.local.md da pasta onde você abriu a sessão e de todas as pastas acima dela. Os arquivos não se sobrepõem: eles são concatenados, da raiz do disco até a pasta atual. Arquivos em subpastas carregam sob demanda, quando o agente lê ou edita algo naquela subpasta. Num monorepo, cada pacote pode ter o próprio CLAUDE.md sem pesar nas sessões dos outros pacotes.

Instruções que o agente consegue seguir

A documentação recomenda instruções concretas o bastante para serem conferidas. “Use indentação de dois espaços” funciona melhor que “formate o código direito”. “Rode npm test antes do commit” funciona melhor que “teste as mudanças”. “Os handlers da API ficam em src/api/handlers/” funciona melhor que “mantenha os arquivos organizados”.

O tamanho também pesa. A recomendação é ficar abaixo de 200 linhas por arquivo, porque um arquivo longo ocupa mais janela de contexto e reduz a aderência às instruções. Instruções que só interessam a uma parte do código vão para .claude/rules/, com o campo paths no frontmatter. Esses arquivos só carregam quando o agente trabalha com arquivos que casam com o padrão. Duas instruções que se contradizem fazem o modelo escolher uma delas de forma imprevisível. Por isso vale revisar os arquivos de tempos em tempos.

O CLAUDE.md aceita importar outros arquivos com a sintaxe @caminho/do/arquivo, com até quatro níveis de importação. O import divide um arquivo longo em partes, mas não reduz o custo, porque o arquivo importado carrega junto. Comentários HTML em bloco são removidos antes de o conteúdo chegar ao modelo, o que permite deixar notas para os colegas do projeto sem gastar janela de contexto.

AGENTS.md e outros agentes

Se o repositório já tem um AGENTS.md para outros agentes de código, o Claude Code lê esse arquivo como instrução do projeto quando não existe CLAUDE.md na pasta nem acima dela. Com os dois arquivos presentes, ele lê só o CLAUDE.md. Para manter um arquivo único entre ferramentas, o CLAUDE.md pode importar o AGENTS.md. A leitura direta do AGENTS.md exige a versão 2.1.277 ou posterior.

A memória que o agente grava sozinho

A auto memory funciona sem você escrever nada. Durante o trabalho, o Claude anota quatro tipos de nota: o seu papel e a sua forma de trabalhar, as correções que você faz e as abordagens que confirma, o andamento do projeto que não aparece no código nem no histórico do Git e onde encontrar informação fora do repositório, como um quadro de tarefas ou um painel. Ele pula o que consegue tirar do código e o que o CLAUDE.md já diz.

Cada projeto tem a própria pasta de memória em ~/.claude/projects/<projeto>/memory/, compartilhada entre os worktrees do mesmo repositório. O arquivo MEMORY.md funciona como índice. As primeiras 200 linhas ou os primeiros 25 KB, o que vier primeiro, carregam em toda sessão. Notas detalhadas ficam em arquivos de tópico que o agente lê só quando o assunto aparece. Quando a interface mostra mensagens como “Saved 2 memories”, o agente está gravando nessa pasta.

O que fica de fora

Instruções não substituem permissões. Uma instrução escrita orienta o comportamento, mas o modelo pode deixar de seguir uma frase ambígua ou perdida no meio de um arquivo grande. Depois de uma compactação longa, o que foi dito no começo da conversa pode sair do resumo. O CLAUDE.md da raiz volta a ser lido, por isso as instruções permanentes moram nele e não na conversa. Procedimentos longos, que só valem para uma tarefa, ficam melhor numa skill, assunto do próximo hub.