Boas práticas de CLAUDE.md (e AGENTS.md, GEMINI.md)

O melhor CLAUDE.md é curto (bem abaixo de 200 linhas), específico e verificável: os comandos para buildar e testar, as convenções que o agente não consegue adivinhar pelo código e os erros que ele já cometeu uma vez. Todo o resto, como um tour pela árvore de pastas, procedimentos longos ou conselhos genéricos como “escreva código limpo”, ou pertence a outro lugar, ou não pertence a lugar nenhum.

Este guia cobre o que são CLAUDE.md, AGENTS.md e GEMINI.md, onde cada agente os procura, o que escrever e o que deixar de fora, como funcionam os imports e como manter um único arquivo que todos os agentes do projeto leem.

O que são esses arquivos

Agentes de código começam toda sessão sem nenhuma memória do seu projeto. Um arquivo de instruções é o bilhete que você deixa para eles: um arquivo Markdown simples que o CLI lê na inicialização e adiciona à janela de contexto do modelo antes da sua primeira mensagem.

O AGENTS.md nasceu de uma colaboração entre OpenAI Codex, Amp, Google Jules, Cursor e Factory, e hoje é mantido pela Agentic AI Foundation, sob a Linux Foundation. É o mais próximo de um padrão compartilhado. O Claude Code manteve o próprio nome, mas versões recentes (v2.1.277 em diante) leem o AGENTS.md nativamente quando não há CLAUDE.md nem CLAUDE.local.md no diretório de trabalho ou acima dele.

Onde os arquivos ficam

Os três agentes usam a mesma ideia: um arquivo global para você, um arquivo de projeto para a equipe e arquivos opcionais mais fundo na árvore para uma parte do código.

Claude Code

Arquivos no diretório de trabalho e nos diretórios acima dele carregam na inicialização e são concatenados, não sobrescritos. Arquivos aninhados em subdiretórios carregam sob demanda, na primeira vez que o Claude mexe em arquivos daquela pasta. Rode /context para ver quais arquivos de memória estão de fato carregados, e /memory para abrir um deles para edição.

Codex

O Codex lê um ~/.codex/AGENTS.md global (ou AGENTS.override.md), depois percorre da raiz do git até o diretório atual e pega um arquivo por pasta: AGENTS.override.md se existir, senão AGENTS.md. Arquivos mais fundos vêm depois no texto combinado, então vencem quando duas regras conflitam. O total é limitado por project_doc_max_bytes, 32 KiB por padrão, e a cadeia é montada uma vez por sessão. Mais sobre o CLI em si na página do Codex.

Gemini CLI

O Gemini CLI carrega ~/.gemini/GEMINI.md, depois os arquivos nos diretórios do seu workspace e nos pais deles, e pega mais arquivos conforme suas ferramentas visitam outras pastas. Tudo é concatenado e enviado com cada prompt. /memory show imprime o texto combinado e /memory reload relê depois que você edita.

O que colocar

Escreva para um colega novo e capaz que nunca viu o repositório e não vai fazer perguntas. Cada linha deve ser algo que o agente consiga executar e que você consiga conferir.

• Comandos. Como instalar, buildar, rodar um teste, rodar todos os testes, lint e type-check. É a seção mais útil de todas; sem ela, o agente chuta.
• Convenções que o código não mostra. “Use pnpm, não npm.” “Novas rotas de API passam por withAuth().” “Datas são armazenadas em UTC.”
• Limites. “Nunca edite arquivos em generated/.” “Não mexa na pasta de migrations sem perguntar.”
• Como terminar uma tarefa. “Rode pnpm test e pnpm typecheck antes de dizer que terminou.” “Mensagens de commit seguem Conventional Commits.”
• Armadilhas conhecidas. O erro que o agente cometeu duas vezes na semana passada, escrito como regra.

Uma boa regra é concreta. “Use indentação de 2 espaços” funciona; “formate o código direito” não. “Rode npm test antes de fazer commit” funciona; “garanta que as coisas funcionam” não.

Um exemplo compacto

# Project notes

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (port 5173)
- One test: `pnpm vitest run path/to/file.test.ts`
- Before finishing: `pnpm lint && pnpm typecheck && pnpm test`

## Conventions
- TypeScript strict; no `any` in new code.
- Server code lives in `src/server`, UI in `src/ui`; never import server code from UI.
- Database access only through `src/server/db.ts`.

## Don’t
- Don’t edit `src/generated/` (run `pnpm codegen` instead).
- Don’t add dependencies without saying why in the summary.

## Learned the hard way
- The payments tests need `STRIPE_KEY=test`; they fail silently without it.

São cerca de 20 linhas, e cobrem a maior parte do que um agente precisa no primeiro dia.

O que deixar de fora

Mantenha curto

Cada linha do CLAUDE.md é enviada no início de toda sessão e fica no contexto durante toda a conversa. A própria documentação da Anthropic sugere ficar abaixo de 200 linhas por arquivo e observa que arquivos mais longos reduzem a confiabilidade com que o Claude os segue. O padrão é conhecido: quanto mais regras, mais cada uma se dilui.

Alguns hábitos ajudam:

• Adicione uma regra só quando precisar. O agente cometeu o mesmo erro duas vezes, uma revisão pegou algo, ou você continua digitando a mesma correção. Esse é o sinal.
• Pode quando adicionar. Se uma regra não fez diferença em um mês, corte.
• Prefira ponteiros a colar texto. “O processo de release está em docs/release.md” custa uma linha; colar o processo custa cinquenta.
• Use comentários HTML para notas a humanos. O Claude Code remove comentários <!-- --> em nível de bloco antes de enviar o arquivo.

Se o custo em tokens te preocupa, o guia de uso de tokens do Claude Code mostra o que mais enche o contexto.

Imports e regras restritas a caminhos

O Claude Code deixa um CLAUDE.md puxar outros arquivos com @path:

See @README.md for the overview.
Coding rules: @docs/conventions.md
@~/.claude/my-preferences.md

Os caminhos são relativos ao arquivo que contém o import, imports podem se aninhar até quatro níveis, e @ dentro de trechos ou blocos de código é ignorado. Na primeira vez que um projeto importa arquivos de fora do repositório, o Claude Code pede sua aprovação.

Um porém: imports organizam o texto, mas não economizam tokens. Um arquivo importado é carregado inteiro na inicialização, igual ao arquivo pai. Para regras que só importam em parte da árvore, use .claude/rules/*.md com um glob paths: no frontmatter, para que carreguem só quando o Claude trabalha em arquivos correspondentes:

---
paths: ["src/api/**/*.ts"]
---
- Every handler validates input with zod before touching the database.

O Gemini CLI suporta a mesma sintaxe de import @file.md no GEMINI.md.

Um arquivo para todos os agentes

Se a sua equipe usa mais de um CLI, manter três arquivos com as mesmas regras é o caminho para eles divergirem. A configuração comum:

1. Coloque as regras compartilhadas no AGENTS.md. Codex, Cursor, Copilot, opencode e a maioria dos outros o leem diretamente.

2. Crie um CLAUDE.md que o importe e adicione o que for específico do Claude:

   @AGENTS.md
   
   ## Claude Code only
   - Use the project's /review skill before opening a PR.

3. No Gemini CLI, adicione AGENTS.md aos nomes de arquivo que ele procura, em .gemini/settings.json:

   { "context": { "fileName": ["AGENTS.md", "GEMINI.md"] } }

Um symlink (ln -s AGENTS.md CLAUDE.md) também funciona no macOS e no Linux, mas a abordagem com import é mais clara e não depende de como o Windows lida com links. O Claude Code também tem uma configuração “Project instructions” em /config, se você quiser que ele leia CLAUDE.md e AGENTS.md juntos.

Escrevendo a primeira versão

Você não precisa começar de uma página em branco. No Claude Code, o /init lê o repositório e esboça um CLAUDE.md. Trate esse rascunho como matéria-prima: mantenha os comandos, apague o tour pelas pastas e corte tudo o que você não diria a um colega novo na primeira manhã.

Depois deixe o arquivo crescer a partir do trabalho real. Cada vez que você corrigir o agente, pergunte a si mesmo se a correção também valeria na semana que vem. Se sim, é candidata a regra.

Fazendo isso com o AgentVera

O AgentVera roda Claude Code, Codex, Gemini CLI e outros CLIs lado a lado em terminais reais. Cada agente continua lendo seu próprio CLAUDE.md, AGENTS.md ou GEMINI.md exatamente como descrito acima; o AgentVera não substitui esses arquivos. Alguns recursos funcionam junto com eles:

• Sugestões de regras a partir das suas correções. Quando você devolve o trabalho de um agente pela review inbox com uma nota, ou o Verify encontra um critério que falhou, um modelo Claude pequeno transforma a correção em uma regra curta. Ela aparece em Rule suggestions; Add to instructions a acrescenta ao CLAUDE.md e ao AGENTS.md do projeto (os que existirem), e regras que já estão nos arquivos são puladas. Se nenhum dos arquivos existir, ele cria o AGENTS.md e um CLAUDE.md que o importa com @AGENTS.md.
• Papéis por agente em vez de um arquivo compartilhado inchado. O campo “Role and instructions” no diálogo do agente é entregue só àquele agente (o Claude o recebe anexado ao system prompt, o Codex como developer instructions). Papéis específicos de um agente ficam fora do arquivo compartilhado. Cursor, Gemini CLI e Amp não usam esse campo e dependem do AGENTS.md ou dos arquivos de regras do projeto.
• Um mapa do código, para você pular o tour pelas pastas. O mapa do projeto é montado localmente e oferecido aos agentes como ferramentas MCP (map_related, map_outline, map_usages e outras), e novos agentes recebem um resumo curto dos módulos, pontos de entrada e do comando de teste. É a parte que as pessoas costumam colar à mão no CLAUDE.md.
• Memória do projeto. O AgentVera Brain lê seus docs rastreados pelo Git, incluindo CLAUDE.md e AGENTS.md, junto com commits, PRs e conversas anteriores, e acompanha quais decisões estão vigentes ou desatualizadas. Um pacote de contexto opcional (desligado por padrão) pode ser adicionado às instruções de novos agentes.
• Procedimentos como skills. A galeria de skills gerencia pastas SKILL.md para Claude Code e Codex, que é onde procedimentos longos devem ficar.
• Regras que sempre precisam rodar. O CLAUDE.md é conselho; para checagens que precisam acontecer toda vez, use hooks do Claude Code, e passe tarefas laterais específicas para subagentes.

Checklist

• Abaixo de 200 linhas; idealmente abaixo de 100.
• Comandos de build, teste, lint e type-check listados e corretos.
• Toda regra é específica o bastante para ser conferida.
• Sem tour pelas pastas, sem secrets, sem conselhos genéricos.
• Regras de uma pasta específica estão em arquivos aninhados ou em regras restritas a caminhos.
• Procedimentos longos estão em skills ou docs, referenciados por uma linha.
• Limites rígidos são impostos com hooks ou permissões, não com texto.
• As regras compartilhadas ficam no AGENTS.md; o CLAUDE.md o importa.
• Preferências pessoais estão em ~/.claude/CLAUDE.md ou no CLAUDE.local.md.

Concluindo

Um arquivo de instruções é o jeito mais barato de fazer um agente se comportar como se já tivesse trabalhado no seu projeto. Mantenha-o curto, concreto, e deixe-o crescer só a partir de erros que você realmente viu. Coloque as regras compartilhadas no AGENTS.md para que todo CLI leia a mesma coisa, mova procedimentos para skills e imponha o que realmente importa com hooks, não com frases.