O que colocar no CLAUDE.md

Se o(a) senhor(a) fica sempre explicando ao Claude Code as mesmas regras do projeto, escreva-as no CLAUDE.md. É um arquivo de texto comum em Markdown. O Claude Code o lê no início da sessão e recebe os seus combinados junto com o resto do contexto.

Para começar bastam algumas linhas já testadas: onde trabalhar, como conferir o resultado e o que precisa ser preservado nas alterações.

Um exemplo de CLAUDE.md

Vamos pegar uma página simples com cartões. O layout, os estilos e o JavaScript estão num único index.html, e a página pode ser aberta direto no navegador. Para um projeto assim, o arquivo de instruções pode ficar assim:

# CLAUDE.md

## Projeto
- A página, os estilos e o JavaScript estão em `index.html`.

## Conferência
- Abrir `index.html` no navegador.
- Conferir a página em tela larga e em tela estreita.

## Regras
- Manter as cores atuais e o estilo dos cartões.
- Não excluir blocos já prontos sem confirmação.
- Depois do trabalho, listar as alterações e as conferências.

Aqui há três grupos: a estrutura do projeto, a conferência do resultado e os combinados. Agora um pedido como "adicione mais um cartão" não exige listar todas as regras de novo. Ainda assim dá para conferir a página por conta própria: ter a instrução não dá ao agente acesso a um navegador se ele não tiver essa ferramenta.

Este é um exemplo para um único arquivo, não um modelo universal. No seu projeto pode haver pastas separadas e comandos próprios de execução. Anote exatamente esses; se não houver testes, não acrescente um comando inventado só para completar.

O que vale a pena anotar

O filtro principal: essa anotação vai ser útil nas próximas tarefas? São úteis comandos já testados, caminhos importantes e combinados que o agente não conseguiria deduzir com segurança a partir do código. Especialmente aqueles que o(a) senhor(a) já teve que repetir.

Formule a regra de um jeito que deixe claro que ação se espera do agente:

"confira tudo" → "depois de alterar os cartões, confira a página em tela larga e em tela estreita";
"não mexa no que é importante" → "não exclua blocos já prontos sem confirmação: o conteúdo deles já foi combinado".

O primeiro caso diz qual conferência fazer; o segundo, onde vale a restrição e por quê. Isso é mais útil do que uma lista longa de desejos do tipo "trabalhe com cuidado".

O README.md explica a uma pessoa o que é aquele projeto e como começar a trabalhar nele. O CLAUDE.md reúne instruções para o agente. Não é preciso repetir todo o README ali. Já uma hipótese como "parece que a legenda desalinha por causa da largura do cartão" fica numa nota da tarefa atual, por exemplo PROJECT_NOTE.md. É um arquivo comum, com o nome que o(a) senhor(a) escolher; ao retomar a tarefa, peça ao agente para ler esse arquivo.

Não anote uma suposição como se fosse um fato estabelecido, e não guarde aqui senhas nem chaves de acesso. O CLAUDE.md compartilhado costuma ser incluído no Git, para que os colegas recebam as mesmas instruções junto com o projeto.

Como criar e conferir o arquivo

Comece pelas regras que o(a) senhor(a) já conhece. Não é preciso esperar acumular uma lista grande de erros, nem descrever de antemão todas as situações possíveis.

Veja se já existe um CLAUDE.md pronto no projeto. Se existir, leia-o e complemente-o. Para um arquivo novo, escolha a raiz do projeto; o caminho .claude/CLAUDE.md também é aceito, mas não há motivo para criar as duas cópias.
Escreva algumas linhas à mão ou digite /init dentro do Claude Code aberto na pasta do projeto. O comando vai analisar o projeto e preparar um rascunho; para um arquivo já existente, vai sugerir melhorias.
Leia o resultado. Confira os comandos e os caminhos com o projeto, remova os palpites. Por exemplo, se o agente incluiu um comando de testes que o(a) senhor(a) não tem, tire-o. As restrições que só o(a) senhor(a) conhece, acrescente-as pessoalmente.
Salve o arquivo e abra uma nova sessão na pasta do projeto. Digite /context: na seção Memory files deve aparecer o caminho do seu CLAUDE.md.

Em seguida, tente um pequeno ajuste: por exemplo, peça para adicionar um cartão e veja se as cores foram mantidas e se apareceu um relato das conferências. Se o arquivo não aparecer na lista, confira primeiro o nome dele e a pasta de onde a sessão foi aberta. Se aparecer, mas o resultado não bater com a regra, revise a formulação e possíveis contradições.

Carregamento e cumprimento

Estar na lista confirma que o arquivo foi carregado, mas não garante que as regras serão cumpridas. Uma resposta correta do agente, por si só, não comprova o carregamento: a informação pode ter sido encontrada em outros arquivos. A instrução orienta o trabalho, mas não cria uma proibição técnica para a ação.

Onde anotar o resto

Para o primeiro projeto, um único CLAUDE.md já basta. Quando surgem indicações pessoais ou muitas regras gerais, este esquema ajuda a escolher onde anotar:

Primeiro defina para que serve a anotação, depois escolha o arquivo.

Uma regra geral pode dizer respeito a uma única pasta e ainda assim ser necessária para toda a equipe. O .claude/rules/ ajuda a dividir instruções assim por tema; a limitação a caminhos específicos é configurada à parte. Para um par de regras, não há motivo para complicar a estrutura.

O CLAUDE.local.md serve para indicações pessoais dentro deste projeto, por exemplo a preferência por respostas curtas. Adicione-o ao .gitignore para não versioná-lo. O agente continua lendo o arquivo local, então segredos também não têm lugar ali.

O auto memory (memória automática) é um conjunto de notas à parte que o Claude salva ao longo do trabalho, quando esse mecanismo está ativado. Não deixe uma regra importante só a critério dele: peça diretamente para incluí-la no CLAUDE.md. Uma hipótese passageira sobre um bug continua sendo uma nota da tarefa.

Se o projeto já tiver um AGENTS.md, não copie o conteúdo dele para um segundo arquivo. No CLAUDE.md dá para importar o arquivo vizinho com a linha @AGENTS.md. Isso é especialmente útil ao adicionar o CLAUDE.local.md: o arquivo pessoal pode interferir na leitura direta do AGENTS.md. Outras opções estão descritas na documentação.

Quando atualizar as regras

Edite o arquivo junto com o projeto. Tirou os estilos do index.html para um arquivo separado? Corrija a linha sobre a estrutura. Mudou a forma de conferir? Substitua a instrução antiga. Não acrescente uma regra nova por cima de uma antiga que a contradiz.

Um ajuste repetitivo pode ser delegado ao agente: "Adicione ao CLAUDE.md que, antes de excluir um bloco já pronto, é preciso a minha confirmação". Depois leia a alteração: ela precisa transmitir o combinado do(a) senhor(a), sem novas restrições inventadas pelo agente. Uma linha costuma bastar.

Se uma regra for descumprida, primeiro entenda o motivo, em vez de repeti-la mais três vezes. Remova anotações desatualizadas e mantenha só o que ajuda na próxima tarefa.