🤖 AI

Exploration Structure in LLM Agents for Multi-File Change Localization

Questo articolo propone e valuta un framework di esplorazione agentica parallela non lineare e con ambito limitato al dominio per la localizzazione di modifiche multi-file nei repository software, dimostrando che supera significativamente gli approcci sequenziali lineari e ottiene risultati competitivi rispetto a modelli molto più grandi su benchmark come SWE-Bench Pro.

Autori originali: Akeela Darryl Fattha, Kia Ying Chua, Lingxiao Jiang, Laura Wynter

Pubblicato 2026-06-11

📖 5 min di lettura🧠 Approfondimento

CC BY 4.0

Autori originali: Akeela Darryl Fattha, Kia Ying Chua, Lingxiao Jiang, Laura Wynter

Articolo originale sotto licenza CC BY 4.0 (http://creativecommons.org/licenses/by/4.0/). ✨ Questa è una spiegazione generata dall'IA dell'articolo qui sotto. Non è stata scritta né approvata dagli autori. Per precisione tecnica, consulta l'articolo originale. Leggi il disclaimer completo

Immagina di essere un detective che cerca di riparare una macchina guasta. La macchina è un enorme progetto software (come una gigantesca biblioteca di codice), e qualcuno ha segnalato un bug. Il tuo compito è trovare esattamente quali pagine della biblioteca devono essere riscritte per risolvere il problema.

Questo articolo parla di come diversi "detective AI" affrontano la ricerca di quelle pagine. I ricercatori volevano vedere se il modo in cui il detective cerca conta più di quanto sia "intelligente" il detective stesso.

Ecco la suddivisione del loro studio utilizzando semplici analogie:

Il Problema: La trappola del "un passo alla volta"

La maggior parte degli strumenti AI attuali agisce come un detective che attraversa una biblioteca un corridoio alla volta. Sceglie uno scaffale, legge un libro, poi si sposta allo scaffale successivo.

Il Difetto: Se il bug è in realtà un mix di problemi in tre ali diverse della biblioteca (ad esempio, la cucina, il giardino e la soffitta), un detective che percorre solo un corridoio alla volta potrebbe incastrarsi in cucina, esaurire il tempo (o il denaro) e non controllare mai il giardino o la soffitta.
L'Idea dell'Articolo: E se, invece di camminare, inviassimo tre diversi specialisti a controllare la cucina, il giardino e la soffitta contemporaneamente?

L'Esperimento: La biblioteca "Ansible"

I ricercatori hanno testato questo su un progetto software specifico chiamato Ansible (pensa a una biblioteca molto grande e organizzata). Hanno creato un test in cui fornivano all'AI un rapporto sul bug e chiedevano di elencare i file che dovevano essere corretti.

Hanno confrontato quattro tipi di detective:

Il "Lettore Accanito" (LLM base): Un'IA intelligente che ha letto molti libri ma non è mai stata dentro questa specifica biblioteca. Deve indovinare basandosi sulla memoria.
L' "Esploratore Solitario" (RLM): Un'IA a cui viene data una chiave della biblioteca e un taccuino. Entra, apre porte e legge i file uno alla volta, prendendo appunti mentre procede.
Il "Team di Specialisti" (Agenti di Dominio - La Nuova Idea): Un manager AI che prima mappa le sezioni della biblioteca (Cucina, Giardino, Soffitta). Quando arriva un bug, il manager invia istantaneamente uno specialista diverso in ogni sezione pertinente per lavorare in parallelo.
Il "Super-Esperto" (Codex): Un'IA detective molto grande, costosa e potente utilizzata come termine di paragone.

Le Grandi Scoperte

1. Il lavoro di squadra batte l'esplorazione solitaria
L'approccio "Team di Specialisti" ha vinto con un margine enorme, anche se utilizzava un modello AI più piccolo e meno costoso.

Analogia: Immagina di cercare una chiave smarrita in uno stadio. L' "Esploratore Solitario" percorre tutto lo stadio da solo e si stanca. Il "Team" invia persone tra gli spalti, sul campo e ai chioschi, simultaneamente. Trovano la chiave molto più velocemente e con maggiore precisione.
Risultato: L'approccio del team ha trovato i file corretti molto meglio del camminatore solitario, anche quando il camminatore solitario aveva un "cervello" più grande (un modello AI più potente).

2. Dare una chiave a un detective può ritorcersi contro
I ricercatori pensavano che dare all'AI l'accesso diretto al sistema dei file (l' "Esploratore Solitario" con una chiave) avrebbe aiutato. Sorprendentemente, spesso ha reso le cose peggiori.

Analogia: Se dai a un detective la chiave di un enorme magazzino, potrebbe distrarsi guardando migliaia di scatole irrilevanti (come file di test o vecchie bozze) e dimenticare di cercare la parte effettivamente rotta. Viene sopraffatto dal "rumore".
Risultato: L'AI con accesso diretto spesso ha indovinato troppi file errati, abbassando la sua precisione. L'approccio del "Team" è stato più intelligente perché sapeva esattamente quali sezioni guardare e ha ignorato la spazzatura.

3. Più agenti non sempre significano risultati migliori
Hanno provato a forzare il team a consultare più specialisti del necessario, solo per sicurezza.

Analogia: È come chiamare l'intero corpo dei vigili del fuoco per spegnere una piccola candela. Non spegne il fuoco più velocemente; crea solo molti più costi (token di calcolo) e molta confusione.
Risultato: Essere "aggressivi" nel chiamare più agenti non ha aiutato a trovare il bug; ha solo sprecato risorse.

4. Il "Punto Cieco della Documentazione"
Indipendentemente da quanto fosse intelligente l'AI, tutti hanno avuto difficoltà a trovare i file di documentazione (i manuali di istruzioni).

Analogia: Se un utente dice: "Il pulsante rosso non funziona", l'AI sa che deve sistemare il pulsante rosso. Ma l'AI raramente si rende conto che anche il manuale di istruzioni deve essere aggiornato per dire "Il pulsante rosso è ora rotto". Il rapporto sul bug non menzionava il manuale, quindi l'AI lo ha ignorato.
Risultato: Questa è una dipendenza nascosta. L'AI ha bisogno di una regola che dica: "Se sistemi un pulsante, devi anche controllare il manuale", anche se l'utente non lo ha esplicitamente chiesto.

La Conclusione

L'articolo conclude che il modo in cui un'AI esplora un codice sorgente è importante quanto quanto è intelligente l'AI stessa.

Un piccolo team ben organizzato di specialisti (Agenti di Dominio) può battere una gigantesca e potente IA che vaga senza meta.
Tuttavia, anche i migliori team di AI faticano a gestire i cambiamenti "invisibili", come l'aggiornamento dei manuali di istruzioni, perché i rapporti sui bug non li richiedono esplicitamente.

In breve: La struttura batte la potenza bruta. Organizzare il processo di ricerca è la chiave per risolvere bug software complessi.

Sintesi Tecnica: Struttura di Esplorazione negli Agenti LLM per la Localizzazione di Modifiche Multi-File

Definizione del Problema

I problemi di ingegneria del software raramente coinvolgono modifiche a un singolo file; risolvere un bug richiede spesso modifiche attraverso molteplici sottosistemi (ad esempio, CLI, librerie sottostanti, plugin e documentazione). Gli attuali agenti basati su Large Language Models (LLM) impiegano tipicamente una strategia di esplorazione lineare e sequenziale, visitando una directory o un file per ogni step. Gli autori postulano che questo approccio lineare rappresenti un disallineamento strutturale per le modifiche multi-file che si estendono su diversi sottosistemi. Se un agente esaurisce il proprio budget di step o di token esplorando il primo sottosistema, i sottosistemi successivi che contengono i file "gold" necessari potrebbero non essere mai esaminati.

Il documento affronta tre questioni fondamentali di ricerca:

L'esplorazione lineare è strutturalmente limitante per le modifiche multi-file, o i modelli più forti possono compensare tramite una migliore selezione degli step?
Concedere agli agenti l'accesso diretto al file system migliora in modo affidabile la localizzazione, o introduce errori di navigazione e sovra-predizione?
Forzare una consultazione multi-agente aggressiva migliora il richiamo (recall), o inietta rumore da sottosistemi irrilevanti?

Metodologia

Costruzione del Benchmark

Lo studio utilizza un benchmark a sessione persistente derivato da SWE-BENCH PRO, focalizzandosi sul repository ansible/ansible.

Ambito: Sono stati costruiti tre intervalli temporali: Maggio–Novembre 2020 (l'insieme curato originale), Aprile–Settembre 2025 e Gennaio–Maggio 2026.
Stabilità: Tutti gli istanze in un intervallo sono ancorate a un singolo commit di base per garantire uno stato costante del repository e costi di esplorazione costanti.
Gold Sets: Gli autori confrontano i risultati con il set gold curato di SWE-BENCH PRO (file sorgente selezionati manualmente) e un set gold espanso basato su PR (ogni file toccato dalla Pull Request risolutiva, inclusi test e changelog).
Metriche: Le metriche primarie includono la Micro-F1, l'All-Gold rate (la frazione di istanze in cui tutti i file di verità fondamentale sono predetti) e la macro F1 per istanza.

Sistemi Sperimentali

Gli autori confrontano quattro famiglie di sistemi LLM, isolando la struttura di esplorazione dalla capacità del modello di base utilizzando lo stesso modello di classe Haiku per la maggior parte delle varianti:

Plain LLM (Nessun accesso al repository): Una singola chiamata API che si affida esclusivamente alla conoscenza della struttura del repository presente nel pre-training.
Single-Agent Recursive Language Model (RLM): Un agente con un REPL Python persistente che consente l'accesso sequenziale al file system (ad esempio, os.listdir, grep). Questo testa l'efficacia dell'esplorazione sequenziale senza specializzazione di dominio.
Sistema Domain-Agent (Proposto): Un'architettura multi-agente caratterizzata da:
- Inizializzazione: Un coordinatore root esplora il repository per identificare aree di manutenzione coerenti (sottosistemi come cli/, module_utils/, docs/) e genera agenti di dominio persistenti per ciascuna.
- Query-Time: Il coordinatore assegna i relativi agenti di dominio in parallelo per esplorare le regioni assegnate.
- I/O Limitato: I file grandi e gli elenchi di directory sono gestiti in un ambiente programmatico; solo anteprime compatte o intervalli di righe specifici entrano nel contesto dell'LLM per prevenire l'esaurimento dei token.
- Ablazioni: Le varianti includono "no-spawn" (il registro è presente ma non c'è l'invio in parallelo) e "nudged" (consultazione aggressiva forzata).
Baseline External CLI: Utilizza Codex 5.5 High, un modello di frontiera molto più grande, per stabilire un riferimento di limite superiore.
Baseline BM25: Un sistema di recupero lessicale classico che scansiona $K$ da 1 a 30 per generare un inviluppo precisione-richiamo.

Contributi Chiave e Risultati

1. La Struttura di Esplorazione è un Fattore Critico

L'approccio Domain-Agent, che parallelizza l'esplorazione lungo i sottosistemi del repository, raggiunge il Micro-F1 più alto tra tutti i modelli di classe Haiku con un ampio margine.

Sul benchmark curato del 2020, il Domain-Agent (Haika) raggiunge un Micro-F1 di 0.447, superando significativamente il Plain LLM (Haika) a 0.199 e il Single-Agent RLM (Haika) a 0.151.
Il sistema Domain-Agent è competitivo con il molto più grande Codex 5.5 High (Micro-F1 0.422 su curato, 0.523 su PR-based), nonostante l'uso di un modello più piccolo.
Risultato: L'esplorazione lineare (RLM) è strutturalmente limitante; l'esplorazione parallela e con ambito di dominio è necessaria per una localizzazione multi-file efficace.

2. L'Accesso Naive al File System Può Degradare le Prestazioni

Contrariamente all'intuizione secondo cui un maggiore accesso equivalga a migliori prestazioni, concedere a un singolo agente l'accesso grezzo al file system (RLM) ha degradato la localizzazione rispetto a un Plain LLM utilizzando lo stesso modello Haiku.

RLM (Haika): Micro-F1 0.151.
Plain LLM (Haika): Micro-F1 0.199.
Causa: L'RLM tendeva a sovra-predire i file di test e a navigare in gerarchie irrilevanti, esaurendo i budget di contesto e introducendo falsi positivi. Il Plain LLM, affidandosi alla conoscenza strutturale pre-addestrata, era più conservativo e preciso.

3. La Consultazione Forzata Non Aiuta

Forzare il coordinatore a consultare più agenti (variante "nudged") non ha migliorato misurabilmente il richiamo, ma ha aumentato significativamente i costi di token (da ~16M a ~25M di token).

L'invio indiscriminato ha introdotto rumore da sottosistemi irrilevanti senza recuperare ulteriori file gold.
Conclusione: L'invio adattivo (consultare solo i domini rilevanti) è superiore alla consultazione forzata e aggressiva.

4. Il Gap di Co-evoluzione della Documentazione

Un fallimento sistematico è stato osservato in tutte le architetture (incluso il grande modello Codex) riguardo ai file di documentazione (docs/docsite/).

Tasso di Mancata Individuazione: I file di documentazione hanno avuto un tasso di mancata individuazione aggregato del 73%, molto più alto dei file di codice.
Ragione: Le descrizioni dei problemi spesso descrivono i cambiamenti del comportamento del codice sorgente senza menzionare esplicitamente la necessità di aggiornare la documentazione. Questa è una dipendenza latente (accoppiamento logico) che le attuali politiche di esplorazione non possono risolvere perché il "segnale" è assente dal testo di input.

5. Generalizzazione nel Tempo

I risultati si generalizzano attraverso gli intervalli temporali (2020, 2025, 2026).

L'approccio Domain-Agent ha costantemente superato le altre baseline di modelli piccoli.
Sui segmenti 2025 e 2026, l'approccio Domain-Agent ha persino superato Codex 5.5 High sul set gold "stretto" (solo sorgente), sebbene Codex abbia mantenuto un vantaggio sul set gold "ampio" (basato su PR) grazie alla sua tendenza a predire set di file più ampi (inclusi i test).

Significato e Rivendicazioni

Il documento sostiene che la struttura di esplorazione sia un fattore di secondo ordine che può compensare la capacità limitata del modello. Ristrutturando l'agente per parallelizzare l'esplorazione lungo i sottistemi del repository e utilizzando un I/O limitato, un modello piccolo può eguagliare o superare le prestazioni di modelli di frontiera molto più grandi nei compiti di localizzazione multi-file.

Tuttavia, gli autori sono modesti riguardo ai limiti:

L'esplorazione non è sufficiente: Nessuna architettura attuale può recuperare in modo affidabile i file di documentazione perché il testo del problema manca dei segnali necessari. Ciò richiede un cambiamento nella politica di instradamento (ad esempio, inviare agenti di documentazione basandosi sui cambiamenti del codice sorgente) piuttosto che una migliore esplorazione.
L'accesso non è una panacea: L'accesso grezzo al file system senza strategie di esplorazione mirate può attivamente danneggiare le prestazioni amplificando le ambiguità del prompt e causando sovra-predizione.
Ambito: Lo studio isola la localizzazione dei file dalla generazione di patch e dall'esecuzione dei test, il che significa che queste conclusioni si applicano specificamente alla fase di "dove cambiare" dell'ingegneria del software.

Il lavoro stabilisce che, per la localizzazione di modifiche multi-file, l'invio in parallelo con ambito di dominio è un pattern architettonico superiore rispetto all'esplorazione sequenziale lineare, a condizione che il sistema eviti l'accesso ingenuo al file system e gestisca i budget di token attraverso un I/O limitato.