AGENTS.md es un archivo de texto que guardas en la carpeta principal de tu proyecto con las instrucciones que lee el agente de programación, la IA que programa por ti, antes de ponerse a trabajar. Es un estándar abierto, así que el mismo archivo lo leen OpenAI Codex, Cursor, GitHub Copilot, Lovable y, con un matiz, Claude Code.
Crearlo es cuestión de minutos. Lo que decide si el agente te hace caso es cómo lo escribes, y un estudio reciente comprobó que generarlo de forma automática no mejora los resultados.
Para qué sirve AGENTS.md y dónde se guarda
En AGENTS.md le cuentas al agente lo que necesita saber de tu proyecto y no puede deducir solo, como los comandos para arrancar la app, las normas del código o lo que tiene prohibido tocar. Como el agente empieza cada sesión sin recordar la anterior, el archivo le da ese contexto en cada conversación y tú lo escribes una sola vez.
La web oficial del estándar lo define como un README para agentes. El README es el archivo de presentación para las personas, donde cuentas qué hace el proyecto y cómo instalarlo. AGENTS.md recoge los detalles técnicos que el agente usa para trabajar.
El archivo va en la raíz del proyecto, que es la carpeta principal, con el nombre exacto AGENTS.md y escrito en Markdown, el formato de texto que usa # para los títulos. Para crearlo sin necesidad de programar, añade un archivo con ese nombre desde Cursor o VS Code, o pídele al agente que lo cree con las reglas que le dictes.
Qué herramientas leen AGENTS.md
La mayoría de agentes de programación con IA ya lo leen, empezando por OpenAI Codex, que lo usa como su archivo de reglas. En la tabla tienes las herramientas más usadas, según su documentación oficial.
La última columna indica dónde guarda cada una sus reglas exclusivas. Salvo Claude Code, todas las leen junto a AGENTS.md, así que no tienes que borrar las que ya tengas.
Claude Code lo lee por su cuenta desde la versión 2.1.277, pero solo si el proyecto no tiene un CLAUDE.md. Si ya usas un archivo CLAUDE.md, escribe @AGENTS.md en su primera línea y añade debajo las instrucciones que sean exclusivas de Claude.
Esa línea carga el contenido de AGENTS.md dentro de CLAUDE.md, así que Claude Code y el resto de herramientas comparten las mismas reglas.
Qué poner dentro del archivo
Un AGENTS.md suele reunir estos bloques, según la documentación del estándar.
Resumen. Qué hace la app y las piezas principales con las que está hecha.
Comandos. Las órdenes para instalar, arrancar la app y preparar la versión que publicas.
Estilo de código. Cómo nombrar los archivos y en qué idioma van los textos.
Pruebas. Qué comprobar antes de dar una tarea por terminada.
Límites. Lo que tiene prohibido tocar, como las contraseñas o la base de datos.
Historial y publicación. Cómo guardar los cambios en el historial de versiones y publicar la app.
De la tecnología basta con las piezas principales, como en el ejemplo de más abajo. La descripción de cada carpeta y la lista de todo lo que tiene instalado tu app sobran, porque el agente ya las encuentra en los archivos.
Basta con los bloques que aplican a tu proyecto, porque ninguno es obligatorio. Si trabajas sin equipo y publicas desde Lovable con un botón, el bloque de historial sobra.
Cómo escribirlo para que el agente te haga caso
Cuanto más concreta es una regla, más fácil es que el agente la cumpla. Le sirve más «los textos van en español y de tú» que «cuida los textos», y más «ejecuta npm run build antes de terminar» que «comprueba que todo funciona».
En un estudio de la ETH de Zúrich con Claude Code y Codex, entre otros, cuando el archivo nombraba un programa concreto el agente lo usaba, y cuando no lo nombraba casi nunca lo tocaba.
El mismo estudio comprobó que los archivos que genera el propio agente con un comando como /init, sin retocarlos, no resolvieron más tareas y encarecieron de media cada tarea más de un 20 %. Los archivos hechos a mano dieron mejores resultados, así que escribe tú las reglas, pocas y sobre lo que el agente no ve en el código.
Para mantenerlo al día, añade una regla cada vez que el agente repita un fallo, como cambiar textos que no le has pedido o instalar cosas sin preguntarte. Y cuando una regla deje de tener sentido, bórrala, porque dos instrucciones que se contradicen suelen confundir al agente.
Ejemplo de AGENTS.md listo para copiar
Este ejemplo es para una app de gastos personales hecha con vibe coding, un proyecto pequeño sin equipo detrás. Cópialo y cambia la tecnología, los comandos y los límites por los de tu app. Si no sabes qué tecnología o qué comandos usa tu proyecto, pídele al agente que los busque en los archivos y te explique para qué sirve cada uno.
Lo que hace que el agente te haga caso es un archivo corto, escrito por ti, con reglas concretas que no puede deducir del código y que vas ampliando cada vez que corriges un fallo. Con él, Codex, Cursor, Lovable o Claude Code empiezan cada sesión con tus reglas delante.
Si quieres ponerlo en práctica en tu propio proyecto, empieza gratis con el curso para aprender vibe coding con Claude Code y construye tu primera aplicación con un agente.
