Memória do Claude Code: /init, CLAUDE.md e o atalho #, ilustrado
Sem memória, o Claude Code esquece tudo a cada sessão. Este passo a passo roda o /init em um projeto real de Next.js, lê o CLAUDE.md gerado, adiciona uma regra do chat com o atalho # e verifica que o Claude realmente segue — cada etapa conferida por screenshot.
TL;DR — a memória do Claude Code em quatro linhas
- Rode o /init uma vez por projeto: o Claude escaneia o repo — estrutura de pastas, scripts, gerenciamento de estado — e escreve um CLAUDE.md estruturado na raiz.
- Esse arquivo entra no contexto de toda sessão automaticamente, então o que você escrever ali molda toda geração de código futura.
- Digite # mais uma regra no chat para memorizar na hora, depois escolha onde ela mora: memória de projeto (commitada), memória local do projeto ou memória de usuário (~/.claude/CLAUDE.md).
- Mantenha o arquivo atualizado quando sua estrutura ou stack mudar — memória desatualizada desvia o Claude — e reabra qualquer arquivo de memória com /memory.
Claude Code Tutorial #2 - CLAUDE.md Files & /init
Canal:Net Ninja12:18
The CLAUDE.md file
Canal:Claude (official Anthropic channel)3:01
Claude Code's Memory System: The Full Guide
Canal:DIY Smart Code5:05
Manage Claude's memory — Claude Code documentation
Docs:code.claude.com
Os frames vêm da lição de CLAUDE.md do Net Ninja (uma gravação limpa de VS Code); o texto do passo a passo foi escrito de forma independente e conferido com a documentação de memória da Anthropic e o vídeo oficial de CLAUDE.md.
Os screenshots permanecem propriedade de seus criadores e são usados com atribuição como documentação visual. Cada passo tem deep-link para o momento exato do vídeo original.
De memória zero a um projeto que o Claude conhece
1 · Gere o CLAUDE.md com /init
- 1
Comece com /init
Quando você traz o Claude Code para um projeto pela primeira vez, rode o /init antes de pedir qualquer código. O tooltip diz exatamente o que ele faz: inicializar um novo arquivo CLAUDE.md com documentação do codebase. O Claude vai ler seu projeto agora para as sessões futuras não precisarem.
/init — o único comando a rodar antes de tudo em um repo novo.Assistir em 0:30 - 2
Veja o Claude explorar antes de escrever
Em vez de adivinhar, o /init monta sua própria lista de todos: explorar a estrutura do repositório, analisar o package.json e o código-fonte, checar documentação existente e, então, criar o CLAUDE.md com os achados. Você vê cada item sendo marcado em tempo real — o arquivo é um resumo do que de fato foi lido, não um template.
A lista de Update Todos durante a inicialização — explorar, analisar, depois escrever.Assistir em 1:42 - 3
Leia o cabeçalho de orientações e os comandos que ele escreveu
O arquivo gerado abre com um cabeçalho de orientações para o Claude Code, seguido de Development Commands extraídos direto do package.json — dev, build, lint, start. É essa seção que impede o Claude de inventar o próprio workflow: os scripts reais já estão no contexto dele.
A abertura do arquivo: orientações para o Claude Code mais os scripts npm reais do projeto.Assistir em 2:56 - 4
Confira as seções de arquitetura e estrutura
Mais abaixo o arquivo documenta a visão geral da arquitetura (este projeto: um blog em Next.js 15 com React 19 e Tailwind), um mapa de Project Structure mostrando onde arquivos novos devem ficar, e notas de Data Persistence para a camada de Hygraph CMS. Sessões novas herdam tudo isso sem reler seu repo.
Project Structure com caminhos selecionados, mais a nota de persistência de dados do Hygraph.Assistir em 2:30
2 · Adicione memórias e prove que elas colam
- 5
Prove que a memória muda o comportamento
O teste: depois de adicionar “todos os hooks reutilizáveis ficam dentro desta pasta hooks” ao arquivo, o prompt pede um hook de preferência de tema — e diz explicitamente para não usá-lo em nenhum lugar ainda. O todo do Claude mostra que ele cria o hook em src/hooks/use-theme, e termina com “o hook está pronto para uso mas não foi integrado em nenhum lugar, como pedido”. Memória entra, comportamento sai.
O hook cai na pasta que o arquivo de memória nomeou — e respeita o “não ligue ainda”.Assistir em 6:40 - 6
Memorize uma regra nova com # direto do chat
Você não precisa editar o arquivo à mão. Comece uma mensagem com # — por exemplo “# ao criar novos componentes de página, sempre adicione um link para essa página no header” — e o Claude Code reconhece como memória para guardar, então pergunta onde ela deve morar: memória de projeto, memória local do projeto ou memória de usuário.
O atalho # e o seletor de três destinos que ele abre.Assistir em 7:30 - 7
Conheça os quatro tipos de memória
A tabela da documentação da Anthropic é o mapa: memória de política corporativa para organizações, memória de projeto (./CLAUDE.md, commitada e compartilhada com o time), memória de usuário (~/.claude/CLAUDE.md, suas preferências globais pessoais) e memória local do projeto (./CLAUDE.local.md, pessoal e sem versionamento) — que a doc marca como deprecada em favor de importar arquivos sem versionamento pela memória de projeto, embora a opção continue aparecendo no seletor.
A tabela oficial de tipos de memória: local, propósito e quem compartilha cada arquivo.Assistir em 10:50 - 8
Confirme que a regra caiu no arquivo
Escolher memória de projeto anexa a regra ao CLAUDE.md do projeto, e lá está ela no fim do arquivo: “ao criar novos componentes de página, sempre adicione um link para essa página no header”. A partir da próxima sessão, essa linha viaja no contexto automaticamente.
A regra nova, salva no fim do CLAUDE.md commitado.Assistir em 11:48
3 · Administre os arquivos de memória no dia a dia
- 9
Verifique a memória em uma tarefa nova
Agora peça uma página About e observe o plano: “vou criar uma nova página About e adicionar um link dela no header conforme sua instrução de memória”, com “Add About page link to header navigation” como todo próprio. A regra de # de dois passos atrás está guiando uma tarefa onde ela nunca se repetiu. (Aviso honesto do vídeo: o Claude também pode adicionar links para páginas que você não mencionou — scope creep que você doma com uma linha no mesmo arquivo.)
“…conforme sua instrução de memória” — a lista de todos prova que a regra está ativa.Assistir em 9:37 - 10
Reabra qualquer arquivo de memória com /memory
O comando /memory lista todos os arquivos de memória com sua localização: memória de projeto commitada em ./.CLAUDE.md, memória local ignorada pelo git em ./.CLAUDE.local.md, e seu arquivo global de usuário em ~/.claude/CLAUDE.md. Escolha um e ele abre no seu editor — 11 memórias contadas no arquivo deste projeto.
Selecione a memória para editar — os três escopos, um seletor.Assistir em 11:22 - 11
Edite como qualquer outro arquivo
O Claude Code confirma “Opened project memory at ./.CLAUDE.md” e abre no VS Code, com uma dica: defina a variável de ambiente $EDITOR ou $VISUAL para escolher outro editor. Do /init à manutenção diária, memória é só um arquivo markdown que você mantém honesto.
“Opened project memory at ./.CLAUDE.md” — edite e mantenha em dia.Assistir em 12:06
As camadas de memória e onde cada arquivo mora
Quatro arquivos, quatro escopos — escolha o certo e a memória do Claude Code deixa de ser adivinhação:
- 1Memória de projeto — ./CLAUDE.md na raiz do repo. Versionada no git, compartilhada com todo dev do projeto. Mantenha-a sobre o projeto: estrutura, convenções, comandos, frameworks.
- 2Memória local do projeto — ./CLAUDE.local.md. Notas pessoais para este repo (suas ferramentas, seus atalhos) que ficam sem versionamento. Deprecada segundo a doc — o padrão recomendado é importar arquivos sem versionamento pela memória de projeto — mas, na época da gravação, a opção ainda aparecia no seletor de #.
- 3Memória de usuário — ~/.claude/CLAUDE.md no seu diretório home. Suas preferências globais em todos os projetos da máquina: estilo de código, idioma das respostas, workflows pessoais.
- 4Além do CLAUDE.md — builds mais recentes do Claude Code adicionam um sistema de memória automática (MEMORY.md e arquivos de tópicos sob ~/.claude/projects/) que o próprio Claude mantém, separado do arquivo de instruções, além de imports com @ para puxar outros docs para o contexto. Desative com CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 se quiser apenas arquivos de instruções.
Seja qual camada você usar, o hábito do vídeo é o mesmo: memória não é criar-e-esquecer. Quando sua estrutura, pacotes ou convenções mudarem, atualize o arquivo — memória desatualizada é pior que nenhuma, porque o Claude a segue com toda a confiança.