CLAUDE.md: o que é e como escrever o seu, com modelo para copiar

Imagine contratar uma pessoa nova toda manhã e ter de explicar tudo de novo: quem você é, como gosta de receber as respostas, o que ela não pode fazer. É assim que o Claude Code funciona se você não deixar nada escrito, porque cada conversa começa sem o histórico das anteriores. A solução é um arquivo chamado CLAUDE.md.

Eu não sou programador e uso esse arquivo em todos os meus projetos. Este texto é independente e não tem vínculo com a Anthropic, que criou o Claude Code.

O que é o CLAUDE.md

É um arquivo de texto comum, com esse nome exato, que o Claude Code lê no início de cada sessão. Funciona como o manual da equipe: tudo o que está nele vale desde a primeira mensagem, sem você repetir.

Pode existir um por projeto, dentro da pasta do projeto, e também um geral seu, que vale para todos os projetos. O arquivo do projeto guarda o que é específico dele. Por exemplo: “este sistema é o Painel de Pedidos da Gráfica Aurora e os status são Recebido, Em produção, Pronto e Entregue”. O arquivo geral guarda o seu jeito de trabalhar, que não muda de um projeto para outro.

Você não precisa saber onde ele fica no computador. Peça ao agente, a IA que trabalha na pasta: “crie o CLAUDE.md na pasta do projeto com este conteúdo”. Depois confirme que o arquivo apareceu.

O que colocar nele

Quatro blocos bastam. Mais do que isso vira texto que ninguém, nem a IA, segue com cuidado.

1. Quem sou eu. Seu nível técnico e o contexto do trabalho. Isso muda o tom das explicações. Quem avisa “não sou programador” recebe explicação em linguagem comum.
2. Como quero as respostas. Idioma, tamanho, se prefere lista ou texto, se quer que os termos técnicos sejam traduzidos.
3. Regras de trabalho. Um resumo de como você quer que o trabalho seja conduzido.
4. O que nunca fazer sem me perguntar. As ações que exigem a sua autorização, como apagar dados ou levar algo para produção, que é a versão que as pessoas usam de verdade.

Escreva como se falasse com uma pessoa inteligente e nova na equipe: frases diretas, no imperativo. “Pergunte antes de apagar” funciona melhor do que um parágrafo sobre cautela.

Modelo para copiar

Este modelo é genérico e serve para qualquer projeto. Troque o que estiver entre colchetes e apague o que não se aplica. Depois, peça ao agente que o salve como CLAUDE.md na pasta do projeto.

# Manual da equipe

## Quem sou eu
- Eu não sou programador. Trabalho em [sua área] e uso este projeto para [objetivo].
- Descrevo o que quero pelo que vejo na tela. Interprete a intenção, mesmo que eu escreva rápido ou com erros.

## Como quero as respostas
- Responda em português do Brasil, direto e em linguagem comum.
- Quando usar um termo técnico, explique em uma frase o efeito prático.
- Termine cada entrega com "Feito" e "Falta" tirados do PLANO.md.

## Regras de trabalho
- Perguntas primeiro: antes de começar, faça todas as perguntas que te bloqueiam, numeradas, de uma vez, com opções e recomendação. Minhas respostas não são aprovação: depois delas, mostre o plano. Depois do meu sim ao plano, vá até o fim sem pedir "continua".
- Lista que não evapora: tudo o que eu pedir vai para o PLANO.md, com caixas de marcar. Marque cada item ao concluir.
- Pronto é testado: só diga que está pronto depois de abrir o sistema e usar de verdade. Termine com um bloco "Como testar" que eu consiga seguir sem saber programar.
- Proteja o que funciona: não mude o que já funciona sem avisar. Faça uma cópia de segurança antes de mexer em dados.

## Nunca faça sem me perguntar
- Apagar arquivos ou dados.
- Levar qualquer coisa para produção, o que as pessoas usam de verdade.
- Instalar programas novos ou criar contas.
- Guardar senhas ou chaves dentro dos arquivos do projeto.
- Se uma ordem minha parecer destrutiva, responda minha dúvida antes de executar.

O modelo cabe numa tela, de propósito: manual curto é lido por inteiro.

Por que cada bloco existe

O bloco “Quem sou eu” evita que o agente responda como se você já conhecesse o assunto. O bloco de respostas elimina pedidos repetidos, como “explica de novo mais simples”.

O bloco de regras é o coração. Cada uma nasceu de um problema meu. “Perguntas primeiro” veio do tempo que perdi digitando “continua”. “Pronto é testado” veio de receber “pronto” quando só os testes automáticos tinham passado e ninguém tinha aberto o sistema para clicar. Escritas no manual, as regras valem mesmo quando você esquece de lembrar.

O último bloco é o seu cinto de segurança. A frase sobre ordem destrutiva tem motivo prático: se você mandar apagar algo por engano, o agente responde primeiro com a dúvida, em vez de executar.

Melhore o arquivo a cada erro repetido

O manual não nasce pronto, cresce com os erros. A regra é simples: se o mesmo erro acontecer duas vezes, ele merece uma linha no CLAUDE.md. Alguns exemplos, com a Gráfica Aurora:

• A tela mostrou o status “In production”. Linha nova: “Todos os textos da tela ficam em português. Os status são Recebido, Em produção, Pronto e Entregue.”
• Em campo vazio, a tela mostrava a palavra “null”. Linha nova: “Campo sem valor aparece como um traço.”
• A Lúcia queria ver o prazo com dia e mês. Linha nova: “Datas aparecem como dia/mês/ano.”

Para fazer isso sem esforço, peça ao próprio agente:

Esse erro já aconteceu antes. Escreva em uma linha, no CLAUDE.md, a regra que evita que ele se repita. Mostre a linha antes de salvar.

Cada linha dessas é um erro que você não paga duas vezes.

O que não vai no manual

Duas coisas ficam de fora.

Primeiro, senhas, chaves de acesso e dados pessoais de clientes. O arquivo fica na pasta do projeto e pode acabar compartilhado sem você perceber.

Segundo, a lista de tarefas do momento. Ela merece arquivo próprio, como um PLANO.md, porque muda toda hora, e o manual deve mudar devagar.

Faça a poda de vez em quando

Manual que cresce sem cuidado vira problema. Uma vez por mês, peça ao agente para listar as linhas repetidas, contraditórias ou que não se aplicam mais, e apague o que for. Regra contraditória confunde a IA do mesmo jeito que confundiria uma pessoa.

Teste se funcionou

Salvo o arquivo, abra uma nova sessão e pergunte: “o que está escrito no seu manual de trabalho?”. Se ele responder com as regras certas, a equipe já tem um manual. Se não, peça que confirme em que pasta está trabalhando e onde o arquivo foi salvo.

Quer o método completo?

O CLAUDE.md é só uma das peças do guia “Equipe de IA sem programar”, que também é independente e não oficial. Nele há o passo a passo para montar a lista de tarefas, conferir entregas e proteger o que já funciona. Se quiser conhecer, o botão está abaixo.