Onde eu crio o arquivo CLAUDE.md?

O mais comum é na raiz do projeto, com o nome CLAUDE.md, para que valha para todo o time via controle de versão. Há outras localizações com escopos diferentes, tema da próxima aula. Você pode escrever o arquivo à mão ou usar o comando de inicialização, que gera um rascunho analisando o seu projeto.

O que acontece se eu não tiver um CLAUDE.md?

O Claude Code funciona mesmo assim, só que sem o contexto permanente do projeto. Você acaba reexplicando comandos e convenções com mais frequência. Um bom CLAUDE.md não é obrigatório, mas é um dos ajustes que mais melhoram a experiência, porque alinha o agente ao seu jeito de trabalhar desde o início.

O CLAUDE.md é o mesmo para todo mundo do time?

O CLAUDE.md da raiz do projeto é compartilhado pelo time via controle de versão, então vale para todos. Existem também arquivos pessoais, que só valem para você, e um nível de usuário que vale para todos os seus projetos. A próxima aula detalha essa hierarquia de escopos.

Se o agente às vezes ignora o CLAUDE.md, ele não serve?

Serve, e muito. O CLAUDE.md é contexto que guia o comportamento, e instruções específicas são seguidas com alta consistência. O que ele não é é uma trava absoluta. Para exigências que precisam acontecer sempre, sem exceção, o certo é usar um hook, que roda automaticamente, tema de um módulo próprio.

Posso colocar qualquer coisa no CLAUDE.md?

Pode, mas não deve. Ele funciona melhor com o essencial e permanente: comandos, convenções, arquitetura, regras do tipo sempre. Detalhes passageiros de uma tarefa e procedimentos longos ficam melhor em outros lugares, como regras path-scoped e skills, que o módulo apresenta. Encher o CLAUDE.md piora a adesão.

Módulo 5 - CLAUDE.md e memória de projeto

O que é o CLAUDE.md e por que ele muda tudo

9 min de leitura · por Cesar Gargiulo, revisão editorial da equipe ValorFinal · Atualizado em 25/09/2026

Velocidade

O que você vai aprender

Explicar o que é o arquivo CLAUDE.md.
Entender por que cada sessão começa do zero.
Aplicar o teste do que eu reexplicaria para decidir o que entra.
Reconhecer o CLAUDE.md como contexto, não como imposição.

Cada sessão começa do zero

Há uma característica do Claude Code que confunde quem está começando: cada sessão nasce sem memória das anteriores. Você explica hoje que o projeto usa duas casas de indentação e roda os testes com um comando; amanhã, numa sessão nova, ele não lembra disso sozinho. Isso não é defeito, é como a ferramenta funciona: a memória da conversa vive dentro da sessão. O problema prático é óbvio: ninguém quer reexplicar as mesmas coisas todo dia. A solução tem nome e é o coração deste módulo: o arquivo CLAUDE.md.

O CLAUDE.md é um arquivo de texto simples, em Markdown, que você escreve uma vez e o Claude Code lê no começo de toda sessão. Nele você escreve o que gostaria que o agente soubesse sempre sobre o seu projeto: qual comando roda os testes, qual é o padrão de código, onde ficam os arquivos importantes, o que nunca deve ser feito. É como deixar um bilhete permanente na porta que o agente sempre lê antes de começar a trabalhar. Com um bom CLAUDE.md, você para de repetir instruções e o agente já chega alinhado com o jeito do projeto.

Diagrama mostrando várias sessões do Claude Code em dias diferentes, cada uma começando vazia, e um arquivo CLAUDE.md acima delas enviando as mesmas instruções permanentes (comandos, convenções, arquitetura) para todas, como um bilhete lido no início de cada sessão. — As sessões começam do zero; o CLAUDE.md entrega as mesmas instruções permanentes para todas.

O teste do que eu reexplicaria

A pergunta natural é o que colocar no CLAUDE.md. Existe um teste simples e certeiro: coloque ali o que você reexplicaria toda vez, o que um colega novo precisaria saber para ser produtivo no projeto. Se você se pegou digitando a mesma correção que digitou na sessão passada, ela é candidata a virar uma linha no CLAUDE.md. Se uma revisão de código pegou algo que o agente deveria saber sobre este projeto, vale registrar. O objetivo é transformar cada reexplicação repetida numa instrução permanente, escrita uma vez e válida sempre.

Bom para o CLAUDE.md	Exemplo
Comandos do projeto	Rodar os testes com determinado comando
Convenções de código	Usar duas casas de indentação
Arquitetura e layout	Os manipuladores de rota ficam em tal pasta
Regras do tipo sempre	Rodar o lint antes de cada commit
O que evitar	Não instalar dependências novas sem pedir

Fatos que valem para toda sessão. Se você reexplicaria, é candidato a entrar no CLAUDE.md.

🎮 Jogo da aula

Entra no CLAUDE.md?

Classifique cada item: é um fato permanente que vale para toda sessão ou algo passageiro que não deveria virar memória fixa?

O contrário também importa: o que NÃO colocar. Coisas passageiras, ligadas a uma única tarefa do dia, não merecem virar instrução permanente, porque poluiriam toda sessão com detalhes que só valiam naquele momento. E procedimentos longos de vários passos, ou instruções que só valem para uma parte do projeto, ficam melhor em outros lugares que você vai conhecer neste módulo, as regras e as skills. O CLAUDE.md é para o essencial e transversal, aquilo que é verdade sobre o projeto inteiro, o tempo todo.

Contexto que guia, não trava que impõe

Um ponto que evita frustração: o CLAUDE.md é contexto, não uma trava rígida. O agente lê as instruções e tenta segui-las, mas não há garantia de obediência absoluta, principalmente se a instrução for vaga ou contradizer outra. Isso quer dizer duas coisas práticas. Primeira: quanto mais específica e clara a instrução, mais confiável o agente a segue. Segunda: se algo PRECISA acontecer sempre, sem exceção, como rodar uma verificação antes de todo commit, o lugar certo não é o CLAUDE.md, é um hook, um mecanismo automático que você vai estudar em módulo próprio.

Entender essa natureza muda como você escreve o arquivo. Em vez de esperar obediência cega, você escreve instruções claras, específicas e sem contradições, que é o que mais aumenta a adesão. E, quando a exigência for crítica, você não confia só no bilhete: usa a ferramenta certa para impor. Ao longo do curso, esses dois níveis, guiar com o CLAUDE.md e impor com hooks, vão se completar. Por enquanto, a mensagem central é que o CLAUDE.md é o seu principal instrumento para alinhar o agente ao projeto, e as próximas aulas mostram como tirá-lo do máximo.

Teste rápido

Qual é o propósito do arquivo CLAUDE.md?

Perguntas frequentes

Onde eu crio o arquivo CLAUDE.md?: O mais comum é na raiz do projeto, com o nome CLAUDE.md, para que valha para todo o time via controle de versão. Há outras localizações com escopos diferentes, tema da próxima aula. Você pode escrever o arquivo à mão ou usar o comando de inicialização, que gera um rascunho analisando o seu projeto.
O que acontece se eu não tiver um CLAUDE.md?: O Claude Code funciona mesmo assim, só que sem o contexto permanente do projeto. Você acaba reexplicando comandos e convenções com mais frequência. Um bom CLAUDE.md não é obrigatório, mas é um dos ajustes que mais melhoram a experiência, porque alinha o agente ao seu jeito de trabalhar desde o início.
O CLAUDE.md é o mesmo para todo mundo do time?: O CLAUDE.md da raiz do projeto é compartilhado pelo time via controle de versão, então vale para todos. Existem também arquivos pessoais, que só valem para você, e um nível de usuário que vale para todos os seus projetos. A próxima aula detalha essa hierarquia de escopos.
Se o agente às vezes ignora o CLAUDE.md, ele não serve?: Serve, e muito. O CLAUDE.md é contexto que guia o comportamento, e instruções específicas são seguidas com alta consistência. O que ele não é é uma trava absoluta. Para exigências que precisam acontecer sempre, sem exceção, o certo é usar um hook, que roda automaticamente, tema de um módulo próprio.
Posso colocar qualquer coisa no CLAUDE.md?: Pode, mas não deve. Ele funciona melhor com o essencial e permanente: comandos, convenções, arquitetura, regras do tipo sempre. Detalhes passageiros de uma tarefa e procedimentos longos ficam melhor em outros lugares, como regras path-scoped e skills, que o módulo apresenta. Encher o CLAUDE.md piora a adesão.

Fontes

Seu progresso fica salvo neste aparelho. Assinantes sincronizam entre os aparelhos.

← Quando ele erra e se corrige Concluir e avançar →