AGENTS.md: um único arquivo de contexto para todo agente de código (Codex, Gemini, 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 Gemini 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

Por enquanto o cenário está dividido por ferramenta:

• CLAUDE.md é o que o Claude Code procura.
• GEMINI.md é a convenção do Gemini CLI.
• AGENTS.md é o padrão entre ferramentas, lido pelo Codex e por outras, projetado para ser o arquivo neutro.

O conteúdo é quase idêntico nos três: contexto do projeto, comandos, convenções. A única diferença real é o nome do arquivo que cada ferramenta lê por padrão. É 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).

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 arquivo canônico, ponteiros enxutos. Coloque tudo no AGENTS.md e transforme CLAUDE.md e GEMINI.md em arquivos de uma linha que dizem "veja AGENTS.md," ou crie links simbólicos. Uma única fonte de verdade, todas as ferramentas alimentadas.
• Um arquivo, compartilhado por convenção. Se as suas ferramentas aceitam apontar para um caminho personalizado, direcione todas para o AGENTS.md e apague o resto.

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 Gemini 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.