Afirmación principal
- Si el archivo de contexto para agentes de código con IA (
AGENTS.md) se genera automáticamente con el comando /init, el rendimiento del agente en realidad empeora y el costo aumenta en más de un 20%
- El problema central es proporcionar de forma redundante información que el agente puede descubrir por sí mismo
- En
AGENTS.md solo se debe incluir información que el agente no pueda saber leyendo el código
Resultados de investigación: ¿AGENTS.md ayuda o perjudica?
- Lulla et al. (ICSE JAWs 2026): experimento pareado sobre 124 PR de GitHub comparando únicamente la presencia o ausencia de
AGENTS.md
- Con
AGENTS.md, el tiempo de ejecución se redujo 28.64% y los tokens de salida 16.58%
- El archivo usado en este estudio era mantenido realmente por desarrolladores e incluía conocimiento específico del proyecto
- Investigación de ETH Zurich: probaron 4 agentes en SWE-bench y otros benchmarks, pero distinguiendo entre archivos generados automáticamente por LLM y archivos escritos por desarrolladores
- Contexto generado automáticamente por LLM: la tasa de éxito cayó entre 2% y 3%, y el costo aumentó 20%+
- En un entorno donde se eliminaron por completo documentos existentes como el README, el archivo generado por LLM sí mejoró el rendimiento en 2.7%
- Archivos escritos directamente por desarrolladores: la tasa de éxito mejoró alrededor de 4%, con un aumento de costo de hasta 19%
- Conclusión: el problema no es el contenido autogenerado en sí, sino la redundancia
- Dar la misma información dos veces solo agrega ruido, y únicamente el conocimiento no descubrible escrito por desarrolladores aporta ayuda real
Por qué la generación automática es dañina
AGENTS.md generado automáticamente suele incluir en su mayoría información que el agente ya descubre por sí mismo
- Resumen del codebase (100% de las salidas de Sonnet 4.5 y 99% de las salidas de GPT-5.2 lo incluían)
- Estructura de directorios, stack tecnológico, descripción de módulos
- Volver a dar información que ya conoce solo consume tokens y no aporta valor
- Efecto de anclaje: si se mencionan patrones legacy, el agente queda fijado en ellos incluso cuando hay alternativas mejores
- Esto coincide con la investigación "Lost in the Middle" (Liu et al., 2024): un contexto largo dispersa la atención y reduce el rendimiento
Qué debe ir en AGENTS.md y qué no
- Debe incluirse (información no descubrible por el agente)
- Herramientas prescritas: "usar
uv para la gestión de paquetes"
- Reglas no intuitivas: "las pruebas deben ejecutarse siempre con
--no-cache; si no, los fixtures generan falsos positivos"
- Restricciones del sistema: "el módulo
auth usa middleware personalizado; no refactorizarlo a Express estándar"
- Si una herramienta aparece en la documentación, el agente la usa entre 1.6 y 2.5 veces por tarea; si no está documentada, cae a menos de 0.05 veces
- No debe incluirse (lo que el agente puede descubrir por sí mismo)
- Estructura de directorios, layout del monorepo
- Resumen del stack tecnológico, patrones arquitectónicos estándar
Limitaciones estructurales de un archivo estático
- Incluso un
AGENTS.md bien escrito tiene una debilidad fundamental: el archivo es estático, pero las tareas son dinámicas
- Las instrucciones en un único archivo no pueden ramificarse según el tipo de tarea
- Incluso en tareas de edición de documentación se aplica la instrucción de "ejecutar la suite completa de pruebas antes de hacer commit", desperdiciando tiempo y tokens
- En una refactorización de CSS se cargan advertencias sobre migraciones de base de datos, y en una corrección de seguridad aparecen consejos de optimización de rendimiento
- Framework ACE (ICLR 2026): frente a un archivo estático, un enfoque de Agentic Context Engineering que hace evolucionar el contexto dinámicamente con un pipeline generator/reflector/curator mostró un rendimiento 12.3% superior
Una estructura mejor, todavía no construida
- Varias personas llegaron de forma independiente a la misma conclusión sobre
AGENTS.md
- La estructura correcta no es un archivo único, sino una capa de enrutamiento + contexto focalizado que se carga cuando hace falta
- Capa 1 - archivo de protocolo: no es una guía del codebase ni una guía de estilo, sino un documento de enrutamiento
- Define personas disponibles y condiciones de invocación, habilidades y tipos de tarea asignados, conexiones MCP y su propósito
- Solo debe incluir el mínimo de hechos del repositorio que el agente no pueda descubrir, y nada más
- Capa 2 - archivos de persona/habilidad: se cargan selectivamente según el tipo de tarea
- El agente de UX y el agente backend cargan contextos distintos, y no cargan el contexto del otro
- Capa 3 - subagente de mantenimiento: un agente dedicado a mantener la precisión del archivo de protocolo
- La documentación se degrada: incluso el estudio de ETH Zurich probó con archivos recién generados y aun así mostró caída de rendimiento
- Si un
AGENTS.md abandonado por 6 meses describe dependencias ya reemplazadas o una estructura de directorios que cambió, el problema es mucho más grave
- Hoy ningún agente de código importante ofrece lifecycle hooks que permitan implementar fácilmente esta arquitectura; se puede aproximar con subagentes y contexto acotado, pero sigue habiendo una brecha de herramientas sin cubrir
Optimización automática
- Arize AI usa un loop de optimización automática en lugar de escribir manualmente las instrucciones de
CLAUDE.md
- Ejecutar el agente en tareas de entrenamiento → evaluar resultados → generar feedback con LLM sobre la causa del fallo → mejorar las instrucciones con metaprompting → repetir
- En pruebas cross-repo mejoró la precisión en +5.19%, y en pruebas in-repo en +10.87%
- La verdad incómoda que reveló el optimizador: lo que ayuda a una persona a entender un codebase no es lo mismo que lo que un LLM necesita para navegarlo
- Información como "este servicio usa el patrón repository" parece obviamente útil para un desarrollador, pero para el modelo puede ser ruido
- En cambio, lo que el modelo realmente necesita (distinguir ciertas rutas de import, reglas no intuitivas de nombres de archivo, etc.) suele estar tan internalizado por el desarrollador que ni siquiera piensa en escribirlo
- Escribir
AGENTS.md a mano asume que el desarrollador sabe qué necesita el agente
- La evidencia empírica sugiere que probablemente no
- El optimizador encuentra la diferencia entre "lo que creemos importante" y "lo que realmente cambia el resultado"
- Esto no significa que haya que dejar de escribirlo: 5% es relevante, pero no transformador. Significa aferrarse menos a la intuición y probarlo en la práctica
La mentalidad correcta para ver AGENTS.md
- Hay que ver
AGENTS.md como un registro de procesos que todavía no se han corregido
- Cada línea que se agrega es una señal de que hay algo en el codebase lo bastante ambiguo como para confundir a un agente de IA, y eso también implica que un nuevo colaborador humano probablemente se desoriente
- La respuesta correcta no es agrandar el archivo de contexto, sino corregir la causa raíz
- El agente pone utilidades en un directorio equivocado → la estructura de directorios es confusa, así que hay que reorganizarla
- El agente sigue usando una dependencia obsoleta → la estructura de imports hace demasiado fácil usar lo incorrecto, así que hay que corregirla
- El agente omite la verificación de tipos → en vez de depender de instrucciones, hay que atraparlo automáticamente en el pipeline de build
AGENTS.md no es una configuración permanente, sino una herramienta de diagnóstico: se agrega una línea, se investiga por qué el agente repite ese error, se corrige la causa raíz y luego se elimina esa línea- Técnica que vale la pena probar: empezar con un
AGENTS.md casi vacío y dejar solo una instrucción: "si encuentras algo sorprendente o confuso en este proyecto, déjalo en un comentario". La mayoría de los agregados que sugiera el agente no son para conservarlos permanentemente, sino marcadores de puntos poco claros en el codebase
Recomendaciones prácticas
- Deja de ejecutar
/init: salvo que el repo no tenga ninguna documentación, el resultado autogenerado duplicará documentos existentes
- Antes de agregar una línea a
AGENTS.md, pregúntate: "¿el agente podría saber esto leyendo el código?" Si la respuesta es sí, no lo escribas
- Cuando el agente falle repetidamente, corrige primero el codebase antes de agrandar el archivo de contexto
- Mejora la estructura del código, agrega reglas del linter, amplía la cobertura de pruebas, y solo si eso no basta toca
AGENTS.md
- Si operas agentes a gran escala en pipelines de CI/CD o revisión automática, ten en cuenta que un sobrecosto de 15% a 20% se acumula de forma compuesta a lo largo de miles de ejecuciones
- El impulso de incorporar al agente como si fuera una persona recién contratada (tour de la oficina, organigrama, explicación de la arquitectura) es natural, pero un agente de código no es un recién llegado: puede hacer
grep sobre todo el codebase antes incluso de que termines de escribir el prompt. Lo que el agente necesita no es un mapa, sino la ubicación de las minas
9 comentarios
Al final dicen que es una pelea por el contexto...
Creo que habría que hacer que creen por separado un md para el agente y otro md para el usuario.
Estoy totalmente de acuerdo. La estructura fácil de leer para las personas (
README) y la estructura fácil de parsear para un LLM (AGENTS.md) son completamente distintas. Cuando se genera automáticamente y se le lanza todo el contexto sin más, lo único que se logra es desperdiciar dinero en tokens de API y, de hecho, muchas veces he visto que las alucinaciones se agravan. Al final, aunque dé flojera, parece que lo más eficiente es que una persona comprima y depure directamente las instrucciones para el agente.En el principio estaba el README, y AGENTS.md es básicamente un README hecho para agentes.
Pero, ¿eso no ya existe en el README?
Pero el modelo en sí cambia en cuestión de unos meses,
y hay que ajustar los agents para que encajen con el modelo...
¿No será que los cambios del modelo van más rápido que el tiempo que toma crear una estructura de agents adecuada?
Al final, antes de que la gente se acostumbre a la herramienta, la herramienta ya cambió...
Al final, parece que lo importante es mantener siempre el contexto puro y con pocos tokens... En ese sentido, hasta dan ganas de pensar que los caracteres chinos podrían ser bastante útiles. jajaja
Para el modelo, el inglés ya es casi como si 1 palabra fuera 1 carácter (token), así que en la práctica ¿no vendría siendo como los caracteres chinos?
Oh, no había pensado en este enfoque, pero me parece que tiene sentido.
Oh..