Como Claude se lembra do seu projeto

Dê a Claude instruções persistentes com arquivos CLAUDE.md e deixe Claude acumular aprendizados automaticamente com memória automática.

Cada sessão do Claude Code começa com uma janela de contexto limpa. Dois mecanismos carregam conhecimento entre sessões:

• Arquivos CLAUDE.md: instruções que você escreve para dar a Claude contexto persistente
• Memória automática: notas que Claude escreve para si mesma com base em suas correções e preferências

Esta página cobre como:

• Escrever e organizar arquivos CLAUDE.md
• Escopear regras para tipos de arquivo específicos com .claude/rules/
• Configurar memória automática para que Claude tome notas automaticamente
• Solucionar problemas quando as instruções não estão sendo seguidas

CLAUDE.md vs memória automática

Claude Code tem dois sistemas de memória complementares. Ambos são carregados no início de cada conversa. Claude os trata como contexto, não como configuração imposta. Para bloquear uma ação independentemente do que Claude decidir, use um hook PreToolUse em vez disso. Quanto mais específicas e concisas forem suas instruções, mais consistentemente Claude as seguirá.

Use arquivos CLAUDE.md quando quiser guiar o comportamento de Claude. A memória automática permite que Claude aprenda com suas correções sem esforço manual.

Subagents também podem manter sua própria memória automática. Veja configuração de subagent para detalhes.

Arquivos CLAUDE.md

Arquivos CLAUDE.md são arquivos markdown que dão a Claude instruções persistentes para um projeto, seu fluxo de trabalho pessoal ou toda a sua organização. Você escreve esses arquivos em texto simples; Claude os lê no início de cada sessão.

Quando adicionar a CLAUDE.md

Trate CLAUDE.md como o lugar onde você escreve o que teria que re-explicar. Adicione a ele quando:

• Claude comete o mesmo erro uma segunda vez
• Uma revisão de código encontra algo que Claude deveria saber sobre esta base de código
• Você digita a mesma correção ou esclarecimento no chat que digitou na sessão anterior
• Um novo colega de equipe precisaria do mesmo contexto para ser produtivo

Mantenha-o com fatos que Claude deve manter em cada sessão: comandos de compilação, convenções, layout do projeto, regras "sempre faça X". Se uma entrada é um procedimento de múltiplas etapas ou só importa para uma parte da base de código, mova-a para uma skill ou uma regra com escopo de caminho em vez disso. A visão geral da extensão cobre quando usar cada mecanismo.

Escolha onde colocar arquivos CLAUDE.md

Arquivos CLAUDE.md podem estar em vários locais, cada um com um escopo diferente. A tabela abaixo lista-os em ordem de carregamento, do escopo mais amplo para o mais específico, então uma instrução de projeto aparece em contexto após uma instrução de usuário.

Arquivos CLAUDE.md e CLAUDE.local.md no diretório acima do diretório de trabalho são carregados no lançamento. Arquivos em subdiretórios são carregados sob demanda quando Claude lê arquivos nesses diretórios. Veja Como arquivos CLAUDE.md são carregados para a ordem de resolução completa.

Para projetos grandes, você pode dividir instruções em arquivos específicos de tópicos usando regras de projeto. As regras permitem que você escope instruções para tipos de arquivo específicos ou subdiretórios.

Configure um CLAUDE.md de projeto

Um CLAUDE.md de projeto pode ser armazenado em ./CLAUDE.md ou ./.claude/CLAUDE.md. Crie este arquivo e adicione instruções que se apliquem a qualquer pessoa trabalhando no projeto: comandos de compilação e teste, padrões de codificação, decisões arquitetônicas, convenções de nomenclatura e fluxos de trabalho comuns. Essas instruções são compartilhadas com sua equipe através do controle de versão, então foque em padrões de nível de projeto em vez de preferências pessoais. Para confirmar que o arquivo foi carregado, execute /context em uma sessão e verifique a lista em Memory files.

Escreva instruções eficazes

Arquivos CLAUDE.md são carregados na janela de contexto no início de cada sessão, consumindo tokens junto com sua conversa. A visualização da janela de contexto mostra onde CLAUDE.md é carregado em relação ao resto do contexto de inicialização. Como são contexto em vez de configuração imposta, como você escreve as instruções afeta o quão confiável Claude as segue. Instruções específicas, concisas e bem estruturadas funcionam melhor.

Tamanho: alvo de menos de 200 linhas por arquivo CLAUDE.md. Arquivos mais longos consomem mais contexto e reduzem a aderência. Se suas instruções estão crescendo muito, use regras com escopo de caminho para que as instruções sejam carregadas apenas quando Claude trabalha com arquivos correspondentes. Você também pode dividir conteúdo em importações para organização, embora arquivos importados ainda sejam carregados e entrem na janela de contexto no lançamento.

Estrutura: use cabeçalhos markdown e bullets para agrupar instruções relacionadas. Claude escaneia a estrutura da mesma forma que os leitores fazem: seções organizadas são mais fáceis de seguir do que parágrafos densos.

Especificidade: escreva instruções que sejam concretas o suficiente para verificar. Por exemplo:

• "Use indentação de 2 espaços" em vez de "Formate o código adequadamente"
• "Execute npm test antes de fazer commit" em vez de "Teste suas alterações"
• "Manipuladores de API vivem em src/api/handlers/" em vez de "Mantenha os arquivos organizados"

Consistência: se duas regras se contradizem, Claude pode escolher uma arbitrariamente. Revise seus arquivos CLAUDE.md, arquivos CLAUDE.md aninhados em subdiretórios e .claude/rules/ periodicamente para remover instruções desatualizadas ou conflitantes. Em monorepos, use claudeMdExcludes para pular arquivos CLAUDE.md de outras equipes que não são relevantes para seu trabalho.

Importe arquivos adicionais

Arquivos CLAUDE.md podem importar arquivos adicionais usando a sintaxe @path/to/import. Arquivos importados são expandidos e carregados em contexto no lançamento junto com o CLAUDE.md que os referencia.

Caminhos relativos e absolutos são permitidos. Caminhos relativos são resolvidos em relação ao arquivo contendo a importação, não ao diretório de trabalho. Arquivos importados podem importar recursivamente outros arquivos, com uma profundidade máxima de quatro saltos.

A análise de importação ignora spans de código Markdown e blocos de código cercados. Para mencionar um caminho em seu CLAUDE.md sem importá-lo, envolva-o em backticks: escrever `@README` mantém o texto literal, enquanto @README fora de backticks importa o arquivo.

Para trazer um README, package.json e um guia de fluxo de trabalho, referencie-os com a sintaxe @ em qualquer lugar do seu CLAUDE.md:

Veja @README para visão geral do projeto e @package.json para comandos npm disponíveis para este projeto.

# Instruções Adicionais
- fluxo de trabalho git @docs/git-instructions.md

Para preferências pessoais por projeto que não devem ser verificadas no controle de versão, crie um CLAUDE.local.md na raiz do projeto. Ele é carregado junto com CLAUDE.md e é tratado da mesma forma. Adicione CLAUDE.local.md ao seu .gitignore para que não seja confirmado. Com CLAUDE_CODE_NEW_INIT=1 definido, executar /init e escolher a opção pessoal faz isso para você.

Se você trabalha em múltiplos git worktrees do mesmo repositório, um CLAUDE.local.md ignorado pelo git só existe no worktree onde você o criou. Para compartilhar instruções pessoais entre worktrees, importe um arquivo do seu diretório home em vez disso:

# Preferências Individuais
- @~/.claude/my-project-instructions.md

AGENTS.md

Claude Code lê CLAUDE.md, não AGENTS.md. Se seu repositório já usa AGENTS.md para outros agentes de codificação, crie um CLAUDE.md que o importe para que ambas as ferramentas leiam as mesmas instruções sem duplicá-las. Você também pode adicionar instruções específicas do Claude Code abaixo da importação. Claude carrega o arquivo importado no início da sessão, depois anexa o resto:

@AGENTS.md

## Claude Code

Use plan mode para alterações em `src/billing/`.

Um symlink também funciona se você não precisar adicionar conteúdo específico do Claude Code:

ln -s AGENTS.md CLAUDE.md

O comando não imprime saída em caso de sucesso. Na próxima sessão, execute /context e confirme que CLAUDE.md aparece em Memory files.

No Windows, criar um symlink requer privilégios de Administrador ou Modo de Desenvolvedor, então use a importação @AGENTS.md em vez disso.

Executar /init lê regras Cursor, em .cursor/rules/ ou .cursorrules, e regras Copilot, em .github/copilot-instructions.md, e incorpora as partes relevantes no CLAUDE.md gerado. Com CLAUDE_CODE_NEW_INIT=1 definido, /init também lê AGENTS.md, .devin/rules/, .windsurf/rules/ ou .windsurfrules, e .clinerules.

Você também pode executar /import para trazer a configuração de um agente de codificação suportado para Claude Code, que anexa uma cópia única de arquivos de instrução como AGENTS.md ao CLAUDE.md correspondente e carrega MCP servers, comandos, subagents e skills. Requer Claude Code v2.1.213 ou posterior.

Como arquivos CLAUDE.md são carregados

Claude Code carrega CLAUDE.md e CLAUDE.local.md do seu diretório de trabalho atual e de cada diretório acima dele. Execute Claude Code em foo/bar/ e ele carrega instruções de foo/bar/CLAUDE.md, foo/CLAUDE.md e qualquer arquivo CLAUDE.local.md ao lado deles.

Todos os arquivos descobertos são concatenados em contexto em vez de se sobreporem. Dentro da árvore de diretórios, o conteúdo é ordenado da raiz do sistema de arquivos até seu diretório de trabalho. Para o exemplo foo/bar/, foo/CLAUDE.md aparece em contexto antes de foo/bar/CLAUDE.md, então as instruções mais próximas de onde você lançou Claude são lidas por último. Dentro de cada diretório, CLAUDE.local.md é anexado após CLAUDE.md, então suas notas pessoais são a última coisa que Claude lê naquele nível.

Claude também descobre arquivos CLAUDE.md e CLAUDE.local.md em subdiretórios sob seu diretório de trabalho atual. Em vez de carregá-los no lançamento, eles são incluídos quando Claude lê arquivos nesses subdiretórios.

Se você trabalha em um grande monorepo onde arquivos CLAUDE.md de outras equipes são capturados, use claudeMdExcludes para pular. Para o layout completo de arquivos CLAUDE.md de raiz e por diretório e regras, veja Monorepos e repositórios grandes.

Comentários HTML em nível de bloco (<!-- notas do mantenedor -->) em arquivos CLAUDE.md são removidos antes do conteúdo ser injetado no contexto de Claude. Use-os para deixar notas para mantenedores humanos sem gastar tokens de contexto neles. Comentários dentro de blocos de código são preservados. Quando você abre um arquivo CLAUDE.md diretamente com a ferramenta Read, os comentários permanecem visíveis.

Carregue de diretórios adicionais

A flag --add-dir dá a Claude acesso a diretórios adicionais fora do seu diretório de trabalho principal. Por padrão, arquivos CLAUDE.md desses diretórios não são carregados.

Para também carregar arquivos de memória de diretórios adicionais, defina a variável de ambiente CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD:

CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config

Isso carrega CLAUDE.md, .claude/CLAUDE.md, .claude/rules/*.md e CLAUDE.local.md do diretório adicional. CLAUDE.local.md é ignorado se você excluir local de --setting-sources.

Organize regras com `.claude/rules/`

Para projetos maiores, você pode organizar instruções em múltiplos arquivos usando o diretório .claude/rules/. Isso mantém as instruções modulares e mais fáceis para as equipes manterem. As regras também podem ser escopadas para caminhos de arquivo específicos, então elas só são carregadas em contexto quando Claude trabalha com arquivos correspondentes, reduzindo ruído e economizando espaço de contexto.

Configure regras

Coloque arquivos markdown no diretório .claude/rules/ do seu projeto. Cada arquivo deve cobrir um tópico, com um nome de arquivo descritivo como testing.md ou api-design.md. Todos os arquivos .md são descobertos recursivamente, então você pode organizar regras em subdiretórios como frontend/ ou backend/:

seu-projeto/
├── .claude/
│   ├── CLAUDE.md           # Instruções principais do projeto
│   └── rules/
│       ├── code-style.md   # Diretrizes de estilo de código
│       ├── testing.md      # Convenções de teste
│       └── security.md     # Requisitos de segurança

Regras sem frontmatter paths são carregadas no lançamento com a mesma prioridade que .claude/CLAUDE.md.

Regras de projeto são ignoradas se você excluir project de --setting-sources. Antes da v2.1.211, regras que carregam sob demanda, incluindo regras com escopo de caminho e regras em diretórios .claude/rules/ aninhados, carregavam mesmo quando project era excluído.

Regras específicas de caminho

As regras podem ser escopadas para arquivos específicos usando frontmatter YAML com o campo paths. Essas regras condicionais só se aplicam quando Claude está trabalhando com arquivos correspondentes aos padrões especificados.

---
paths:
  - "src/api/**/*.ts"
---

# Regras de Desenvolvimento de API

- Todos os endpoints de API devem incluir validação de entrada
- Use o formato de resposta de erro padrão
- Inclua comentários de documentação OpenAPI

Regras sem um campo paths são carregadas incondicionalmente e se aplicam a todos os arquivos. Regras com escopo de caminho são acionadas quando Claude lê arquivos correspondentes ao padrão, não em cada uso de ferramenta. A partir da v2.1.198, a correspondência também funciona quando Claude alcança um arquivo através de um caminho vinculado simbolicamente para o diretório do projeto, por exemplo em um checkout vinculado simbolicamente.

Use padrões glob no campo paths para corresponder arquivos por extensão, diretório ou qualquer combinação:

Você pode especificar múltiplos padrões e usar expansão de chaves para corresponder múltiplas extensões em um padrão:

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

Cada grupo de chaves multiplica o número de padrões expandidos: src/*.{ts,tsx} expande para dois padrões, e {a,b}/{c,d}/*.{ts,tsx} para oito. Para manter a expansão limitada, a lista paths inteira de uma regra compartilha um orçamento de 1.000 padrões expandidos e 4 MiB, e padrões sem chaves não contam contra ele.

Claude Code usa qualquer padrão que excederia o orçamento não expandido, e suas chaves literais não correspondem a nenhum arquivo. Antes da v2.1.217, um valor paths com muitos grupos de chaves travava ou fazia o CLI falhar na inicialização.

Sintaxe glob trata [ como o início de uma expressão de colchete como [abc]. Um padrão com um [ que não pode ser lido como uma expressão de colchete, como photos [2024/**, é inválido: ele não corresponde a nada, e os outros padrões da regra continuam funcionando. Para corresponder um [ literal em um nome de arquivo, escape-o como photos \[2024/**. Antes da v2.1.207, um padrão inválido fazia a ferramenta Read falhar para cada arquivo em que a regra era avaliada, em vez de não corresponder a nada.

Compartilhe regras entre projetos com symlinks

O diretório .claude/rules/ suporta symlinks, então você pode manter um conjunto compartilhado de regras e vinculá-las em múltiplos projetos. Symlinks circulares são detectados e tratados graciosamente.

Claude Code trata um symlink cujo alvo está fora do seu diretório de trabalho como uma importação externa. As regras vinculadas não são carregadas até que você aprove importações externas para o projeto, e depois disso apenas as sem um campo paths são carregadas. Claude Code pede essa aprovação apenas quando um arquivo de memória de projeto importa um arquivo fora do diretório de trabalho com @path, não para symlinks sozinhos. Para carregar regras compartilhadas sem essa aprovação, mantenha-as em ~/.claude/rules/, onde se aplicam a cada projeto na sua máquina.

Este exemplo vincula tanto um diretório compartilhado quanto um arquivo individual:

ln -s ~/shared-claude-rules .claude/rules/shared
ln -s ~/company-standards/security.md .claude/rules/security.md

Regras de nível de usuário

Regras pessoais em ~/.claude/rules/ se aplicam a cada projeto na sua máquina. Use-as para preferências que não são específicas do projeto:

~/.claude/rules/
├── preferences.md    # Suas preferências pessoais de codificação
└── workflows.md      # Seus fluxos de trabalho preferidos

Regras de nível de usuário são carregadas antes das regras de projeto, dando às regras de projeto prioridade mais alta.

Gerencie CLAUDE.md para grandes equipes

Para organizações implantando Claude Code em equipes, você pode centralizar instruções e controlar quais arquivos CLAUDE.md são carregados.

Implante CLAUDE.md em toda a organização

As organizações podem implantar um CLAUDE.md gerenciado centralmente que se aplica a todos os usuários em uma máquina. Este arquivo não pode ser excluído por configurações individuais.

A chave claudeMd permite que você coloque conteúdo CLAUDE.md gerenciado diretamente dentro de managed-settings.json em vez de implantar um arquivo separado.

Escopo: cada sessão de Claude Code na máquina, em cada repositório. Para orientação específica do repositório, confirme um CLAUDE.md de projeto em vez disso.

Precedência: igual a um arquivo CLAUDE.md gerenciado. Carrega antes de CLAUDE.md de usuário e projeto.

Onde é honrado: apenas configurações gerenciadas e de política. Definir claudeMd em configurações de usuário, projeto ou local não tem efeito.

O exemplo abaixo adiciona instruções comportamentais diretamente em um arquivo de configurações gerenciadas:

{
  "claudeMd": "Always run `make lint` before committing.\nNever push directly to main."
}

Um CLAUDE.md gerenciado e configurações gerenciadas servem a propósitos diferentes. Use configurações para imposição técnica e CLAUDE.md para orientação comportamental:

Regras de configurações são impostas pelo cliente independentemente do que Claude decide fazer. Instruções de CLAUDE.md moldam o comportamento de Claude, mas não são uma camada de imposição rígida.

Exclua arquivos CLAUDE.md específicos

Em grandes monorepos, arquivos CLAUDE.md ancestrais podem conter instruções que não são relevantes para seu trabalho. A configuração claudeMdExcludes permite que você pule arquivos específicos por caminho ou padrão glob.

Este exemplo exclui um CLAUDE.md de nível superior e um diretório de regras de uma pasta pai. Adicione-o a .claude/settings.local.json para que a exclusão permaneça local à sua máquina:

{
  "claudeMdExcludes": [
    "**/monorepo/CLAUDE.md",
    "/home/user/monorepo/other-team/.claude/rules/**"
  ]
}

Padrões são correspondidos contra caminhos de arquivo absolutos usando sintaxe glob. Você pode configurar claudeMdExcludes em qualquer camada de configurações: usuário, projeto, local ou política gerenciada. Arrays são mesclados entre camadas.

Para excluir um arquivo de regras que você alcança através de um symlink, seja o arquivo ou seu diretório o link, escreva o padrão contra qualquer caminho: o caminho do arquivo em .claude/rules/ ou seu alvo de link. Um padrão que corresponde a qualquer caminho exclui o arquivo. Antes da v2.1.239, apenas um padrão que correspondia ao alvo do link excluía o arquivo.

Arquivos CLAUDE.md de política gerenciada não podem ser excluídos. Isso garante que as instruções em toda a organização sempre se apliquem independentemente das configurações individuais.

Memória automática

A memória automática permite que Claude acumule conhecimento entre sessões sem você escrever nada. Conforme funciona, Claude salva quatro tipos de notas para si mesma. Claude registra o tipo como um campo type no frontmatter do arquivo de memória:

• user: seu papel, expertise e preferências de trabalho
• feedback: correções que você dá a Claude e abordagens que você confirma
• project: trabalho em andamento, prazos e decisões que Claude não consegue derivar do código ou histórico do git
• reference: onde encontrar informações fora do projeto, como um rastreador de problemas ou dashboard

Claude pula qualquer coisa que possa derivar da base de código, como arquitetura, caminhos de arquivo ou correções de depuração. Também pula qualquer coisa que seus arquivos CLAUDE.md já dizem.

Claude não salva algo a cada sessão. Ela decide o que vale a pena lembrar com base em se a informação seria útil em uma conversa futura.

Ative ou desative a memória automática

A memória automática está ativada por padrão. Para alterná-la, abra /memory em uma sessão e use o toggle de memória automática, que salva autoMemoryEnabled nas configurações do usuário em ~/.claude/settings.json. Para desativá-la para um único projeto, defina autoMemoryEnabled nas configurações desse projeto:

{
  "autoMemoryEnabled": false
}

Para desabilitar a memória automática via variável de ambiente, defina CLAUDE_CODE_DISABLE_AUTO_MEMORY=1.

Local de armazenamento

Cada projeto obtém seu próprio diretório de memória em ~/.claude/projects/<project>/memory/. O caminho <project> é derivado do repositório git, então todos os worktrees e subdiretórios dentro do mesmo repositório compartilham um diretório de memória automática. Fora de um repositório git, a raiz do projeto é usada em vez disso.

Se você definir CLAUDE_CODE_PROJECT_DIR_NAME ao lado de CLAUDE_CONFIG_DIR, Claude Code usa esse nome como o diretório <project> sob <config dir>/projects/ independentemente de qual repositório você o inicia, então projetos iniciados com esse diretório de configuração compartilham um diretório de memória automática. Requer Claude Code v2.1.234 ou posterior.

Para armazenar memória automática em um local diferente, defina autoMemoryDirectory em seu settings.json. Ele é lido de qualquer escopo de configurações: usuário, projeto, local, política, ou --settings.

{
  "autoMemoryDirectory": "~/my-custom-memory-dir"
}

O valor deve ser um caminho absoluto ou começar com ~/. Quando você o define no .claude/settings.json ou .claude/settings.local.json de um projeto, Claude Code o honra sob a mesma regra de confiança de workspace que hooks em arquivos de configurações.

O diretório contém um índice MEMORY.md e um arquivo de tópico por memória:

~/.claude/projects/<project>/memory/
├── MEMORY.md           # Índice, uma linha por memória, carregado em cada sessão
├── user_role.md        # Uma memória
├── feedback_testing.md # Uma memória
└── ...                 # Qualquer outro arquivo de tópico que Claude cria

MEMORY.md atua como um índice do diretório de memória. Claude lê e escreve arquivos neste diretório ao longo de sua sessão, usando MEMORY.md para acompanhar o que está armazenado onde.

A memória automática é local da máquina. Todos os worktrees e subdiretórios dentro do mesmo repositório git compartilham um diretório de memória automática. Os arquivos não são compartilhados entre máquinas ou ambientes em nuvem.

Claude Code exclui transcrições de sessão antigas após o período de retenção cleanupPeriodDays, mas exclui os arquivos de memória no diretório de memória dessa varredura de retenção. MEMORY.md e arquivos de tópico permanecem até você ou Claude editá-los ou deletá-los.

Como funciona

As primeiras 200 linhas de MEMORY.md, ou os primeiros 25KB, o que vier primeiro, são carregados no início de cada conversa. Conteúdo além desse limite não é carregado no início da sessão. Claude mantém MEMORY.md conciso movendo notas detalhadas para arquivos de tópico separados.

Depois que Claude escreve em MEMORY.md, Claude Code mede o arquivo contra os limites de leitura de 200 linhas e 25KB. Se o arquivo está próximo de um limite, Claude Code lembra Claude de encurtá-lo: mantenha uma linha por entrada, mova detalhes para arquivos de tópico e mescle ou descarte entradas obsoletas. Se o arquivo está acima de um limite, a escrita ainda é bem-sucedida, mas Claude Code retorna um erro dizendo a Claude para reescrever o índice, porque tudo além do limite é descartado no próximo carregamento.

Este limite se aplica apenas a MEMORY.md. Claude Code carrega um arquivo CLAUDE.md de até 4 MiB na íntegra e pula um arquivo maior. Arquivos mais curtos produzem melhor aderência.

Claude Code não carrega arquivos de tópico como user_role.md ou feedback_testing.md na inicialização. Claude os lê sob demanda usando suas ferramentas de arquivo padrão quando precisa da informação.

A memória automática da conversa principal não é carregada em subagentes; a exceção é um fork, que herda a conversa pai e o prompt do sistema. A própria memória automática de um subagente, ativada com o campo memory do subagente, é um diretório separado.

Claude lê e escreve arquivos de memória durante sua sessão. Quando você vê mensagens como "Saved 2 memories" ou "Recalled 2 memories" na interface do Claude Code, Claude está ativamente atualizando ou lendo de ~/.claude/projects/<project>/memory/.

Quando Claude escreve um arquivo de memória que começa com frontmatter YAML, Claude Code registra o tempo de escrita em um campo modified do frontmatter como um timestamp ISO 8601. O timestamp mostra como o fato é atual, tanto para você quanto para Claude quando o lê de volta. Qualquer arquivo que tenha frontmatter obtém o campo na próxima vez que Claude o escreve, incluindo arquivos criados em versões anteriores; Claude Code nunca adiciona frontmatter a um arquivo que não tenha nenhum. O campo modified requer Claude Code v2.1.214 ou posterior.

Audite e edite sua memória

Arquivos de memória automática são markdown simples que você pode editar ou deletar a qualquer momento. Execute /memory para navegar e abrir arquivos de memória de dentro de uma sessão.

Visualize e edite com `/memory`

O comando /memory lista seus arquivos CLAUDE.md, CLAUDE.local.md e outros locais de arquivo de memória em escopos de usuário e projeto, incluindo entradas CLAUDE.md de usuário e projeto para arquivos que ainda não existem. Também permite que você alterne a memória automática ativada ou desativada e fornece uma opção para abrir a pasta de memória automática. Selecione qualquer arquivo para abri-lo no seu editor; selecionar um que ainda não existe o cria primeiro. Para verificar quais arquivos realmente foram carregados na sessão atual, execute /context.

Editores GUI como VS Code abrem o arquivo em uma janela separada, e você pode continuar usando a sessão enquanto está aberta. Antes da v2.1.216, /memory esperava você fechar o arquivo antes de responder. Editores de terminal como Vim assumem o controle do terminal até você sair.

Quando você pede a Claude para lembrar algo, como "sempre use pnpm, não npm" ou "lembre-se de que os testes de API requerem uma instância local de Redis," Claude salva em memória automática. Para adicionar instruções a CLAUDE.md em vez disso, peça a Claude diretamente, como "adicione isto a CLAUDE.md," ou edite o arquivo você mesmo via /memory.

Solucione problemas de memória

Estes são os problemas mais comuns com CLAUDE.md e memória automática, junto com passos para depurá-los.

Claude não está seguindo meu CLAUDE.md

O conteúdo de CLAUDE.md é entregue como uma mensagem de usuário após o prompt do sistema, não como parte do próprio prompt do sistema. Claude o lê e tenta segui-lo, mas não há garantia de conformidade estrita, especialmente para instruções vagas ou conflitantes.

Para depurar:

• Execute /context e verifique a lista sob Memory files para verificar se seus arquivos CLAUDE.md e CLAUDE.local.md foram carregados. Se um arquivo não estiver listado lá, Claude não pode vê-lo. Use /memory para abrir e editar os arquivos.
• Verifique se o CLAUDE.md relevante está em um local que é carregado para sua sessão (veja Escolha onde colocar arquivos CLAUDE.md).
• Torne as instruções mais específicas. "Use indentação de 2 espaços" funciona melhor do que "formate o código adequadamente."
• Procure por instruções conflitantes entre arquivos CLAUDE.md. Se dois arquivos dão orientação diferente para o mesmo comportamento, Claude pode escolher um arbitrariamente.

Se a instrução é algo que deve ser executado em um ponto específico, como antes de cada commit ou após cada edição de arquivo, escreva-a como um hook em vez disso. Hooks são executados como comandos shell em eventos de ciclo de vida fixos e se aplicam independentemente do que Claude decidir fazer.

Para instruções que você quer no nível do prompt do sistema, use --append-system-prompt. Você passa isso no lançamento, então é mais adequado para scripts e automação do que para uso interativo. Para como se comporta quando você retoma uma conversa, veja Sinalizadores de prompt do sistema em conversas retomadas.

Não sei o que a memória automática salvou

Execute /memory e selecione a pasta de memória automática para navegar o que Claude salvou. Tudo é markdown simples que você pode ler, editar ou deletar.

Meu CLAUDE.md é muito grande

Arquivos com mais de 200 linhas consomem mais contexto e podem reduzir a aderência. Claude Code pula um arquivo com mais de 4 MiB. Use regras com escopo de caminho para carregar instruções apenas quando Claude trabalha com arquivos correspondentes, ou reduza conteúdo que não é necessário em cada sessão. Dividir em importações @path ajuda na organização, mas não reduz contexto, já que arquivos importados são carregados no lançamento.

O checkup /doctor propõe cortes para um CLAUDE.md verificado: ele corta conteúdo que Claude pode derivar da base de código, como layouts de diretório, listas de dependências e visões gerais de arquitetura, e mantém armadilhas, justificativa e convenções que diferem dos padrões de ferramentas. A verificação de corte requer Claude Code v2.1.206 ou posterior.

Instruções parecem perdidas após `/compact`

CLAUDE.md de raiz de projeto sobrevive à compactação: após /compact, Claude relê do disco e reinjecta no contexto. Arquivos CLAUDE.md aninhados em subdiretórios e regras com frontmatter paths: recarregam conforme Claude lê arquivos aos quais se aplicam.

Se uma instrução desapareceu após compactação, ela foi dada apenas em conversa, vive em um CLAUDE.md aninhado que ainda não recarregou, ou é uma regra com escopo de caminho que não correspondeu a um arquivo desde então. Adicione instruções apenas de conversa a CLAUDE.md para torná-las persistir. Veja O que sobrevive à compactação para o detalhamento completo.

Veja Escreva instruções eficazes para orientação sobre tamanho, estrutura e especificidade.

Recursos relacionados

• Debug sua configuração: diagnostique por que CLAUDE.md ou configurações não estão tendo efeito
• Skills: empacote fluxos de trabalho repetíveis que carregam sob demanda
• Settings: configure o comportamento do Claude Code com arquivos de configurações
• Memória de subagent: deixe subagents manter sua própria memória automática