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.
//
Busque em todas as páginas da documentação
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.
/init./init, escrevendo regras que realmente são seguidas, herança de escopo de CLAUDE.md aninhado.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.
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:
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.
À 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.
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.
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.
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.
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.
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.
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.
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 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.
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.
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.
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.
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.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026