Agenti IA e codice legacy: come usarli senza rompere ciò che funziona
Contesto, confini e test di caratterizzazione: tre pilastri per far lavorare gli agenti di IA sul codice legacy in sicurezza. Con un caso pratico su Rails.

Il codice legacy è software che esiste da anni, produce valore ogni giorno e contiene decisioni che in azienda nessuno ricorda più. Molto spesso è un’applicazione con dieci anni di regole che sono evolute insieme al business, dipendenze intrecciate e test che coprono solo una parte del sistema.
Quasi tutto ciò che si legge sugli agenti di IA per la programmazione parla di progetti nuovi. Questo articolo parla di codice esistente. Non spiega come chiedere a un agente di scrivere una funzione, ma come impedirgli di rompere il sistema di fatturazione mentre aggiorna una dipendenza. In questo articolo andremo a descrivere il metodo che seguiamo noi, in tre pilastri: contesto, confini e test di caratterizzazione. Per descrivere tutto ciò utilizzeremo un caso pratico: l’aggiornamento di un’applicazione Ruby on Rails dalla versione 6 alla 8.1.
Perché il codice legacy è il vero banco di prova
La maggior parte del software che fa funzionare un’azienda non è nuovo. È il gestionale, il sistema di fatturazione, il portale clienti scritto anni fa e cresciuto un pezzo alla volta. Se gli agenti di IA devono essere utili in azienda, è lì che devono lavorare: capire, manutenere, aggiornare. È il lavoro che nessuno vuole fare a mano e quello che i tutorial non mostrano.
Un tutorial non corrisponde mai a codice reale
Il format è sempre lo stesso: un agente scrive in cinque minuti un’app per gestire una TODO list, il video finisce e tutto sembra perfetto. È un’applicazione costruita nelle condizioni migliori possibili: il codice ha cinque minuti di vita, l’ha scritto un solo autore e sta tutto in tre file. Nessuna scorciatoia presa anni prima, nessuna convenzione rispettata a metà, nessun intreccio da districare.
Il vostro codice è l’opposto. L’agente che ha brillantemente creato l’applicazione del tutorial non ha mai visto due moduli che si chiamano a vicenda, scritti nel 2016 da una persona che non lavora più in azienda. Quello che il tutorial dimostra non è che l’agente sa lavorare sul vostro sistema: è che sa lavorare dove non c’è ancora niente da rompere.
Il debito invisibile
Nel codice legacy la documentazione, quando esiste, descrive il sistema di tre versioni fa. La verità è nel codice, e il codice dice cosa fa, non perché lo fa. I test, se ci sono, coprono i percorsi che qualcuno ha avuto tempo di coprire.
Un agente entra quindi in un sistema di cui nessuno, né la persona né la macchina, conosce per intero il comportamento atteso. La domanda non è “l’agente sa scrivere buon codice?”. La domanda è: cosa succede quando lo scrive senza sapere cosa non deve cambiare?
Il rischio: la regressione silenziosa
Chiamiamo regressione silenziosa una modifica del comportamento che supera la code review, supera i test automatici e viene scoperta in produzione. Non è un errore di sintassi: il codice è pulito, i nomi sono sensati, la modifica sembra ragionevole. L’agente ha “capito” una regola di business che non esisteva, oppure ha semplificato un caso particolare che qualcuno aveva gestito apposta.
Il problema non è la qualità del modello. Il problema è mettere uno strumento probabilistico a lavorare su un sistema che dovrebbe essere deterministico, e di cui nessuno ha mai fissato il comportamento corretto.
Un esempio: l’agente tocca la fatturazione
Immaginiamo un compito innocuo: “sposta la logica di arrotondamento in una funzione condivisa”. L’agente trova tre punti in cui si arrotonda, li unifica in una funzione elegante, aggiorna il codice che la chiama. Quaranta righe modificate, code review in due minuti.
Uno dei tre punti però arrotondava per difetto, non per eccesso, perché una norma fiscale di un mercato specifico lo richiede. Non c’era un commento. Non c’era un test. C’era solo un floor al posto di un round, e l’agente lo ha letto come un’incoerenza da correggere.
Questo è un caso d’uso inventato, ma lo scenario è realistico: una regola non documentata, un test che manca, una modifica che sembra un miglioramento. Il primo ad accorgersene sarebbe il cliente, settimane dopo, con un centesimo sbagliato su ogni riga di fattura.
Troppi strumenti, nessuna regola comune
C’è un secondo rischio, meno drammatico ma più diffuso. Nel 2026, in un team distribuito, non c’è “lo strumento di IA”: c’è Copilot per il completamento automatico, Cursor per chi vive nell’editor, Claude Code per gli interventi pesanti da terminale. Tre agenti, tre file di istruzioni, tre versioni di “come si fanno le cose qui”.
Senza regole comuni ogni agente riceve un contesto leggermente diverso e prende decisioni leggermente diverse. Il repository accumula convenzioni divergenti più in fretta di quanto una persona possa riconciliarle. L’IA, in questo scenario, non riduce il debito tecnico: lo moltiplica.
Primo pilastro: il contesto
Un nuovo assunto in azienda non riceve solo le credenziali del repository. Riceve un inserimento: quali moduli sono intoccabili, quali convenzioni sono negoziabili, chi decide cosa. Un agente ha bisogno dello stesso trattamento, in una forma che possa leggere.
Un file per ogni strumento, le regole di dominio scritte una volta sola
Ogni strumento legge il proprio file di istruzioni, e la tentazione è duplicare tutto ovunque. È un errore: le regole del dominio vanno scritte una volta sola.
| File | Chi lo legge | Cosa contiene |
|---|---|---|
AGENTS.md |
Formato neutro, letto da più strumenti | Regole di dominio comuni, mappa del repository, aree critiche |
CLAUDE.md |
Claude Code | Convenzioni specifiche di quello strumento: comandi, hook, flussi di lavoro |
.cursorrules |
Cursor | Preferenze di scrittura e stile nell’editor |
La regola è semplice. Se un’indicazione vale per qualunque agente (“il modulo billing/ non si tocca senza approvazione”), sta nel file neutro. Se vale per un solo strumento (“usa bin/rails test e non rspec”), sta nel file di quello strumento.
Il file principale rimanda, i file di dominio spiegano
Nei repository grandi conviene che il file principale non contenga le regole, ma dica dove trovarle:
/
├── AGENTS.md ← mappa dei domini e rimandi
├── CLAUDE.md ← "leggi AGENTS.md, poi le regole specifiche di Claude"
├── .cursorrules ← "leggi AGENTS.md, poi le regole specifiche di Cursor"
├── billing/
│ └── AGENTS.md ← regole del dominio fatturazione
├── inventory/
│ └── AGENTS.md ← regole del dominio magazzino
└── legacy_reports/
└── AGENTS.md ← "sola lettura, vedi sezione Confini"
Il file principale dice a ogni agente dove guardare. I file di dominio dicono cosa vale lì dentro. I file di strumento aggiungono solo ciò che è specifico. Quando il team cambia strumento, cambia un file, non venti.
Far capire a un agente un sistema che non gli sta in testa
Il contesto ha un limite fisico: un agente legge una quantità finita di testo per sessione, e un’applicazione di dieci anni non ci sta. Chiedergli di “capire il sistema” in un colpo solo produce riassunti superficiali e una sicurezza mal riposta.
Funziona meglio procedere per strati. Nel file principale si mette una mappa del repository: quali cartelle contengono cosa, quali sono i punti di ingresso, quali le tabelle principali. È una pagina, non un trattato, e l’agente la legge a ogni sessione. Poi si lavora un modulo alla volta: si chiede all’agente di leggere una singola area e di scrivere cosa fa, chi la chiama e cosa chiama, senza modificare nulla. Quel riassunto, corretto da chi conosce il sistema, diventa il file di dominio di quell’area. Alla sessione successiva l’agente non riparte da zero: parte dalla mappa e dai riassunti, e legge il codice solo dove serve.
È lo stesso lavoro che fa un collega nuovo nel primo mese, con la differenza che l’agente lo scrive tutto e non lo tiene a mente.
Secondo pilastro: i confini
Un file di istruzioni contiene indicazioni. Un modello linguistico le segue nella grande maggioranza dei casi, ma “la grande maggioranza dei casi” non è una soglia accettabile per il sistema di fatturazione, dove le regole devono valere “sempre”.
Chiamiamo confini le aree del repository in cui l’agente può leggere ma non scrivere, dove il divieto è imposto da qualcosa che non è un’istruzione testuale. Si costruiscono a più livelli, e nessuno da solo è sufficiente.
Primo livello: i permessi dello strumento
Claude Code permette di vietare la modifica di percorsi specifici nel file di configurazione del progetto, versionato insieme al codice e quindi valido per tutto il team:
{
"permissions": {
"deny": [
"Edit(./billing/**)",
"Edit(./legacy_reports/**)"
]
}
}
Bastano poche righe: l’agente può leggere quelle cartelle, ma ogni tentativo di scrittura viene rifiutato prima di arrivare al disco. Gli altri strumenti hanno meccanismi simili; il principio è lo stesso.
Secondo livello: un hook che registra e decide
Se serve più flessibilità (registrare i tentativi, bloccare solo certi tipi di file, chiedere conferma), Claude Code offre gli hook: piccoli programmi che si attivano prima che l’agente usi uno strumento. Un hook PreToolUse su Edit e Write riceve il percorso che l’agente vuole modificare e può fermarlo.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{ "type": "command", "command": "./scripts/controllo-confini.sh" }
]
}
]
}
}
#!/usr/bin/env bash
# controllo-confini.sh: blocca le scritture nelle aree protette e le registra
path=$(jq -r '.tool_input.file_path')
case "$path" in
*/billing/*|*/legacy_reports/*)
echo "$(date -Iseconds) tentativo di scrittura: $path" >> .agent-audit.log
echo "CONFINE: $path è in area protetta. Serve approvazione umana." >&2
exit 2 ;;
esac
exit 0
Il vantaggio è che l’hook agisce sull’intenzione, quindi lascia una traccia: a fine sessione si sa quante volte l’agente ha provato a entrare dove non doveva, ed è un’informazione preziosa su quanto ha capito del sistema. Il limite è che vale per un solo strumento. Nomi e formati cambiano spesso: va sempre controllata e manutenuta la documentazione aggiornata.
Terzo livello: il file system
L’ultimo livello è il più semplice e funziona con qualsiasi agente, presente o futuro: togliere i permessi di scrittura ai file, lasciando quelli di lettura e l’accesso alle cartelle.
find billing legacy_reports -type d -exec chmod 555 {} +
find billing legacy_reports -type f -exec chmod 444 {} +
L’agente legge, analizza, propone. Se prova a scrivere, fallisce, e il fallimento è un’informazione: stava toccando qualcosa che non doveva. La modifica passa allora per un canale esplicito: una persona che toglie il blocco, oppure la pipeline di integrazione continua che applica la modifica solo dopo che i test sono passati.
Va detto con chiarezza cosa questo livello non fa. Un agente con accesso alla shell può ripristinare i permessi da solo, e Git non li conserva: il blocco vale sulla macchina dove è stato impostato e non si propaga ai colleghi né ai server. Non è una barriera contro un agente che vuole aggirarla; è una rete contro un agente che sbaglia. Nella pratica è il caso di gran lunga più frequente, e per questo il livello vale la pena.
I tre livelli insieme sono una difesa a strati: le regole di permesso danno una garanzia condivisa dal team, l’hook dà visibilità, il file system copre gli strumenti che non prevedono nessuno dei due.
Terzo pilastro: i test di caratterizzazione
I confini dicono all’agente dove non può andare. Non dicono nulla su cosa può fare dove può andare. Per questo serve una rete: un modo per sapere, in automatico, se il comportamento visibile del sistema è cambiato.
Nel codice legacy questa rete di solito non esiste, e l’istinto è farla costruire all’agente mentre modifica il codice. È l’ordine sbagliato. Il primo compito dell’agente su un sistema esistente non è scrivere logica: è fotografare il comportamento attuale e fissarlo.
Fotografare ingressi e uscite
Michael Feathers, in Working Effectively with Legacy Code, li chiama test di caratterizzazione: test che non verificano che il sistema sia corretto, ma che si comporti come ieri. Si prende un ingresso rappresentativo, si registra l’uscita esatta, e da quel momento ogni modifica deve riprodurla al byte. Quando l’uscita è un documento intero, come una fattura, si parla anche di Golden Master.
RSpec.describe InvoiceCalculator, :characterization do
Dir["spec/fixtures/invoices/*.json"].each do |fixture|
it "riproduce l'uscita registrata per #{File.basename(fixture)}" do
input = JSON.parse(File.read(fixture))
golden = File.read(fixture.sub(".json", ".golden"))
expect(InvoiceCalculator.new(input).render).to eq(golden)
end
end
end
Per chi non legge Ruby: il test prende ogni file di esempio nella cartella, calcola la fattura e la confronta carattere per carattere con la versione salvata in precedenza. Se differisce anche di un centesimo, il test fallisce.
Qui l’agente è eccellente: generare centinaia di casi di test da dati di produzione anonimizzati è lavoro di quantità, e la quantità è il suo punto di forza. Il valore umano sta altrove: scegliere quali percorsi fotografare.
Il ciclo diventa: registrare le uscite, salvare il riferimento, lasciare lavorare l’agente, confrontare. Se il confronto non è identico le possibilità sono due: l’agente ha sbagliato oppure il riferimento va aggiornato in modo consapevole. In entrambi i casi la regressione non è più silenziosa.
Rivedere il lavoro dell’agente
I test dicono se qualcosa è cambiato; non dicono se la modifica è buona. Quella parte resta a una persona, e nell’esempio della fatturazione la code review di due minuti era proprio l’anello debole.
Con il codice generato da un agente conviene cambiare il modo di rivedere. Non si legge la modifica chiedendosi “è scritta bene?” (di solito lo è) ma “cosa faceva prima questo pezzo, e perché?”. Ogni riga cancellata merita più attenzione di ogni riga aggiunta: è lì che spariscono i floor messi apposta. E le modifiche vanno fatte poco alla volta: un intervento da quaranta righe lo si rilegge sul serio, uno da quattrocento si approva per sfinimento.
Riportare le scoperte nei file di dominio
Ogni sessione di questo tipo produce conoscenza: l’agente scopre che quel floor non era un errore, che un campo chiamato status_2 è in realtà lo stato fiscale, che una tabella si chiama tmp_orders dal 2017 ed è la tabella principale.
Questa conoscenza va scritta nel file di dominio (billing/AGENTS.md), non lasciata scomparire a fine sessione. È il punto in cui i tre pilastri si toccano: i test scoprono il dominio, il dominio finisce nel contesto, il contesto migliora le sessioni successive. Dopo qualche ciclo l’agente sa del vostro sistema più di quanto sapesse l’ultimo collega esperto prima di andarsene.
Caso pratico: aggiornare Ruby on Rails dalla 6 alla 8.1
Da Rails 6.0 a Rails 8.1 ci sono sei passaggi: 6.1, 7.0, 7.1, 7.2, 8.0, 8.1. La tentazione è riscrivere tutto, e la riscrittura è dove i progetti muoiono. L’approccio che funziona è graduale, una versione alla volta, con i tre pilastri attivi.
Due versioni in parallelo con next_rails
La libreria next_rails permette di mantenere due Gemfile, quello attuale e Gemfile.next, ed eseguire applicazione e test su entrambe le versioni.
bundle add next_rails
next --init # genera Gemfile.next
# in Gemfile.next: gem "rails", "~> 6.1.0"
next bundle install
next rails test # test sulla versione nuova
bin/rails test # test sulla versione attuale
È la stessa logica dei test di caratterizzazione, portata al livello del framework: la versione vecchia è il riferimento, la nuova è il candidato. Finché i test non passano su entrambe, non si avanza.
Il flusso passo per passo
- Lo sviluppatore alza
Gemfile.nextdi una versione e lancianext rails test. - L’agente riceve la lista degli avvisi di deprecazione e dei test falliti, con i confini attivi su
billing/e sulle altre aree critiche. - L’agente corregge una deprecazione alla volta, su un ramo separato, e ogni modifica viene verificata con entrambi gli insiemi di test.
- Quando i test passano, lo sviluppatore incrementa
config.load_defaultsdi una versione, mai di più, e il ciclo riparte. - Ciò che l’agente ha imparato sul dominio finisce nei file
AGENTS.md. - Quando
Gemfile.nextè alla 8.1 e i test passano, i dueGemfilesi fondono.
Il lavoro dell’agente è meccanico e voluminoso: rinominare chiamate, aggiornare configurazioni, adattare test. Il lavoro dello sviluppatore è decidere quando avanzare e cosa non toccare. La stessa struttura vale per Laravel, Django o qualunque applicazione con una lunga storia di versioni.
Da dove iniziare: ecco la nostra check-list
La domanda giusta non è “l’IA sa scrivere codice?”. La risposta è sì da anni. La domanda è “come evito che l’agente rompa qualcosa di cui non aveva il contesto?”. In ordine di adozione:
- Un
AGENTS.mdprincipale con la mappa del repository e i rimandi ai file di dominio. - Un file di dominio per ogni area critica, con le regole di business esplicite.
- Regole di permesso nello strumento che vietano la scrittura nelle aree protette.
- Un hook che registra i tentativi di scrittura bloccati.
- Permessi di sola lettura sul file system, per gli strumenti che non prevedono i punti 3 e 4.
- Test di caratterizzazione sui percorsi di business critici, generati dall’agente e scelti da una persona.
- Modifiche piccole e code review che guarda prima alle righe cancellate.
- Un passaggio esplicito che riporta le scoperte dell’agente nei file di dominio.
- Per gli aggiornamenti: due versioni in parallelo e un passaggio alla volta, nessuna fusione senza test verdi su entrambe.
Si parte da una domanda sul vostro repository: quali aree sono il vostro billing/? Se la risposta richiede più di dieci minuti, è lì che l’agente farà il primo danno.
In conclusione
I tre pilastri non sono un’invenzione dell’era degli agenti. Contesto scritto, confini che non si possono ignorare e test che fotografano il comportamento attuale sono le stesse cose che rendono manutenibile un sistema di dieci anni anche senza IA. L’agente non cambia il problema: lo accelera, e insieme al lavoro accelera anche il danno quando quei tre pilastri mancano. È per questo che la check-list parte dal vostro billing/ e non dallo strumento: lo strumento è la parte facile.
Tutto questo ha un costo, ed è giusto dirlo: più esecuzioni di test nell’integrazione continua, un passaggio in più a fine sessione per riportare le scoperte nei file di dominio, revisioni più lente perché devono guardare il perché e non solo il come. Si contiene tenendo i test di caratterizzazione sui percorsi che contano davvero, e resta comunque inferiore a quello di una regressione silenziosa scoperta dal cliente. Ma il guadagno non è andare più veloci. È che, quando qualcosa cambia nel vostro billing/, lo sapete voi prima del cliente.