CLAUDE.md: o que incluir após 42 projetos

Atualização (9 de novembro de 2026): Claude Fable 5.2 e Mythos 5.2 foram lançados - preços, acesso e benchmarks no meu guia do Claude Fable 5.2.

👁 112 leituras

Tenho 42 arquivos de instruções para agentes de IA no meu disco: 16 CLAUDE.md e 26 AGENTS.md, cada um na pasta de um projeto. O mais curto tem uma linha; o mais longo, 402. Esse maior tem o dobro do tamanho recomendado pela Anthropic. Vou começar por ele porque mostra bem o que acaba entrando nesse tipo de arquivo.

O que é um arquivo CLAUDE.md

É um arquivo Markdown comum que o Claude Code lê no início de cada sessão. Toda conversa com o agente começa sem memória, então você precisa repetir tudo o que não dá para descobrir pelo código. O CLAUDE.md faz isso por você: reúne comandos de teste, regras do projeto, coisas que o agente não pode fazer e armadilhas que você já encontrou.

A documentação do Claude Code diz claramente que o arquivo fornece contexto, não configurações rígidas. Em geral, o agente segue as instruções, mas não é obrigado a fazê-lo. Se algo precisa ser sempre bloqueado, como apagar arquivos ou fazer uma implantação no servidor, use hooks e permissões nas configurações, não uma frase no CLAUDE.md.

Onde fica e o que é carregado

É possível ter vários arquivos ao mesmo tempo. O Claude Code não escolhe apenas um: combina todos os que encontra, da instrução mais geral à mais próxima da pasta em que você está trabalhando.

Os arquivos das pastas acima do local em que você inicia o agente são carregados imediatamente. Os arquivos de subpastas só são carregados quando o agente começa a ler ou alterar arquivos nelas. Assim, em um repositório grande, as instruções de frontend não ocupam espaço quando o agente está trabalhando no banco de dados.

Você pode gerar uma primeira versão com o comando /init. O Claude examina o código e registra os comandos e padrões que consegue encontrar. É um bom começo, mas eu sempre acrescento o restante manualmente: as linhas mais valiosas são justamente as que não dá para descobrir pelo código.

Meu arquivo mais longo: 402 linhas

A documentação recomenda que cada CLAUDE.md tenha menos de 200 linhas, porque um arquivo maior consome contexto e o agente tende a seguir menos as instruções. Meu arquivo do projeto Jantaris tem 402 linhas e 46.095 bytes. Dos meus 16 arquivos CLAUDE.md, só esse passa do limite; a mediana é de 35 linhas.

Ele não ficou pronto de uma vez. Foi crescendo com novas armadilhas, anotadas depois de cada erro: como o servidor armazena imagens em cache e por que substituir um arquivo pelo mesmo nome só faz a mudança chegar às pessoas uma semana depois; quantos cadastros por hora a proteção permite e como os testes precisam zerar esse limite; onde fica o servidor e como o envio de e-mails funciona. Cada linha registra um problema concreto. Juntas, elas acabaram ficando demais.

Na minha opinião, o CLAUDE.md não é a documentação do projeto: é um mapa de armadilhas. O agente encontra no código e no README a descrição de como o aplicativo funciona. No CLAUDE.md, entram as coisas que o código não mostra, mas que já deram problema. Quando o arquivo passa de 200 linhas, eu o divido em arquivos temáticos dentro de .claude/rules/. Importar por meio de @arquivo.md ajuda a organizar, mas o arquivo importado ainda é carregado por inteiro.

O arquivo que mostro no curso: 34 linhas

Um bom exemplo é o CLAUDE.md do projeto “Base de reparos”, um aplicativo para uma oficina mecânica que estamos criando do zero no meu curso SaaS em um fim de semana com Claude Code. Abaixo está o arquivo inteiro, traduzido do original em polonês. Os nomes, comandos e regras técnicas foram mantidos; o texto traduzido não representa um novo teste em português:

# Base de reparos - anotações para o agente

Produto, telas e regras: @SPEC.md
Implemente apenas a seção PRECISA TER do ESCOPO.md. Acrescente ideias
fora dela à seção DEPOIS, com uma condição para retomá-las, e me pergunte.

## Stack
- Node 22.13 ou superior, sem dependências npm: node:http, node:sqlite, node:test, fetch.
- SQLite em data/app.db, migrações em migrations/NNN_nome.sql.
- HTML renderizado no servidor; no navegador, JavaScript puro.

## Comandos
- npm run dev                 servidor na porta 8080, reinicia ao alterar um arquivo
- npm test                    node --test "test/*.test.js" (padrão glob entre aspas)
- npm run reset               banco de dados do zero + dados de teste + contas de teste
- python tools/capturas.py URL capturas em 1440 px e 390 px em data/shots/

## Regras
- Valores monetários em centavos, como INTEGER. Nunca use números de ponto flutuante.
- O servidor verifica os limites dos planos (R1-R3). O navegador apenas os exibe.
- Cada regra R do SPEC.md precisa de um teste com seu número no nome.
- Salve arquivos de texto com finais de linha LF.
- Use apenas hífen "-" nos textos. O teste verifica todos os modelos.

## Proibições
- Não leia .env. Não faça implantação. Não execute git push, git reset ou git clean.
- Não execute testes em data/app.db (os testes usam um banco em memória).
- Não importe dados de fábrica (Autodata, HaynesPro, portais de fabricantes):
  licenças dos fabricantes e proteção de bancos de dados na UE.

## Armadilhas
- O Git Bash altera caminhos: use MSYS_NO_PATHCONV=1 antes de comandos com /...
- Salve arquivos com expressões regulares usando uma ferramenta de escrita de arquivos,
  não um heredoc no bash (que pode perder barras invertidas).

Cada seção tem um motivo:

• Referência à especificação. A descrição do produto fica em SPEC.md, e o CLAUDE.md apenas a importa. A instrução para implementar a seção PRECISA TER mantém o agente dentro do escopo. Sem ela, depois de uma hora você pode receber funcionalidades que ninguém pediu.
• Comandos com a sintaxe exata. Colocar o padrão glob entre aspas no comando de teste é um detalhe fácil de esquecer, mas dele depende a execução de todos os arquivos de teste.
• Regras verificáveis. Valores em centavos, limites no servidor e um teste para cada regra. Nada de “escreva código limpo”, porque não dá para verificar isso.
• Proibições. Repito as mais importantes nas configurações de permissões, porque o arquivo é apenas um pedido.
• Armadilhas do ambiente. O Windows e o Git Bash podem alterar caminhos que começam com uma barra. O agente só descobre isso quando o comando falha.

A linha que me custou uma rodada de edição

Um exemplo mostra bem a importância dessas instruções. Em 30 de outubro, durante a edição de textos da revista DYGOT, um script que busca o estado atual no servidor foi executado entre as correções e o envio. Ele sobrescreveu as alterações locais, e a primeira rodada de edição se perdeu. Desde então, o arquivo de instruções desse projeto inclui a frase: “Execute SOMENTE antes de começar a trabalhar: entre a edição e o envio, o script sobrescreve suas alterações”. Nenhum gerador teria escrito isso, porque não dá para deduzir pelo código do script quando é seguro executá-lo.

AGENTS.md: instruções para outros agentes

AGENTS.md é um arquivo de instruções do mesmo tipo, mas com um nome lido por várias ferramentas: Codex, da OpenAI; Cursor; Gemini CLI; o agente do GitHub Copilot; e muitas outras. O formato é mantido pela Agentic AI Foundation, da Linux Foundation. Tenho 26 arquivos desse tipo, e eles são curtos: a mediana é de 8 linhas, porque a maioria descreve tarefas gráficas específicas para o Codex.

O Claude Code também consegue ler AGENTS.md a partir da versão 2.1.277. Por padrão, isso só acontece quando não há um arquivo CLAUDE.md no projeto. Se os dois existirem, o Claude lê o próprio arquivo e ignora o AGENTS.md. Para que as duas ferramentas recebam as mesmas regras, a opção mais simples é mantê-las no AGENTS.md e acrescentar no CLAUDE.md uma linha que importe o arquivo: @AGENTS.md. Expliquei como migrar o conjunto inteiro, incluindo skills e servidores MCP, no artigo como migrar do Claude Code para o Codex.

Nos projetos em que Claude e Codex trabalham alternadamente, também deixo uma regra no fim do arquivo: depois de trabalhar, registre as mudanças em um diário compartilhado dos agentes, com a data, o nome do agente e a lista de alterações. O próximo agente lê o diário antes de começar e sabe o que o anterior mudou. É mais simples do que sincronizar a memória das duas ferramentas.

O que não incluo

• Chaves e senhas. O arquivo do projeto muitas vezes vai para o repositório. Nos meus arquivos, prefiro proibir a leitura de .env a incluir seu conteúdo.
• A estrutura das pastas. O agente consegue encontrá-la em poucos segundos, e a descrição no arquivo fica desatualizada assim que algo muda.
• Generalidades. “Preze pela qualidade” não muda nada. “Cada regra precisa de um teste com seu número” muda.
• Regras contraditórias. A documentação alerta que, diante de duas instruções conflitantes, o Claude pode escolher qualquer uma. De vez em quando, reviso meus arquivos e removo o que já não vale.
• Anotações para pessoas. Se elas precisarem ficar no arquivo, coloco-as em um comentário HTML <!-- -->. O Claude Code remove esses comentários antes de carregar o arquivo, então eles não consomem contexto.

Por onde começar

Se você está começando com o Claude Code, não escreva um CLAUDE.md antecipadamente. Execute /init, mantenha o que fizer sentido e acrescente uma linha cada vez que o agente repetir o mesmo erro. Depois de uma semana, você terá um arquivo que descreve o seu projeto, não o projeto de um tutorial. Explico a instalação e os primeiros passos no guia Claude Code: instalação; os custos dos planos estão no artigo quanto custa o Claude Code.

Desenvolvemos a especificação e o CLAUDE.md passo a passo no curso SaaS em um fim de semana com Claude Code: são 30 aulas, desde validar a demanda pela ideia até banco de dados, login, pagamentos e implantação em um servidor próprio. O curso também está no pacote kombAIn, junto com outros 27 cursos.

Fontes e data da verificação

Informações verificadas em 6 de novembro de 2026.

• Arquivos CLAUDE.md e AGENTS.md dos meus projetos (42 arquivos, depois de remover cópias e um repositório de terceiros), contados em 6 de novembro de 2026
• Claude Code - documentação: How Claude remembers your project (CLAUDE.md, AGENTS.md, imports e limite de 200 linhas)
• AGENTS.md - descrição do formato

// continue lendoClaude Pro, Max ou API: quantas tarefas o Opus 5.5 faz?RevistaGPT-6.1 Terra vs Claude Sonnet 5.5: comparação e testesBenchmarksClaude Duet no Brasil: dá para usar? O que fazer agoraGuias