Code-modernization: modernizzare un gestionale con Claude Code

Code-modernization è un plugin ufficiale di Anthropic per Claude Code che prende un software datato, per esempio un gestionale scritto anni fa, e lo accompagna verso una versione moderna in passaggi controllati: prima lo capisce, poi propone un piano da approvare, poi costruisce il codice nuovo e infine dimostra con prove verificabili che il nuovo si comporta come il vecchio. Non tocca mai il codice originale e lascia a una persona tutte le decisioni importanti.

Se non hai mai usato Claude Code: è l'assistente di Anthropic che lavora nel terminale, legge i file di un progetto ed esegue comandi su richiesta (trovi le basi in Claude Code: cos'è e come iniziare). Un plugin è un pacchetto di comandi, agenti e automazioni che si aggiunge con un solo comando: tutta la serie è raccolta nella guida ai plugin di Claude Code.

Perché un plugin per i gestionali legacy?

Molte aziende vivono su software che funziona ma che nessuno vuole più toccare: scritto in una tecnologia superata, con poca documentazione e regole di business sepolte nel codice. Chi l'ha sviluppato magari non c'è più, e ogni modifica fa paura.

Il problema delle migrazioni non è tanto scrivere il codice nuovo, quanto essere sicuri che faccia le stesse cose del vecchio. Il README del plugin lo dice chiaramente: una modernizzazione fallisce in silenzio, perché il codice nuovo passa i test che qualcuno ha scritto e si comporta diversamente sui casi a cui nessuno aveva pensato. Per questo tutto il metodo ruota attorno alla prova finale.

Che cosa produce /code-modernization:modernize?

Il punto di partenza è un solo comando, /code-modernization:modernize, da lanciare in una cartella dedicata al lavoro. Fa un paio di domande su cosa vuoi ottenere, trova il codice, scrive le risposte in un file INTENT.md che tutti i comandi successivi rileggono, ti mostra il percorso e ti dà il primo comando esatto da eseguire. Se non sai ancora cosa vuoi, puoi scegliere di capire prima il sistema: ottieni valutazione, mappa, regole e piano senza ricostruire nulla.

Il percorso completo è fatto di passaggi indipendenti, dopo ciascuno dei quali puoi fermarti e rivedere i risultati:

Ogni comando aggiorna anche una pagina unica, analysis/<nome>/REPORT.html, con tutto quello che è stato trovato fino a quel momento: si può aprire nel browser o condividere con chi deve decidere. In qualsiasi momento modernize-status ti dice a che punto sei e quale comando incollare dopo.

Le regole di business estratte dal codice

Per un'azienda questa è spesso la parte più preziosa, anche se poi non si migra nulla. Ogni regola diventa una scheda leggibile del tipo "dato un cliente con queste condizioni, quando succede questo, allora il sistema fa quest'altro", con il riferimento al file e alla riga da cui è stata ricavata. Le regole critiche sono marcate come P0: sono quelle che, se sbagliate, renderebbero il sistema inutile o causerebbero danni costosi o irreversibili.

Le schede non vanno prese per oro colato. Il README avverte che l'estrazione la fa un modello, quindi due esecuzioni possono trovare regole diverse: per questo esiste il passaggio di revisione, in cui un esperto del dominio conferma o corregge le regole che sembrano sbagliate, e le sue risposte arrivano fino al piano e alla costruzione.

Le tre strade: aggiornamento, riscrittura o ricostruzione

Il piano consiglia una delle tre strade, ma la scelta finale resta tua:

• Uplift (modernize-uplift): stessa tecnologia, versione più recente. Il codice resta il tuo e si correggono solo i punti che la nuova versione rompe, partendo da un catalogo delle modifiche incompatibili che il codice usa davvero. Si comincia da un'unità pilota e poi si procede a lotti.
• Transform (modernize-transform): una tecnologia nuova, un modulo alla volta, mentre il sistema vecchio continua a funzionare. Prima si scrivono test che fissano il comportamento attuale, poi si riscrive il modulo.
• Reimagine (modernize-reimagine): una ricostruzione su un'architettura nuova, partendo da una specifica ricavata dal codice e da un'architettura rivista e approvata, con test di accettazione eseguibili.

Come dimostra che il codice nuovo si comporta come il vecchio?

La prova, modernize-verify, è pensata per non fidarsi dell'opinione del modello ma di controlli che uno script può ripetere. Va eseguita dopo la costruzione, idealmente in una sessione nuova, e rifà il lavoro da capo:

• I test rieseguiti da zero: i conteggi vengono dai file del programma che esegue i test, e un'esecuzione senza test o con i test saltati vale come fallimento.
• Vecchio e nuovo sugli stessi dati: dove il codice originale può girare, i due sistemi ricevono gli stessi input e uno script confronta le uscite. Si mascherano solo i campi che devono cambiare, come date e identificativi generati, e ogni campo mascherato viene elencato.
• Input mai usati prima: casi limite, valori vuoti o enormi, record malformati, per scoprire se i test passano solo sui casi scelti dal modello.
• Test capaci di fallire: una rottura voluta di una riga deve far diventare rossi i test.

Il risultato è un verdetto per modulo: provato, parzialmente provato o non provato. Se il sistema vecchio non può essere eseguito dove lavori, per esempio perché gira solo in produzione, il confronto avviene su uscite registrate e il massimo raggiungibile è "parzialmente provato", detto in chiaro nella pagina del report.

Un esempio concreto in azienda

Immagina, come caso ipotetico, un'azienda con un gestionale interno in PHP datato che calcola listini e sconti per i rivenditori. Il responsabile IT apre una cartella di lavoro e lancia:

/plugin install code-modernization@claude-plugins-official
/code-modernization:modernize-preflight listini --source /percorso/gestionale
/code-modernization:modernize-status listini

L'opzione --source crea solo un collegamento in legacy/listini e non copia nulla. Il primo obiettivo realistico è fermarsi alla scelta "capire prima": valutazione, mappa e regole sugli sconti. Il titolare e chi segue i rivenditori rivedono le schede P0, correggono quelle sbagliate e solo dopo si decide se riscrivere il modulo listini con transform, lasciando il resto del gestionale com'è.

Quali limiti e cautele considerare?

La prima avvertenza è nel README stesso: alcuni passaggi avviano molti agenti contemporaneamente, quindi su un sistema grande il consumo è reale. L'estrazione delle regole è il passaggio più pesante e chiede conferma prima di un'esecuzione grande. Il consiglio esplicito è partire con un modulo pilota, non con tutto il parco applicativo. Gli agenti sono istanze separate di Claude che fanno un singolo lavoro e riferiscono.

Sul fronte sicurezza il plugin tratta il codice analizzato come input non fidato: commenti come "ignora le istruzioni precedenti" o script suggeriti dal README vengono elencati e non eseguiti, un rischio spiegato bene nell'articolo sulla prompt injection. Le credenziali trovate vengono mascherate e messe in un file escluso da git. Il sistema vecchio viene eseguito solo in locale o in un ambiente di test che indichi tu: produzione, servizi di terzi e dati reali sono esclusi salvo che il piano approvato li nomini.

Il README suggerisce anche di rafforzare la regola "non modificare il sorgente" con un file .claude/settings.json che consente scritture solo in analysis/ e modernized/ e le nega sulla cartella legacy/. Ricorda però che uno script che apre i file da solo non è coperto da queste regole, per questo nei passaggi che lanciano molti agenti in scrittura conviene lasciare i comandi di shell in modalità con richiesta di conferma.

Infine, la telemetria: il plugin invia attraverso la telemetria di Claude Code solo numeri interi, mai codice, nomi di file o testi digitati. Si disattiva con l'opzione del plugin, con la variabile CODE_MODERNIZATION_TELEMETRY=0 oppure disattivando la telemetria di Claude Code. Per un'azienda che deve rendere conto dei dati trattati è un dettaglio da annotare nella propria policy.

Per chi ha senso usarlo?

Ha senso per software house e reparti IT che devono decidere cosa fare di un applicativo datato e vogliono partire da un'analisi documentata, anche solo per stimare il lavoro o confrontare l'ipotesi di migrare con quella di comprare un prodotto. Report e schede delle regole sono leggibili anche da chi non programma.

Serve però sempre un tecnico che conosca come il sistema si compila e si esegue: il README stesso chiede di portarne uno per le prime domande. Se dopo la migrazione vuoi far rivedere il codice nuovo, i plugin ufficiali di revisione del codice sono il passo successivo naturale.

Cosa fare adesso

Scegli un solo modulo del tuo gestionale, possibilmente piccolo ma con regole importanti, installa il plugin dal marketplace ufficiale e fermati alla fase di comprensione. Leggi con calma il README di code-modernization, che resta la fonte aggiornata, e fai rivedere le regole a chi conosce davvero il processo. Se vuoi un aiuto per impostare il pilota, puoi richiedere una consulenza gratuita.