O arquivo CLAUDE.md: ensinando o robô sobre o seu projeto

Toda vez que você abre uma sessão nova do Claude Code, ele começa do zero — sem lembrar das conversas anteriores. Isso quer dizer que, em tese, você teria que explicar tudo de novo a cada vez: o que é o projeto, como você gosta das coisas, o que ele deve ou não fazer. Cansativo.

Existe um jeito de não repetir. Um arquivo especial que o Claude Code lê sozinho, automaticamente, sempre que começa. Ele se chama CLAUDE.md. Hoje você vai criar o seu.

A ideia: o manual que você deixa pro novo colega

Imagine que chega uma pessoa nova pra te ajudar num trabalho. Você poderia explicar cada detalhe de viva voz toda manhã. Ou poderia escrever um bilhete uma vez só: "Olha, esse projeto é tal coisa. Eu prefiro que você faça assim. Não mexe naquilo. Fala comigo em português."

O CLAUDE.md é esse bilhete. É um arquivo de texto onde você escreve as regras da casa do seu projeto. O Claude Code lê esse arquivo antes de começar qualquer tarefa, sem você precisar pedir. As instruções que estão lá valem para todas as sessões, sempre.

Onde ele fica

O CLAUDE.md mora na pasta do seu projeto — a mesma pasta onde você abre o Claude Code. Nome exato, tudo em maiúsculas: CLAUDE.md. O .md de novo significa Markdown, aquele formato de texto simples que você já conhece.

Como ele fica na raiz do projeto, sempre que você abre o Claude Code naquela pasta, ele acha e lê o arquivo na hora.

O jeito mais fácil de criar: peça pro próprio Claude

Você não precisa escrever do zero olhando pra uma tela em branco. O mais prático é pedir pra ele mesmo criar uma primeira versão. Dentro de uma sessão, escreva:

Crie um arquivo CLAUDE.md para este projeto. É um site pessoal simples. Quero que você sempre me explique as coisas em português e em linguagem fácil, porque eu estou aprendendo.

Ele vai propor o arquivo, te mostrar o conteúdo e pedir sua confirmação (lembra das permissões do post anterior?). Aprove. Pronto: seu CLAUDE.md nasceu.

Depois, abra o arquivo (no VS Code, ou com cat CLAUDE.md no Mac / type CLAUDE.md no Windows) e leia. Ele é seu — você pode editar à vontade, acrescentar e tirar linhas.

Exemplos de linhas úteis

Não existe fórmula certa. Escreva em português normal, frases simples, uma instrução por linha. Alguns exemplos do que costuma ajudar:

• Sobre o projeto: "Este é um site pessoal simples, com uma página de apresentação e uma de contato."
• Sobre como falar com você: "Explique tudo em português e em linguagem fácil. Sou iniciante e não sei programar."
• Sobre o ritmo: "Antes de fazer mudanças grandes, me explique o plano e espere eu aprovar."
• Sobre o estilo: "Prefiro textos curtos e diretos." Ou: "Use cores claras e visual minimalista."
• Sobre limites: "Não apague arquivos sem me perguntar." Ou: "Não instale coisas novas sem avisar."

Pense no CLAUDE.md como algo vivo. Toda vez que você se pegar repetindo a mesma instrução em várias sessões — "lembra de explicar em português", "lembra de não mexer naquilo" —, é sinal de que aquilo deveria virar uma linha no CLAUDE.md. Aí você nunca mais precisa repetir.

Comece pequeno

Não tente prever tudo no primeiro dia. Um CLAUDE.md de cinco linhas já vale muito. Comece com o básico — o que é o projeto e como você quer ser tratado — e vá engordando o arquivo conforme o projeto cresce e você descobre suas preferências. Curto e útil é melhor que longo e esquecido.

Como saber se funcionou

Teste fácil: depois de criar o arquivo, feche o Claude Code (exit) e abra de novo na mesma pasta. Faça uma pergunta qualquer. Se você escreveu "explique em português fácil" e ele responde justamente assim, mesmo sem você ter pedido naquela sessão — funcionou. As regras da casa estão valendo sozinhas.

Se algo der errado

• Ele parece ignorar o CLAUDE.md. Confira o nome e o lugar. Tem que ser exatamente CLAUDE.md (maiúsculas) e estar na pasta onde você abre o Claude Code. Se estiver numa subpasta ou com nome diferente, ele não acha.
• O arquivo ficou enorme e confuso. Menos é mais. Apague o que não é essencial. Instruções demais se atrapalham; poucas regras claras funcionam melhor do que um calhamaço.
• Você escreveu uma regra e ela não está sendo seguida à risca. Tente deixá-la mais direta e específica. "Não mexa em arquivos da pasta fotos" funciona melhor que "tenha cuidado com as coisas importantes".

No próximo post, fechamos esse bloco de habilidades com uma das mais poderosas: o modo plano. Para tarefas maiores, você vai aprender a pedir que ele pense e explique o passo a passo antes de pôr a mão na massa — e por que isso evita um monte de bagunça.