📖 O que é AGENTS.md
Se o CLAUDE.md é um documento específico do ecossistema Anthropic, o AGENTS.md é a resposta da indústria para a mesma necessidade — um arquivo padronizado que qualquer agente de código pode ler. Iniciado como padrão comunitário e adotado pela Linux Foundation em 2025, o AGENTS.md é o "README para máquinas": fornece contexto de projeto, build steps, convenções e restrições de forma que funciona em OpenAI Codex, Google Jules, Cursor, Factory e qualquer agente que siga o padrão.
🌐 Por que um padrão aberto importa
- •Portabilidade — escreva uma vez, funciona em múltiplos agentes.
- •Sem vendor lock-in — não amarra seu projeto a um único provider.
- •Ecossistema — contribuições de OpenAI, Google, Anthropic, Cursor e outros.
- •Evolução governada — Linux Foundation garante processo de mudança aberto.
📊 Adoção em 2026
- OpenAI Codex — suporte oficial desde lançamento (mai/2025)
- Google Jules — adoção confirmada junto ao A2A (abr/2025)
- Cursor, Amp, Factory — suporte nativo ao AGENTS.md
- agents.md — site oficial com spec, exemplos e guias
- Linux Foundation — governança desde dez/2025
🆚 CLAUDE.md vs AGENTS.md
Os dois documentos têm o mesmo objetivo — dar contexto ao agente — mas diferem em escopo e audiência. O CLAUDE.md é Anthropic-específico: lido pelo Claude Code, pode usar recursos e sintaxe próprios do Claude. O AGENTS.md é vendor-neutral: funciona em qualquer agente compatível. Em projetos multi-agente de 2026, ter os dois é comum e recomendado.
CLAUDE.md
- •Lido pelo Claude Code
- •Identidade, regras, personas
- •Pode referenciar skills e hooks
- •Hierarquia: global/projeto/local
- •Vendor: Anthropic
AGENTS.md
- •Lido por Codex, Jules, Cursor...
- •Build, test, convenções técnicas
- •Contexto técnico do projeto
- •Override chain por pasta
- •Vendor: Linux Foundation (aberto)
💡 Estratégia recomendada
Mantenha os dois. O AGENTS.md carrega o contexto técnico portável (build, test, stack). O CLAUDE.md carrega identidade, regras de negócio e recursos específicos do Claude. Se há conflito, o CLAUDE.md prevalece para o Claude Code.
🔗 Cadeia de instrução do Codex
O OpenAI Codex implementou uma cadeia de instrução hierárquica que espelha a lógica do CLAUDE.md, mas com nomenclatura própria. Entender essa cadeia é útil para qualquer equipe que usa múltiplos agentes — e o padrão AGENTS.md serve como denominador comum entre todos eles.
Cadeia de precedência no Codex
- 1. AGENTS.override.md (global) — regras pessoais do usuário, máxima precedência.
- 2. AGENTS.md (projeto) — contexto e convenções do repositório.
- 3. AGENTS.md (subpasta) — override local para área específica.
- 4. System prompt do agente — fallback padrão se nenhum arquivo encontrado.
Mesma lógica do CSS: mais específico ganha. Mais próximo do arquivo em questão, mais relevante.
Analogia CSS
Pense em AGENTS.override.md como !important: sobrescreve tudo. O AGENTS.md do projeto é o stylesheet da página. O AGENTS.md da subpasta é estilo inline. A cascata é previsível e intencional.
🤝 Adoção real em 2026
O AGENTS.md deixou de ser padrão emergente para se tornar infraestrutura de fato em 2026. Equipes que investiram cedo já colhem o retorno: um único arquivo de contexto funciona com Codex, Jules, Cursor e Factory sem adaptação. Esse é o tipo de padronização que acontece uma vez e dura anos.
Quem adotou e como
- OpenAI Codex — suporte nativo, documentação oficial referencia AGENTS.md como padrão primário.
- Google Jules — integrado ao lançamento; JulesBot lê AGENTS.md automaticamente.
- Cursor — suporta AGENTS.md via Rules for AI, combinável com cursorrules.
- Factory Droids — usa AGENTS.md como fonte de contexto para agendar tarefas.
- Amp (Sourcegraph) — leitura automática de AGENTS.md em todo repositório.
💡 ROI do padrão
Quem investe em AGENTS.md bem escrito hoje colhe em todos os agentes que adotarem o padrão amanhã. É como escrever HTML semântico: o trabalho de hoje paga dividendos em todos os browsers do futuro. O custo é uma hora; o benefício é anos de portabilidade.
📋 Template inicial
Um AGENTS.md eficaz não precisa ser longo — precisa ser completo nas seções certas. As seções Project, Build, Test, Conventions, Constraints e Context cobrem tudo que um agente de código precisa para operar sem fazer perguntas desnecessárias. Um arquivo de 200 linhas bem estruturado elimina horas de overhead conversacional.
Seções do template padrão
- # Project — o que é o projeto, linguagem, framework, arquitetura resumida.
- # Build — como buildar: comandos exatos, dependências, ordem.
- # Test — como rodar testes, coverage mínimo, o que não pode quebrar.
- # Conventions — naming, estilo de código, padrões de PR, mensagens de commit.
- # Constraints — o que o agente NUNCA deve fazer (escrever em /prod, apagar banco).
- # Context — estado atual, o que está em andamento, links relevantes.
Marco — e-commerce de moda
Marco criou um AGENTS.md em 45 minutos para seu projeto Next.js. Na semana seguinte, trocou de Claude Code para Cursor para testar performance em um módulo específico. O Cursor leu o AGENTS.md e já sabia o stack, os comandos de build e as convenções. Zero tempo de setup.
⚠️ Limitações do padrão
O AGENTS.md é markdown puro, sem schema obrigatório, sem validação. Isso é uma escolha deliberada — a simplicidade facilita adoção — mas cria responsabilidades que ficam inteiramente com você. Sem validação automática, a qualidade do arquivo depende exclusivamente da disciplina da equipe. Entender as limitações é essencial para não superestimar o que o padrão entrega sozinho.
Limitações reais
- ✗Sem schema — qualquer formato "vale"
- ✗Sem linter — você não sabe se está bom
- ✗Sem versioning semântico do padrão
- ✗Drift silencioso: fica desatualizado sem avisar
- ✗Não há garantia de que o agente leu
Como mitigar
- ✓Review obrigatório no PR de mudança
- ✓Atualização mensal como rotina
- ✓Teste: peça ao agente para resumir o AGENTS.md
- ✓Mantenha seções nomeadas consistentemente
- ✓Use CHANGELOG.md separado para histórico
📋 Resumo do Módulo
Próximo Módulo:
2.3 — Regras com escopo de caminho