Qué es esto y en qué punto está el estándar
Por su propia definición, AGENTS.md es un «README para agents»: un sitio designado y previsible dentro del repo donde le das al coding agent el contexto y las reglas del proyecto.
Conviene saber cuatro cosas sobre su estado en septiembre de 2026:
- Tiene una organización detrás. El formato lo mantiene la Agentic AI Foundation, dependiente de la Linux Foundation, desde diciembre de 2025. Entre los miembros fundadores están casi todos los grandes desarrolladores de modelos y proveedores de nube.
- Está extendido. Lo usan más de 60.000 proyectos de código abierto y lo leen unas 26 herramientas.
- No tiene formato. «Markdown normal. Usa los encabezados que quieras, el agent simplemente lee el texto.» No hay campos obligatorios, ni tampoco una especificación normativa con número de versión.
- El sitio sí está fijado: la raíz del repo. Con paquetes anidados, cada uno puede llevar el suyo.
Que no tenga formato es a la vez la fuerza y la debilidad del estándar. Fuerza, porque se adopta en cinco minutos. Debilidad, porque nada te dice qué debe ir dentro — y por eso la mayoría de estos archivos acaban siendo inservibles de tan largos.
Qué herramienta lee qué archivo
Aquí está la trampa más habitual, y merece la pena citar la documentación del fabricante palabra por palabra: uno de los grandes agents de terminal lee su propio archivo, no AGENTS.md.
| Archivo | Estado en septiembre de 2026 |
|---|---|
AGENTS.md |
El denominador común. Lo lee casi todo. |
CLAUDE.md |
Vigente — y no lee AGENTS.md en su lugar. |
.github/copilot-instructions.md |
Vigente; además recoge archivos por ruta y también AGENTS.md. |
.cursor/rules/*.mdc |
Esta es la forma actual; lee AGENTS.md igualmente. |
.cursorrules |
La documentación oficial ya no lo lista. No lo uses en un proyecto nuevo. |
GEMINI.md |
Vigente. |
.windsurfrules, .clinerules, .devin/rules/ |
Formatos heredados. |
La solución es simple y conviene adoptarla: que haya una sola fuente, y que el resto apunte a ella. Con un import desde el otro archivo, o con un enlace simbólico. En Windows el enlace simbólico exige modo administrador o de desarrollador — ahí el camino es el import.
La precedencia también difiere. En una herramienta la instrucción personal es la más fuerte, después el repo y por último la de la organización. En otra, los archivos no se sobrescriben entre sí, se concatenan, desde la raíz hacia el directorio de trabajo.
Qué sabemos por medición — y qué no
Hay un experimento de 2026 sobre esto, publicado en una conferencia, y su metodología es inusualmente limpia.
Diez repos, 124 pull requests, comparación pareada: la misma tarea, el mismo estado del repo, la misma base de código — una vez con archivo de instrucciones de proyecto y otra sin él. Contenedores aislados, checkout limpio en el commit correspondiente. Solo cambios pequeños: como mucho cien líneas y cinco archivos.
| Indicador | Sin el archivo | Con el archivo | Cambio |
|---|---|---|---|
| Tokens de salida de media | 5.745 | 4.591 | −20 % |
| Tiempo medio de finalización | 162,9 s | 129,9 s | −20,3 % |
| Tokens de entrada | — | — | aprox. −10 % |
Y ahora el límite sin el cual todo esto engaña: la corrección no se midió. Sobre una muestra revisada a mano de cincuenta tareas, los autores solo confirmaron que se había producido «un cambio de código no vacío, no trivial y acorde a la tarea». La evaluación completa de la corrección quedó para trabajo futuro.
Es decir, lo que el archivo de instrucciones sí está demostrado que hace hoy: vuelve al agent más rápido y más barato, alrededor de una quinta parte. Que le haga escribir mejor código no lo ha demostrado nadie. Esto no es un argumento en su contra, pero sí un argumento contra tomarlo por una herramienta de aseguramiento de calidad.
¿De qué tamaño debe ser?
Los tres grandes fabricantes recomiendan tres cifras distintas, y eso ya dice algo:
- Menos de 200 líneas por archivo. El motivo, textualmente: «los archivos más largos consumen más contexto y reducen el cumplimiento».
- Menos de 500 líneas por regla, repartidas en varias reglas componibles.
- Menos de dos páginas.
La más estricta de las tres — 200 líneas — cumple con todas. Empieza ahí.
Y hay investigación independiente que dice dónde está el techo real. Un experimento de 2026 probó cinco modelos para ver qué pasa al ir sumando reglas simultáneas: 10, 20, 40, 80, 120 y 160 reglas, en cuatro formatos distintos, con dos colocaciones y 960 llamadas por modelo.
El resultado: en todos los modelos, en todos los formatos, con ochenta reglas la proporción de «respuestas perfectas» cayó a cero. No empeoró: cayó a cero. Con ciento sesenta reglas todos los modelos estaban a cero en todas las condiciones.
Un archivo de 200 líneas contiene unas 30–60 reglas reales. Eso queda justo por debajo del techo — y ahora ya sabes por qué el techo está ahí.
Por qué es una sugerencia y no una orden
Esto lo dice la propia documentación del fabricante, y conviene tomárselo en serio:
El contenido del archivo de instrucciones de proyecto llega después del system prompt, como mensaje de usuario, no como parte del system prompt. El modelo lo lee e intenta seguirlo, pero no hay garantía de cumplimiento estricto, sobre todo con instrucciones vagas o contradictorias.
Tres consecuencias prácticas:
- No dejes dentro una regla contradictoria. Si dos reglas chocan, el modelo «puede elegir una de forma arbitraria».
- El archivo sobrescrito consigue lo contrario. La documentación, textualmente: un archivo de instrucciones hinchado hace que el modelo ignore tus instrucciones de verdad.
- También se puede abusar del énfasis. Si una línea se salta una y otra vez, recálcala — pero «si destacas muchas líneas, ninguna destaca».
Hay una pregunta de autocomprobación para cada línea, y es el mejor filtro que existe: «si borrara esto, ¿fallaría algo?» Si no — bórralo.
Lo obligatorio no debe ser una instrucción
Este es el consejo técnico más importante del artículo, y otra vez es el fabricante quien lo formula con más precisión:
A diferencia de las instrucciones de proyecto, que son de carácter orientativo, los hooks son deterministas y garantizan que la operación ocurre.
O sea: si quieres que el formateador se ejecute antes de cada commit, no lo escribas en el archivo de instrucciones. Engánchalo como hook o mételo en el CI. El archivo de instrucciones sirve para que el modelo entienda el proyecto, no para obligarlo.
La estructura que escala
1. UN archivo en la raíz del repo, MENOS DE 200 LÍNEAS.
Lo que vale siempre: el objetivo del proyecto, los
comandos (build, test, lint), las convenciones no obvias.
2. LO QUE SOLO VALE PARA UNA PARTE -> regla ligada a ruta.
La regla de la API debe cargarse solo cuando el agent
toca un archivo de la API. Las tres herramientas
grandes tienen su propio formato para esto.
3. LO OBLIGATORIO -> hook o CI, no instrucción.
4. LO QUE SE CONTRADICE -> borra una de las dos. No es
tarea del modelo adivinar cuál iba en serio.
5. VARIOS AGENTS -> UNA fuente + import o symlink.
No mantengas tres archivos con el mismo contenido.
6. REVISIÓN trimestral: para cada línea,
"si borrara esto, ¿fallaría algo?"
El reglamento de 37 páginas que nadie cumple
Hay una medición de 2026 que no va de programación pero encaja exactamente aquí.
Diez empresas ficticias, cinco áreas de negocio, 65 tareas, y para cada una un reglamento corporativo con formato realista: de 20 a 124 páginas, mediana de 37, en PDF, Word y HTML. Entre todas, las tareas llevaban 824 criterios de aceptación comprobables por programa: acciones obligatorias y acciones prohibidas.
El resultado estricto: el mejor modelo llegó al 36,2 %, y la mayoría de los modelos punteros se quedó por debajo del 25 %.
Y el detalle más elocuente: si permites un solo criterio fallado por tarea, las puntuaciones se duplican más o menos. O sea, los agents sacan adelante la mayor parte del trabajo que rige un reglamento, y justo se saltan los controles críticos.
Este es el mejor argumento de que el archivo de instrucciones no sustituye a la revisión. Un reglamento de treinta y siete páginas lo incumple en algún punto incluso el mejor modelo en dos de cada tres casos. Lo que eso te deja por revisar a mano lo desglosa el post revisar el código generado , punto por punto.
Malentendidos habituales
- «AGENTS.md lo leen todas las herramientas.» No. Uno de los grandes agents lee expresamente su propio archivo. Mantén una fuente y que el resto apunte a ella.
- «Cuanto más detallado, mejor lo cumple.» Con ochenta reglas simultáneas, la proporción de cumplimiento perfecto cae a cero. Y con el archivo hinchado se pierden tus instrucciones de verdad.
- «Si lo escribo, se hace.» Es orientativo, llega como mensaje de usuario y no hay garantía de cumplimiento estricto. Lo obligatorio va en un hook o en el CI.
- «Le hace escribir mejor código.» La medición mostró un 20 % de ahorro en tokens y en tiempo. La corrección no se midió.
- «Si lo destaco todo, lo cumple todo.» «Si destacas muchas líneas, ninguna destaca.»
Lo que conviene llevarse
El archivo de instrucciones hace al agent más rápido y más barato, no más preciso. Que sea un archivo, en la raíz del repo, por debajo de doscientas líneas; lo que solo afecta a una parte del código va en una regla ligada a ruta; lo obligatorio va en un hook o en el CI. Y hazle a cada línea la pregunta: si borrara esto, ¿fallaría algo?
Cómo repartir esa primera tarea real lo recorre el post la primera tarea con un coding agent , paso a paso; y dónde conviene que se ejecute todo esto lo detalla el post elegir tu entorno de desarrollo , con las opciones.