Onde eu crio o arquivo CLAUDE.md?

O mais comum e na raiz do projeto, com o nome CLAUDE.md, para que valha para todo o time via controle de versão. Ha outras localizacoes com escopos diferentes, tema da próxima aula. Você pode escrever o arquivo a mão ou usar o comando de inicializacao, 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 convencoes com mais frequência. Um bom CLAUDE.md não é obrigatório, mas e 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 e o mesmo para todo mundo do time?

O CLAUDE.md da raiz do projeto e 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 as vezes ignora o CLAUDE.md, ele não serve?

Serve, e muito. O CLAUDE.md e contexto que guia o comportamento, e instruções específicas são seguidas com alta consistencia. O que ele não é e uma trava absoluta. Para exigencias que precisam acontecer sempre, sem exceção, o certo e 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, convencoes, 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 adesao.

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, revisado pela equipe ValorFinal e GuardiaSec · Atualizado em 13/07/2026

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 imposicao.

Cada sessão começa do zero

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

O CLAUDE.md e um arquivo de texto simples, em Markdown, que você escreve uma vez e o Claude Code le 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. E como deixar um bilhete permanente na porta que o agente sempre le 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, convencoes, 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 e 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 e transformar cada reexplicacao repetida numa instrução permanente, escrita uma vez e valida sempre.

Bom para o CLAUDE.md	Exemplo
Comandos do projeto	Rodar os testes com determinado comando
Convencoes de código	Usar duas casas de indentacao
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 dependencias novas sem pedir

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

🎮 Jogo da aula

Entra no CLAUDE.md?

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

O contrario 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 e para o essencial e transversal, aquilo que é verdade sobre o projeto inteiro, o tempo todo.

Contexto que guia, não trava que impoe

Um ponto que evita frustracao: o CLAUDE.md e contexto, não uma trava rigida. O agente le as instruções e tenta segui-las, mas não ha garantia de obediencia 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 confiavel o agente a segue. Segunda: se algo PRECISA acontecer sempre, sem exceção, como rodar uma verificacao antes de todo commit, o lugar certo não é o CLAUDE.md, e 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 obediencia cega, você escreve instruções claras, específicas e sem contradicoes, que é o que mais aumenta a adesao. E, quando a exigencia for critica, 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, vao se completar. Por enquanto, a mensagem central e que o CLAUDE.md e o seu principal instrumento para alinhar o agente ao projeto, e as próximas aulas mostram como tira-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 e na raiz do projeto, com o nome CLAUDE.md, para que valha para todo o time via controle de versão. Ha outras localizacoes com escopos diferentes, tema da próxima aula. Você pode escrever o arquivo a mão ou usar o comando de inicializacao, 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 convencoes com mais frequência. Um bom CLAUDE.md não é obrigatório, mas e 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 e o mesmo para todo mundo do time?: O CLAUDE.md da raiz do projeto e 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 as vezes ignora o CLAUDE.md, ele não serve?: Serve, e muito. O CLAUDE.md e contexto que guia o comportamento, e instruções específicas são seguidas com alta consistencia. O que ele não é e uma trava absoluta. Para exigencias que precisam acontecer sempre, sem exceção, o certo e 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, convencoes, 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 adesao.

Fontes

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

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