Resumen Técnico: Harness Handbook

Planteamiento del Problema

La evolución de los sistemas modernos de agentes de IA está cada vez más limitada por la dificultad de la localización de comportamiento dentro de los arneses (harnesses) de escala de producción. Un arnés es la capa de software que construye los prompts, gestiona el estado, invoca herramientas y coordina la ejecución, traduciendo efectivamente las capacidades del modelo fundacional en un comportamiento del sistema. A medida que los requisitos cambian, los desarrolladores o los agentes de codificación deben modificar estos arneses. Sin embargo, identificar todos los lugares del código que implementan una solicitud de comportamiento específica es notoriamente difícil debido a:

1. Complejidad Estructural: Los comportamientos suelen estar distribuidos en archivos no adyacentes, funciones, etapas de ejecución y transiciones de estado compartido.
2. Desajuste de Representación: Las solicitudes de modificación describen qué debe hacer el sistema (comportamiento), mientras que los repositorios se organizan según cómo está estructurado el código (archivos, módulos, funciones).
3. Limitaciones de las Herramientas Existentes: Los enfoques actuales (búsqueda de código, indexación de repositorios, procesamiento de contexto largo) organizan la información en torno a artefactos de implementación. Ayudan a localizar fragmentos de código individuales, pero no logran mapear explícitamente cómo piezas dispersas trabajan juntas para producir un comportamiento específico, dejando que el agente o el desarrollador infiera estas conexiones manualmente.

Esta brecha obliga a los desarrolladores a construir modelos mentales del sistema y a los agentes a explorar repositorios de forma iterativa, perdiendo a menudo rutas de código dispersas o ejecutadas raramente.

Metodología

El artículo introduce Harness Handbook, una representación centrada en el comportamiento sintetizada automáticamente a partir de un código base de un arnés, y Behavior-Guided Progressive Disclosure (BGPD), un flujo de trabajo para utilizar esta representación.

1. Representación Harness Handbook

El Handbook reorganiza el conocimiento de implementación en torno al comportamiento en tiempo de ejecución en lugar de la estructura de archivos. Consta de dos vistas complementarias:

• Árbol de Documentos ($D$): Una jerarquía de tres niveles (L1–L3) que progresa desde visiones generales del sistema de alto nivel hasta unidades detalladas fundamentadas en el código fuente.
  • L1 (Visión General del Sistema): Arquitectura, modelo de ejecución, etapas principales y flujo de datos global.
  • L2 (Visión General del Componente): Responsabilidades, entradas/salidas, dependencias y estado local para etapas de ejecución específicas.
  • L3 (Inmersión Profunda en la Unidad): Entradas de implementación fundamentadas en el código (funciones o archivos) vinculadas a ubicaciones de código específicas.
• Vista del Registro de Estado ($Z$): Una vista transversal de las etapas que rastrea las relaciones de estado que cruzan los límites de las etapas, asegurando que se capturen los comportamientos que dependen de estados compartidos, incluso si están estructuralmente distantes.

La representación se adhiere a dos reglas:

• Divulgación Progresiva: Los lectores se mueven de L1 a L3 solo cuando una tarea requiere más detalle.
• Alineación Comportamiento–Implementación: Cada localizador L3 activo debe resolverse con el repositorio de código fuente actual. Si un localizador no puede ser revalidado, se congela para evitar alucinaciones.

2. Pipeline de Construcción

El Handbook se construye automáticamente a partir de un repositorio ($R$) mediante tres fases:

• Fase I: Extracción de Hechos Estáticos: El análisis determinista extrae funciones, grafos de llamadas y accesos al estado. Las llamadas no resueltas se registran en lugar de suponerse.
• Fase II: Organización del Comportamiento: Las unidades de código se mapean a un esqueleto de etapa de ejecución ($S$). El pipeline soporta dos modos de hoja:
  • Función como hoja: Parte de un esqueleto semilla y asigna funciones (o regiones contiguas) a las etapas.
  • Archivo como hoja: Infiere el esqueleto de las etapas a partir de resúmenes de archivos y organiza los archivos en consecuencia.
• Fase III: Síntesis Jerárquica: Convierte la organización en el árbol de documentos L1–L3 y la vista del registro de estado, validando todos los localizadores contra el código fuente.

3. Flujo de Trabajo de Modificación (BGPD)

El flujo de trabajo para modificar un arnés utilizando el Handbook implica cuatro pasos:

1. Localización: El agente utiliza BGPD para navegar por el Handbook desde una granularidad gruesa (L1/L2) hasta una fina (L3). Identifica etapas relevantes y registros de estado, expande el conjunto de candidatos mediante grafos de llamadas y luego verifica estos candidatos contra el repositorio de código actual para producir evidencia verificada ($bEq$).
2. Planificación: Un planificador convierte $bEq$ en un plan de edición ($P$) y declaraciones de acción ($\Gamma$).
3. Ejecución: Un ejecutor aplica el plan al repositorio.
4. Resincronización: Cualquier diff no vacío dispara una resincronización automática del Handbook. El sistema actualiza solo las partes afectadas (usando huellas digitales o hashes de contenido) en lugar de reconstruir todo el Handbook, asegurando que la representación se mantenga consistente con el código base en evolución.

Contribuciones Clave

1. Definición de Localización de Comportamiento: El artículo define formalmente la localización de comportamiento como el paso previo necesario de encontrar todas las ubicaciones de código que implementan una solicitud de comportamiento antes de que se pueda planificar una edición.
2. Harness Handbook: Una representación novedosa, generada automáticamente, que vincula descripciones de comportamiento directamente con implementaciones de código fuente distribuidas, organizada por "qué hace el arnés" en lugar de la estructura de archivos.
3. Flujo de Trabajo BGPD: Un método para guiar a los agentes de codificación desde descripciones de comportamiento de alto nivel hacia detalles de implementación relevantes en etapas, verificando los candidatos contra el código fuente vivo.
4. Validación Empírica: Evaluación en dos arneses de código abierto (Terminus-2 y Codex) que demuestra que la planificación asistida por el Handbook mejora la precisión de la localización y la calidad del plan de edición, reduciendo al mismo tiempo el uso de tokens.

Resultados Experimentales

Los autores evaluaron el enfoque en 60 solicitudes de modificación (30 por cada arnés) a través de tres tipos: Consulta (Query, modificando el comportamiento existente), Transversal de Archivos (Cross-file, añadiendo capacidades que abarcan módulos) y Hostil a la Búsqueda (Search-Hostile, ocultando implementaciones en rutas difíciles de encontrar).

• Calidad del Plan y Costo: La planificación asistida por el Handbook logró tasas de éxito significativamente mayores en la calidad del plan (por ejemplo, +18.9% en Terminus-2) en comparación con un baseline que explora el repositorio directamente. Crucialmente, esta mejora se logró con menos tokens del planificador (reducciones de 12.7% y 8.6% en Codex y Terminus-2, respectivamente), lo que indica mayor eficiencia en lugar de simplemente un mayor presupuesto.
• Precisión de Localización: Un planificador más débil (DeepSeek-V4-Pro) asistido por el Handbook igualó la localización de sitios de implementación de modelos sustancialmente más fuertes (Opus 4.8, GPT-5.5). Las puntuaciones F1 para la localización a nivel de archivo y de símbolo mejoraron entre 5.0 y 18.8 puntos en todas las comparaciones. La métrica "Incorrecto" (Wrong, cero solapamiento con la referencia) disminuyó significamente, indicando menos fallos totales.
• Robustez: Las ganancias persistieron en todos los tipos de solicitud (Consulta, Transversal de Archivos, Hostil a la Búsqueda) y niveles de dificultad (Fácil, Medio, Difícil). Las mejoras más significativas se observaron en cambios que involucraban sitios de implementación dispersos e interacciones entre módulos.

Significado y Reivindicaciones

El artículo sostiene que la evolución de sistemas de agentes complejos depende no solo de generar ediciones, sino de determinar dónde deben realizarse esas ediciones. Al hacer explícita la conexión entre el comportamiento y la implementación, Harness Handbook aborda el cuello de botella central de la localización de comportamiento.

Los autores posicionan este trabajo como un paso hacia la auto-evolución de los arneses. Sugieren que una representación de repositorio centrada en el comportamiento que se mantenga sincronizada con el código puede soportar usos más amplios como la auditoría de comportamiento y el análisis de impacto de regresión. El objetivo final es permitir que los agentes cierren autónomamente el ciclo de localización, planificación, ejecución y resincronización, moviendo los arneses de los agentes hacia la auto-mejora sin requerir presupuestos de tokens de planificación más grandes.