Anthropic y ETH Zurich: un CLAUDE.md largo empeora el trabajo del agente y encarece el uso

CLAUDE.md y AGENTS.md nacieron como una forma rápida de explicar a un agente las reglas de un proyecto, pero un nuevo estudio indica que el contexto largo perjudica más de lo que ayuda. En una muestra de 138 repositorios de Python, los investigadores de ETH Zurich observaron una caída de la tasa de éxito y un aumento de los costes, sobre todo con los archivos generados automáticamente.

Qué mostró el estudio

Los autores de Evaluating AGENTS.md: Are Repository-Level Context Files Helpful for Coding Agents? tomaron 138 repositorios reales, reunieron 5694 pull requests y ejecutaron las tareas con cuatro modelos: Claude Sonnet 4.5, Codex GPT-5.2, GPT-5.1 Mini y Qwen3-30B. Compararon tres escenarios: sin archivos especiales, con instrucciones generadas por LLM y con AGENTS.md mantenidos por personas. Es un punto importante: el estudio no se basó en demos abstractas, sino en tareas reales de bases de código en uso.

El resultado principal para los archivos creados automáticamente fue desfavorable. La tasa de éxito bajó en promedio un 3%, mientras que el coste de inferencia subió más de un 20%. Los archivos escritos por humanos funcionaron mejor: elevaron el éxito en torno a un 4%, pero el coste también aumentó casi un 19%. Es decir, el archivo de contexto no resultó ser un acelerador gratuito. Incluso cuando ayuda, la mejora de calidad es modesta frente al sobrecoste constante en tokens y pasos innecesarios del agente.

Por qué un archivo largo estorba

La observación más contraintuitiva del artículo: las descripciones de la estructura del proyecto apenas ayudan al agente a orientarse. Las secciones sobre carpetas, arquitectura y stack parecen útiles para una persona, pero el agente suele encontrarlo todo igualmente con grep, glob y la lectura de archivos. Si la información ya está en pyproject.toml, package.json, la configuración del linter o en la propia estructura del repositorio, una explicación larga solo duplica lo que el modelo puede descubrir rápidamente por su cuenta.

Si el agente puede averiguarlo por sí mismo a partir del código, es

mejor eliminarlo de las instrucciones.

Los investigadores también notaron que los modelos con archivos de contexto realizan más acciones de las necesarias para la tarea concreta. Releen las instrucciones con más frecuencia, ejecutan las pruebas una vez de más y llaman con más ganas a las herramientas mencionadas en el archivo. El artículo señala por separado un aumento de los reasoning tokens en los modelos GPT. En otras palabras, la instrucción no solo añade conocimiento, sino que cambia el comportamiento del agente: empieza a seguir reglas incluso donde no ayudan a resolver la tarea actual.

Qué conviene conservar

El estudio no concluye que haya que abandonar por completo CLAUDE.md o AGENTS.md. La conclusión es más bien que estos archivos deben ser cortos y contener solo lo que el agente no puede deducir de forma fiable a partir del código o las configuraciones. Cuanto menos texto decorativo, menor es el riesgo de que el modelo se obsesione con rituales superfluos en lugar de cumplir la petición concreta.

• Un comando no estándar para ejecutar las pruebas
• El gestor de paquetes, si no es evidente
• Scripts personalizados, herramientas y particularidades del despliegue
• Reglas de nomenclatura, si no se pueden deducir rápidamente del código
• Una referencia a .env.example u otro archivo de entrada crítico

Otro estudio complica el panorama: en él, Codex con AGENTS.md mostró una aceleración y un menor consumo de tokens. Pero la muestra era mucho menor y la corrección de los resultados se evaluó de forma limitada. Por eso, la conclusión general sigue siendo cautelosa: un contexto corto y aplicado a veces ayuda, mientras que un archivo largo con un repaso de la arquitectura, el stack y las reglas generales se convierte fácilmente en lastre costoso. ETH Zurich tampoco aborda apenas la mantenibilidad del código ni la adecuación al estilo del proyecto, así que el debate sobre la utilidad de estos archivos sigue abierto.

Qué significa esto

La conclusión práctica es sencilla: trata CLAUDE.md como una lista de errores corregidos del agente, no como la enciclopedia del proyecto. Si una instrucción no ayuda a evitar un fallo concreto, no describe un comando no estándar y no aporta contexto único, es mejor quitarla. Para los equipos que usan mucho agentes de código, es un motivo directo para recortar los archivos de contexto, reducir el gasto en tokens y comprobar con sus propias tareas qué líneas mejoran realmente el resultado y cuáles solo generan ruido caro.