Sintesi Tecnica: REFINE – Un approccio Multi-Agente LLM per il Refactoring del Codice Guidato dall'Evidenza

Definizione del Problema

Sebbene i Large Language Models (LLM) dimostrino forti capacità nella generazione e trasformazione di codice, la loro applicazione al refactoring del software affronta sfide significative. Un refactoring efficace richiede non solo la modifica del codice per ridurre i problemi di qualità (code smells), ma anche la garanzia che le modifiche non introducano nuovi difetti, non alterino il comportamento esterno o rimuovano elementi strutturali critici (ad es., API pubbliche, asserzioni).

Gli attuali approcci di refactoring assistiti da LLM spesso mancano di una verifica rigorosa, portando a rischi quali suggerimenti allucinati, trasformazioni inconsistenti e la rimozione di strutture di codice rilevanti per il comportamento. È necessario un approccio sistematico che:

1. Guidi gli LLM con evidenze derivanti dall'analisi statica.
2. Orchestri un workflow multi-agente per pianificare, generare e verificare le modifiche.
3. Fornisca un'evidenza tracciabile di ciò che è stato cambiato, dei rischi rimanenti e se l'output sia un candidato al refactoring vitale piuttosto che una soluzione accettata automaticamente.

Metodologia: Il Workflow REFINE

Gli autori introducono REFINE (Refactoring with Evidence-aware Flow for Integrated ageNtic Execution), un framework multi-agente agnostico rispetto agli strumenti e consapevole delle evidenze, progettato per il refactoring a livello di file Java. Il sistema è implementato come prototipo di ricerca utilizzando un'interfzione Next.js, un backend Java Spring Boot (per l'analisi statica tramite PMD 7.x) e un servizio agente Python (utilizzando LangGraph v1.1) per l'orchestrazione.

Il workflow opera attraverso tre fasi primarie:

1. Caratterizzazione del Task

• Input: Un singolo file Java da un progetto open-source.
• Raccolta delle Evidenze: L'analisi statica (PMD) identifica i code smell a livello di file e le evidenze a livello di regola.
• Contestualizzazione: Il sistema estrae le firme delle API pubbliche, il contesto del workspace e dà priorità ai code smell rilevati per formare un compito di refactoring delimitato.

2. Orchestrazione del Refactoring

Il workflow coordina undici ruoli distinti (agenti) per gestire il processo:

• Agente di Pianificazione (Planning Agent): Combina la guida deterministica basata su regole con l'opzionale raffinamento tramite LLM per creare un piano di refactoring orientato allo smell.
• Agente di Refactoring (Refactoring Agent): Invocano un LLM per generare una trasformazione candidata basata sul piano, sulla sorgente originale e sui vincoli (ad es., preservare le API pubbliche).
• Agente di Verifica (Verification Agent): Analizza il candidato generato rispetto ai controlli di evidenza configurati prima che venga mantenuto.

3. Traccia di Verifica e Analisi

REFINE non tratta l'output dell'LLM come definitivo. Inveve, ri-analizza il file trasformato per calcolare:

• Riduzione degli Smell: Miglioramenti assoluti ($\Delta_{smell} = B - A$) e relativi nei code smell rilevati.
• Proxy di Preservazione Statica: Controlli per la preservazione delle API pubbliche, la gestione delle eccezioni, i contratti del framework, la logica condizionale e le chiamate critiche assert/fail.
• Diagnostica di Fallimento: Registra le ragioni specifiche di rifiuto (ad es., rimozione di un metodo pubblico).
• Tracciabilità: Persiste la sorgente originale, il candidato generato, i passaggi degli agenti, le metriche e gli esiti della verifica per collegare ogni decisione alla propria evidenza.

Design Sperimentale

• Dataset: 450 file Java da 15 sistemi open-source (ad es., JHotDraw, Apache Ant, Guava, JabRef), selezionati tramite campionamento casuale stratificato basato sul conteggio dei code smell e sulle Linee di Codice (LOC).
• Configurazioni LLM: Tre modelli di frontiera sono stati valutati: OpenAI GPT-5.5, Google Gemini 3.1 Pro Preview e Anthropic Claude Opus 4.8.
• Scala: Ciò ha portato a 1.350 output di passaggio del modello.
• Baseline: Una baseline di prompting diretto accoppiata è stata condotta su un subset di 150 file per confrontare il workflow multi-agente rispetto al semplice prompting.
• Metriche: Riduzione dei code smell, indicatori di qualità (Complessità Ciclotica, Indice di Manutenibilità, ecc.), cambiamenti strutturali e rischi di preservazione.

Risultati Chiave

1. Riduzione dei Code Smell (RQ1)

REFINE ha ottenuto riduzioni sostanziali dei code smell rilevati in tutte e tre le configurazioni LLM:

• Riduzione Totale: 68,26% (GPT-5.5), 72,79% (Gemini 3.1) e 68,49% (Opus 4.8).
• Major Smells: I miglioramenti più significativi sono stati nei major code smell (riduzione dell'86,51% - 91,60%).
• Indicatori di Qualità: I miglioramenti nei parametri di qualità più ampi non sono stati uniformi. Mentre Gemini 3.1 ha mostrato riduzioni significative nella Complessità Ciclotica e LCOM, altre metriche (Manutenibilità, Testabilità, sforzo di Halstead) hanno mostrato cambiamenti misti o avversi a seconda del modello.

2. Preservazione e Rischi (RQ2)

• Tassi di Superamento Elevati: La maggior parte degli indicatori di preservazione statica (firme dei metodi pubblici, gestione delle eccezioni, contratti del framework) è passata con tassi elevati (dall'81,8% al 94,2%).
• Rischi Critici:
  • Chiamate Assert/Fail: Solo il 57,1% degli output ha preservato le chiamate critiche assert/fail tra tutti i modelli, indicando un rischio sistemico.
  • Rimozione di Metodi Pubblici: Questa è stata la diagnostica di fallimento più concreta. Gemini 3.1 ha mostrato il tasso più alto di rimozione di metodi pubblici (71 casi), seguito da GPT-5.5 (41) e Opus 4.8 (34).

3. Comportamento di Refactoring (RQ3)

Diversi modelli hanno ottenuto la riduzione degli smell attraverso profili di modifica distinti:

• GPT-5.5: Ha prodotto le modifiche più compatte.
• Gemini 3.1: Ha mostrato un profilo "pesante sulle cancellazioni", rimuovendo il maggior numero di righe e metodi.
• Opus 4.8: Ha mostrato un profilo "pesante sulle estrazioni" con il maggior numero di estrazioni di metodi.
• Correlazione: Volumi di modifica più grandi correla con una maggiore riduzione assoluta degli smell, ma non necessariamente con una maggiore riduzione relativa.

4. Confronto con il Prompting Diretto

Sul subset accoppiato di 150 file, REFINE ha superato il prompting diretto in:

• Riduzione degli Smell: Riduzione totale mediana del 100,0% (REFINE) rispetto al 20,8% (Prompt Diretto).
• Impronta di Modifica (Edit Footprint): Churn mediana minore (14 LOC rispetto a 65 LOC).
• Sicurezza API: Meno rimozioni di metodi pubblici (46 casi rispetto a 112).
• Trade-off: Il prompting diretto ha preservato le costrutti critici assert/fail più spesso (100% rispetto a 58%).

Significato e Rivendicazioni

Il paper posiziona REFINE non come un sostituto degli strumenti di refactoring che preservano il comportamento, ma come un meccanismo tracciabile e consapevole delle evidenze per generare e valutare i candidati al refactoring.

• Consapevolezza delle Evidenze: Il contributo primario è il collegamento del codice generato alla specifica evidenza statica (smell) che ha motivato il cambiamento e ai controlli di verifica che ha superato o fallito.
• Generazione Controllata: Il workflow multi-agente fornisce una generazione di candidati più controllata rispetto al prompting diretto, risultando in modifiche più piccole e meno rimozioni accidentali di API, sebbene non elimini tutti i rischi comportamentali.
• Limitazioni: Gli autori dichiarano esplicitamente che gli output generati sono candidati, non refactoring pronti per la produzione. I controlli di preservazione statica sono proxy e non provano l'equivalenza comportamentale.
• Implicazione Pratica: I candidati generati richiedono compilazione, test, analisi delle dipendenze e revisione umana prima dell'adozione, in particolare in contesti ricchi di dipendenze o di livello di sistema.

Lo studio conclude che, sebbene i workflow multi-agente basati sulle evidenze siano promettenti per la mitigazione mirata dei code smell a livello di file, né il prompting diretto né l'approccio multi-agente forniscono attualmente prove sufficienti di piena preservazione del comportamento per operare autonomamente in ecosistemi software complessi.