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.
- 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:
- Mapa. O que existe na pasta e onde.
- Regras duras. O que o agente nunca faz, com o motivo.
- 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
- Comece por cinco linhas. O que é a pasta, onde fica cada tipo de arquivo, uma coisa que nunca pode acontecer.
- 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 é.
- Aponte, não copie. Se o manual de marca tem 40 páginas, o CLAUDE.md diz onde ele está.
- Date as decisões. "28/09: gestão só no sistema X." Quando a regra mudar, você sabe de quando era a anterior.
- 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.