Explicação · atualizado Oct 10, 2026
O que é o AGENTS.md e como os agentes de programação o usam
O AGENTS.md é um arquivo Markdown simples em um repositório que dá aos agentes de programação passos de build, testes e convenções. Não tem campos obrigatórios, e os agentes leem o arquivo mais próximo na árvore de diretórios.
O que é o AGENTS.md
O AGENTS.md é um arquivo Markdown simples que você coloca em um repositório para dar aos agentes de programação as instruções do projeto de que eles precisam, como passos de build, testes e convenções. O site do AGENTS.md o descreve como um README para agentes. As pessoas continuam lendo o README normal, e os agentes ganham um lugar previsível para os detalhes que o poluiriam. O site diz que o formato é mantido pela Agentic AI Foundation, da Linux Foundation. Entre os agentes que o leem estão o Claude Code, o OpenAI Codex, o Gemini CLI, o Cursor e o GitHub Copilot.
Não há campos obrigatórios nem esquema. É Markdown comum, então você pode usar os títulos que quiser. Como o agente trata o conteúdo depende de cada agente, e esse é o principal ponto a saber antes de confiar nele. Como o formato não define regras para o conteúdo, dois agentes podem ler o mesmo arquivo e agir de formas diferentes, por isso vale verificar como cada ferramenta que você usa lida com ele.
Como o AGENTS.md funciona
O agente lê o AGENTS.md mais próximo do arquivo que está editando. Em um monorepo, você pode manter um arquivo na raiz do repositório e acrescentar outro dentro de cada pacote, de modo que cada subprojeto tenha suas próprias instruções. Quando dois arquivos entram em conflito, vale o mais próximo. Os prompts explícitos do usuário no chat prevalecem sobre tudo, inclusive sobre o arquivo. Isso faz do AGENTS.md uma orientação para o agente, não uma regra rígida. Camadas específicas de cada ferramenta ficam por cima: regras do Cursor, skills do Claude Code e servidores MCP para ferramentas externas.
- Dá aos agentes um lugar previsível para instruções de configuração, testes e estilo de código
- Mantém os detalhes voltados a agentes fora do README das pessoas
- Aceita arquivos AGENTS.md aninhados; vale o mais próximo do arquivo editado
- Funciona com muitos agentes usando um só arquivo, em vez de um formato por ferramenta
Quanto custa o AGENTS.md
O AGENTS.md é um formato de arquivo, não um produto pago, então não há planos nem preços para comparar. Nosso perfil não lista licença nem data de lançamento, e o repositório público de código-fonte não foi verificado, por isso não os informamos. O único requisito é um agente que leia o AGENTS.md. O resto é o tempo que você gasta para escrever e manter o arquivo. Se você ainda está escolhendo um agente, comece por Codex vs Claude Code, Cursor vs GitHub Copilot ou pela lista dos melhores agentes de IA; o guia de ferramentas de programação com IA cobre o cenário mais amplo, e a engenharia de prompts explica como redigir o arquivo.
Para quem é o AGENTS.md e para quem não é
Serve para equipes que usam mais de um agente de programação no mesmo repositório, porque um só arquivo substitui um formato separado para cada ferramenta. Também serve para monorepos que precisam de instruções por pacote, e para quem quer que os agentes executem os comandos de teste listados antes de terminar. Manter esses detalhes fora do README das pessoas deixa os dois documentos mais curtos e fáceis de ler.
Não é uma forma de impor políticas. O arquivo é um texto de orientação, e os prompts explícitos do usuário no chat prevalecem sobre ele. Se uma regra precisa valer sempre, ela exige um mecanismo fora do arquivo, já que o formato não obriga nenhum agente a seguir um conteúdo específico. Trate-o como um conjunto de instruções compartilhado que muitos agentes leem, e verifique você mesmo o comportamento de cada agente.
Quais agentes leem o AGENTS.md
O site lista Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Copilot coding agent, Windsurf e outros. Nosso catálogo vincula perfis relacionados do OpenAI Codex, Cursor, Gemini CLI e Windsurf Editor. Algumas ferramentas exigem uma configuração: o Gemini CLI lê o arquivo quando context.fileName é definido como AGENTS.md em .gemini/settings.json, e o Aider precisa de read: AGENTS.md em .aider.conf.yml.
Primeiros passos com o AGENTS.md
Crie um AGENTS.md na raiz do repositório e acrescente seções como visão geral do projeto, comandos de build e teste, estilo de código, testes e instruções de PR. Em um monorepo, adicione outro arquivo dentro de cada pacote. Se você já tem um arquivo AGENT.md, o comando de migração também está listado abaixo. Depois, configure os agentes que não leem o arquivo por padrão.
- Crie um arquivo AGENTS.md na raiz do repositório
- Acrescente seções como visão geral do projeto, comandos de build e teste, estilo de código, testes e instruções de PR
- Em monorepos, adicione outro AGENTS.md dentro de cada pacote
- Para migrar: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
- Gemini CLI: defina context.fileName como AGENTS.md em .gemini/settings.json; Aider: adicione read: AGENTS.md a .aider.conf.yml
Leia a seguir
- Regras do Cursor: arquivos .mdc, modos de aplicação e AGENTS.md em 2026
- Skills do Claude Code: a lista oficial explicada em 2026
- O que é um servidor MCP? Uma explicação simples para 2026
- O que é o Claude Code e para quem ele serve
- O que é o OpenAI Codex e para quem ele serve
- O que é o Gemini CLI e para quem ele serve em 2026
- O que é o Cursor AI e para quem ele serve em 2026
- O que são as skills do Claude e como elas funcionam em 2026
- Codex vs Claude Code em 2026: qual agente de programação combina com o seu trabalho
- Cursor vs GitHub Copilot em 2026: qual combina com o seu trabalho
- Melhores ferramentas de programação com IA em 2026
- Melhores agentes de IA em 2026
Perguntas frequentes
O que é o AGENTS.md?
O AGENTS.md é um arquivo Markdown simples colocado em um repositório para dar aos agentes de programação passos de build, testes e convenções. O site o chama de README para agentes.
O que devo colocar no AGENTS.md?
Coloque o que um agente precisa para trabalhar no seu repositório: visão geral do projeto, comandos de build e teste, estilo de código, regras de testes e instruções de PR. Deixe os detalhes voltados a pessoas no README e, em um monorepo, adicione um AGENTS.md aninhado por pacote.
O que acontece quando arquivos AGENTS.md entram em conflito?
Vale o AGENTS.md mais próximo do arquivo editado, e os prompts explícitos do usuário no chat prevalecem sobre tudo.
Quais agentes são compatíveis com o AGENTS.md?
O site lista Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Copilot coding agent, Windsurf e outros.
Como faço o Gemini CLI ler o AGENTS.md?
Defina context.fileName como AGENTS.md em .gemini/settings.json.