Cómo escribir un archivo AGENTS.md en 2026 (breve, escrito a mano y respaldado por datos)

Un archivo AGENTS.md es un "README para tu agente de programación" en Markdown puro que vive en la raíz de tu repositorio y les indica a herramientas como Claude Code, Codex y Cursor cómo compilar, probar y comportarse en tu proyecto. Los mejores son breves, específicos y escritos a mano: enumeran tus comandos exactos, nombran tu stack con versiones y trazan líneas rojas alrededor de lo que el agente nunca debe tocar. Los peores son largos, vagos y autogenerados, y ahora hay evidencia medida de que hacen que los agentes sean más lentos y menos precisos.

Construimos TechRiseUps con Claude Code, y el único archivo que más cambió la fiabilidad con la que entrega trabajo correcto fue el archivo de instrucciones del agente. Esta es la guía práctica que nos habría gustado tener: qué escribir, qué recortar y por qué menos es más.

¿Qué es un archivo AGENTS.md?

AGENTS.md es un formato abierto e independiente de la herramienta para guiar a los agentes de programación: "un lugar dedicado y predecible para proporcionar el contexto y las instrucciones que ayudan a los agentes de IA de programación a trabajar en tu proyecto". Piénsalo como la contraparte de tu README orientado a humanos: pasos de compilación, comandos de prueba y convenciones que recargarían el README pero que un agente realmente necesita.

El formato fue impulsado por OpenAI para Codex y, en diciembre de 2025, se donó a la Agentic AI Foundation bajo la Linux Foundation, así que ya no es la convención de un único proveedor. Ahora lo reconocen más de 60.000 proyectos de código abierto y cuenta con soporte en más de 28 herramientas, entre ellas Codex, Cursor, Aider, Devin, Google Jules y VS Code. Claude Code lee su propio CLAUDE.md y cada vez respeta más también AGENTS.md; los consejos sobre contenido que siguen aplican a ambos. Un archivo, muchos agentes: ese es todo el propósito.

Qué poner en un archivo AGENTS.md

GitHub analizó más de 2.500 archivos agents.md reales (publicados el 19 de noviembre de 2025) y encontró una división clara entre los archivos que ayudan y los que se ignoran. Los que fallan comparten un rasgo: son demasiado vagos. Las personalidades de "asistente de programación servicial" no hacían nada; los comandos exactos y los límites firmes eran los que hacían el trabajo.

Esto es lo que se gana su lugar, y lo que conviene dejar fuera:

Incluir (se gana sus tokens)	Recortar (los desperdicia)
Comandos exactos con flags: pnpm test, pytest -v	"Ejecuta las pruebas" sin ningún comando
Stack con versiones: "React 18, TS 5, Vite, Tailwind"	"Stack web moderno"
Un fragmento de código real que muestre tu estilo	Párrafos que describen tu estilo
Límites de tres niveles: Siempre / Preguntar primero / Nunca	Una línea genérica de "ten cuidado"
Trampas no evidentes (peculiaridades del monorepo, configuración del entorno)	Un árbol de directorios completo que el agente puede leer por sí mismo
"Nunca hagas commit de secretos" y rutas protegidas	Repetir la documentación del lenguaje que el modelo ya conoce

La restricción genuinamente útil más común en los 2.500 repositorios era contundente: "Nunca hagas commit de secretos". Esa sola línea es el seguro más barato que puedes escribir, y se conecta directamente con las lecciones más amplias sobre la cadena de suministro que dejó la crisis de Shai-Hulud en npm: los agentes con acceso a la shell pueden filtrar credenciales tan rápido como un paquete comprometido.

Por qué un AGENTS.md más corto supera a uno más largo

Esta es la parte que la mayoría de las guías omite, y es la más importante. Cada línea de tu AGENTS.md se inyecta en cada sesión del agente, así que cada línea compite por el presupuesto de atención limitado del modelo. Rellenarlo no ayuda al agente: lo perjudica activamente.

Un estudio de ETH Zurich de 2026 puso números sobre la mesa. Los archivos de contexto autogenerados e inflados redujeron el éxito en las tareas en 5 de 8 escenarios probados, hicieron que los agentes dieran de 2,45 a 3,92 pasos adicionales por tarea y elevaron los costes de inferencia un 20–23 %, todo ello sin añadir calidad medible. Los archivos curados por humanos, en cambio, superaron a los generados por LLM en todos los agentes probados, en aproximadamente 4 puntos porcentuales en el benchmark AGENTbench. Cuando los investigadores eliminaron por completo la documentación redundante, el rendimiento de los archivos autogenerados en realidad mejoró, lo que confirma que en su mayoría duplicaban cosas que el modelo ya sabía.

La regla práctica de los profesionales coincide con los datos: mantenlo corto. El consenso general es menos de 300 líneas, y equipos como HumanLayer mantienen el suyo por debajo de 60. Escríbelo tú mismo, de forma deliberada, porque "una mala línea en AGENTS.md se propaga en forma de malos planes, mal código y malos resultados en cada sesión".

Cómo escribir tu AGENTS.md, paso a paso

Puedes tener un archivo funcional en diez minutos. Hazlo en este orden:

1. Crea AGENTS.md en la raíz del repositorio. Empieza vacío. Resiste la tentación de ejecutar un comando de "genera mi AGENTS.md": ya sabes que los datos dicen que gana el escrito a mano.
2. Escribe primero los comandos. Las líneas exactas que teclearías para instalar, ejecutar, probar y hacer lint. Incluye los flags. Esta es la sección de mayor valor, así que va arriba.
3. Nombra el stack con versiones. Una línea: lenguajes, framework, gestor de paquetes, bibliotecas clave y sus versiones principales. La ambigüedad aquí es lo que causa más pasos desperdiciados del agente.
4. Añade un fragmento de código real que demuestre tus convenciones: una función o componente real de tu repositorio, no una descripción de uno.
5. Fija límites de tres niveles. Siempre (p. ej. "ejecuta el linter antes de terminar"), Preguntar primero (p. ej. "antes de cambiar el esquema de la base de datos"), Nunca (p. ej. "nunca hagas commit de secretos, nunca toques /vendor, nunca git push"). Aquí es donde codificas el criterio que el modelo no puede inferir.
6. Anota solo lo no evidente. La disposición de los paquetes del monorepo, una variable de entorno obligatoria, una prueba inestable que hay que ignorar. Omite cualquier cosa que el agente pueda descubrir leyendo el árbol.
7. Pruébalo y luego recórtalo. Ejecuta una tarea real, observa dónde el agente adivina mal, añade una línea para corregirlo y elimina cualquier línea que nunca se haya ganado su lugar.

Una recompensa contraintuitiva: las herramientas que nombras en AGENTS.md se usan unas 160× más a menudo que las que no nombras. Si quieres que el agente use tu script personalizado o un servidor MCP concreto, menciónalo explícitamente; de lo contrario, en la práctica no existe. Si todavía estás eligiendo qué agente estandarizar, nuestro enfrentamiento Cursor vs Copilot vs Windsurf vs Claude Code cubre cómo carga cada uno el contexto del proyecto.

AGENTS.md, CLAUDE.md y .cursorrules: ¿necesitas los tres?

No. AGENTS.md es el estándar cross-tool emergente, así que conviértelo en tu fuente de verdad. Claude Code todavía busca CLAUDE.md y Cursor usaba históricamente .cursorrules; la jugada de menor esfuerzo es mantener el contenido real en AGENTS.md y, allí donde una herramienta insista en su propio nombre de archivo, crear un symlink o importarlo en lugar de mantener dos copias que se van desincronizando. En un monorepo, también puedes anidar archivos: los agentes leen automáticamente el AGENTS.md más cercano en el árbol de directorios, de modo que un paquete puede anular la raíz; el propio repositorio de OpenAI incluye 88 de ellos. Mantén general el archivo raíz y deja que cada paquete guarde sus particularidades. Con qué agente lo emparejes sigue importando; consulta nuestra recopilación de las mejores herramientas de IA para programar en 2026.

Errores comunes que evitar

• Autogenerar el archivo entero. La forma más rápida de conseguir un agente más lento. Genera como mucho un esqueleto y luego reescríbelo a mano.
• Pegar tu árbol de directorios. Los agentes listan los archivos por sí mismos; un árbol estático simplemente se pudre y quema tokens.
• Repetir lo obvio. El modelo sabe cómo funciona Python. Dile qué es específico de tu repositorio.
• Un único archivo gigante para todo. Usa la divulgación progresiva: mantén las notas específicas de cada tarea en documentos separados (p. ej. agent_docs/running-tests.md) y hazles referencia, para que el archivo raíz se mantenga esbelto.
• No revisarlo nunca. El archivo se desincroniza a medida que cambia tu proyecto. Recórtalo cada vez que el agente adivine mal.

Preguntas frecuentes

¿Dónde va el archivo AGENTS.md?

En la raíz de tu repositorio. Para monorepos, añade archivos AGENTS.md adicionales dentro de los paquetes individuales; el agente lee el más cercano al archivo en el que está trabajando, y ese archivo más cercano tiene prioridad.

¿Qué longitud debe tener un AGENTS.md?

Corta. El consenso práctico es menos de 300 líneas, y muchos buenos ejemplos se sitúan por debajo de 100. Como cada línea se carga en cada sesión, la longitud tiene un coste real tanto en precisión como en tokens: escribe solo lo que cambia el comportamiento del agente.

¿Debería dejar que una IA genere mi AGENTS.md?

Usa una para redactar un esqueleto aproximado si hace falta, pero no lo publiques tal cual. La investigación de ETH Zurich descubrió que los archivos autogenerados reducían el éxito en las tareas en la mayoría de los escenarios y elevaban los costes un 20–23 %. Los archivos curados por humanos superaron a los generados en todos los casos: vale la pena escribir el archivo a mano.

¿Usa Claude Code AGENTS.md?

Claude Code lee de forma nativa CLAUDE.md y cada vez reconoce más AGENTS.md. Los principios de contenido son idénticos en cualquier caso: comandos exactos, stack con versiones, límites firmes y brevedad. Si ya mantienes un buen CLAUDE.md, tienes el 90 % del camino recorrido hacia un buen AGENTS.md.

¿Qué es lo único que todo AGENTS.md debería tener?

Un límite de "Nunca" que incluya "nunca hagas commit de secretos". Fue la restricción útil más común en más de 2.500 repositorios reales, y es la línea más barata para proteger una base de código que un agente ahora puede editar y ejecutar.

Fuentes

• agents.md — el formato abierto y la especificación: definición, herramientas compatibles, anidamiento en monorepos y la administración de la Agentic AI Foundation / Linux Foundation.
• Blog de GitHub — How to write a great agents.md: lessons from over 2,500 repositories: las secciones respaldadas por datos que funcionan y el modo de fallo del "demasiado vago" (19 de noviembre de 2025).
• Philipp Schmid — Writing a Good AGENTS.md: el consenso de "mantenlo por debajo de 300 líneas" y el hallazgo del 160× por mencionar herramientas.
• Augment Code — How to Build Your AGENTS.md: resumen del estudio de ETH Zurich que muestra que los archivos autogenerados reducen el éxito en las tareas y elevan el coste.