SWE-Adept: An LLM-Based Agentic Framework for Deep Codebase Analysis and Structured Issue Resolution

Il paper presenta SWE-Adept, un framework basato su agenti LLM che migliora l'analisi e la risoluzione strutturata dei problemi nei repository di codice attraverso un agente di localizzazione con ricerca in profondità guidata e un agente di risoluzione dotato di pianificazione adattiva e controllo versione Git, ottenendo risultati superiori su SWE-Bench.

L'essenziale

Immagina di avere un enorme archivio di documenti (il codice di un software) composto da migliaia di file, e qualcuno ti dice: "C'è un errore qui, ma non so esattamente dove". Trovare quel file e correggerlo è come cercare un ago in un pagliaio, ma peggio ancora: l'ago potrebbe essere nascosto in un altro pagliaio collegato al primo.

Questo è il problema che affronta il nuovo sistema chiamato SWE-Adept. È un "assistente intelligente" basato sull'intelligenza artificiale (LLM) progettato per risolvere problemi di programmazione complessi in modo autonomo.

Ecco come funziona, spiegato con semplici metafore:

1. Il Problema: Troppo Rumore, Troppo Caos

I modelli di intelligenza artificiale attuali sono bravissimi a scrivere codice semplice, ma quando devono lavorare su un intero progetto (con migliaia di file), si perdono.

• Il problema della memoria: Se provi a leggere tutto il codice per trovare l'errore, l'IA si "intasa" la memoria (il contesto) con informazioni inutili e dimentica cosa stava cercando.
• Il problema della correzione: Quando provano a correggere l'errore, spesso fanno un "pasto di spaghetti": modificano un pezzo, rompono qualcos'altro, provano a ripararlo, e finiscono per creare un disastro che non sanno più come smontare.

2. La Soluzione: SWE-Adept (Il Team di Due Esperti)

SWE-Adept non è un singolo robot, ma un team di due agenti specializzati che lavorano insieme, ognuno con un compito preciso.

Agente 1: Il Detective (Localizzazione)

Il suo lavoro è trovare esattamente dove si trova l'errore.

• Come lavora: Invece di leggere tutto il libro a caso, usa una mappa intelligente (un albero di struttura del codice).
• La strategia: Immagina di dover trovare una stanza specifica in un palazzo enorme. Il Detective non apre tutte le porte a caso. Usa un metodo chiamato "ricerca in profondità guidata": entra in un corridoio, guarda le porte laterali, e se una porta sembra promettente, la apre e scende nel corridoio successivo. Se si rende conto che quella strada è un vicolo cieco, torna indietro subito senza sprecare tempo.
• Il trucco: Legge solo gli "scheletri" dei file (i titoli e le funzioni principali) per decidere se vale la pena approfondire. Solo quando ha quasi trovato l'errore, legge il testo completo. Questo gli permette di non intasare la memoria.

Agente 2: L'Architetto (Risoluzione)

Una volta che il Detective ha detto: "L'errore è qui, nella funzione X", l'Architetto entra in azione per ripararlo.

• Il problema dei vecchi metodi: Spesso gli IA provano a correggere, falliscono, provano di nuovo, e il codice diventa un groviglio incomprensibile.
• La soluzione di SWE-Adept: L'Architetto usa un sistema di punti di salvataggio (checkpoint) come nei videogiochi.
  • Prima di toccare qualsiasi cosa, fa una foto dello stato attuale (un "punto di salvataggio").
  • Se ha un'idea (un'ipotesi) su come riparare, crea un ramo separato (come un sentiero laterale nel bosco) per provarla.
  • Se la riparazione funziona, bene! Se fallisce, non deve preoccuparsi di "smontare" il codice rotto. Basta tornare al punto di salvataggio precedente e ripartire da lì.
  • Può anche creare più sentieri paralleli per provare diverse soluzioni contemporaneamente, e poi scegliere quella migliore.

3. La Memoria Condivisa

Il vero segreto di SWE-Adept è una memoria condivisa tra i due agenti.

• Immagina un quaderno di appunti che tiene traccia di ogni passo: "Ho provato a cambiare questa riga, ho creato questo ramo, ho fatto questo punto di salvataggio".
• Questo permette all'IA di non perdere mai il filo del discorso, anche dopo ore di lavoro, e di poter tornare indietro in modo sicuro se qualcosa va storto.

Il Risultato

Grazie a questo approccio, SWE-Adept è molto più bravo dei sistemi precedenti a:

1. Trovare l'errore con precisione chirurgica (senza perdersi nel codice inutile).
2. Ripararlo in modo ordinato, potendo tornare indietro se necessario senza creare disastri.

In pratica, SWE-Adept trasforma il lavoro di un programmatore da un'operazione caotica e rischiosa in un processo metodico, sicuro e controllato, come un chirurgo che usa strumenti precisi invece di un martello. I test hanno dimostrato che questo sistema risolve molti più problemi reali rispetto alle tecnologie attuali.

Sommario tecnico

1. Il Problema

Nonostante i recenti progressi dei Large Language Models (LLM) nelle attività di programmazione isolate (a livello di funzione o file), questi modelli faticano ancora a risolvere problemi di ingegneria del software a livello di repository (SWE). Le principali sfide identificate sono:

• Navigazione complessa del codice: I repository reali contengono migliaia di file con dipendenze incrociate dense. Identificare la causa radice di un problema richiede spesso l'esplorazione di queste dipendenze, ma i modelli LLM hanno limiti di contesto (context window). Gli approcci esistenti tendono a inondare il contesto con informazioni irrilevanti o a utilizzare strategie di esplorazione rigide (es. breadth-first) che introducono ridondanza.
• Mancanza di strategie sistemiche per la risoluzione: Molti approcci attuali operano in un ciclo "pensa-edita" libero, senza una pianificazione esplicita o un tracciamento dello stato. Questo porta a modifiche di codice disordinate, rendendo difficile validare i risultati o tornare indietro (revert) quando un tentativo di riparazione fallisce. Manca un meccanismo robusto di "checkpointing" per gestire stati intermedi durante iterazioni lunghe.

2. Metodologia: SWE-Adept

SWE-Adept è un framework basato su agenti LLM che divide il processo di risoluzione dei problemi in due agenti specializzati, operanti in finestre di contesto separate per evitare l'accumulo di tracce non necessarie.

A. Agente di Localizzazione (Issue Localization Agent)

L'obiettivo è identificare con precisione le posizioni nel codice rilevanti per il problema.

• Indicizzazione a livello di definizione: Il codice viene segmentato in unità fini (classi, funzioni) utilizzando tree-sitter, creando un albero di struttura del codice (Code-Structure Tree) che mappa le dipendenze (contiene/chiamata).
• Esplorazione guidata dall'agente (Agentic Traversal): Invece di un'espansione cieca, l'agente esegue una ricerca in profondità (Depth-First Search) selettiva. Utilizza strumenti di ricerca leggeri che restituiscono solo scheletri di codice e metadati (non il contenuto completo) per navigare le dipendenze.
• Filtraggio in due stadi:
  1. Pre-filtraggio: Selezione dei candidati basata su scheletri di codice e metadati di posizione per minimizzare l'uso del contesto.
  2. Raffinamento: Caricamento del codice completo solo per i candidati selezionati per un'analisi finale e un riordinamento preciso.

B. Agente di Risoluzione (Issue Resolution Agent)

Una volta localizzati i file, questo agente implementa e valida le correzioni.

• Pianificazione Strutturata: L'agente formula ipotesi di riparazione (soluzioni alternative) e crea liste di attività (to-do) dinamiche e granulari.
• Controllo Versioni Guidato dall'Agente: È stato introdotto un interfaccia strumento-memoria basata su Git. L'agente utilizza comandi CLI personalizzati (hypothesis_git) che interagiscono con una memoria di lavoro condivisa.
  • Checkpointing: Dopo ogni passo completato (es. una modifica o un test), lo stato del codice viene committato e i metadati (hash Git, messaggio) vengono salvati nella memoria.
  • Branching e Revert: L'agente può creare rami (branch) per esplorare ipotesi diverse. Se un'ipotesi fallisce parzialmente, l'agente può tornare a un checkpoint precedente (revert) e creare un nuovo ramo per esplorare una direzione diversa, mantenendo le tracce di risoluzione separate e pulite.
• Memoria di Lavoro: Archivia ipotesi, stati delle attività e checkpoint del codice, permettendo all'agente di recuperare stati specifici senza dover tracciare manualmente hash Git complessi nel contesto.

3. Contributi Chiave

1. Framework Agentic Duale: Separazione efficace tra localizzazione e risoluzione, ottimizzando l'uso del contesto e la specializzazione degli agenti.
2. Navigazione Selettiva: Introduzione di una strategia di DFS guidata dall'agente combinata con un indicizzazione a livello di definizione e un filtraggio in due stadi, che riduce drasticamente il rumore nel contesto.
3. Gestione dello Stato Robusta: Progettazione di un'interfaccia strumento-memoria che abilita operazioni di controllo versione affidabili (branching, checkpointing, revert) per la risoluzione sistematica di problemi a lungo termine (long-horizon).
4. Prestazioni Superiori: Dimostrazione che la combinazione di localizzazione precisa e risoluzione strutturata supera gli approcci precedenti.

4. Risultati Sperimentali

Il framework è stato valutato su due benchmark principali: SWE-Bench Lite e SWE-Bench Pro, utilizzando modelli come GPT-5.2 e Claude-Sonnet-4.5.

• Localizzazione: SWE-Adept ha ottenuto le migliori prestazioni sia a livello di file che di funzione.
  • Su SWE-Bench Lite, ha migliorato l'accuratezza a livello di funzione (Func Acc@5) del 5.4% rispetto al miglior baseline (SWE-agent) con GPT-5.2.
  • Ha consumato meno token rispetto agli approcci basati su grafi grazie alla gestione efficace del contesto.
• Risoluzione End-to-End:
  • Su SWE-Bench Lite, ha raggiunto un tasso di risoluzione (resolve rate) superiore del 3.3% (GPT-5.2) e 2.6% (Claude) rispetto ai baseline.
  • Su SWE-Bench Pro (più complesso), il miglioramento è stato del 4.7% e 4.0% rispettivamente.
• Analisi degli Errori: L'analisi mostra che SWE-Adept riduce significativamente i fallimenti dovuti a localizzazione errata, ipotesi di soluzione sbagliate e incapacità di recuperare da modifiche errate (grazie al meccanismo di revert).

5. Significato e Impatto

SWE-Adept rappresenta un passo avanti significativo verso l'automazione dell'ingegneria del software. Dimostra che:

• La separazione dei compiti (localizzazione vs. risoluzione) è cruciale per gestire la complessità dei repository reali.
• La gestione dello stato esplicita (tramite checkpointing e controllo versione) è fondamentale per permettere agli agenti di navigare scenari di risoluzione complessi e iterativi senza perdere il filo logico o commettere errori irreversibili.
• L'approccio proposto è scalabile e può essere adattato ad altri linguaggi di programmazione, offrendo una soluzione robusta per problemi software che richiedono una comprensione profonda delle dipendenze e una pianificazione strategica.

In sintesi, SWE-Adept trasforma l'approccio "trial-and-error" tipico degli agenti LLM attuali in un processo sistematico, controllato e reversibile, avvicinandosi alle pratiche di sviluppo software professionali.