Madureira
← Todas as edições

IA e Automações · 18 de novembro de 2026 · 5 min

CLAUDE.md: o que é, para que serve e o que eu coloco no meu

CLAUDE.md é o arquivo que o Claude Code lê no começo de toda sessão. O que colocar nele, o que deixar de fora e as regras que estão no meu.

Abrir no ChatGPTAbrir no Claude

O problema
Toda conversa com o agente começa do zero e você repete as mesmas regras, ou escreveu um CLAUDE.md enorme que o agente segue pela metade.
Para aplicar
Escreva no CLAUDE.md só três coisas: onde fica cada tipo de arquivo, uma regra dura com o motivo e o caminho do documento mais importante. Na próxima sessão, peça algo que dependa dessas três.

CLAUDE.md é um arquivo de texto que o Claude Code lê sozinho no começo de toda sessão. Fica na raiz da pasta do projeto e carrega as instruções que valem sempre: o que é aquele lugar, onde fica cada coisa e o que nunca pode acontecer. Sem ele, toda conversa começa do zero. Com ele, o agente chega sabendo as regras da casa.

O meu é o primeiro arquivo da pasta onde eu trabalho e já foi reescrito do zero uma vez, em agosto, quando decidi parar a maior parte dos produtos próprios para focar em poucas frentes. Mostro aqui o que tem nele e por quê.


Para que serve o CLAUDE.md?

Para tirar da sua cabeça o que você repetiria em toda conversa. Entram três tipos de coisa:

  1. Mapa. O que existe na pasta e onde.
  2. Regras duras. O que o agente nunca faz, com o motivo.
  3. Ponteiros. Onde está o detalhe de cada assunto, sem copiar o detalhe para dentro.

O que fica de fora: tarefa do dia, lista de pendências e frase de estado, como "o deploy está quebrado". Isso envelhece em uma semana, e o agente continua lendo como verdade.

O que tem no meu

As frentes da casa. Uma tabela com as seis frentes de trabalho (a agência e os produtos próprios) e, para cada uma, o arquivo índice que deve ser aberto. O CLAUDE.md não descreve a frente: aponta para quem descreve.

Onde fica cada coisa. Uma regra de uma linha organiza a pasta inteira: se tem package.json ou .git, vai para code/; texto em markdown e imagem leve vão para vault/; vídeo vai para media/. Nunca arquivo solto na raiz.

Regras duras, numeradas. As que mais trabalham:

  • Nunca publicar nem agendar sem o meu OK explícito, para qualquer cliente.
  • Número em material da Kaleidos só sai de um arquivo de provas. Se a peça precisa de um número que não está lá, o agente para e pede apuração.
  • Zero hashtag.
  • Nunca apagar, sempre mover para uma pasta de arquivo datada.
  • Deploy só está feito quando o comportamento foi exercido contra produção.
  • Antes de escrever para um cliente, ler o arquivo daquele cliente e a régua do canal.

O diário. Toda tarefa pedida, iniciada e terminada vira uma linha no diário do dia, com o projeto marcado. E a seção de próximos passos tem teto de três linhas abertas.


A regra que veio de uma medição

O teto de três linhas é a parte mais estranha do arquivo e a que mais me ensinou.

Em 19 de agosto medi o diário: havia 1.430 tarefas abertas espalhadas pelos dias, e nenhuma voltava a aparecer em três dias ou mais. A tarefa era escrita uma vez em "próximos" e nunca relida. Aquilo era sedimento com cara de dívida, não backlog.

Desde então, "próximos" é fila curta e relida, e o excedente vai para um arquivo de ideias sem prazo nem dono. Escrevi o motivo dentro do próprio CLAUDE.md, porque regra sem motivo é a primeira a ser quebrada por um agente que acha que está ajudando.

CLAUDE.md, AGENTS.md e os outros níveis

O Claude Code lê CLAUDE.md em mais de um nível: o pessoal, que vale para todos os projetos; o da raiz do projeto; e os das subpastas, quando ele trabalha nelas. O mais específico complementa o geral.

Outras ferramentas de agente leem um arquivo parecido chamado AGENTS.md. No código deste site, o CLAUDE.md tem uma linha só, @AGENTS.md, que importa o outro. Uma fonte, duas ferramentas lendo.


Como escrever o seu

  1. Comece por cinco linhas. O que é a pasta, onde fica cada tipo de arquivo, uma coisa que nunca pode acontecer.
  2. Toda regra com o porquê. "Nunca apague arquivo" é fácil de ignorar. "Nunca apague arquivo, porque esta pasta não tem backup e o que sai não volta" já não é.
  3. Aponte, não copie. Se o manual de marca tem 40 páginas, o CLAUDE.md diz onde ele está.
  4. Date as decisões. "28/09: gestão só no sistema X." Quando a regra mudar, você sabe de quando era a anterior.
  5. Releia quando o agente errar. Erro repetido costuma ser regra ausente, ou regra escrita de um jeito que dá para ler ao contrário.

O erro que eu cometi

A versão anterior do meu era um mapa de todos os projetos da casa, cada um com a sua descrição. Quando parei a maioria deles, o mapa passou a mandar o agente para lugar onde ninguém devia mais trabalhar.

Reescrevi em 20 de agosto para descrever só o que muda devagar: as frentes, as regras e onde mora cada índice. A versão antiga ficou guardada num arquivo, para comparar. Desde então, quando uma frente nasce ou para, muda uma linha da tabela, e o resto do arquivo continua verdadeiro.

Se você quer ir além do arquivo de regras, escrevi sobre as outras camadas em Memória para agentes de IA.

O que fazer amanhã

Abra o CLAUDE.md do seu projeto, ou crie um, e escreva só três coisas: onde fica cada tipo de arquivo, uma regra dura com o motivo e o caminho do documento mais importante. Na próxima sessão, peça algo que dependa dessas três e veja se o agente segue sem você lembrar.