Explicación · actualizado Oct 10, 2026

Qué es AGENTS.md y cómo lo usan los agentes de programación

AGENTS.md es un archivo Markdown sencillo en un repositorio que da a los agentes de programación pasos de compilación, pruebas y convenciones. No tiene campos obligatorios, y los agentes leen el archivo más cercano en el árbol de directorios.

AGENTS.md →

Qué es AGENTS.md

AGENTS.md es un archivo Markdown sencillo que colocas en un repositorio para darles a los agentes de programación las instrucciones del proyecto que necesitan, como pasos de compilación, pruebas y convenciones. El sitio de AGENTS.md lo describe como un README para agentes. Las personas siguen leyendo el README de siempre, y los agentes tienen un lugar predecible para el detalle que lo saturaría. El sitio indica que el formato está a cargo de la Agentic AI Foundation, bajo la Linux Foundation. Entre los agentes que lo leen están Claude Code, OpenAI Codex, Gemini CLI, Cursor y GitHub Copilot.

No hay campos obligatorios ni esquema. Es Markdown estándar, así que puedes usar los encabezados que quieras. Cómo trate cada agente el contenido depende de ese agente, y es lo principal que debes saber antes de apoyarte en él. Como el formato no impone reglas sobre el contenido, dos agentes pueden leer el mismo archivo y actuar de forma distinta, así que conviene comprobar cómo lo maneja cada herramienta que uses.

Un README para personas, un AGENTS.md para agentes: pasos de compilación, pruebas y convenciones

Cómo funciona AGENTS.md

Un agente lee el AGENTS.md más cercano al archivo que está editando. En un monorepo puedes, por tanto, mantener un archivo en la raíz del repositorio y añadir otro dentro de cada paquete, de modo que cada subproyecto tenga sus propias instrucciones. Cuando dos archivos se contradicen, gana el más cercano. Los prompts explícitos del usuario en el chat prevalecen sobre todo, incluido el archivo. Eso convierte a AGENTS.md en una guía para el agente, no en una regla estricta. Encima hay capas específicas de cada herramienta: reglas de Cursor, skills de Claude Code y MCP servers para herramientas externas.

Archivos AGENTS.md anidados: gana el más cercano, y tu prompt en el chat prevalece sobre todos

Da a los agentes un lugar predecible para instrucciones de configuración, pruebas y estilo de código
Mantiene el detalle pensado para agentes fuera del README para personas
Admite archivos AGENTS.md anidados; gana el más cercano al archivo editado
Funciona con muchos agentes con un solo archivo, en lugar de un formato por herramienta

Cuánto cuesta AGENTS.md

AGENTS.md es un formato de archivo, no un producto de pago, así que no hay planes ni precios que comparar. Nuestro perfil no indica licencia ni fecha de lanzamiento, y no verificamos el repositorio público del código fuente, así que no los afirmamos. El único requisito es un agente que lea AGENTS.md. Todo lo demás es el tiempo que te lleva escribir y mantener el archivo. Si todavía estás eligiendo agente, empieza con Codex vs Claude Code, Cursor vs GitHub Copilot o la lista de los mejores agentes de IA; la guía de herramientas de programación con IA cubre el panorama más amplio, y prompt engineering explica cómo redactar el archivo.

Para quién es AGENTS.md y para quién no

Encaja con equipos que usan más de un agente de programación en el mismo repositorio, porque un solo archivo sustituye a un formato distinto para cada herramienta. También sirve para monorepos que necesitan instrucciones por paquete, y para quien quiere que los agentes ejecuten los comandos de prueba indicados antes de terminar. Mantener este detalle fuera del README para personas hace que ambos documentos sean más cortos y fáciles de leer.

No sirve para imponer políticas. El archivo es texto de orientación, y los prompts explícitos del usuario en el chat lo anulan. Si una regla debe cumplirse siempre, necesita un mecanismo fuera del archivo, ya que el formato no obliga a ningún agente a seguir un contenido concreto. Trátalo como un conjunto de instrucciones compartido que leen muchos agentes, y comprueba tú mismo el comportamiento de cada uno.

Qué agentes leen AGENTS.md

El sitio enumera Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Copilot coding agent, Windsurf y otros. Nuestro catálogo enlaza perfiles relacionados de OpenAI Codex, Cursor, Gemini CLI y Windsurf Editor. Algunas herramientas necesitan un ajuste: Gemini CLI lee el archivo cuando context.fileName está configurado como AGENTS.md en .gemini/settings.json, y Aider necesita read: AGENTS.md en .aider.conf.yml.

Agentes que enumera el sitio, y los dos ajustes que necesitan Gemini CLI y Aider

Primeros pasos con AGENTS.md

Crea un AGENTS.md en la raíz del repositorio y añade secciones como descripción del proyecto, comandos de compilación y pruebas, estilo de código, pruebas e instrucciones para PR. En un monorepo, añade otro archivo dentro de cada paquete. Si ya tienes un archivo AGENT.md, el comando de migración también aparece más abajo. Después configura cualquier agente que no recoja el archivo por defecto.

Crea el archivo en la raíz, añade secciones y luego uno por paquete

Crea un archivo AGENTS.md en la raíz del repositorio
Añade secciones como descripción del proyecto, comandos de compilación y pruebas, estilo de código, pruebas e instrucciones para PR
En monorepos, añade otro AGENTS.md dentro de cada paquete
Para migrar: mv AGENT.md AGENTS.md && ln -s AGENTS.md AGENT.md
Gemini CLI: configura context.fileName como AGENTS.md en .gemini/settings.json; Aider: añade read: AGENTS.md a .aider.conf.yml

Lee a continuación

Preguntas frecuentes

¿Qué es AGENTS.md?

AGENTS.md es un archivo Markdown sencillo que se coloca en un repositorio para dar a los agentes de programación pasos de compilación, pruebas y convenciones. El sitio lo llama un README para agentes.

¿Qué debo poner en AGENTS.md?

Lo que un agente necesita para trabajar en tu repositorio: descripción del proyecto, comandos de compilación y pruebas, estilo de código, reglas de pruebas e instrucciones para PR. Deja en el README el detalle para personas, y en un monorepo añade un AGENTS.md anidado por paquete.

¿Qué pasa cuando hay archivos AGENTS.md en conflicto?

Gana el AGENTS.md más cercano al archivo editado, y los prompts explícitos del usuario en el chat prevalecen sobre todo.

¿Qué agentes admiten AGENTS.md?

El sitio enumera Codex, Jules, Factory, Aider, goose, opencode, Zed, Warp, VS Code, Devin, Junie, Amp, Cursor, RooCode, Gemini CLI, Kilo Code, Copilot coding agent, Windsurf y otros.

¿Cómo hago que Gemini CLI lea AGENTS.md?

Configura context.fileName como AGENTS.md en .gemini/settings.json.