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

URL: https://agentvera.dev/pt/blog/claude-md-agents-md/ · Publicado: 2026-10-22

Boas práticas de CLAUDE.md: onde o arquivo fica, o que incluir e deixar de fora, imports, manter curto e um AGENTS.md compartilhado por Claude, Codex e Gemini.

**Resumo:**

- Um CLAUDE.md funciona melhor quando fica abaixo de 200 linhas e lista comandos de build e teste, convenções que o código não mostra e erros que o agente já cometeu.
- Tours pelas pastas, procedimentos longos, secrets e conselhos genéricos não pertencem a ele; regras que nunca podem ser quebradas devem ser impostas com hooks ou permissões, não com texto.
- Para compartilhar regras entre CLIs, mantenha-as no AGENTS.md, importe-o no CLAUDE.md com @AGENTS.md e adicione AGENTS.md ao context.fileName nas configurações do Gemini CLI.

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](/pt/glossary/context-window/ "Janela de contexto") do modelo antes da sua primeira mensagem.

| Arquivo | Lido por | Observações |
| --- | --- | --- |
| `CLAUDE.md` | Claude Code | Suporta imports com `@path` e regras restritas a caminhos |
| `AGENTS.md` | Codex, Cursor, Copilot, opencode, Aider, goose, Amp, Gemini CLI (se configurado) e outros | Um formato aberto, muitas vezes chamado de “um README para agentes” |
| `GEMINI.md` | Gemini CLI | Suporta imports com `@file.md`; o nome do arquivo é configurável |

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

| Escopo | Local | Compartilhado? |
| --- | --- | --- |
| Política gerenciada | `/Library/Application Support/ClaudeCode/CLAUDE.md` (macOS), `/etc/claude-code/CLAUDE.md` (Linux), `C:\Program Files\ClaudeCode\CLAUDE.md` (Windows) | Definido por um admin para todos |
| Usuário | `~/.claude/CLAUDE.md` | Só você, em todo projeto |
| Projeto | `./CLAUDE.md` ou `./.claude/CLAUDE.md` | Com commit, a equipe toda |
| Local | `./CLAUDE.local.md` | Só você; adicione ao `.gitignore` |
| Aninhado | `src/payments/CLAUDE.md` e assim por diante | Carregado quando o Claude lê ou edita arquivos ali |

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](/pt/agents/codex/ "Codex CLI").

### 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

```markdown
# 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

| Deixe de fora | Por quê | Coloque aqui no lugar |
| --- | --- | --- |
| Um tour arquivo por arquivo do repositório | O agente consegue listar pastas sozinho, e o tour fica desatualizado | Nada, ou uma ferramenta de mapa do código |
| Procedimentos longos passo a passo (release, migrations) | Carregados a cada turno, mesmo sem uso | Uma [skill](/pt/glossary/agent-skills/ "Agent skills") ou um doc para o qual o arquivo aponta |
| Regras só para uma pasta | Custam contexto em todo lugar | Um CLAUDE.md / AGENTS.md aninhado, ou `.claude/rules/` com `paths:` |
| Conselhos genéricos (“escreva código limpo”) | Nenhum efeito no comportamento | Apague |
| Secrets, tokens, URLs internas | O arquivo vai para o git e é enviado ao modelo | Variáveis de ambiente |
| Coisas que nunca podem acontecer | Instruções são contexto, não imposição | Um [hook](/pt/glossary/claude-code-hooks/ "Hooks do Claude Code") ou uma regra de permissão |

## 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](/pt/blog/claude-code-token-usage/ "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`:

```markdown
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:

```markdown
---
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:

   ```markdown
   @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`:

   ```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](/pt/download/ "Baixar 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](/pt/features/review-inbox/ "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](/pt/features/project-map/ "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](/pt/features/brain/ "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](/pt/features/skill-gallery/ "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](/pt/blog/claude-code-hooks-guide/ "Guia de hooks do Claude Code"), e passe tarefas laterais específicas para [subagentes](/pt/blog/claude-code-subagents/ "Subagentes do Claude Code").

## 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.

## Perguntas frequentes

**Qual deve ser o tamanho de um arquivo CLAUDE.md?** A orientação da Anthropic é mirar em menos de 200 linhas por arquivo. O arquivo é carregado no contexto no início de toda sessão, então arquivos mais longos custam mais tokens e, na prática, o agente os segue com menos confiabilidade.

**Qual a diferença entre CLAUDE.md e AGENTS.md?** Eles fazem o mesmo trabalho. CLAUDE.md é o arquivo que o Claude Code lê; AGENTS.md é um formato aberto lido por Codex, Gemini CLI (quando configurado), Cursor, Copilot, opencode, Aider, goose e muitos outros. Versões recentes do Claude Code também leem o AGENTS.md quando não existe CLAUDE.md.

**Posso usar um único arquivo de instruções para Claude Code, Codex e Gemini CLI?** Sim. Mantenha as regras compartilhadas no AGENTS.md, coloque ao lado um CLAUDE.md com a linha @AGENTS.md (mais eventuais notas só para o Claude) e configure context.fileName nas configurações do Gemini CLI para incluir AGENTS.md.

**O CLAUDE.md deve ir para o git?** O CLAUDE.md do projeto, sim: é conhecimento compartilhado da equipe. Preferências pessoais vão em ~/.claude/CLAUDE.md ou no CLAUDE.local.md, que você adiciona ao .gitignore.

**O CLAUDE.md garante que o agente siga uma regra?** Não. É contexto, não imposição. O agente geralmente segue regras claras e específicas, mas, se uma ação nunca pode acontecer, bloqueie-a com um hook ou uma configuração de permissão em vez de uma frase no CLAUDE.md.

---

**Sobre o AgentVera.** AgentVera é um app desktop para macOS, Windows e Linux, desenvolvido pela Solviera Teknoloji. Ele roda 18 agentes de programação com IA (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) lado a lado, por projeto, em terminais reais com as instalações e logins de CLI do próprio usuário. O plano gratuito tem agentes ilimitados. Baixar: https://agentvera.dev/pt/download/ · Preços: https://agentvera.dev/pt/pricing/