Por que o seu projeto precisa de um AGENTS.md (e não de um arquivo pra cada IA)

Cada ferramenta de IA criou o seu arquivo de instruções. O AGENTS.md tenta fazer com os agentes o que os padrões web fizeram com os browsers: um arquivo só, que qualquer agente sabe ler.

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.md no Claude Code, ou o AGENTS.override.md no 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 componentes

A 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).