Ciao a tutti, in questo articolo voglio raccontarvi di un progetto che mi ha tenuto impegnato negli ultimi mesi: documentare un progetto legacy sviluppato in Delphi per quasi 30 anni, senza una riga di documentazione e senza che nessun developer del team di sviluppo fosse in grado di descrivere la logica di business senza aprire il codice e ricostruirla a mano.
Io faccio parte di un nuovo team con l’obiettivo di riscrivere il prodotto attuale, un client Delphi, verso un nuovo progetto web, con un backend in .NET Core e un frontend Angular, di cui sono il responsabile. Prima di poter scrivere anche solo una riga del nuovo software però, ci siamo scontrati con un problema non indifferente: nessuno sapeva davvero cosa facesse il vecchio software. La (poca) conoscenza viveva nella testa di poche persone e cosa peggiore, non esisteva una documentazione (se non frammentaria e quasi sempre non allineata).
Vediamo quindi il percorso che ci ha portati a costruire una skill di Claude piuttosto complessa per affrontare questo problema, con i tentativi falliti lungo la strada e i risultati che abbiamo ottenuto.
Il progetto di partenza
Prima di partire vi contestualizzo il progetto. Il prodotto da migrare era un’applicazione Delphi cresciuta per quasi tre decenni, costruita come UI sopra un database Oracle. 3/4 della logica di business è centralizzata nel database tra store procedure, package e trigger, il restante quarto invece è nell’applicazione Client, principalmente nelle form.
Documentazione? Praticamente assente, i pochi documenti erano inaffidabili poichè obsoleti e non aggiornati e l’unica strada per estrarre logica era aprire il codice e leggerlo. A complicare ancora di più era il processo di sviluppo, assolutamente non strutturato: analisi fatte alla macchinetta del caffè, sviluppi detti a voce o su Teams e una gestione delle versioni manuale.
In tutto questo caos il mio ruolo era quello di gestire e coordinare lo sviluppo della nuova applicazione web, in un contesto ancorato al mantra “abbiamo sempre fatto così, meglio non cambiare”. Le premesse non erano affatto buone ma ho imparato molto, una cosa tra tante è sicuramente quella che vi racconto in questo articolo: ricostruire la documentazione partendo dal codice.
Viviamo in un mondo dove l’IA è una grande novità per tutti e ciò che ci fa crescere sono proprio progetti come quello che sto per raccontarvi.
I primi tentativi (e i primi fallimenti)
Creare una skill claude non è mai stato il nostro primo pensiero, ma un punto di arrivo. Ecco come ci siamo arrivati
Step 1: gli esperti di dominio
Il primo approccio è stato quello classico: mettere due esperti di dominio (il responsabile tecnico ed una seconda persona esperta) a documentare uno specifico contesto, quello dei permessi (con il supporto di Github Copilot). Dopo un mese di lavoro avevano prodotto una decina documenti su Confluence, descrivendo come venivano gestiti utenti, ruoli e permessi nell’applicazione legacy.
Il primo campanello di allarme è stato il tempo: due persone “esperte” ci avevano messo un mese per analizzare un contesto relativamente semplice, senza logica di business complessa. Quanto ci avremmo messo per documentare tutto il progetto? La stima era di qualche anno solo per la documentazione, assolutamente non sostenibile.
Il secondo problema è emerso quando abbiamo collegato Claude a Confluence come supporto. Confluence conteneva moltissimi documenti vecchi e non aggiornati e questo mandava in confusione il modello: parte delle allucinazioni che vedevamo derivava proprio da lì.
Step 2: il primo server MCP
Contestualmente alla scrittura della documentazione il responsabile tecnico aveva provato a scrivere un server MCP preso dall’enfasi e senza un’oculata analisi. L’MCP recuperava le informazioni dai commenti sulle colonne delle tabelle Oracle e da una struttura dati di helper utilizzata dall’applicazione legacy. In questo caso il server MCP era consumato da Github Copilot (prima che si pagasse a consumo) ed era pensato come supporto per aiutare Copilot a comprendere la natura di certi campi mentre analizzava i sorgenti.
Il primo problema con questo approccio è stato che, anche in questo caso, i dati non erano sempre corretti, anzi a volte pure incoerenti.
Il secondo problema era la visione limitata dei dati utilizzati. Anche ipotizzando che i dati fossero corretti, non tutto era documentato, molti metadati erano mancanti ed il modello si confondeva o provava a dare un significato deducendolo dal nome del campo.
Terzo ed ultimo problema: ogni documentazione richiedeva un’elevata quantità di token e non produceva nessun documento di output. Se 3 persone avessero fatto la stessa richiesta ci sarebbero state 3 istanze impegnate a fare la medesima analisi, sprecando tempo e risorse
Il progetto di documentazione
A questo punto abbiamo cambiato completamente approccio. L’obiettivo è diventato costruire un sistema in grado di leggere direttamente i sorgenti e il dump del database per costruire la documentazione, dominio dopo dominio, in modo da fornire una base accurata e aggiornata a chi sviluppava il nuovo prodotto.
La prima mossa è stata creare un nuovo progetto dedicato alla documentazione, con dentro il dump del database Oracle e i sorgenti Delphi. Questo passaggio era necessario perché il progetto originale è gestito versionato con CVS e avevamo bisogno di un ambiente stabile e leggibile su cui far lavorare Claude, basato su Git.
Le skill per leggere il legacy
Il primo step è stato costruire delle skill dedicate alla lettura del progetto Delphi e dei pattern utilizzati al suo interno. Abbiamo classificato le strutture ricorrenti del codice: come venivano gestiti i permessi, come erano organizzate le funzioni condivise, e così via.
In parallelo abbiamo creato un file di indice in markdown con la spiegazione della struttura fisica del progetto: quali tipologie di file erano salvate dove, alberatura delle directory, significati semantici delle directory, ecc.
Dato che molta della logica di business viveva nel database, abbiamo costruito anche una documentazione dedicata ai pattern e alle strutture ricorrenti nel database
Gli agenti che orchestrano l’estrazione
Con le skill e la nuova documentazione come fondamenta, abbiamo creato degli agenti in grado di orchestrare l’estrazione della logica di business mettendo in relazione database e applicazione client, sfruttandogli elementi costruiti al passaggio precedente. Differentemente dal server MCP, che aveva una visione solo sui sorgenti, con questo approccio la documentazione era costruita intrecciando la logica dell’applicazione con quella sul database. Inoltre ogni esecuzione produceva una serie di documenti in markdown, versionati in un repo git.
I command per analizzare da più punti di vista
Il passo successico è stato definire i primi command, pensati per lanciare analisi sotto diversi punti di vista:
- analizza-modulo: per l’analisi di un singolo modulo applicativo. Nel software legacy un modulo era una porzione (standard o a pagamento) che aggiungeva funzionalità al software.
- analizza-tabella: per analizzare una tabella Oracle a partire dal dump DDL e produrre una documentazione completa. Utile perchè le tabelle erano un aggregato di molte entità (centinaia di tabelle avevano più di 500 colonne). Questa analisi serviva anche per capire il numero di entità nella tabella, in ottica di spezzarle e separarle in un secondo momento
- documenta-dominio: per eseguire una documentazione completa di un dominio funzionale (es. utenti, anagrafica, prodotti, ordini)
- verifica-docs: usata per verificare la completezza della documentazione di un dominio rispetto al formato atteso.
In questo modo potevamo scendere dal singolo campo di una tabella fino all’intero dominio funzionale, scegliendo ogni volta il livello di dettaglio ce ci interessava. Il risultato di ogni command era la generazione di una serie di documenti “standard”, ognuno focalizzato su uno specifico aspetto
Ottimizzare per migliorare
Da questo momento in avanti ci siamo concentrati a generare la documentazione sempre sullo stesso dominio, lo stesso che in precedenza era stato documentato manualmente dai due esperti. Avere un termine di paragone “umano” ci permetteva di trovare le allucinazioni e le mancanze, e di ottimizzare la skill di conseguenza.
Il metodo di lavoro era ordinato: per ogni ambito di miglioria veniva creato un branch dedicato, si faceva il lavoro di ottimizzazione delle skill, si validava l’output e solo a quel punto si faceva il merge nel ramo principale. Ogni miglioramento veniva validato prima di entrare nel ramo stabile.
Il fun fuct è che man mano che la skill diventava sempre più ottimizzata, emergevano sempre più aspetti che non erano stati considerati e mappati dai due esperti nella prima documentazione
Domini sempre più ampi
Man mano che le skill diventavano più affidabili, abbiamo iniziato ad affrontare aspetti sempre più ampi e a spingerci oltre la semplice documentazione dell’as-is, considerato che l’obiettivo era quello di riscrivere il software legacy.
Abbiamo costruito un nuovo step nella skill per estrarre l’organizzazione dei dati nelle form del progetto legacy, per produrre un documento che sintetizzasse come riorganizzarli nella nuova app Angular.
Poi abbiamo creato un nuovo step dedicato a proporre delle API REST per il nuovo backend. Il progetto legacy non aveva una suddivisione in domini, e molte tabelle gestivano decine e decine di entità di dominio differenti come entità uniche. Non mi dilungherò su questo tema perchè esula dal tema della skill.
Il risultato
Dopo tutto questo lavoro, il sistema è entrato a regime con un workflow ben definito dopo circa un mese di lavoro, lo stesso tempo impiegato per mappare il dominio dei permessi.
Eseguire un comando di mappatura del dominio dei ruoli/permessi ha richiesto quasi 4 ore a Claude (Opus 4.8)
Il workflow
A seguito di questo lavoro il nostro modo di lavorare e di procedere con il refactoring si è strutturato nel seguente modo:
- Si decide quale è il prossimo ambito da migrare
- Si genera la documentazione grazie a Claude, in un branch dedicato
- Gli esperti di dominio validano la documentazione
- Si fa il merge della documentazione nel master
- La documentazione prodotta viene usata come linea guida per gli sviluppi, sia sul frontend che sul backend e rimane a disposizione di tutti
Quello che abbiamo guadagnato è che lo sviluppatore è molto più autonomo, non deve più dipendere in continuazione da chi lavora sul prodotto da anni.
I benefici
Per rendere concreti i vantaggi, conviene mettere a confronto il vecchio e il nuovo metodo:
| Aspetto | Vecchio metodo | Nuovo metodo (con Claude) |
|---|---|---|
| Tempo di documentazione | 2 esperti di dominio, 1 mese di lavoro | circa 4 ore + 1/2 giorni di verifica |
| Qualità | variabile, dipendente dalla persona | più alta, con linee guida standard sullo sviluppo |
| Autonomia dei dev | bassa, dipendenza continua dagli esperti | alta, la doc è la linea guida |
Oltre alla velocità e alla qualità, c’è un beneficio che non mi aspettavo all’inizio: la documentazione è diventata la base per una skill sul progetto frontend. Partendo dalla doc prodotta, questa skill è in grado di generare componenti Angular nel nuovo progetto mantenendo la stessa UI e le stesse dinamiche della vecchia applicazione (ovviamente solo nei casi in cui non è necessario ripensare le form o i processi da zero)
Osservazioni
Chiudo con qualche osservazione pratica emersa lungo il percorso, utile a chi volesse provare un approccio simile:
- Claude Opus 4.8 con licenza Max è stato obbligatorio: la licenza Pro ha troppi pochi token per un progetto grosso e complesso come questo (l’applicazione client ha circa 4222 form, un progetto mastodontico)
- Sonnet 4.7 e Deepseek 3.6 non sono riusciti a produrre una documentazione al pari di Opus 4.8, nonostante tutte le skill a disposizione.
- Il ruolo dell’esperto di dominio come validatore rimane comunque fondamentale. L’IA accelera enormemente il lavoro, ma la validazione umana resta il passaggio che garantisce l’affidabilità del risultato.
Conclusioni
Quello che mi porto a casa da questa esperienza è che documentare un progetto legacy con l’IA può essere la chiave vincente per colmare un vuoto che si è formato in molti anni di carenze. Un altro insegnamento fondamentale è il costruire pazientemente gli strumenti giusti, skill, agenti e command, e soprattutto dare in pasto al modello solo fonti affidabili: i sorgenti e il database, non documentazione di seconda mano, vecchia o non aggiornata.
Il salto da un mese di lavoro a poche ore più la verifica è enorme, ma il vero valore è un altro: aver trasformato una conoscenza bloccata nel codice e in poche teste in una documentazione versionata, aggiornata e utilizzabile da tutto il team. E, come spesso accade, un buon lavoro di base apre porte che non avevi previsto: nel nostro caso, una skill che genera direttamente i componenti del nuovo frontend.
Spero che questo articolo vi sia piaciuto, grazie per essere passati qui sul mio blog!
