AGENTS.md: um único arquivo de contexto para todo agente de código (Codex, Antigravity, Claude)

Você passou uma tarde escrevendo um CLAUDE.md caprichado. Seu agente finalmente parou de adivinhar a sua stack e começou a rodar o comando de teste certo. E aí um colega abre o mesmo repo com Codex, você testa o Antigravity CLI numa branch paralela, e nada daquele contexto suado se carrega. Cada ferramenta quer o próprio arquivo, no próprio lugar.

AGENTS.md é a resposta para essa bagunça: um único arquivo Markdown puro, na raiz do seu repo, que qualquer agente de código lê antes de tocar no seu código.

O que o AGENTS.md realmente é

Nada de mágica. É um arquivo Markdown chamado AGENTS.md, em geral na raiz do repositório, que um agente carrega como instruções permanentes antes de começar a trabalhar. Pense nele como o README que você escreve para os seus colegas de equipe de IA em vez dos humanos: o que é o projeto, como buildar e testar, as convenções a respeitar e as armadilhas a evitar.

É uma convenção aberta, já lida pelo Codex e por uma lista crescente de ferramentas de agentes, pensada para ser portátil entre elas. Um arquivo, vários agentes, em vez de um arquivo sob medida por ferramenta.

AGENTS.md vs CLAUDE.md vs GEMINI.md

Quando este guia foi escrito, cada ferramenta procurava o próprio arquivo. Desde então, a maioria convergiu para o AGENTS.md:

• O Codex lê AGENTS.md, assim como GitHub Copilot CLI, Cursor, Amp e a maioria dos agentes CLI mais recentes.
• O Claude Code lê CLAUDE.md, e desde a versão 2.1.277 também lê AGENTS.md por conta própria quando o seu diretório de trabalho e os diretórios acima dele não têm CLAUDE.md nem CLAUDE.local.md. Quando existe um CLAUDE.md, o Claude lê só esse arquivo, a menos que você mude a configuração Project instructions em /config.
• O Antigravity CLI lê AGENTS.md ou GEMINI.md, na raiz do repositório ou em qualquer subdiretório, além de uma pasta .agents/rules/ e regras globais em ~/.gemini/.

O conteúdo é quase idêntico nos três: contexto do projeto, comandos, convenções. O que ainda muda é qual arquivo uma ferramenta escolhe quando encontra vários. É exatamente por isso que duplicar as mesmas regras à mão em três arquivos é uma batalha perdida (mais abaixo a gente volta a como mantê-los sincronizados). Conferimos esses comportamentos em 10 de outubro de 2026 na documentação de memória do Claude Code e na documentação de regras do Antigravity.

Se você trabalha principalmente no Claude Code, o nosso guia do CLAUDE.md aprofunda a estrutura específica do Claude. AGENTS.md é o primo neutro, independente de provider, desse arquivo.

O que colocar nele

Mantenha curto e com alto sinal. Um agente lê isso a cada tarefa, então cada linha briga por atenção. O essencial:

• A stack, numa frase só. "Next.js 16, TypeScript, Prisma, MariaDB." Sem histórico, sem marketing.
• Os comandos que importam. Como instalar, rodar, buildar, testar e lintar. Comandos exatos: npm test, não "rode os testes."
• As convenções. Nomenclatura, organização dos arquivos, tratamento de erros, os padrões que você de fato cobra no review.
• Um mapa dos diretórios. Duas linhas sobre onde as coisas ficam, para o agente parar de grepar às cegas.
• Regras de "leia antes de tocar". "Leia docs/payments.md antes de editar qualquer coisa em billing/." Esse único hábito evita um monte de estrago.
• Os "nuncas" inegociáveis. "Nunca crie uma branch sem ser solicitado." "Sem caminhos absolutos de máquina em arquivos commitados."

Os erros que fazem os agentes ignorarem o arquivo

Um arquivo de contexto falha em silêncio. O agente não dá erro, ele só vai à deriva. As causas de sempre:

1. Longo demais. Um arquivo de 600 linhas enterra as cinco regras que importam. Corte tudo que o agente consegue deduzir do próprio código.
2. Contradições. "Sempre escreva testes" numa seção, "pule os testes para protótipos" em outra. O agente escolhe uma ao acaso.
3. Caminhos atrelados à máquina. /Users/you/project/... num arquivo commitado quebra para todos os seus colegas, e para todo agente em qualquer outra máquina. Mantenha os caminhos relativos.
4. Comandos desatualizados. O comando de teste mudou seis meses atrás, o arquivo não. Agora o agente roda a coisa errada com total confiança.
5. Sem prioridades. Tudo é "importante," então nada é. Coloque os inegociáveis primeiro e marque-os.
6. Despejo de documentação. Isso são instruções, não um wiki. Aponte links para a sua doc, não cole ela dentro.

Mantendo um único contexto entre providers

Aqui está a parte prática que a maioria dos guias pula. Se você, ou seu time, rodam mais de um agente CLI, você não quer três cópias divergentes das mesmas regras.

Duas abordagens limpas:

• Um único AGENTS.md, nada mais. Se ninguém precisa de regras só para o Claude, mantenha um único AGENTS.md: Codex, Antigravity CLI e Claude Code 2.1.277 ou mais recente leem esse arquivo. A armadilha é silenciosa: um CLAUDE.md, ou um CLAUDE.local.md pessoal, adicionado mais tarde faz o Claude Code parar de ler o AGENTS.md.
• Um arquivo canônico, uma importação. Coloque tudo no AGENTS.md e comece o CLAUDE.md com a linha @AGENTS.md, depois escreva abaixo as regras só para o Claude. O Claude lê primeiro o arquivo importado. O nosso próprio repositório funciona assim: o CLAUDE.md dele é essa única linha. Um link simbólico (ln -s AGENTS.md CLAUDE.md) também funciona, mas mal no Windows, onde criar um exige privilégios de administrador ou o Modo de Desenvolvedor, e um clone sem core.symlinks recebe um arquivo de texto de uma linha no lugar das suas instruções.

De um jeito ou de outro, a regra é a mesma: escreva o contexto uma vez, não uma vez por provider. Essa também é a única forma de ele continuar correto, porque um arquivo único é o único arquivo que as pessoas de fato mantêm.

Quando você roda vários agentes ao mesmo tempo

Um AGENTS.md no nível do repo responde a "o que é este projeto." Ele não responde a "quem é este agente." Quando você roda um agente Backend, um agente Frontend e um agente QA em paralelo no mesmo código, cada um precisa do contexto de projeto compartilhado mais o próprio papel.

Essa é a camada que o AgentsRoom adiciona por cima do seu AGENTS.md. Cada agente recebe um papel dedicado com o próprio system prompt (DevOps, Frontend, Segurança e mais), para que o arquivo compartilhado fique enxuto enquanto cada agente continua sabendo qual é a sua função. É agnóstico ao provider por design, então o mesmo setup roda Claude, Codex ou Antigravity lado a lado, e suas instruções reaproveitáveis vivem numa biblioteca de prompts em vez de serem redigitadas em cada sessão.

Chegando aí, o método para rodar vários agentes em paralelo sem perder o fio da meada é a leitura que vem naturalmente em seguida.

O que fica

Escreva um único AGENTS.md. Mantenha curto, mantenha atualizado, mantenha portátil. Aponte cada ferramenta para ele em vez de manter um arquivo por agente. Seu contexto deixa de estar preso ao CLI pelo qual você começou, e seus agentes, sejam quais forem, partem todos do mesmo ponto.

Quer todos os seus agentes numa só tela, cada um com o próprio papel e o seu contexto compartilhado? Baixe o AgentsRoom, conecte o seu provider e ponha a sua frota para trabalhar.

Perguntas frequentes

O que é AGENTS.md?

Um arquivo Markdown, geralmente na raiz de um repositório, que os agentes de código carregam como instruções permanentes antes de trabalhar: o que é o projeto, como compilá-lo e testá-lo, as convenções a respeitar e as armadilhas a evitar. É uma convenção aberta compartilhada entre ferramentas, e não o arquivo de uma única ferramenta, lida pelo Codex, Antigravity CLI, GitHub Copilot CLI, Cursor, Amp e, desde a versão 2.1.277, pelo Claude Code.

O Claude Code lê AGENTS.md?

Sim, desde o Claude Code 2.1.277, mas só quando não existe nenhum CLAUDE.md, .claude/CLAUDE.md ou CLAUDE.local.md no seu diretório de trabalho ou acima dele. Ele então carrega cada AGENTS.md do diretório de trabalho para cima, e o AGENTS.md de um subdiretório quando abre um arquivo ali. Se existe um CLAUDE.md, o Claude lê só esse arquivo, a menos que você defina Project instructions como claude-md-and-agents-md em /config. Em versões mais antigas, coloque a linha @AGENTS.md no topo de um CLAUDE.md.

O Antigravity usa AGENTS.md ou GEMINI.md?

Os dois. O Antigravity lê um AGENTS.md, um GEMINI.md ou uma pasta .agents/rules/ na raiz do repositório ou em qualquer subdiretório, e regras globais de ~/.gemini/. As regras se somam em vez de se substituírem, e quando duas delas entram em conflito, vale a regra do diretório mais específico.

Devo manter AGENTS.md ou CLAUDE.md?

Fique com o AGENTS.md como o único arquivo que você mantém. Se você também precisa de regras só para o Claude, adicione um CLAUDE.md cuja primeira linha seja @AGENTS.md e escreva essas regras abaixo dela: o Claude lê primeiro o arquivo importado. Se não precisa de nenhuma, o AGENTS.md sozinho basta para o Claude Code 2.1.277 ou mais recente. Evite duas cópias completas das mesmas regras: a que ninguém edita fica desatualizada.

Onde colocar o AGENTS.md?

Na raiz do repositório, para as regras que valem em todo lugar. O Claude Code e o Antigravity também leem arquivos AGENTS.md em subdiretórios, então um pacote ou um serviço com seus próprios comandos pode ter o próprio arquivo, lido quando o agente trabalha naquela pasta.