🤖 machine learning

Probe-and-Refine Tuning of Repository Guidance for Coding Agents

Este artículo introduce el "ajuste de sondeo y refinamiento" (probe-and-refine tuning), un método que optimiza iterativamente los archivos de guía del repositorio (AGENTS.md) utilizando sondas sintéticas de corrección de errores para mejorar significativamente el rendimiento de los agentes de codificación en SWE-bench Verified mediante la expansión de la cobertura de parches evaluables en lugar de aumentar la precisión por parche.

Autores originales: Asa Shepard, Jeannie Albrecht

Publicado 2026-06-19

📖 5 min de lectura🧠 Análisis profundo

CC BY 4.0

Autores originales: Asa Shepard, Jeannie Albrecht

Artículo original bajo licencia CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Esta es una explicación generada por IA del artículo a continuación. No ha sido escrita ni avalada por los autores. Para mayor precisión técnica, consulte el artículo original. Leer descargo de responsabilidad completo

Imagina que contratas a un aprendiz brillante pero inexperto para arreglar una biblioteca masiva y antigua (el repositorio de código). El aprendiz es lo suficientemente inteligente como para leer libros y reparar páginas rotas, pero no conoce las reglas secretas de la biblioteca: qué estante contiene los mapas raros, cómo pedir ayuda al bibliotecario sin despertar a los gatos que duermen, o qué escaleras son seguras para subir.

Sin este "conocimiento local", el aprendiz deambula sin rumbo, sube la escalera equivocada o intenta reparar un libro en la sección incorrecta, rompiendo cosas en el proceso.

Este artículo presenta un método llamado "Probe-and-Refine Tuning" (Ajuste de Sondeo y Refinamiento) para resolver este problema. Así es como funciona, utilizando analogías sencillas:

El Problema: El Manual de "Talla Única"

Los ingenieros suelen escribir una "hoja de trucos" (como un archivo AGENTS.md) para sus agentes de codificación de IA.

La Forma Antigua (Conocimiento Estático): Le piden a una IA inteligente que escriba un manual genérico: "Siempre revise el índice antes de reparar" o "Busque el punto de entrada principal". Esto es como darle al aprendiz un mapa de todas las bibliotecas del mundo. Es útil, pero no le dice dónde está escondido el tesoro específico de esta biblioteca.
El Resultado: El aprendiz se desenvuelve bien, pero aun así se pierde con frecuencia.

La Solución: El Entrenador de "Ensayo y Error"

Los autores crearon un nuevo proceso llamado Probe-and-Refine. En lugar de simplemente escribir un manual una vez, tratan el manual como un documento vivo que se entrena cometiendo errores.

Piénsalo como un entrenador entrenando a un nuevo jugador:

Los Sondas (Los Simulacros): El entrenador genera 10 problemas falsos, inventados, específicos para esta biblioteca (probes).
El Intento: El aprendiz intenta resolver estos problemas falsos usando el manual actual.
El Diagnóstico: El entrenador observa el intento. "Oh, intentaste reparar la plomería en la cocina, pero las tuberías están en realidad en el sótano. Y olvidaste revisar los planos primero".
El Refinamiento: El entrenador actualiza el manual inmediatamente con una regla específica: "Para esta biblioteca, la plomería está en el sótano, y siempre revisa los planos primero".
Repetir: Hacen esto de 3 a 5 veces. El manual evoluciona de una guía genérica a una guía de "insider" hiperespecífica.

Crucialmente, todo este proceso de entrenamiento ocurre sin que el agente realmente arregle errores reales. Es un bucle de simulación donde la IA escribe el manual, lo prueba con problemas falsos y corrige el manual basándose en los resultados.

Lo que Encontraron

Los investigadores probaron esto en un famoso benchmark de codificación (SWE-bench) con cuatro ejecuciones diferentes. Esto fue lo que sucedió:

Sin Guía: El aprendiz resolvió el 25.5% de los problemas.
Guía Genérica: El aprendiz resolvió el 28.3% de los problemas.
Guía Probe-and-Refine: El aprendiz resolvió el 33.0% de los problemas.

El Gran Secreto: Se Trata de Encontrar la Puerta Correcta, No de Reparar Mejor
Podrías pensar que el manual mejorado hizo al aprendiz más inteligente o mejor para reparar cosas. No fue así.

Cuando el aprendiz sí reparó algo, la calidad de la reparación fue exactamente la misma (aproximadamente un 59% de tasa de éxito) independientemente de qué manual usara.
La verdadera magia fue la "Cobertura". El manual mejorado ayudó al aprendiz a encontrar el archivo correcto para reparar con mucha más frecuencia.
- Analogía: El manual genérico hizo que el aprendiz llamara a 100 puertas, pero solo 40 eran las correctas. El manual refinado hizo que llamara a 100 puertas, y 56 de ellas eran las correctas. Una vez que encontraba la puerta correcta, su capacidad para arreglar la cerradura era la misma.

La Trampa del "Presupuesto de Pasos"

El artículo también descubrió que la guía solo funciona si le das al aprendiz suficiente tiempo.

Si le das al aprendiz solo 25 pasos para resolver un problema, el manual sofisticado no ayuda. No tiene tiempo para seguir las instrucciones complejas.
Si le das 200 pasos, el manual sofisticado brilla. Les indica un flujo de trabajo (Reproducir -> Rastrear -> Reparar) que toma tiempo pero funciona. Sin el manual, simplemente se apresuran y fallan.
Analogía: Si le dices a alguien: "Toma una ruta escénica para evitar el tráfico", pero solo le das 5 minutos para llegar al trabajo, simplemente se perderá. Necesitas darle tiempo suficiente para que realmente pueda tomar la ruta escénica.

La Advertencia de "Desajuste de Modelo"

El hallazgo más sorprendente fue que esta guía no es universal.

Intentaron usar la guía entrenada en un modelo de IA (Qwen) con un modelo diferente y ligeramente más débil (Nemotron).
Resultado: El segundo modelo colapsó. Se confundió tanto con las instrucciones específicas que dejó de funcionar por completo.
Analogía: Es como darle un manual de carreras de alta velocidad detallado a un conductor en un sedán viejo y lento. Las instrucciones son demasiado complejas para el coche, y el conductor se queda paralizado. La guía debe ser "ajustada" específicamente para el cerebro (modelo) que la leerá.

Resumen

Este artículo demuestra que cómo escribes las instrucciones importa más que el simple hecho de tener instrucciones.
Al usar un bucle simple de "crear un problema falso, intentar resolverlo y corregir las instrucciones basándose en el fallo", puedes convertir una guía genérica en un manual de experto especializado. Esto no hace que la IA sea más inteligente para reparar código; simplemente evita que busque en el lugar equivocado, permitiéndole usar todo su potencial para resolver más problemas.

Resumen Técnico: Ajuste de Sonda y Refinamiento del Guía de Repositorio para Agentes de Programación

Declaración del Problema

Los agentes de programación basados en LLM a menudo fallan al resolver tareas de ingeniería de software no debido a una falta de capacidad de razonamiento, sino porque carecen de conocimiento operativo de alto nivel sobre un repositorio de código específico. Este conocimiento implícito —como los límites de los subsistemas, los flujos de trabajo de ejecución de pruebas, los patrones históricos de depuración— rara vez está documentado en el propio código. Mientras que los ingenieros mantienen archivos de contexto (por ejemplo, AGENTS.md) para suministrar esta información, la literatura reciente presenta evidencia contradictoria sobre su eficacia: algunos estudios sugieren que mejoran la eficiencia, mientras que otros indican que pueden reducir las tasas de resolución si la guía es genérica o contraproducente. El problema central es que no está claro si el fallo reside en el concepto de la guía en sí o en cómo se produce dicha guía. Los métodos actuales suelen depender de la generación de un solo paso por parte del LLM, lo que produce consejos genéricos en lugar de las estrategias operativas específicas e informadas por fallos que los agentes requieren.

Metodología

El artículo introduce el Ajuste de Sonda y Refinamiento (Probe-and-Refine Tuning), un procedimiento ligero diseñado para diagnosticar y parchear iterativamente el archivo de guía de un repositorio mediante el uso de sondas sintéticas de corrección de errores. El procedimiento se distingue de los bucles de agentes estándar ya que depende enteramente de llamadas de LLM de un solo paso (single-shot) sin uso de herramientas ni aprendizaje por refuerzo durante la fase de ajuste.

El Bucle de Ajuste

El proceso transforma una base de conocimientos estática y genérica en una guía operativa especializada a través de 3 a 5 iteraciones:

Generar Sondas: El sistema genera un lote de 10 tareas sintéticas de corrección de errores a partir del código fuente del repositorio, apuntando a diversos subsistemas.
Intentar Corrección: Para cada sonda, una llamada de un solo paso al LLM intenta generar un parche utilizando el artefacto de guía actual.
Juzgar Intento: Una llamada separada de un solo paso evalúa la solución intentada frente a los comportos esperados (por ejemplo, correcciones sólidas, parciales o ausentes) y propone ediciones específicas a la guía donde se identifican deficiencias.
Agregar y Aplicar: Una llamada final agrega los diagnósticos de todas las sondas y propone un conjunto consolidado de ediciones. Estas ediciones se aplican mecánicamente (insertando, modificando o fortaleciendo secciones) al archivo de guía, con un límite de 3,000 caracteres.

El bucle termina prematuramente si la guía se estabiliza (sin cambios entre iteraciones consecutivas). El artefacto resultante se utiliza luego para guiar a un agente de programación estándar de tipo ReAct durante la fase de evaluación en SWE-bench Verified.

Configuración Experimental

Los autores evaluaron tres condiciones en 500 instancias de SWE-bench Verified a través de cuatro ensayos independientes utilizando el modelo Qwen3.5-35B-A3B:

Sin Contexto: El agente opera sin guía específica del repositorio.
KB Estática: El agente utiliza una base de conocimientos de dos capas que contiene datos estructurales (analizados mediante tree-sitter) y mejores prácticas genéricas y ajenas al repositorio.
Sonda y Refinamiento: El agente utiliza la guía producida por el procedimiento de ajuste iterativo descrito anteriormente.

Un experimento secundario sustituyó el modelo por NVIDIA-Nemotron-3-Nano-30B-A3B para probar la generalización entre modelos, y se realizó un barrido de presupuesto de pasos (25, 50, 100, 200 pasos) para analizar la interacción entre la guía y el presupuesto del agente.

Resultados Clave

Ganancias de Rendimiento

A través de cuatro ensayos, Sonda y Refinamiento logró una tasa media de resolución del 33.0%, superando significativamente a la KB Estática (28.3%) y a la línea base de Sin Contexto (25.5%). La mejora fue estadísticamente significativa ( $p < 0.001$ ) para ambos contrastes. El procedimiento también produjo 31 soluciones consistentemente únicas (resueltas en $\ge$ 3 de 4 ensayos) que ninguna de las otras condiciones pudo resolver.

Mecanismo: Cobertura vs. Precisión

El artículo descompone la ganancia de rendimiento para determinar cómo ayuda la guía:

Cobertura: El principal motor de la mejora es la cobertura de evaluación. La guía de Sonda y Refinamiento permitió al agente producir parches bien formados y evaluables para el 56.2% de las instancias, en comparación con el 41.7% de la línea base sin guía (una brecha de 14.5 puntos porcentuales).
Precisión: La corrección de los parches, condicional a que sean evaluables, se mantuvo estadísticamente constante en todas las condiciones ( $\sim$ 59%, $p = 0.119$ ).
Conclusión: La guía no mejora la calidad de los cambios de código que realiza el agente; más bien, ayuda al agente a llegar al archivo correcto y producir un parche que el entorno de evaluación pueda aceptar. La guía reduce eficazmente la tasa de parches malformados o parches que provocan el fallo de la suite de pruebas antes de que las aserciones puedan ser verificadas.

Presupuesto de Pasos y Flujo de Trabajo

El estudio encontró que la guía actúa como un moderador de la utilidad del presupuesto de pasos.

Agentes sin guía: Se saturan rápidamente; aumentar el presupuesto de pasos de 25 a 200 pasos no mejoró su tasa de resolución, ya que carecen de un plan estructurado para convertir pasos adicionales en mejores parches.
Agentes de Sonda y Refinamiento: Utilizan presupuestos mayores de forma productiva. El flujo de trabajo prescrito de "reproducir-rastrear-parchear" requiere más pasos para completarse. En consecuencia, la condición de sonda y refinamiento mostró ganancias significativas en presupuestos más altos (100 y 200 pasos) donde la guía simple (KB Estática) se estancó.

Generalización entre Modelos

Al aplicarse al modelo Nemotron, los resultados destacaron una dependencia de ajuste del modelo:

Fallo de Ajuste: El bucle de ajuste se degradó en Nemotron porque el modelo no pudo generar una salida suficientemente diagnóstica para el paso de "Juez", causando que el bucle se estancara.
Transferencia Negativa: La guía ajustada en Qwen, al aplicarse a Nemotron, colapsó activamente el rendimiento del agente (13.2% de tasa de resolución frente al 27.0% de la propia línea base de Nemotron). La guía detallada y prescriptiva causó que Nemotron incurriera en "cumplimiento por análisis" (escribir prosa sobre lo que haría) en lugar de ejecutar comandos, desencadenando una cascada de fallos de respaldo.
Constancia de la Precisión: Incluso en el colapso entre modelos, la precisión de los pocos parches que sí se produjeron se mantuvo constante, reforzando que el fallo fue enteramente en la cobertura (el agente fallando en producir un parche), no en la calidad del parche en sí.

Significado y Reivindicaciones

El artículo afirma que la calidad de la instrucción es una variable de primer orden en la fiabilidad de los agentes de programación, comparable en magnitud a la capacidad del modelo o a las elecciones del presupuesto de pasos.

El Conocimiento Operativo es Aprendible: Los autores demuestran que el conocimiento operativo (qué archivos albergan qué subsistemas, cómo ejecutar pruebas) puede destilarse de fallos sintéticos en un artefacto de texto compacto sin bucles de agentes complejos o uso de herramientas.
El Cuello de Botella es la Guía, No el Razonamiento: Los resultados sugieren que para muchos casos "difíciles", el fallo del agente no es una falta de poder de razonamiento, sino un fallo al localizar el problema en el archivo correcto. La guía actúa como un auxilio de localización, permitiendo al agente navegar la estructura del repositorio de manera efectiva.
Calibración Específica del Modelo: La guía no es conocimiento transferible del repositorio; es una calibración de comportamiento específica del modelo. La guía ajustada para los modos de fallo de un modelo puede dañar activamente a un modelo diferente con un perfil de comportamiento distinto.
Reconciliación de Discrepancias Previas: El artículo reconcilia la literatura contradictoria sobre los archivos AGENTS.md al mostrar que la eficacia de la guía depende de cómo se produce (refinamiento iterativo vs. generación de un solo paso) y del presupuesto de pasos disponible. La guía estática y genérica puede ser neutra o perjudicial, mientras que la guía de flujo de trabajo iterativamente refinada es beneficiosa, siempre que el presupuesto permita completar el flujo de trabajo.

Los autores concluyen que, para los profesionales, invertir en una guía refinada iterativamente es valioso para repositorios con altos volúmenes de problemas, siempre que la guía se ajuste al modelo específico que la consumirá y el presupuesto de pasos sea suficiente para acomodar el flujo de trabajo prescrito.