AGENTS.md, instruções de projeto para o agente de código
No repositório, o agente de código precisa de um lugar previsível para build, testes e convenções. É nesse recorte que entra o AGENTS.md, também listado no índice de protocolos.
O que o formato descreve
A homepage oficial apresenta o AGENTS.md como um formato simples e aberto para orientar agentes de código, e sugere pensá-lo como um README para o agente: um lugar dedicado e previsível para o contexto e as instruções que ajudam o agente a trabalhar no projeto. A página da AAIF resume o mesmo recorte: um formato simples e aberto para orientar coding agents.
A homepage explica a separação em relação ao README humano. O README.md fica com o que serve a pessoas: início rápido, descrição do projeto e diretrizes de contribuição. O AGENTS.md complementa esse arquivo com o contexto extra, por vezes detalhado, de que o agente de código precisa: passos de build, testes e convenções que poderiam sobrecarregar o README ou que não interessam a quem contribui em pessoa.
A FAQ oficial, na mesma homepage, afirma que não há campos obrigatórios. O AGENTS.md é Markdown padrão. Qualquer heading serve; o agente simplesmente analisa o texto que está no arquivo. Nas páginas oficiais reabertas, não aparece um número de especificação. Eu trato o artefato como esse formato aberto, sem inventar versão.
A página Para agentes explica o que um agente pode ler neste site. O AGENTS.md, neste texto, é o formato de instruções no repositório do projeto.
História e governança
A seção About da homepage diz que o AGENTS.md surgiu de esforços colaborativos no ecossistema de desenvolvimento de software com IA, incluindo OpenAI Codex, Amp, Jules da Google, Cursor e Factory, e que o compromisso é manter e evoluir o formato aberto, independentemente do agente de código que se use. A mesma seção afirma que o AGENTS.md está agora sob a custódia da Agentic AI Foundation, na Linux Foundation.
A nota da Linux Foundation atribui o lançamento à OpenAI, como contribuição fundadora à AAIF, ao lado do MCP da Anthropic e do goose da Block. A fundação descreve o formato como uma convenção em Markdown que dá aos agentes de código uma fonte consistente de orientação específica do projeto, para operarem de modo mais previsível entre repositórios e toolchains distintos. O repositório steward apontado pela AAIF é https://github.com/agentsmd/agents.md.
Como usar no repositório
A homepage, na seção «How to use AGENTS.md?», descreve o fluxo assim. Cria-se um arquivo AGENTS.md na raiz do repositório. O texto deve cobrir o que importa, com seções sugeridas: visão geral do projeto, comandos de build e de teste, diretrizes de estilo, instruções de teste e considerações de segurança. Podem entrar ainda regras de commit ou de pull request, cuidados de segurança, conjuntos grandes de dados e passos de deployment: o que se diria a um colega novo no projeto.
Em monorepos, a orientação oficial é colocar outro AGENTS.md dentro de cada package. Os agentes leem automaticamente o arquivo mais próximo na árvore de diretórios, e o mais próximo tem precedência. A FAQ formula a regra de conflito deste modo: o AGENTS.md mais próximo do arquivo editado prevalece, e prompts explícitos do usuário no chat sobrepõem-se a tudo. Registro isso só como regra de precedência documentada na homepage.
A mesma FAQ afirma que, se os comandos de teste estiverem listados, o agente tentará executar as verificações programáticas relevantes e corrigir falhas antes de concluir a tarefa. Não há, nesta página, um protocolo de descoberta do tipo /.well-known/ nem um manifesto JSON de agente a agente. O artefato é um arquivo Markdown no repositório.
Um exemplo oficial
O exemplo abaixo é o «Sample AGENTS.md file» da documentação oficial, no README do repositório steward, em https://raw.githubusercontent.com/agentsmd/agents.md/main/README.md, o mesmo exemplo longo que a homepage aponta na seção Examples.
# Sample AGENTS.md file
## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package instead of scanning with `ls`.
- Run `pnpm install --filter <project_name>` to add the package to your workspace so Vite, ESLint, and TypeScript can see it.
- Use `pnpm create vite@latest <project_name> -- --template react-ts` to spin up a new React + Vite package with TypeScript checks ready.
- Check the name field inside each package's package.json to confirm the right name—skip the top-level one.
## Testing instructions
- Find the CI plan in the .github/workflows folder.
- Run `pnpm turbo run test --filter <project_name>` to run every check defined for that package.
- From the package root you can just call `pnpm test`. The commit should pass all tests before you merge.
- To focus on one step, add the Vitest pattern: `pnpm vitest run -t "<test name>"`.
- Fix any test or type errors until the whole suite is green.
- After moving files or changing imports, run `pnpm lint --filter <project_name>` to be sure ESLint and TypeScript rules still pass.
- Add or update tests for the code you change, even if nobody asked.
## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing.
Relação com o MCP e com o A2A
Nas páginas oficiais do próprio AGENTS.md, a relação com o MCP e com o A2A não aparece descrita como integração no fio do protocolo. O que as fontes sustentam é a governança compartilhada: AGENTS.md, MCP e goose são contribuições fundadoras da AAIF, e o blog oficial do A2A chama-os, com o próprio A2A, de projetos irmãos. O recorte do AGENTS.md permanece o das instruções de projeto no repositório.
Trato o AGENTS.md como guia de projeto que fica na árvore, sob a mesma custódia da AAIF que o MCP e o A2A. O restante do mapa está no índice.