AGENTS.md, instrucciones de proyecto para el agente de código
Dentro del repositorio, el agente de código necesita un lugar previsible para el build, las pruebas y las convenciones. En ese recorte entra AGENTS.md, también presente en el índice de protocolos.
Lo que describe el formato
La homepage oficial presenta AGENTS.md como un formato simple y abierto para orientar agentes de código, y sugiere pensarlo como un README para el agente: un lugar dedicado y previsible para el contexto y las instrucciones que ayudan al agente a trabajar en el proyecto. La página de la AAIF resume el mismo recorte: un formato simple y abierto para orientar coding agents.
La homepage explica la separación respecto del README humano. El README.md queda con lo que sirve a las personas: inicio rápido, descripción del proyecto y pautas de contribución. AGENTS.md complementa ese archivo con el contexto extra, a veces detallado, que el agente de código necesita: pasos de build, pruebas y convenciones que podrían recargar el README o que no resultan relevantes para quien contribuye en persona.
La FAQ oficial, en la misma homepage, afirma que no hay campos obligatorios. AGENTS.md es Markdown estándar. Cualquier heading sirve; el agente simplemente analiza el texto que está en el archivo. En las páginas oficiales reabiertas no aparece un número de especificación. Trato el artefacto como ese formato abierto, sin inventar versión.
La página Para agentes explica lo que un agente puede leer en este sitio. AGENTS.md, en este texto, es el formato de instrucciones en el repositorio del proyecto.
Historia y gobernanza
La sección About de la homepage dice que AGENTS.md surgió de esfuerzos colaborativos en el ecosistema de desarrollo de software con IA, incluidos OpenAI Codex, Amp, Jules de Google, Cursor y Factory, y que el compromiso es mantener y evolucionar el formato abierto, con independencia del agente de código que se use. La misma sección afirma que AGENTS.md está ahora bajo la custodia de la Agentic AI Foundation, en la Linux Foundation.
La nota de la Linux Foundation atribuye el lanzamiento a OpenAI, como contribución fundadora a la AAIF, junto al MCP de Anthropic y al goose de Block. La fundación describe el formato como una convención en Markdown que da a los agentes de código una fuente consistente de orientación específica del proyecto, para que operen de modo más previsible entre repositorios y toolchains distintos. El repositorio steward señalado por la AAIF es https://github.com/agentsmd/agents.md.
Cómo usarlo en el repositorio
La homepage, en la sección «How to use AGENTS.md?», describe el flujo así. Se crea un archivo AGENTS.md en la raíz del repositorio. El texto debe cubrir lo que importa, con secciones sugeridas: visión general del proyecto, comandos de build y de prueba, pautas de estilo, instrucciones de prueba y consideraciones de seguridad. También pueden entrar reglas de commit o de pull request, cuidados de seguridad, conjuntos grandes de datos y pasos de deployment: lo que se diría a un colega nuevo en el proyecto.
En monorepos, la orientación oficial es colocar otro AGENTS.md dentro de cada package. Los agentes leen automáticamente el archivo más cercano en el árbol de directorios, y el más cercano tiene precedencia. La FAQ formula la regla de conflicto de este modo: el AGENTS.md más cercano al archivo editado prevalece, y los prompts explícitos del usuario en el chat se superponen a todo. Lo registro solo como regla de precedencia documentada en la homepage.
La misma FAQ afirma que, si los comandos de prueba están listados, el agente intentará ejecutar las verificaciones programáticas relevantes y corregir fallos antes de concluir la tarea. No hay, en esta página, un protocolo de descubrimiento del tipo /.well-known/ ni un manifiesto JSON de agente a agente. El artefacto es un archivo Markdown en el repositorio.
Un ejemplo oficial
El ejemplo siguiente es el «Sample AGENTS.md file» de la documentación oficial, en el README del repositorio steward, en https://raw.githubusercontent.com/agentsmd/agents.md/main/README.md, el mismo ejemplo largo que la homepage señala en la sección 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.
Relación con el MCP y con el A2A
En las páginas oficiales del propio AGENTS.md, la relación con el MCP y con el A2A no aparece descrita como una integración en el hilo del protocolo. Lo que las fuentes sostienen es la gobernanza compartida: AGENTS.md, MCP y goose son contribuciones fundadoras de la AAIF, y el blog oficial del A2A los llama, con el propio A2A, proyectos hermanos. El recorte de AGENTS.md sigue siendo el de las instrucciones de proyecto en el repositorio.
Guardo AGENTS.md como guía de proyecto dentro del árbol, bajo la misma custodia de la AAIF que el MCP y el A2A. El resto del mapa está en el índice.