Resumen Técnico: Evaluación de AGENTS.md

Declaración del Problema

La industria de la ingeniería de software ha adoptado rápidamente los agentes de codificación, con una recomendación predominante de los desarrolladores de modelos y agentes de adaptar estos agentes a repositorios específicos mediante archivos de contexto (por ejemplo, AGENTS.md o CLAUDE.md). Estos archivos suelen contener descripciones generales de los repositorios, instrucciones de herramientas y guías de estilo destinadas a mejorar la navegación, la ejecución de compilaciones y la resolución de tareas. A pesar de su adopción generalizada —reportada en más de 60,000 repositorios de código abierto— y del fuerte estímulo de la industria, no existe una investigación rigurosa y a gran escala sobre si estos archivos de contexto realmente mejoran el rendimiento de los agentes de codificación en tareas del mundo real. Benchmarks previos como SWE-bench carecen de archivos de contexto, y los repositorios populares utilizados en tales benchmarks a menudo no representan las bases de código donde se despliegan realmente los archivos de contexto.

Metodología

Para abordar esta brecha, los autores realizaron una evaluación exhaustiva a través de dos entornos complementarios:

1. Benchmark Novel (CTXBENCH): Los autores construyeron un nuevo benchmark compuesto por 138 instancias derivadas de problemas reales de GitHub en 12 repositorios de nicho basados en Python que ya contienen archivos de contexto comprometidos por desarrolladores. A diferencia de SWE-bench, que depende de repositorios populares, CTXBENCH apunta a repositorios donde los archivos de contexto son una práctica activa. La generación del conjunto de datos implicó:

   • Filtrar repositorios con AGENTS.md o CLAUDE.md y al menos 400 Pull Requests (PRs).
   • Seleccionar PRs que introducen comportamientos deterministas y testeables.
   • Utilizar agentes de LLM para generar descripciones de tareas estandarizadas y nuevos tests unitarios donde los PRs originales carecían de ellos, asegurando que los tests pasen en el código corregido pero fallen en el código base.
   • Validar que los archivos de contexto proporcionados por los desarrolladores sean distintos de los generados por LLM (más cortos, con puntuaciones de detección de IA más bajas).

2. Configuración Experimental: El estudio evaluó cuatro agentes de codificación (CLAUDE CODE, CODEX, QWEN CODE) emparejados con varios modelos (SONNET-4.5, GPT-5.2, GPT-5.1 Mini, QWEN3-30B-CODER) en dos conjuntos de datos:

   • SWE-BENCH Lite: 300 tareas de repositorios populares sin archivos de contexto de desarrollador.
   • CTXBENCH: 138 tareas de repositorios con archivos de contexto de desarrollador.

3. Condiciones de Evaluación: Para cada tarea, los agentes fueron probados en tres configuraciones:

   • None (Ninguno): Sin archivo de contexto proporcionado.
   • LLM: Un archivo de contexto generado automáticamente por el comando de inicialización recomendado por el agente.
   • DEV: El archivo de contexto real comprometido por el desarrollador (disponible solo para CTXBENCH).

4. Métricas: El rendimiento se midió mediante la tasa de éxito (porcentaje de tareas donde el parche generado pasa todos los tests), el número de pasos de interacción y el costo total de inferencia. Se realizó un análisis de trazas para comprender los cambios de comportamiento, incluyendo la frecuencia de uso de herramientas y el consumo de tokens de razonamiento.

Contribuciones Clave

1. CTXBENCH: Un nuevo benchmark diseñado específicamente para evaluar el impacto de los archivos de contexto activos y proporcionados por desarrolladores en los agentes de codificación, con 138 instancias de 12 repositorios.
2. Evaluación Exhaustiva: Un estudio extenso a través de múltiples modelos y agentes tanto en SWE-BENCH como en CTXBENCH, revelando que los archivos de contexto no mejoran significativamente las tasas de éxito de las tareas.
3. Análisis de Comportamiento: Una investigación detallada de las trazas de los agentes demostrando que, si bien los agentes siguen estrictamente las instrucciones en los archivos de contexto (lo que conduce a un aumento en las pruebas y la exploración), estos archivos no logran servir como descripciones efectivas del repositorio y aumentan los costos operativos.

Resultados

El estudio arroja varios hallazgos contraintuitivos respecto a la eficacia de los archivos de contexto:

• Sin Ganancia de Rendimiento: Proporcionar archivos de contexto no mejora generalmente las tasas de éxito de las tareas.
  • En SWE-BENCH, los archivos de contexto generados por LLM resultaron en una disminución marginal y estadísticamente insignificante en las tasas de éxito (promedio -0.5%).
  • En CTXBENCH, los archivos generados por LLM también mostraron una mejora no significativa (promedio -2%).
  • Los archivos comprometidos por desarrolladores mostraron una mejora marginal del 2.4% en promedio sobre la configuración "None", pero esto no fue estadísticamente significativo ($p=0.21$). Sin embargo, los archivos de desarrolladores superaron significativamente a los generados por LLM ($p=0.038$).
• Aumento de Costo y Pasos: Los archivos de contexto aumentan consistentemente el costo y la complejidad de la resolución de tareas.
  • Los archivos generados por LLM aumentaron los costos de inferencia en más de un 20% en promedio en ambos benchmarks.
  • Los archivos comprometidos por desarrolladores aumentaron los costos hasta un 19%.
  • El número de pasos de interacción aumentó significamente en todas las configuraciones con archivos de contexto.
• Mecanismos de Comportamiento:
  • Seguimiento de Instrucciones: Los agentes siguen estrictamente las instrucciones en los archivos de contexto. Cuando se mencionan herramientas específicas (ej. uv, pytest), su uso aumenta drásticamente. Esto conduce a pruebas más exhaustivas, exploración de archivos y uso de herramientas específicas del repositorio.
  • Descripciones Generales Ineficaces: A pesar de las recomendaciones de incluir descripciones generales del código base, estas secciones no ayudan a los agentes a localizar archivos relevantes más rápido. De hecho, los agentes a menudo gastan pasos adicionales buscando y releyendo archivos de contexto que ya están en su ventana de contexto.
  • Sobrecarga de Razonamiento: La presencia de archivos de contexto aumenta el número de tokens de razonamiento utilizados por los modelos adaptativos (ej. +22% para GPT-5.2 con archivos generados por LLM), lo que sugiere que las instrucciones adicionales hacen que la tarea sea cognitivamente más difícil sin proporcionar la información necesaria.
• Redundancia: Los archivos de contexto a menudo actúan como documentación redundante. Cuando se eliminan las documentaciones existentes (READMEs, carpetas docs), los archivos generados por LLM en realidad mejoran el rendimiento, lo que sugiere que su valor principal en configuraciones estándar es la redundancia en lugar de un conocimiento único.

Significado y Conclusión

El artículo concluye que la práctica actual de la industria de generar automáticamente o incluir ampliamente archivos de contexto como AGENTS.md no está respaldada por evidencia empírica para mejorar el rendimiento de los agentes de codificación. Si bien los agentes siguen las instrucciones dentro de estos archivos, lo que conduce a una exploración más exhaustiva (y costosa), los archivos generalmente no logran proporcionar descripciones de repositorio efectivas que aceleren la resolución de tareas.

Los autores argumentan que los archivos de contexto deben reservarse para especificar prácticas de codificación no estándar o convenciones específicas que no estén ya presentes en el README del repositorio. Recomiendan que los desarrolladores evalúen rigurosamente cualquier intento de usar archivos de contexto antes de su despliegue, en lugar de confiar en la generación automática o en recomendaciones generales. Este trabajo resalta una brecha entre las recomendaciones de los desarrolladores de agentes y los resultados observados, motivando la investigación futura en la generación de guías principios, concisas y relevantes para las tareas para los agentes de codificación.