1.2 AGENTS.md vs CLAUDE.md

📜 Origem do AGENTS.md

Padrão criado por Sourcegraph, OpenAI, Google, Cursor e Factory em colaboração. Em 2026 já está sob o guarda-chuva da Agentic AI Foundation, parte da Linux Foundation. Multi-vendor governance é o que dá tranquilidade.

📊 Dados que importam

60.000+ repos no GitHub já usam AGENTS.md
18+ ferramentas de coding agent leem AGENTS.md nativamente
Linux Foundation é o steward — não uma empresa só
Listado em agentsmd.dev com schema oficial

💡 Por que importa

Padrão proprietário pode ser descontinuado. Padrão multi-vendor sob Linux Foundation NÃO some — é infraestrutura comum. Aposta tranquila pra anos.

📋 O que vai em cada arquivo

A divisão correta evita duplicação. Universal num arquivo, específico no outro.

📄 AGENTS.md (universal)

✓Project overview
✓Comandos de build/test/lint
✓Code style (linter rules, naming)
✓Estrutura do projeto (folders)
✓Boundaries (não-mexer)
✓Decision log (ADRs curtos)

⚙️ CLAUDE.md (Claude-only)

✓@AGENTS.md na primeira linha
✓Hooks config (PreToolUse, PostToolUse)
✓Permission levels (acceptEdits, etc)
✓Path-scoped rules
✓Local overrides (settings.local.json)

🔗 @import: CLAUDE.md lendo AGENTS.md

Claude Code suporta nativamente @AGENTS.md. Você cria um CLAUDE.md fininho que importa o universal e adiciona o que é Claude-only.

CLAUDE.md mínimo recomendado:

@AGENTS.md

## Claude-only

### Hooks
PreToolUse: ./scripts/pre-edit-check.sh
PostToolUse: ./scripts/format.sh

### Path-scoped
- src/legacy/**: read-only, propor mudança em RFC primeiro
- migrations/**: nunca editar arquivo já aplicado em prod

Vantagem real: atualiza AGENTS.md, Claude lê na hora. Zero duplicação. Codex, Cursor, Gemini também leem AGENTS.md — uma única fonte de verdade pra todos.

🔁 Codex lendo CLAUDE.md como fallback

Caminho inverso: você já tem CLAUDE.md mas ainda não criou AGENTS.md. Configura o Codex pra ler CLAUDE.md como fallback — zero esforço de migração pra testar.

~/.codex/config.toml:

project_doc_fallback_filenames = ["CLAUDE.md", "COPILOT.md"]

Fluxo de migração suave

1. Config fallback hoje → Codex já lê CLAUDE.md
2. Use as duas ferramentas por 1-2 semanas
3. Quando estiver confortável, gere AGENTS.md (via prompt do módulo 2.1)
4. Esvazia CLAUDE.md, deixa só @AGENTS.md + Claude-only

🚫 O que NÃO pôr no AGENTS.md

Arquivo inchado vira ruído. Modelo lê tudo em cada turn — token desperdiçado, atenção diluída. Lista de coisas que NÃO devem entrar:

✓ Vai em AGENTS.md

✓Regras perenes (sempre valem)
✓Convenções não-óbvias
✓Boundaries (não-mexer)
✓Decisões arquiteturais (ADR curtos)

✗ NÃO vai em AGENTS.md

✗Histórico de bugs (vai em git log)
✗Notas de PRs antigos
✗Regras temporárias ("durante migração X")
✗Conteúdo duplicado do README

📊 Sinais de que está dando certo

Não dá pra "sentir" se AGENTS.md está pagando. Use os 3 sinais práticos:

Mesmo prompt funciona em Claude e Codex

Você manda "implementa X" nos dois — saída sai aderente ao projeto nos dois. Isso é AGENTS.md cumprindo.

Agente novo produz código aderente em 1 turn

Sem precisar de "corrige isso", "segue convenção tal". Primeiro shot já correto = AGENTS.md bem escrito.

Você para de repetir as mesmas correções

Toda correção recorrente deveria virar linha em AGENTS.md. Se você ainda repete = falta lá.

📚 Resumo do Módulo

✓

AGENTS.md é padrão Linux Foundation — 60k+ repos, 18+ ferramentas

✓

Universal no AGENTS.md, Claude-only no CLAUDE.md — single source of truth

✓

@import faz CLAUDE.md ler AGENTS.md — zero duplicação

✓

project_doc_fallback_filenames pro Codex — testa Codex sem migrar

✓

Histórico e regras temporárias FORA — só regras perenes

✓

3 sinais de sucesso — mesmo prompt funciona, agente novo aderente, correções pararam

Próximo Módulo:

1.3 — Anatomia: .claude/ vs .codex/

← Módulo anterior Próximo: .claude/ vs .codex/ →