📄 O que é o CLAUDE.md
Novo aqui? O CLAUDE.md é um arquivo de
texto simples (extensão .md, de "markdown" — um formato de texto puro com poucos símbolos de
formatação), colocado na raiz do projeto, que o agente lê automaticamente sempre que abre a pasta.
É o seu bilhete fixo pra ele.
💡 Conceito Principal
- •Leitura automática: você não precisa colar as regras em toda conversa.
- •Regras persistentes: ficam válidas em qualquer sessão nova.
Novo aqui? "Raiz do projeto" é a pasta principal — a de cima de todas
as outras, aquela que você abriu quando digitou claude no terminal (o programa de linha de
comando onde você digita instruções em vez de clicar em botões). Se o seu projeto é uma pasta chamada
meu-site com subpastas imagens/ e textos/ dentro, o CLAUDE.md fica
solto dentro de meu-site/, no mesmo nível de imagens/ e textos/ — nunca
dentro de uma subpasta.
imagens/ ou textos/.🔍 Ver por dentro
O CLAUDE.md é um arquivo de texto comum, do mesmo jeito que uma foto ou um documento — ele fica salvo no seu computador, dentro da pasta do projeto. Nada nele "vai pra internet" sozinho: só sai da sua máquina se você publicar o projeto em algum lugar (ex.: git push) ou colar o conteúdo em algum site.
Ele não custa nada pra existir — é só um arquivo de texto. O único "custo" é indireto: quanto mais linhas ele tem, mais texto o agente processa toda sessão, o que pode deixar as respostas mais lentas e caras (tema do próximo tópico).
✓ Onde criar o arquivo
- ✓Direto na raiz do projeto, mesmo nível das outras pastas
- ✓Nome exato:
CLAUDE.md, com maiúsculas e a extensão.md
✗ Erros comuns
- ✗Salvar dentro de uma subpasta — o agente não vai achar sozinho
- ✗Nome errado, tipo
claude.mdminúsculo ouClaude.MD— em alguns sistemas isso quebra a leitura automática
🔁 Por que ele é lido toda sessão
Novo aqui? Uma "sessão" é uma janela de conversa com o agente —
começa quando você abre o terminal e digita claude, e termina quando você fecha aquela janela ou
aquele processo. Cada nova sessão de conversa "esquece" o que foi dito na sessão anterior — o agente começa
do zero, sem lembrar de nada que vocês combinaram antes. O CLAUDE.md é o jeito de dar continuidade mínima:
qualquer sessão nova já nasce sabendo o essencial do projeto.
💡 Dica Prática
Colar as regras toda vez no chat funciona, mas cansa e você esquece um dia. O CLAUDE.md resolve isso de vez: escreva uma única vez, e a partir daí toda sessão nova — mesmo daqui a 3 meses — já começa sabendo as regras do projeto.
Você fecha o terminal
A conversa daquela sessão se perde.
Você roda claude de novo, dias depois
Nova sessão, sem memória da conversa antiga.
O CLAUDE.md é lido de novo, automático
As regras fixas continuam valendo, mesmo sem você repetir nada.
⚠️ Erro comum: editei o arquivo e "não funcionou"
Se você edita o CLAUDE.md no meio de uma sessão que já está aberta, é normal a mudança não valer na hora — o agente já leu o arquivo no começo daquela sessão e não fica reconferindo a cada mensagem. Solução simples: salve o arquivo e comece uma sessão nova (feche e rode claude de novo, ou digite /clear se o comando existir na sua versão). Na sessão nova, ele lê a versão atualizada.
✂️ Por que enxuto vence gigante
Este é o princípio-chave do módulo: um CLAUDE.md de 20 linhas bem escritas orienta melhor que um de 500 linhas genéricas. O agente lê o arquivo inteiro toda sessão — informação demais dilui o que realmente importa, e regras muito específicas competem por atenção com as regras essenciais.
Pense assim: se alguém te entregasse um manual de 40 páginas antes de cada tarefa de 5 minutos, você não ia conseguir lembrar de tudo — as instruções mais importantes se perderiam no meio de detalhes raros. Com o agente acontece algo parecido: ele lê o CLAUDE.md inteiro, mas quanto mais texto tem ali, mais difícil fica pra ele "pesar" cada regra igualmente. Um arquivo curto garante que as 3-5 regras que realmente importam fiquem em destaque, em vez de escondidas entre exceções raras.
Sinais de que seu CLAUDE.md engordou demais: você mesmo não lembra o que tem escrito lá; tem seções que você nunca releu desde que criou; ou o agente começa a ignorar uma regra que estava clara — sinal de que ela "sumiu" no meio de texto demais. Nesses casos, corte o que for raro e mantenha só o que muda o comportamento em quase toda tarefa.
✓ CLAUDE.md enxuto
- ✓20-40 linhas, direto ao ponto
- ✓Regras que realmente mudam o comportamento
- ✓Aponta pra outros arquivos quando precisa de detalhe
✗ CLAUDE.md gigante
- ✗Centenas de linhas, tenta documentar tudo
- ✗Regras raras misturadas com as essenciais
- ✗O agente "perde" a regra importante no meio do texto
💡 Dica Prática
Esse mesmo princípio reaparece na Trilha 3 (Skills): documentação boa aponta em vez de inchar.
📋 Exemplo real de CLAUDE.md, pronto pra copiar
Copie o modelo abaixo, ajuste os trechos marcados e salve como CLAUDE.md na raiz do seu projeto.
Objetivo: ter um CLAUDE.md funcional no seu primeiro projeto. Como verificar: abra o Claude Code na pasta e pergunte "quais são as regras deste projeto?" — a resposta deve citar o que você escreveu.
🔍 Cada seção do modelo, explicada
- Objetivo: uma frase que resume o projeto — ajuda o agente a entender o contexto geral antes de qualquer tarefa específica.
- Regras: o coração do arquivo — comportamentos que devem valer sempre, tipo "nunca publique sem aprovação" ou "responda em português".
- Comandos úteis: atalhos que você usa com frequência (ex.: como rodar os testes, como iniciar o servidor) — poupa o agente de "adivinhar" o comando certo.
- O que nunca fazer: a lista de linhas vermelhas — pastas que não podem ser apagadas, ações que exigem confirmação explícita antes de rodar.
✓ Ao escrever o seu
- ✓Salve com o nome exato
CLAUDE.md, sem espaços - ✓Use frases curtas e diretas, uma regra por linha
✗ Erros comuns
- ✗Deixar os textos de exemplo (
<...>) sem substituir — o agente vai levar ao pé da letra - ✗Escrever regras vagas demais, tipo "seja cuidadoso" — prefira algo específico e testável
🧩 Quando o projeto crescer: aponte, não inche
Se o projeto ganhar processos mais complexos, o detalhe extra vai para arquivos separados (dentro de
.claude/ ou uma pasta doc/) que o CLAUDE.md aponta com uma linha — não para dentro
dele. Isso mantém o arquivo principal sempre enxuto, mesmo que o projeto cresça.
🔍 Por dentro
Esse "apontar em vez de inchar" é o mesmo princípio que sustenta as skills — processos reutilizáveis que o agente carrega só quando precisa, tema da Trilha 3.
✓ Quando o projeto crescer
- ✓Crie um arquivo separado por assunto (ex.:
doc/deploy.md) - ✓No CLAUDE.md, deixe só uma linha apontando pra ele
✗ O que evitar
- ✗Colar o conteúdo inteiro do arquivo de detalhe dentro do CLAUDE.md
- ✗Deixar informação desatualizada duplicada em dois lugares
🧪 Testar o CLAUDE.md: peça um resumo
A prova de que o arquivo funciona é simples: peça pro agente resumir o próprio projeto logo depois de escrever o arquivo. Se a resposta bater com o que você escreveu, deu certo.
Objetivo: confirmar que o CLAUDE.md está sendo lido de verdade. Como verificar: a resposta deve citar o objetivo e as regras exatamente como você escreveu — esse é o exercício final da trilha, retomado no módulo 0.6.
⚠️ Deu errado? Checklist rápido
- •A resposta veio genérica, sem citar suas regras? Confira se o arquivo está mesmo na raiz do projeto (Tópico 1) e se você abriu o terminal dentro dessa pasta antes de rodar
claude. - •Editou o arquivo agora e a resposta não mudou? Feche e abra uma sessão nova (Tópico 2) — edição no meio da sessão não é relida sozinha.
- •Salvou como
.txtpor engano em vez de.md? Renomeie o arquivo — a extensão errada impede a leitura automática.