Nos capítulos anteriores você aprendeu a conversar com o Claude Code e a escrever instruções que funcionam na primeira ou segunda tentativa. Neste capítulo você vai aprender a fazer essas instruções durarem: ao final, você saberá criar e manter arquivos CLAUDE.md que o Claude Code lê automaticamente no início de cada sessão, escolher em qual nível da hierarquia cada regra deve ficar, importar documentos existentes, adicionar memória no meio do trabalho e verificar se tudo isso está sendo obedecido.
Por que instruções persistentes
Repare no que acontece sem um arquivo de contexto. A cada sessão nova, você precisa lembrar ao Claude Code qual comando roda os testes, que o projeto usa aspas simples, que a pasta legada não deve ser tocada e que o time decidiu não usar determinada biblioteca. Como a janela de contexto é limpa quando você usa o comando de barra clear ou abre uma sessão nova, todo esse conhecimento evapora. O arquivo CLAUDE.md resolve exatamente isso. Ele é um arquivo Markdown comum, escrito em linguagem natural, que o Claude Code carrega sozinho antes de ler sua primeira mensagem. Pense nele como o briefing que você daria a uma pessoa nova no time no primeiro dia, só que dado uma única vez e valendo para sempre.
Começando com o comando init
No capítulo dois o comando de barra init foi mencionado de passagem. Agora é a hora de usá-lo. Dentro da raiz do projeto, abra o Claude Code e digite o comando de barra init. Ele vai explorar o repositório, ler o arquivo de dependências, o README e os scripts de build, e propor um CLAUDE.md inicial. Você verá o conteúdo como um diff, igual a qualquer outra edição, e precisa aprovar.
Não aceite cegamente. O que o init gera é um rascunho razoável, mas costuma ter três problemas. Primeiro, ele descreve coisas óbvias, como a lista de pastas que qualquer pessoa vê com um comando de listagem. Segundo, ele às vezes inventa convenções a partir de padrões que aparecem só em parte do código. Terceiro, ele não conhece as decisões do time que não estão escritas em lugar nenhum. Então revise o rascunho com uma pergunta em mente para cada linha: se eu apagasse esta frase, o Claude Code erraria algo? Se a resposta for não, apague.
A hierarquia de arquivos e quando usar cada um
Existem quatro lugares onde você, como pessoa desenvolvedora, costuma colocar um arquivo de contexto, e o Claude Code combina todos eles. Em empresas há ainda um quinto nível, um arquivo de política instalado pela organização na máquina, que é carregado antes dos seus e tem precedência sobre eles.
- Ouça o áudio com a tela desligada
- Ganhe Certificado após a conclusão
- + de 5000 cursos para você explorar!
Baixar o aplicativo
- CLAUDE.md global do usuário, na pasta .claude dentro da sua pasta pessoal. Vale para todos os projetos da sua máquina. Coloque aqui só preferências suas que não dependem de projeto: o idioma em que quer as explicações, o pedido para sempre mostrar o plano antes de executar tarefas grandes, o estilo de mensagem que você prefere. Nada específico de um repositório.
- CLAUDE.md na raiz do projeto, versionado no Git. É o mais importante. Ele descreve o projeto para qualquer pessoa do time que use o Claude Code, e por isso deve conter apenas o que vale para todo mundo.
- CLAUDE.md em subpastas. O Claude Code carrega esses arquivos sob demanda, quando começa a trabalhar em arquivos daquela pasta. Servem para regras que só fazem sentido em uma parte do projeto, como o padrão de componentes da pasta de interface ou o cuidado extra com as migrações da pasta de banco de dados.
- CLAUDE.local.md na raiz, que deve estar no gitignore. Vale um aviso: esse formato está marcado como obsoleto na documentação oficial e pode deixar de ser carregado em versões futuras; a alternativa recomendada hoje é guardar suas anotações em um arquivo fora do versionamento e importá-lo com arroba a partir do CLAUDE.md do projeto. É o seu espaço pessoal dentro do projeto: o caminho do seu banco local, uma anotação sobre a tarefa em que você está mergulhado, um lembrete de que você prefere que ele rode apenas os testes da sua área. Ninguém mais do time vê.
A regra prática é subir cada informação até o nível mais alto em que ela ainda é verdadeira para todos, e não mais. Uma convenção do time inteiro vai para a raiz. Uma preferência só sua vai para o arquivo local ou para o global. Se você não sabe onde algo deveria ficar, comece na raiz e mova depois.
O que colocar e o que deixar de fora
Um bom CLAUDE.md de raiz costuma ter cinco blocos. O primeiro é a lista de comandos essenciais: como instalar dependências, rodar o servidor, rodar os testes, rodar o linter. Isso evita que o Claude Code chute o comando e perca tempo com erros. O segundo são as convenções de código que uma ferramenta automática não impõe, como nomear arquivos em kebab case, nunca lançar exceções genéricas ou sempre validar entrada na camada de rota. O terceiro é a arquitetura em poucas frases: quais são as camadas, por onde entra uma requisição, onde ficam as regras de negócio. O quarto são decisões que não devem ser revertidas, com a justificativa curta, porque a inteligência artificial tende a sugerir a solução mais comum e pode desfazer uma escolha deliberada do time. O quinto é a lista do que nunca fazer: não editar arquivos gerados, não tocar a pasta de migrações antigas, não alterar o esquema do banco sem criar migração.
Igualmente importante é o que fica de fora. Não coloque informação que muda toda semana, como a lista de tarefas do sprint ou o nome da branch atual, porque o arquivo vai ficar mentiroso rápido. Não coloque o que já está óbvio no código, como a estrutura de pastas ou a lista de dependências, porque o Claude Code lê isso sozinho e cada linha desnecessária consome janela de contexto em toda sessão. Não coloque documentação longa de biblioteca; se precisar, importe um arquivo separado, como veremos a seguir. E não coloque regras de permissão, que têm lugar próprio no settings.json e serão tratadas no capítulo seis. Por fim, nunca escreva segredos nesses arquivos: senhas, tokens, chaves de API ou strings de conexão com credenciais não devem entrar nem no arquivo versionado nem no local, porque todo o conteúdo é carregado na janela de contexto e enviado ao modelo, além de poder acabar no histórico do Git.
Importando arquivos com arroba
A mesma referência de arquivo com arroba que você usa nas mensagens funciona dentro do CLAUDE.md. Se o projeto já tem um documento de arquitetura ou um guia de contribuição, não copie o conteúdo: escreva uma linha como arroba docs barra arquitetura ponto md e o Claude Code incluirá aquele arquivo automaticamente ao carregar o contexto. Isso mantém uma única fonte de verdade e evita que o CLAUDE.md e a documentação divirjam com o tempo. Use com moderação, porque cada importação entra inteira na janela de contexto. Importe documentos curtos e estáveis, não pastas inteiras.
Monorepos
Em um monorepo, a hierarquia brilha. Coloque na raiz apenas o que vale para todos os pacotes: como instalar tudo, como rodar a suíte completa, as convenções gerais. Em cada pacote, crie um CLAUDE.md próprio com os comandos daquele pacote, o framework usado e as regras locais. Como os arquivos de subpasta são carregados apenas quando o Claude Code toca aquela área, você não paga o custo de contexto de vinte pacotes quando está trabalhando em um só.
Adicionando memória durante a sessão
Muitas regras boas surgem no meio do trabalho, quando você corrige o Claude Code pela segunda vez sobre a mesma coisa. Nesse momento, em vez de só dar o feedback específico, comece sua mensagem com o símbolo de cerquilha, o mesmo que abre um título em Markdown. O Claude Code entende isso como um pedido para gravar a instrução em memória e pergunta em qual arquivo salvar: o global, o do projeto ou o local. Escreva a regra como você gostaria de encontrá-la depois, por exemplo: cerquilha, sempre rodar o linter antes de considerar uma tarefa concluída. A partir da próxima sessão, aquilo já está valendo. É a forma mais barata de fazer o arquivo crescer apenas com regras que provaram ser necessárias.
Mantendo o arquivo curto e verificando a obediência
Um CLAUDE.md eficaz cabe em uma tela. Não existe um limite oficial de tamanho, mas quanto mais longo o arquivo, mais difícil fica para o modelo dar peso a cada regra, e regras contraditórias passam despercebidas. Revise o arquivo a cada poucas semanas, remova o que virou obsoleto e junte linhas repetidas. Prefira frases imperativas e específicas: use o comando npm test para rodar os testes funciona melhor que os testes são importantes.
Para verificar se o arquivo está sendo lido, faça dois testes simples. Primeiro, abra uma sessão nova e pergunte diretamente: quais regras deste projeto você conhece? Ele deve listar o conteúdo do CLAUDE.md. Segundo, peça uma tarefa pequena que exercite uma regra específica, como criar um arquivo, e confira no diff se a convenção de nomes foi respeitada. Se uma regra é ignorada com frequência, quase sempre ela está vaga demais ou enterrada em um parágrafo longo. Reescreva-a em uma linha própria, no imperativo, e teste de novo.
Um modelo comentado
O modelo a seguir usa um projeto de API em Node.js como exemplo. Os comentários em itálico explicam a intenção de cada bloco e devem ser removidos no arquivo real.
# API de pedidos ## Comandos - Instalar: npm install - Rodar em desenvolvimento: npm run dev - Testes: npm test - Lint: npm run lint (Comandos exatos evitam tentativas erradas.) ## Arquitetura Express com três camadas: rotas em src/routes, regras de negócio em src/services, acesso a dados em src/repositories. Rotas nunca acessam o banco diretamente. (Poucas frases; o detalhe está no código.) ## Convenções - Arquivos em kebab-case, funções em camelCase. - Validar entrada com zod na camada de rota. - Erros de negócio lançam AppError, nunca Error genérico. (Apenas o que o linter não garante.) ## Decisões que não devem ser revertidas - Usamos Knex em vez de ORM completo por controle de SQL. Não sugerir Prisma. (Justificativa curta para a IA não propor a troca.) ## Nunca fazer - Não editar arquivos em src/generated. - Não alterar migrações já aplicadas; criar uma nova. - Não desabilitar testes para fazer a suíte passar. ## Referências @docs/arquitetura.md (Importação de documento curto e estável.)Recapitulando
O CLAUDE.md é a memória persistente do Claude Code e substitui a repetição de instruções a cada sessão. O comando de barra init gera um rascunho que precisa ser revisado e enxugado. A hierarquia tem o global do usuário para preferências pessoais, o da raiz do projeto para regras do time, os de subpasta para áreas específicas e, quando existe, um arquivo de política da organização acima de todos; o CLAUDE.local.md ainda funciona para anotações não versionadas, mas é considerado obsoleto e tende a ser substituído por uma importação com arroba. Coloque comandos, convenções, arquitetura resumida, decisões protegidas e proibições; deixe de fora o que muda toda semana e o que já está óbvio no código. Importe documentos com arroba, aproveite os arquivos por pacote em monorepos, use a cerquilha para gravar regras durante a sessão, mantenha tudo em uma tela e verifique periodicamente se as regras estão sendo seguidas.
