Quantos arquivos de instrução pra IA o seu projeto tem hoje? Um CLAUDE.md porque alguém do time usa Claude, um .cursorrules porque outra pessoa usa Cursor, um GEMINI.md que alguém criou num teste e ninguém mais mexeu (e você sabe dizer qual deles está atualizado?).
Se a resposta for mais de um, você tem o mesmo problema que o AGENTS.md tenta resolver.
Cada ferramenta com o seu arquivo
Todo agente de IA começa cada sessão sem lembrar nada do seu projeto. Por isso cada ferramenta criou um arquivo onde você escreve o que ele deve ler antes de começar: como rodar os testes, quais convenções seguir, o que não pode quebrar.
O problema é que cada uma criou o seu, com conteúdo praticamente igual e nome diferente. A mesma informação fica duplicada, alguém atualiza o comando de teste num arquivo e esquece dos outros, e trocar de ferramenta vira retrabalho.
Quem trabalhou com front-end no começo dos anos 2000 lembra da época em que os browsers brigavam. Cada navegador entendia o HTML e o CSS do seu jeito, e a gente fazia gambiarra pra cada um.
Os padrões web do W3C resolveram isso combinando uma base comum. O AGENTS.md é uma tentativa muito parecida com os agentes de IA: um arquivo só, com nome e lugar previsíveis, que qualquer agente sabe que deve ler.
Ele surgiu da colaboração entre empresas que fazem agentes de código (OpenAI Codex, Amp, Jules do Google, Cursor, Factory) e hoje é mantido pela Agentic AI Foundation, debaixo da Linux Foundation.
E a adoção já é grande. Um censo de 22.854 repositórios populares do GitHub encontrou instruções pra agentes em 26,3% deles, e em 59,6% dos mais estrelados.
Outro estudo com 2.853 repositórios e cinco ferramentas aponta o AGENTS.md como o padrão que está se firmando entre elas.
A comparação com o W3C tem um limite: o AGENTS.md é uma convenção, sem especificação formal. Contudo, os padrões web também foram adotados de forma desigual pelos browsers durante anos, e mesmo assim mudaram o jogo.
Como o AGENTS.md funciona
É um arquivo markdown comum, na raiz do repositório, sem campo obrigatório nem formato fixo. O README é pra humanos, o AGENTS.md é pro agente. Ele traz o contexto que o agente precisa e que só poluiria o README.
O agente coloca o conteúdo do arquivo no contexto antes de trabalhar, e o que você pede no chat vale mais que o arquivo.
Então pensa nos dois juntos. O AGENTS.md diz "rode pnpm test antes de finalizar" e vale pra qualquer tarefa. O pedido diz "corrige o cálculo do frete no checkout sem mexer na API pública" e vale só pra essa.
Se você lista comandos de teste e de lint no arquivo, o agente tenta rodar esses comandos e corrigir o que falhar antes de dizer que terminou.
Nem toda ferramenta lê o AGENTS.md sozinha. Por isso eu deixo ele como fonte única e faço o arquivo de cada ferramenta apontar pra ele, com um link simbólico ou uma linha importando o AGENTS.md.
O censo encontrou o mesmo padrão: quando os dois existem, o CLAUDE.md geralmente aponta pro AGENTS.md.
Os níveis de instrução
Entender os níveis evita misturar coisa sua com coisa do time.
- Global, na pasta do seu usuário, vale pra todos os projetos:
~/.codex/AGENTS.md,~/.claude/CLAUDE.md,~/.gemini/GEMINI.md. Ali vão as suas preferências, tipo "peça confirmação antes de instalar uma dependência nova". - Projeto, na raiz do repositório e no git. É do time: comandos, convenções, o que não pode quebrar.
- Subpastas, pra regras específicas de um pacote ou módulo.
- Pessoal dentro do projeto, fora do git, pra coisa que é só sua (tipo a URL do seu ambiente de teste): o
CLAUDE.local.mdno Claude Code, ou oAGENTS.override.mdno Codex.
Num monorepo, isso fica mais ou menos assim:
repo/
├── AGENTS.md ← segurança, commits, lint, testes
├── apps/web/AGENTS.md ← comandos e convenções do front
└── packages/design-system/AGENTS.md ← regras dos componentesA ordem vai do mais geral pro mais específico, e o arquivo mais próximo do que está sendo editado prevalece.
O padrão cobre bem o projeto e as subpastas, mas o global e o pessoal ainda dependem de cada ferramenta (a documentação do Codex, do Claude Code e do Gemini CLI explica bem cada caso).