🤖 machine learning

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

Cet article introduit le « probe-and-refine tuning », une méthode qui optimise de manière itérative les fichiers de guidage du dépôt (AGENTS.md) à l'aide de sondes de correction de bogues synthétiques afin d'améliorer significativement les performances des agents de codage sur SWE-bench Verified en élargissant la couverture des correctifs évaluables plutôt qu'en augmentant la précision par correctif.

Auteurs originaux : Asa Shepard, Jeannie Albrecht

Publié 2026-06-19

📖 6 min de lecture🧠 Analyse approfondie

CC BY 4.0

Auteurs originaux : Asa Shepard, Jeannie Albrecht

Article original sous licence CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Ceci est une explication générée par l'IA de l'article ci-dessous. Elle n'a pas été rédigée ni approuvée par les auteurs. Pour une précision technique, consultez l'article original. Lire la clause de non-responsabilité complète

Imaginez que vous engagiez un apprenti brillant mais inexpérimenté pour réparer une immense bibliothèque ancienne (le dépôt de code). L'apprenti est assez intelligent pour lire des livres et réparer des pages déchirées, mais il ne connaît pas les règles secrètes de la bibliothèque : quel rayon contient les cartes rares, comment demander de l'aide au bibliothécaire sans réveiller les chats qui dorment, ou quelles échelles sont sûres à grimper.

Sans cette « connaissance locale », l'apprenti erre sans but, grimpe la mauvaise échelle ou tente de réparer un livre dans la mauvaise section, cassant souvent des choses au passage.

Ce document présente une méthode appelée « Probe-and-Refine Tuning » (Ajustement par Sondage et Affinement) pour résoudre ce problème. Voici comment cela fonctionne, en utilisant des analogies simples :

Le Problème : Le manuel « Taille Unique »

Les ingénieurs écrivent souvent une « fiche de triche » (comme un fichier AGENTS.md) pour leurs agents de codage IA.

L'ancienne méthode (Connaissance Statique) : Ils demandent à une IA intelligente d'écrire un manuel générique : « Vérifiez toujours l'index avant de réparer » ou « Cherchez le point d'entrée principal ». C'est comme donner à l'apprenti une carte de chaque bibliothèque du monde. C'est utile, mais cela ne lui dit pas où se cache le trésor spécifique de cette bibliothèque.
Le Résultat : L'apprenti s'en sort bien, mais il se perd encore souvent.

La Solution : Le coach par « Essai et Erreur »

Les auteurs ont créé un nouveau processus appelé Probe-and-Refine. Au lieu de simplement écrire un manuel une fois, ils traitent le manuel comme un document vivant qui est entraîné par ses propres erreurs.

Considérez cela comme un coach entraînant un nouveau joueur :

Les Sondes (Les exercices) : Le coach génère 10 problèmes fictifs, inventés, spécifiques à cette bibliothèque (les sondes).
La Tentative : L'apprenti essaie de résoudre ces faux problèmes en utilisant le manuel actuel.
Le Diagnostic : Le coach observe la tentative. « Oh, tu as essayé de réparer la plomberie dans la cuisine, mais les tuyaux sont en fait dans le sous-sol. Et tu as oublié de vérifier les plans d'abord. »
L'Affinement : Le coach met à jour le manuel immédiatement avec une règle spécifique : « Pour cette bibliothèque, la plomberie est au sous-sol, et vérifiez toujours les plans d'abord. »
Répétition : Ils font cela 3 à 5 fois. Le manuel évolue d'un guide générique vers un guide « d'initié » hyper-spécifique.

Crucialement, tout ce processus d'entraînement se déroule sans que l'agent n'ait réellement à réparer de vrais bugs. C'est une boucle de simulation où l'IA écrit le manuel, le teste sur de faux problèmes, et corrige le manuel en fonction des résultats.

Ce qu'ils ont découvert

Les chercheurs ont testé cela sur un célèbre benchmark de codage (SWE-bench) avec quatre passages différents. Voici ce qui s'est passé :

Sans guide : L'apprenti a résolu 25,5 % des problèmes.
Guide Générique : L'apprenti a résolu 28,3 % des problèmes.
Guide Probe-and-Refine : L'apprenti a résolu 33,0 % des problèmes.

Le Grand Secret : Il s'agit de trouver la bonne porte, pas de mieux réparer
Vous pourriez penser que le manuel amélioré a rendu l'apprenti plus intelligent ou meilleur pour réparer les choses. Ce n'est pas le cas.

Quand l'apprenti a réparé quelque chose, la qualité de la réparation était exactement la même (environ 59 % de taux de réussite) quel que soit le manuel utilisé.
La vraie magie était la « Couverture ». Le manuel amélioré a aidé l'apprenti à trouver le bon fichier à réparer beaucoup plus souvent.
- Analogie : Le manuel générique faisait frapper à 100 portes à l'apprenti, mais seulement 40 étaient les bonnes. Le manuel affiné faisait frapper à 100 portes, et 56 étaient les bonnes. Une fois qu'il trouvait la bonne porte, sa capacité à réparer la serrure était la même.

Le piège du « Budget d'Étapes »

Le papier a également découvert que le guide ne fonctionne que si vous donnez assez de temps à l'apprenti.

Si vous donnez à l'apprenti seulement 25 étapes pour résoudre un problème, le manuel sophistiqué n'aide pas. Il n'a pas le temps de suivre les instructions complexes.
Si vous lui donnez 200 étapes, le manuel sophistiqué brille. Il lui indique un flux de travail (Reproduire -> Tracer -> Réparer) qui prend du temps mais qui fonctionne. Sans le manuel, il se précipite et échoue.
Analogie : Si vous dites à quelqu'un : « Prenez un itinéraire pittoresque pour éviter les bouchons », mais que vous ne lui donnez que 5 minutes pour aller au travail, il va juste se perdre. Vous devez lui donner assez de temps pour réellement prendre l'itinéraire pittoresque.

L'avertissement sur le « Mismatch de Modèle »

La découverte la plus surprenante est que ce guide n'est pas universel.

Ils ont essayé d'utiliser le guide entraîné sur un modèle d'IA (Qwen) avec un autre modèle, légèrement plus faible (Nemotron).
Résultat : Le second modèle a planté. Il a été tellement confus par les instructions spécifiques qu'il a cessé de fonctionner entièrement.
Analogie : C'est comme donner un manuel de course automobile de haute vitesse à un conducteur d'une vieille berline lente. Les instructions sont trop complexes pour la voiture, et le conducteur se fige. Le guide doit être « ajusté » spécifiquement pour le cerveau (le modèle) qui va le lire.

Résumé

Ce papier prouve que la manière dont vous rédigez les instructions compte plus que le simple fait d'avoir des instructions.
En utilisant une simple boucle de « créer un faux problème, essayer de le résoudre, et corriger les instructions basées sur l'échec », vous pouvez transformer un guide générique en un manuel d'expert spécialisé. Cela ne rend pas l'IA plus intelligente pour réparer le code ; cela l'empêche simplement de chercher au mauvais endroit, lui permettant d'utiliser tout son potentiel pour résoudre plus de problèmes.

Résumé technique : Ajustement par sondage et raffinement de l'orientation des dépôts pour les agents de codage

Énoncé du problème

Les agents de codage basés sur les LLM échouent souvent à résoudre des tâches d'ingénierie logicielle non pas par manque de capacité de raisonnement, mais parce qu'ils manquent de connaissances opérationnelles de haut niveau sur un dépôt de code spécifique. Cette connaissance implicite — telle que les limites des sous-systèmes, les flux de travail d'exécution de tests, ou les schémas historiques de débogage — est rarement documentée dans le code lui-même. Bien que les ingénieurs maintiennent des fichiers de contexte (ex: AGENTS.md) pour fournir cette information, la littérature récente présente des preuves contradictoires sur leur efficacité : certaines études suggèrent qu'ils améliorent l'efficacité, tandis que d'autres indiquent qu'ils peuvent réduire les taux de résolution si l'orientation est générique ou contre-productive. Le problème central est qu'il reste difficile de déterminer si l'échec réside dans le concept même d'orientation ou dans la manière dont cette orientation est produite. Les méthodes actuelles reposent souvent sur une génération par LLM en un seul passage, ce qui produit des conseils génériques plutôt que les stratégies opérationnelles spécifiques et informées par les échecs requises par les agents.

Méthodologie

Le papier introduit l'Ajustement par Sondage et Raffinement (Probe-and-Refine Tuning), une procédure légère conçue pour diagnostiquer et corriger de manière itérative le fichier d'orientation d'un dépôt à l'aide de sondes de correction de bugs synthétiques. La procédure se distingue des boucles d'agents standards car elle repose entièrement sur des appels de LLM en un seul coup (single-shot), sans utilisation d'outils ni apprentissage par renforcement durant la phase d'ajustement.

La boucle d'ajustement

Le processus transforme une base de connaissances statique et générique en une orientation opérationnelle spécialisée à travers 3 à 5 itérations :

Générer des sondes : Le système génère un lot de 10 tâches de correction de bugs synthétiques à partir du code source du dépôt, ciblant divers sous-systèmes.
Tenter la correction : Pour chaque sonde, un appel de LLM en un seul coup tente de générer un correctif en utilisant l'artefact d'orientation actuel.
Juger la tentative : Un appel distinct en un seul coup évalue la solution tentée par rapport aux comportements attendus (ex: corrections fortes, partielles ou manquantes) et propose des modifications spécifiques à l'orientation là où des lacunes sont identifiées.
Aggréger et appliquer : Un appel final agrège les diagnostics de toutes les sondes et propose un ensemble consolidé de modifications. Ces modifications sont appliquées mécaniquement (insertion, modification ou renforcement de sections) au fichier d'orientation, avec un plafond de 3 000 caractères.

La boucle se termine prématurément si l'orientation se stabilise (aucun changement entre deux itérations consécutives). L'artefact résultant est ensuite utilisé pour guider un agent de codage standard de type ReAct lors de la phase d'évaluation sur SWE-bench Verified.

Configuration expérimentale

Les auteurs ont évalué trois conditions sur 500 instances de SWE-bench Verified à travers quatre essais indépendants en utilisant le modèle Qwen3.5-35B-A3B :

Sans contexte : L'agent opère sans orientation spécifique au dépôt.
Base de connaissances (KB) statique : L'agent utilise une base de connaissances à deux couches contenant des données structurelles (analysées via tree-sitter) et des meilleures pratiques génériques et agnostiques au dépôt.
Sondage et Raffinement : L'agent utilise l'orientation produite par la procédure d'ajustement itérative décrite ci-dessus.

Une expérience secondaire a substitué le modèle par NVIDIA-Nemotron-3-Nano-30B-A3B pour tester la généralisation inter-modèles, et un balayage du budget d'étapes (25, 50, 100, 200 étapes) a été effectué pour analyser l'interaction entre l'orientation et le budget de l'agent.

Résultats clés

Gains de performance

À travers quatre essais, le Sondage et Raffinement a atteint un taux de résolution moyen de 33,0 %, surpassant significativement la KB statique (28,3 %) et la ligne de base Sans Contexte (25,5 %). L'amélioration était statistiquement significative ( $p < 0,001$ ) pour les deux contrastes. La procédure a également produit 31 résolutions systématiquement uniques (résolues dans $\ge$ 3 des 4 essais) que l'une ou l'autre des autres conditions n'a pas pu résoudre.

Mécanisme : Couverture vs Précision

Le papier décompose le gain de performance pour déterminer comment l'orientation aide :

Couverture : Le principal moteur de l'amélioration est la couverture d'évaluation. L'orientation par Sondage et Raffinement a permis à l'agent de produire des correctifs bien formés et évaluables pour 56,2 % des instances, contre 41,7 % pour la ligne de base non guidée (un écart de 14,5 points de pourcentage).
Précision : La justesse des correctifs, sous réserve qu'ils soient évaluables, est restée statistiquement constante à travers toutes les conditions ( $\sim$ 59 %, $p = 0,119$ ).
Conclusion : L'orientation n'améliore pas la qualité des changements de code effectués par l'agent ; elle aide plutôt l'agent à atteindre le bon fichier et à produire un correctif que le banc d'essai peut accepter. L'orientation réduit efficacement le taux de correctifs malformés ou de correctifs qui font planter la suite de tests avant que les assertions ne puissent être vérifiées.

Budget d'étapes et flux de travail

L'étude a révélé que l'orientation agit comme un modérateur pour l'utilité du budget d'étapes.

Les agents non guidés saturent rapidement ; augmenter le budget d'étapes de 25 à 200 étapes n'a pas amélioré leur taux de résolution, car ils manquent d'un plan structuré pour convertir les étapes supplémentaires en meilleurs correctifs.
Les agents de Sondage et Raffinement utilisent les budgets plus larges de manière productive. Le flux de travail prescrit "reproduire-tracer-corriger" nécessite plus d'étapes pour s'achever. Par conséquent, la condition de sondage et raffinement a montré des gains significatifs à des budgets plus élevés (100 et 200 étapes) là où l'orientation plus simple (KB statique) plafonnait.

Généralisation inter-modèles

Lorsqu'elle a été appliquée au modèle Nemotron, les résultats ont mis en évidence une dépendance critique à l'adéquation du modèle :

Échec de l'ajustement : La boucle d'ajustement s'est dégradée sur Nemotron car le modèle ne pouvait pas générer de sortie suffisamment diagnostique pour l'étape du "Juge", provoquant un blocage de la boucle.
Transfert négatif : L'orientation ajustée sur Qwen, lorsqu'appliquée à Nemotron, a activement provoqué l'effondrement de la performance de l'agent (taux de résolution de 13,2 % contre 27,0 % pour la propre ligne de base de Nemotron). L'orientation détaillée et prescriptive a poussé Nemotron à s'engager dans une "conformité par analyse" (écrire de la prose sur ce qu'il ferait) plutôt qu'à exécuter des commandes, déclenchant une cascade d'échecs de repli.
Constance de la précision : Même dans l'effondrement inter-modèles, la précision des rares correctifs qui ont été produits est restée constante, renforçant l'idée que l'échec concernait entièrement la couverture (l'agent échouant à produire un correctif), et non la qualité du correctif lui-même.

Signification et affirmations

Le papier affirme que la qualité de l'instruction est une variable de premier ordre dans la fiabilité des agents de codage, comparable en magnitude à la capacité du modèle ou aux choix de budget d'étapes.

La connaissance opérationnelle est apprenable : Les auteurs démontrent que la connaissance opérationnelle (quels fichiers abritent quels sous-systèmes, comment exécuter les tests) peut être distillée à partir d'échecs synthétiques en un artefact textuel compact sans boucles d'agents complexes ou utilisation d'outils.
Le goulot d'étranglement est l'orientation, pas le raisonnement : Les résultats suggèrent que pour beaucoup d'instances "difficiles", l'échec de l'agent n'est pas un manque de puissance de raisonnement, mais un échec de localisation du problème dans le bon fichier. L'orientation agit comme une aide à la localisation, permettant à l'agent de naviguer efficacement dans la structure du dépôt.
Calibration spécifique au modèle : L'orientation n'est pas une connaissance de dépôt transférable ; c'est une calibration comportementale spécifique au modèle. Une orientation ajustée pour les modes de défaillance d'un modèle peut activement nuire à un autre modèle ayant un profil de comportement différent.
Réconciliation des désaccords antérieurs : Le papier réconcilie les contradictions de la littérature sur les fichiers AGENTS.md en montrant que l'efficacité de l'orientation dépend de la manière dont elle est produite (raffinement itératif vs génération en un seul passage) et du budget d'étapes disponible. Une orientation statique et générique peut être neutre ou nuisible, tandis qu'une orientation spécifique au flux de travail et raffinée de manière itérative est bénéfique, à condition que le budget permette de compléter le flux de travail.

Les auteurs concluent que pour les praticiens, investir dans une orientation raffinée de manière itérative est précieux pour les dépôts ayant des volumes d'incidents élevés, à condition que l'orientation soit ajustée sur le modèle spécifique qui la consommera et que le budget d'étapes soit suffisant pour accommoder le flux de travail prescrit.