Anthropic y ETH Zurich: un CLAUDE.md largo empeora el rendimiento del agente y eleva los costos

CLAUDE.md y AGENTS.md fueron concebidos como una forma rápida de explicar las reglas del proyecto a un agente, pero una nueva investigación muestra: el contexto largo más a menudo perjudica que ayuda. En una muestra de 138 repositorios Python, investigadores de ETH Zurich observaron una caída en la tasa de éxito y aumento de costos, especialmente para archivos generados automáticamente.

Lo que mostró la investigación

Los autores del artículo Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? tomaron 138 repositorios reales, recopilaron 5694 pull requests y ejecutaron tareas a través de cuatro modelos: Claude Sonnet 4.5, Codex GPT-5.2, GPT-5.1 Mini y Qwen3-30B. Compararon escenarios sin archivos especiales, con instrucciones generadas por LLM y con AGENTS.md mantenidos por humanos. Este es un punto importante: la investigación no miró demostraciones abstractas, sino tareas reales de bases de código vivas.

La conclusión principal para archivos creados automáticamente resultó ser desagradable. La tasa de éxito bajó en promedio 3%, y el costo de inferencia aumentó más del 20%. Los archivos mantenidos por humanos se desempeñaron mejor: elevaron el éxito aproximadamente 4%, pero el costo también subió casi 19%. En otras palabras, un archivo de contexto no resultó ser un acelerador gratuito. Incluso cuando ayuda, la ganancia de calidad permanece modesta en comparación con el pago excesivo constante de tokens y pasos adicionales del agente.

Por qué los archivos largos perjudican

La observación más contraintuitiva del artículo: las descripciones de la estructura del proyecto apenas ayudan al agente a navegar. Las secciones sobre carpetas, arquitectura y stack se ven útiles para humanos, pero los agentes a menudo encuentran todo por sí solos a través de grep, glob y lectura de archivos. Si la información ya está en pyproject.toml, package.json, configuración de linter o en la propia estructura del repositorio, una explicación larga solo duplica lo que el modelo es capaz de descubrir rápidamente por sí mismo.

Si el agente puede aprender esto del código por sí mismo, es mejor

eliminarlo de la instrucción.

Los investigadores también notaron que los modelos con archivos de contexto realizan más acciones de las necesarias para la tarea específica. Releeen las instrucciones con más frecuencia, ejecutan pruebas innecesariamente e invocan más activamente herramientas que fueron mencionadas en el archivo. El artículo destaca por separado un aumento en los tokens de razonamiento en modelos GPT. En otras palabras, la instrucción no simplemente agrega conocimiento, sino que cambia el comportamiento del agente: comienza a seguir reglas incluso donde no ayudan a resolver la tarea actual.

Qué debería mantenerse

Un rechazo completo de CLAUDE.md o AGENTS.md no se desprende de esta investigación. Más bien, la conclusión es diferente: tales archivos deben ser breves y contener solo lo que el agente no puede deducir de manera confiable del código o configuraciones por sí mismo. Cuanto menos texto decorativo, menor el riesgo de que el modelo se atasque en rituales innecesarios en lugar de ejecutar la solicitud específica.

• Comandos no estándar para ejecutar pruebas
• Gestor de paquetes, si no es obvio
• Scripts personalizados, herramientas y particularidades de despliegue
• Convenciones de nomenclatura, si no pueden deducirse rápidamente del código
• Enlace a .env.example u otro archivo de entrada crítico

Otra investigación se superpone a este cuadro, donde Codex con AGENTS.md mostró aceleración y menor consumo de tokens. Pero allí la muestra era mucho más pequeña, y la corrección de los resultados se evaluó de forma limitada. Entonces la conclusión general por ahora es cautelosa: el contexto corto y práctico a veces ayuda, mientras que un archivo largo que revisa arquitectura, tech stack y reglas generales fácilmente se convierte en lastre costoso. ETH Zurich también apenas aborda la mantenibilidad del código y la adherencia al estilo del proyecto, por lo que el debate sobre la utilidad de tales archivos aún no está cerrado.

Qué significa esto

La conclusión práctica es simple: trate CLAUDE.md como una lista de correcciones para errores del agente, no como una enciclopedia del proyecto. Si la instrucción no ayuda a evitar una falla específica, no describe un comando no estándar y no agrega contexto único, es mejor eliminarla. Para equipos que utilizan activamente agentes de codificación, esta es una motivación directa para reducir archivos de contexto, reducir el gasto de tokens y verificar en sus propias tareas qué líneas realmente mejoran los resultados y cuáles solo crean ruido costoso.