O Que CLAUDE.md Realmente Faz: Memória Persistente de Projeto Explicada
Toda vez que você inicia uma nova conversa com o Claude Code, ele não sabe nada sobre seu projeto, exceto o que pode ver nos próprios arquivos.
Ele não se lembra que você pediu ontem para sempre usar uma biblioteca de testes específica, ou que sua equipe nunca faz commit diretamente em main.
CLAUDE.md existe para preencher essa lacuna.
É um arquivo markdown simples, registrado em seu repositório, que o Claude Code lê automaticamente para que as convenções, a estrutura e as regras do seu projeto persistam entre as sessões, em vez de evaporarem no momento em que uma conversa termina.
Resumo
- Ideia Central: CLAUDE.md é um arquivo de memória de projeto que dá ao Claude Code conhecimento persistente das convenções, estrutura e regras do seu projeto entre as sessões.
- Por Que Importa: Sem ele, cada sessão começa do zero, e você acaba repetindo as mesmas instruções em prompt após prompt.
- Conceitos Chave: memória de projeto, persistência de sessão, convenções vs. instruções, escopo aninhado, o bootstrap
/init. - Quando Usar: Qualquer projeto ao qual você retorna mais de uma vez, qualquer repositório de equipe com convenções compartilhadas e qualquer base de código com regras que um agente de codificação genérico não adivinharia por conta própria.
- Limitações / Compromissos: CLAUDE.md é tão útil quanto o que você coloca nele - orientações vagas são ignoradas, e um arquivo desatualizado pode induzir o Claude Code a erro se ele se desviar do código real.
- Tópicos Relacionados: bootstrap com
/init, escrevendo regras que realmente são seguidas, herança de escopo de CLAUDE.md aninhado.
Fundamentos
Em sua forma mais simples, CLAUDE.md é apenas um arquivo markdown chamado CLAUDE.md na raiz do seu projeto.
O Claude Code o procura automaticamente e carrega seu conteúdo como contexto antes de começar a trabalhar em sua solicitação.
Pense nele como o documento de integração do projeto, exceto que o leitor é um agente de codificação de IA em vez de um novo contratado.
Uma analogia útil é a primeira semana de um novo engenheiro.
Um bom documento de integração informa qual gerenciador de pacotes usar, onde estão os testes e quais padrões a equipe padronizou, para que ele não precise adivinhar ou perguntar em cada tarefa.
CLAUDE.md desempenha o mesmo papel para o Claude Code, exceto que ele é relido no início de cada sessão em vez de ser lido uma vez e meio esquecido.
O arquivo geralmente cobre coisas como a pilha de tecnologia do projeto, estrutura de pastas, convenções de codificação, abordagem de testes e quaisquer regras rígidas ("nunca edite arquivos gerados diretamente", "sempre execute o linter antes de finalizar").
Um exemplo mínimo pode parecer assim:
# Projeto: Order Service
- Linguagem: TypeScript, modo estrito.
- Testes ficam em `__tests__/`, espelhando a estrutura de pastas de origem.
- Nunca modifique arquivos sob `generated/` - eles são reconstruídos por `npm run codegen`.
- Use a utilidade `logger` existente em vez de `console.log`.Nada aqui é exótico. É a mesma informação que você colocaria em um README para um humano, apenas direcionada a um agente que o lê do zero a cada vez.
Mecânica e Interações
A mecânica que torna CLAUDE.md diferente de um prompt único é quando ele é lido.
Um prompt só existe para a conversa em que foi digitado. CLAUDE.md é carregado automaticamente no início de uma nova sessão, antes que você tenha digitado qualquer coisa, o que o torna "persistente" em vez de "lembrado".
O Claude Code não está realmente retendo memória entre as sessões da maneira que um humano faria.
Cada nova conversa ainda é uma lousa em branco em termos de histórico de chat anterior.
O que muda é que a lousa em branco agora inclui o conteúdo de CLAUDE.md como parte de seu contexto inicial, para que o agente se comporte como se já conhecesse as convenções do projeto.
Isso tem algumas consequências práticas que valem a pena internalizar:
- O conteúdo de CLAUDE.md compete por espaço na janela de contexto junto com seus prompts, leituras de arquivos e saída de ferramentas, então não é gratuito - um arquivo inchado tem um custo real.
- Como é um arquivo normal em seu repositório, ele é versionado, comparável e revisável através do mesmo processo de pull-request de qualquer outra alteração.
- Ele pode ser em camadas: um CLAUDE.md raiz define regras para todo o projeto, e arquivos CLAUDE.md aninhados em subpastas adicionam regras mais específicas que se aplicam apenas dentro desse escopo.
- É descritivo, não imposto - o Claude Code o segue porque as instruções estão em seu contexto, não por causa de qualquer barreira técnica rígida que impeça o desvio.
Esse último ponto é importante. CLAUDE.md é uma orientação que o agente lê e raciocina, não um sistema de permissão.
Se uma regra genuinamente nunca deve ser violada, apoie-a com algo imposto fora do modelo, como uma verificação de CI ou um hook de pré-commit, além de declará-la em CLAUDE.md.
Considerações Avançadas e Aplicações
À medida que um projeto cresce, CLAUDE.md tende a crescer com ele, e esse crescimento precisa de gerenciamento ativo em vez de acúmulo passivo.
Um arquivo que começa com dez linhas focadas pode se tornar silenciosamente duzentas linhas de histórico parcialmente relevante se ninguém o podar.
Como CLAUDE.md consome orçamento de contexto em cada sessão, um arquivo grande ou mal organizado tem um custo real: ele pode lotar o espaço para os arquivos e conversas reais que o agente precisa para raciocinar sobre sua tarefa atual.
É por isso que regras concretas e atuais superam as exaustivas - um arquivo mais curto com orientação precisa e específica supera um arquivo longo preenchido com generalidades ou notas desatualizadas.
Equipes que trabalham em várias partes de uma grande base de código geralmente passam de um único CLAUDE.md raiz para uma estrutura aninhada, onde uma pasta de backend e uma pasta de frontend carregam seus próprios CLAUDE.md com regras específicas para essa área, sobrepostas ao arquivo raiz compartilhado.
Isso mantém cada arquivo focado e relevante para o trabalho que está realmente acontecendo naquele subdiretório, em vez de forçar cada sessão a carregar regras para partes da base de código que ela não está tocando.
| Abordagem | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
| CLAUDE.md raiz único | Simples, um lugar para procurar, fácil de manter sincronizado | Pode se tornar difícil de gerenciar em bases de código grandes e multi-domínio | Projetos pequenos a médios, repositórios de equipe única |
| Arquivos CLAUDE.md aninhados | As regras permanecem com escopo e relevantes para o subdiretório em que se está trabalhando | Mais arquivos para manter consistentes, requer compreensão da herança de escopo | Grandes monorepos, projetos multi-pacote |
| Sem CLAUDE.md | Manutenção zero | Cada sessão reexplica as convenções do zero, resultados inconsistentes | Scripts descartáveis, experimentos únicos |
CLAUDE.md também interage com a forma como uma sessão evolui ao longo do tempo. À medida que uma conversa se prolonga e sua janela de contexto enche, ferramentas como /compact e /clear entram em jogo para gerenciar esse orçamento - mas o CLAUDE.md em si é recarregado do zero no início de cada nova sessão, independentemente, o que é exatamente o que o torna uma âncora durável em vez de algo que se deteriora à medida que uma conversa progride.
Conceitos Equivocados Comuns
- "CLAUDE.md significa que o Claude se lembra de nossas conversas passadas." - Não. Cada sessão ainda é independente; CLAUDE.md apenas garante que as mesmas informações de fundo estejam presentes todas as vezes, o que produz um comportamento semelhante à memória sem recall real entre sessões.
- "Mais longo é sempre melhor." - Um CLAUDE.md inchado custa orçamento de contexto em cada sessão e enterra as regras que importam. Conciso e específico supera exaustivo.
- "É imposto como um sistema de permissão." - CLAUDE.md é contexto que o agente lê e raciocina, não uma barreira técnica rígida. Regras críticas ainda precisam de imposição fora do modelo, como verificações de CI.
- "Um CLAUDE.md tem que cobrir todo o codebase igualmente." - Arquivos CLAUDE.md aninhados permitem que diferentes partes de um grande projeto carreguem suas próprias regras com escopo sobrepostas ao arquivo raiz.
- "É documentação opcional, então a precisão não importa muito." - Um CLAUDE.md desatualizado ou impreciso induz o agente a erro ativamente, pois é confiável como contexto de projeto atual por padrão.
FAQs
Qual nome e localização de arquivo o Claude Code realmente procura?
Um arquivo chamado CLAUDE.md, tipicamente na raiz do projeto. Versões aninhadas do mesmo nome de arquivo também podem residir em subpastas para adicionar regras adicionais e mais específicas.
CLAUDE.md substitui a escrita de bons prompts?
Não. Ele remove a necessidade de repetir o contexto estável do projeto (convenções, estrutura, regras) em cada prompt, mas as instruções específicas da tarefa sobre o que você deseja que seja feito no momento ainda pertencem ao próprio prompt.
CLAUDE.md é lido uma vez por projeto ou uma vez por sessão?
Ele é carregado no início de cada nova sessão. Não há memória de chat persistente entre as sessões - CLAUDE.md é o que torna o efeito de memória persistente.
Que tipo de conteúdo pertence a CLAUDE.md?
- Pilha de tecnologia e dependências chave
- Estrutura de pastas e onde as coisas ficam
- Convenções de codificação e padrões de nomenclatura
- Abordagem de testes e como executar testes
- Regras rígidas ("nunca faça X", "sempre faça Y antes de finalizar")
CLAUDE.md pode fazer o Claude Code fazer algo objetivamente errado se o arquivo estiver desatualizado?
Sim. Como o agente trata CLAUDE.md como contexto confiável do projeto, uma regra desatualizada (referindo-se a uma biblioteca que você removeu, uma pasta que mudou) pode levá-lo a um comportamento desatualizado ou incorreto. Trate-o como documentação viva que precisa de manutenção.
Um arquivo CLAUDE.md grande deixa o Claude Code lento?
Ele consome parte da janela de contexto em cada sessão, o que deixa menos espaço para leituras de arquivos e conversas antes que a janela se encha. Não é "lento" no sentido literal, mas é um custo real de orçamento que vale a pena minimizar.
Como CLAUDE.md é diferente de um README regular?
Um README é escrito para contribuidores humanos que navegam pelo repositório. CLAUDE.md é escrito para ser carregado automaticamente como contexto do agente em cada sessão - ele pode e frequentemente se sobrepõe ao conteúdo do README, mas seu público e mecanismo de entrega são diferentes.
Eu tenho que escrever CLAUDE.md manualmente?
Não. O comando de barra /init inicializa um CLAUDE.md inicial inspecionando um repositório novo, que você então edita e refina para as necessidades reais do seu projeto.
O que acontece se um projeto não tiver CLAUDE.md?
O Claude Code ainda funciona, mas cada sessão começa com o que ele pode inferir dos arquivos que ele lê - não há memória de projeto permanente, então convenções e regras precisam ser reafirmadas ou redescobertas a cada vez.
CLAUDE.md pode entrar em conflito com o que eu peço em um prompt?
Pode, no sentido de que ambos são apenas contexto competindo pela atenção do agente. Uma instrução de prompt específica e explícita para a tarefa atual geralmente tem precedência sobre as regras gerais do projeto, mas orientações genuinamente contraditórias devem ser resolvidas corrigindo o arquivo, não contando com o modelo para adivinhar corretamente todas as vezes.
CLAUDE.md é específico para uma linguagem de programação?
Não. É um arquivo markdown simples descrevendo convenções de projeto, então ele se aplica igualmente a qualquer linguagem ou stack - o conteúdo é o que seu projeto realmente precisa documentado.
CLAUDE.md deve ser commitado no controle de versão?
Sim. Como ele vive no repositório como qualquer outro arquivo, fazer o commit dele significa que toda a equipe compartilha a mesma memória de projeto, e as alterações nele passam pelo mesmo processo de revisão que as alterações de código.
Relacionados
- Bootstrapping de um Novo Projeto com /init - a maneira mais rápida de gerar um CLAUDE.md inicial automaticamente.
- Escrevendo um Arquivo CLAUDE.md Que Realmente é Seguido - como estruturar regras para que o Claude Code realmente as obedeça.
- Arquivos CLAUDE.md Aninhados e Como Funciona a Herança de Escopo - sobrepondo memória de projeto em subpastas.
- Noções Básicas de Gerenciamento de Contexto - o ponto de partida para toda esta seção.
Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5. Nomes de modelos, preços e recursos de produtos mudam rapidamente - verifique as especificações atuais em platform.claude.com/docs antes de confiar nelas.