Ao usar o Claude Code em um projeto, surgem duas necessidades: “siga esta regra sempre” e “lembre o que descobrimos da última vez”.
A primeira é responsabilidade do arquivo de regras CLAUDE.md; a segunda, do recurso de memória. Ambos são “instruções que permanecem após o fim da sessão”, o que pode confundir, mas diferem em responsável e natureza.
Neste artigo, organizo a hierarquia do CLAUDE.md, o funcionamento da memória e os critérios para decidir o que colocar em cada lugar.
Vamos começar pelo resumo essencial.
- CLAUDE.md é carregado automaticamente a cada sessão e tem níveis global e de projeto
- A memória registra e recupera, por pasta de projeto, fatos que Claude aprende durante o trabalho
- Regras definidas por pessoas ficam no CLAUDE.md; experiências acumuladas pelo agente ficam na memória
- Ambos consomem contexto, então devem ser mantidos enxutos, considerando “isso é sempre necessário?”
CLAUDE.md: a localização define o escopo
CLAUDE.md é um arquivo Markdown carregado integralmente no prompt ao iniciar a sessão. Ele contém regras que “devem ser sempre verdadeiras”, como convenções de código, proibições e contexto do projeto.
Mesmo arquivos com o mesmo nome têm escopos diferentes conforme a localização.
| Localização | Escopo | Compartilhamento |
|---|---|---|
| ~/.claude/CLAUDE.md | Todos os projetos | Uso pessoal |
| projeto/CLAUDE.md | Projeto correspondente | Compartilhado com a equipe via git |
| subpasta/CLAUDE.md | Ao trabalhar nessa pasta | Compartilhado com a equipe via git |
No arquivo global, coloque preferências pessoais independentes do projeto, como estilo de commit e idioma das respostas; no arquivo do projeto, regras específicas do repositório. Se houver conflito, é mais seguro declarar que a regra mais específica, geralmente a do projeto, tem prioridade.
Quando o arquivo fica longo, você pode dividi-lo importando outros documentos com @경로/파일.md. Porém, os documentos importados também entram no contexto; portanto, o recurso serve para facilitar a manutenção, não para economizar espaço.
Memória: notas escritas pelo próprio agente
Se CLAUDE.md é um conjunto de regras de cima para baixo, escrito por pessoas, a memória segue o caminho oposto. Claude registra em arquivos, numa pasta de memória por projeto, os fatos que aprende durante o trabalho e os reutiliza na sessão seguinte.
A estrutura é simples. Cada memória corresponde a um arquivo, e o arquivo de índice (MEMORY.md) acumula resumos de uma linha. No início da sessão, apenas o índice entra no contexto; o conteúdo de cada memória é lido quando relevante para a tarefa.
O tipo de conteúdo registrado também difere das regras. São fatos que não estão na documentação, mas só se aprendem na prática: “depois do batch, este DB precisa de verificação de tipos” ou “o servidor dev só funciona quando iniciado neste worktree”. É conhecimento experiencial acumulado antes de ser formalizado como regra.
Durante a conversa, você também pode enviar uma mensagem iniciada por # e dizer diretamente: “lembre disso”. Nesse caso, Claude pode perguntar em qual arquivo salvar ou classificar o conteúdo por conta própria.
Critérios para decidir onde colocar cada coisa
Quando os papéis se sobrepõem, use três perguntas.
Primeiro: quem decidiu isso? Se for uma regra definida pela equipe ou por você, é CLAUDE.md; se for um fato descoberto durante o trabalho, é memória.
Segundo: há problema se isso for violado? Regras cuja violação causa incidentes — como proibir commits de chaves secretas ou exigir um procedimento de deploy — devem ficar no CLAUDE.md. A memória é mais uma nota de referência do que um mecanismo de imposição com recuperação garantida.
Terceiro: isso já pode ser descoberto no código ou na documentação? Por princípio, informações que podem ser obtidas apenas lendo o repositório não devem ir para nenhum dos dois. Elas desperdiçam contexto e se tornam falsas quando o código muda.
Duas práticas para manter no dia a dia
Primeiro: faça limpezas periódicas. CLAUDE.md tende a acumular regras sem removê-las. Exclua assim que encontrar regras que já não valem ou instruções usadas uma única vez, evitando desperdiçar contexto em toda sessão. O mesmo vale para a memória: quando o código mudar e um item deixar de ser verdadeiro, apagá-lo é melhor do que mantê-lo.
Segundo: mantenha as regras curtas e assertivas. Frases como “se possível, é melhor fazer ~” são menos eficazes que “faça “ ou “ é proibido”. Adicionar uma linha de exemplo aumenta visivelmente a taxa de conformidade.
Conclusão
CLAUDE.md é a constituição; a memória é o diário de trabalho. Regras imutáveis definidas por pessoas descem de cima, enquanto experiências obtidas em campo se acumulam de baixo para cima.
Ao gerenciar os dois separadamente, você repete menos as mesmas explicações em toda sessão e evita reviver os mesmos problemas da sessão anterior.