Reverse engineering di piattaforme legacy assistito dall'AI: lezioni dal campo

Il problema

Ogni azienda con qualche anno alle spalle ha almeno un sistema che nessuno capisce fino in fondo. Gli sviluppatori originali se ne sono andati. La documentazione, se mai è esistita, è ferma da anni. Il codice è stato rattoppato, esteso e aggirato da team successivi che conoscevano ciascuno il proprio pezzo ma non l'insieme. Eppure quel sistema fa girare processi di business critici che non si possono fermare.

Modernizzare questi sistemi senza prima capirli è il modo in cui le organizzazioni producono fallimenti costosi. L'approccio tradizionale (mettere un team di analisti a leggere il codice e scrivere documentazione) richiede mesi e produce documenti soggettivi, incompleti e già superati prima di essere finiti.

Cosa porta il RAG

Caricare un'intera codebase in un vector store (noi usiamo Weaviate) crea una base di conoscenza interrogabile per significato. Puoi fare domande come "quali moduli scrivono nella tabella clienti?" o "cosa succede quando un ordine viene annullato?" e ottenere risposte ancorate al codice reale, con riferimenti a file e numeri di riga precisi.

È una cosa profondamente diversa dal chiedere a un LLM di "spiegare questo codice". Le risposte ancorate al RAG sono tracciabili: ogni affermazione si può verificare sulla sorgente. Questa tracciabilità non è solo utile; nella nostra esperienza è la proprietà più importante in assoluto per costruire fiducia con i team che dovranno agire sulla base dell'analisi.

Orchestrazione multi-agente

Una singola query RAG risponde a una domanda specifica. Produrre un'analisi completa richiede di orchestrare centinaia di query in una sequenza strutturata. Usiamo n8n per costruire workflow multi-agente che esplorano una codebase in modo sistematico:

• Individuare tutti i punti di ingresso (API, job schedulati, controller della UI)
• Tracciare i flussi di dati dall'ingestione allo storage fino all'output
• Mappare le dipendenze tra moduli
• Segnalare le regole di business non documentate nascoste nel codice
• Generare output strutturati: specifiche funzionali, dizionari dati, diagrammi di architettura

Ogni passaggio produce artefatti che vengono rivisti da analisti umani prima di passare al successivo. L'AI accelera il lavoro; le persone lo validano.

Cosa non funziona

Dare in pasto a un LLM un'intera codebase chiedendo "un'analisi completa" produce risultati che suonano sicuri ma non sono affidabili. Senza l'ancoraggio del retrieval, il modello inventa collegamenti che non esistono e si perde quelli non ovvi che esistono. I limiti della finestra di contesto fanno sì che percorsi di codice critici vengano ignorati senza alcun avviso. E senza tracciabilità non c'è modo di verificare un'affermazione se non con una revisione manuale del codice, il che vanifica lo scopo.

La toolchain nel dettaglio: com'è fatta davvero la pipeline

La toolchain specifica conta. In produzione, la nostra pipeline di reverse engineering è composta da:

• Vector store Weaviate: la codebase è suddivisa in chunk a livello di funzione o metodo, con finestre di contesto sovrapposte che preservano le relazioni di chiamata. Ogni chunk include metadati: percorso del file, modulo, linguaggio e un tag strutturale (controller, service, model, utility). Questi metadati permettono un retrieval filtrato: una domanda sui pattern di accesso ai dati cerca solo nei livelli model e repository, non nel codice della UI.
• Modello di embedding: usiamo embedding per il codice adattati al dominio invece di embedding testuali generici. I modelli specifici per il codice capiscono che implementazioni sintatticamente diverse dello stesso pattern (per esempio la gestione degli errori in Java e in C#) sono semanticamente simili.
• Orchestrazione con n8n: i workflow multi-agente sono definiti come flussi n8n con diramazioni condizionali, gestione degli errori e approval gate umani. Ogni agente del flusso ha un ruolo preciso: mappatura delle dipendenze, tracciamento dei flussi di dati, estrazione delle regole di business, analisi della superficie API. Il livello di orchestrazione garantisce che gli agenti elaborino la codebase nell'ordine giusto e che l'output di ciascuno sia disponibile agli agenti a valle.
• Formato dell'output: artefatti JSON strutturati, non testo libero. Specifiche funzionali, dizionari dati e mappe delle dipendenze sono prodotti in formati leggibili dalle macchine, che si possono importare in strumenti di architettura e sistemi di project management o usare come input per la fase successiva (la generazione del codice).

Dall'analisi alla modernizzazione: la pipeline completa

Il reverse engineering non è l'obiettivo finale: è la base della modernizzazione. Gli artefatti di analisi prodotti dalla pipeline AI alimentano direttamente la fase di ricostruzione. Le specifiche funzionali diventano user story. I dizionari dati diventano definizioni di schema. Le mappe delle dipendenze diventano diagrammi di architettura per il nuovo sistema.

Nel nostro progetto IATP, la fase di reverse engineering ha prodotto 47 specifiche funzionali, un dizionario dati completo su oltre 180 tabelle di database e una mappa delle dipendenze che ha fatto emergere 12 punti di integrazione non documentati con sistemi esterni. Questo output è diventato la specifica della nuova piattaforma, riducendo la fase di specifica da mesi a giorni ed eliminando l'ambiguità che di solito affligge i progetti di riscrittura di sistemi legacy.

La pipeline AI ha anche individuato il pattern del motore di obsolescenza: componenti in cui il debito tecnico si era accumulato fino al punto in cui il costo della manutenzione superava quello della sostituzione. Quantificandolo (righe di codice morto, dipendenze inutilizzate, chiamate ad API deprecate, vulnerabilità di sicurezza nelle versioni di librerie bloccate) l'analisi ha fornito una base oggettiva per decidere quali componenti ricostruire per primi.

Risultati in produzione

Nel progetto IATP questo approccio ha ridotto la fase di analisi da 3-4 mesi stimati di lavoro manuale a meno di due settimane. Soprattutto, l'output era verificabile: ogni specifica funzionale era riconducibile a codice preciso, e il team di sviluppo poteva validare le affermazioni sulla sorgente in pochi minuti invece che in giorni. Oggi è una metodologia ripetibile della nostra practice di modernizzazione legacy.

Da un progetto all'altro la direzione è la stessa: l'analisi è più rapida del reverse engineering manuale, fa emergere punti di integrazione e regole di business che una lettura manuale non vede, e le specifiche funzionali che produce vanno comunque validate da una persona. Quanto tempo e quanto costo fa risparmiare dipende dal sistema e va misurato caso per caso; i numeri di IATP qui sopra sono quelli che abbiamo misurato.