En el mundo de la IA, de alto riesgo, la ‘Ingeniería de Contexto’ se ha convertido en la última frontera para exprimir el rendimiento de los LLM. Los líderes de la industria han promocionado AGENTS.md (y sus primos como CLAUDE.md) como el punto de configuración definitivo para los agentes de codificación: una ‘Estrella del Norte’ a nivel de repositorio inyectada en cada conversación para guiar a la IA a través de bases de código complejas.
Pero un estudio reciente realizado por investigadores de ETH Zurich acaba de arrojar una enorme prueba de la realidad. Los hallazgos son bastante claros: si no es deliberado con sus archivos de contexto, probablemente esté saboteando el desempeño de su agente mientras paga una prima del 20% por el privilegio.
Los datos: más tokens, menos éxito
El equipo de investigación de ETH Zurich analizó agentes de codificación como Sonnet-4.5, GPT-5.2 y Qwen3-30B a través de puntos de referencia establecidos y un nuevo conjunto de tareas del mundo real llamado AGENTBENCH. Los resultados fueron sorprendentemente desiguales:
El impuesto generado automáticamente: los archivos de contexto generados automáticamente redujeron las tasas de éxito en aproximadamente un 3%. El costo de la ‘ayuda’: estos archivos aumentaron los costos de inferencia en más de un 20 % y requirieron más pasos de razonamiento para resolver las mismas tareas. El margen humano: Incluso los archivos escritos por humanos solo proporcionaron una ganancia marginal de rendimiento del 4%. El límite de inteligencia: Curiosamente, el uso de modelos más potentes (como GPT-5.2) para generar estos archivos no produjo mejores resultados. Los modelos más potentes suelen tener suficiente “conocimiento paramétrico” de las bibliotecas comunes como para que el contexto adicional se convierta en ruido redundante.
Por qué falla el contexto “bueno”
El equipo de investigación destaca una trampa de comportamiento: los agentes de IA son demasiado obedientes. Los agentes codificadores tienden a respetar las instrucciones que se encuentran en los archivos contextuales, pero cuando esos requisitos son innecesarios, dificultan la tarea.
Por ejemplo, los investigadores descubrieron que las descripciones generales de la base de código y los listados de directorios (un elemento básico de la mayoría de los archivos AGENTS.md) no ayudaban a los agentes a navegar más rápido. Los agentes son sorprendentemente buenos descubriendo estructuras de archivos por sí solos; leer un listado manual solo consume tokens de razonamiento y agrega una sobrecarga “mental”. Además, los archivos generados por LLM suelen ser redundantes si ya tiene documentación decente en otra parte del repositorio.
Las nuevas reglas de la ingeniería contextual
Para que los archivos contextuales sean realmente útiles, es necesario pasar de la “documentación completa” a la “intervención quirúrgica”.
1. Qué incluir (los ‘pocos vitales’)
La pila técnica y la intención: explique el “qué” y el “por qué”. Ayude al agente a comprender el propósito del proyecto y su arquitectura (por ejemplo, una estructura monorepo). Herramientas no obvias: aquí es donde brilla AGENTS.md. Especifique cómo crear, probar y verificar cambios utilizando herramientas específicas como uv en lugar de pip o bun en lugar de npm. El efecto multiplicador: los datos muestran que se siguen las instrucciones; Las herramientas mencionadas en un archivo de contexto se utilizan con mucha más frecuencia. Por ejemplo, la herramienta uv se usó 160 veces más frecuentemente (1,6 veces por instancia frente a 0,01) cuando se mencionó explícitamente.+1
2. Qué excluir (el ‘ruido’)
Árboles de directorios detallados: omítelos. Los agentes pueden encontrar los archivos que necesitan sin un mapa. Guías de estilo: no desperdicies tokens diciéndole a un agente que “use camelCase”. En su lugar, utilice linters y formateadores deterministas: son más baratos, más rápidos y más confiables. Instrucciones específicas para cada tarea: evite reglas que solo se aplican a una fracción de sus problemas. Contenido automático no examinado: no permita que un agente escriba su propio archivo contextual sin una revisión humana. El estudio demuestra que los modelos “más fuertes” no necesariamente son mejores guías.
3. Cómo estructurarlo
Manténgalo ajustado: el consenso general para archivos contextuales de alto rendimiento es inferior a 300 líneas. Los equipos profesionales suelen mantener las suyas aún más ajustadas: menos de 60 líneas. Cada línea cuenta porque cada línea se inyecta en cada sesión. Divulgación progresiva: no coloque todo en el archivo raíz. Utilice el archivo principal para señalar al agente documentación separada y específica de la tarea (por ejemplo, agent_docs/testing.md) solo cuando sea relevante. Punteros sobre copias: en lugar de incrustar fragmentos de código que eventualmente quedarán obsoletos, utilice punteros (por ejemplo, archivo:línea) para mostrarle al agente dónde encontrar patrones de diseño o interfaces específicas.
Conclusiones clave
Impacto negativo de la generación automática: los archivos de contexto generados por LLM tienden a reducir las tasas de éxito de las tareas en aproximadamente un 3 % en promedio en comparación con no proporcionar ningún contexto de repositorio. Aumentos significativos de costos: la inclusión de archivos de contexto aumenta los costos de inferencia en más de un 20 % y genera una mayor cantidad de pasos necesarios para que los agentes completen las tareas. Beneficio humano mínimo: si bien los archivos contextuales escritos por humanos (proporcionados por el desarrollador) funcionan mejor que los generados automáticamente, solo ofrecen una mejora marginal de aproximadamente el 4 % en comparación con el uso de archivos sin contexto. Redundancia y navegación: las descripciones detalladas de la base de código en archivos contextuales son en gran medida redundantes con la documentación existente y no ayudan a los agentes a encontrar archivos relevantes más rápido. Seguimiento estricto de instrucciones: los agentes generalmente respetan las instrucciones de estos archivos, pero los requisitos innecesarios o demasiado restrictivos a menudo dificultan la resolución de tareas del mundo real para el modelo.
Consulte el documento. Además, no dude en seguirnos en Twitter y no olvide unirse a nuestro SubReddit de más de 120.000 ML y suscribirse a nuestro boletín. ¡Esperar! estas en telegrama? Ahora también puedes unirte a nosotros en Telegram.