Il debito di comprensione: cosa l'AI accumula nella tua codebase mentre sembra accelerare

Negli ultimi sei mesi ricevo periodicamente la stessa domanda da chi gestisce team di sviluppo che hanno adottato Cursor, Copilot o Claude Code in modo aggressivo: l'output di codice è esploso, le velocity dashboard mostrano numeri da record, ma nei postmortem più recenti capita sempre più spesso che nessuno sappia più spiegare con precisione cosa fa un certo modulo, perché quella service boundary è stata disegnata in quel modo, o cosa dovrebbe succedere quando una specifica eccezione viene catturata. Il sistema funziona, fino a quando non smette, e a quel punto la risposta tecnica al problema diventa archeologia.

Esiste un nome preciso per questa condizione, e non è ancora entrato nel vocabolario dei dashboard di engineering management italiani. Si chiama debito di comprensione. È diverso dal debito tecnico in modo chirurgico: è invisibile, non lo accetti consapevolmente, non lo trovi in nessun report di SonarQube. E nei dodici mesi che vanno da gennaio 2025 a gennaio 2026, ha smesso di essere un'astrazione teorica ed è diventato un dato di fatto misurato su 211 milioni di righe di codice da GitClear, l'analisi più estesa pubblicamente disponibile sul code quality nell'era post-Copilot.

Il punto di questo articolo, e dei quattro che lo seguiranno nella stessa serie, è semplice: la diagnosi del coding AI 2026 non è "l'AI scrive codice peggiore". È molto peggio. Sta riscrivendo le regole di chi è in grado di capire il codice che gestiamo, e a chi spetta il costo quando il sistema non si comporta come previsto.

Cosa significa che il codice non è mai stato così costoso?

Per anni la narrativa dominante ha trattato il codice come una commodity da minimizzare. Meno righe scritte, più valore. La promessa della seconda metà 2024 e del 2025, sotto la spinta dell'AI generativa applicata al coding, è stata l'estensione naturale di quella narrativa: il codice diventa così cheap che non vale più la pena curarlo, basta rigenerarlo.

Non funziona così, e i numeri stanno cominciando a inchiodarlo. Il principio operativo lo hanno sintetizzato Hunt e Thomas in un libro del 1999 che gli ingegneri italiani senior conoscono come The Pragmatic Programmer, nel suo Topic 3 dedicato alla software entropy: ogni modifica fatta a un sistema senza pensare al sistema nel suo complesso aumenta il disordine totale. La metafora termodinamica non è un vezzo letterario, è una proprietà strutturale del modo in cui i sistemi software degradano nel tempo. Quando l'unità di lavoro diventa "rigenera questo modulo dato il prompt corrente", e nessuno tiene viva la memoria del perché il modulo era stato disegnato in un certo modo sei mesi prima, l'entropia accelera.

Il debito tecnico è una scelta esplicita: hai scritto codice meno pulito di quanto avresti potuto in cambio di velocità a breve termine, e sai che dovrai rifondarlo prima o poi. Il debito di comprensione è il gap tra quanto codice esiste nel tuo sistema e quanto codice una persona qualunque del tuo team è in grado di spiegare. Cresce in modo invisibile perché non c'è una metrica unica che lo cattura. Cresce in modo silenzioso perché ogni singolo commit, preso da solo, è ragionevole. Cresce in modo cumulativo perché il codice generato da modelli probabilistici tende a stratificare assunzioni implicite invece di renderle esplicite.

Nel mio orchestrator personale per task tecnici interni, dove combino agent Claude Code con strumenti di analisi statica, ho impostato come primo gate operativo la generazione di una mappa cognitiva esplicita della codebase prima che qualunque agente abbia il permesso di toccare il codice. Quella mappa, scritta in markdown come asset vivo del repository, contiene tre cose: il modello di dominio in linguaggio condiviso, le decisioni architettoniche con relativa motivazione (le ADR canoniche), e le invarianti di sistema che il codice deve rispettare anche dopo refactoring. Senza quella mappa, il prompt più sofisticato non sostituisce la conoscenza che manca all'agente. Con quella mappa, l'output AI diventa molto più allineato all'intento, perché il modello non deve indovinare il perché.

Che cos'è il debito di comprensione, e perché non lo trovi nei tuoi dashboard?

Risposta secca: il debito di comprensione è la differenza tra le righe di codice presenti nel tuo sistema e le righe che almeno una persona del tuo team è in grado di spiegare in un postmortem. Non lo trovi nei dashboard perché tutti i tool standard di engineering management misurano output, non comprensione. Velocity, throughput, lines of code, change failure rate: questi rispondono alla domanda "quanto produciamo", non alla domanda "quanto capiamo di quello che gestiamo".

Per misurarlo serve un esperimento mentale che faccio sempre quando audito una codebase recente: prendo a campione cinque file modificati negli ultimi tre mesi e chiedo all'autore originario di spiegarmi, senza guardare il codice, perché certe scelte sono state fatte. Nelle codebase pre-Copilot la percentuale di risposta che include "perché ricordo bene la conversazione con il product owner" o "perché c'era un bug specifico che ci aveva colpito" oscilla tra il 60% e l'80% per chi ha scritto il codice. Nelle codebase post-Copilot, dove l'autore ha generato una porzione significativa del modulo via agente AI accettando rapidamente la prima proposta sintatticamente corretta, quella percentuale scende sotto il 30%. La risposta tipica diventa "non ricordo, lasciami guardare il codice", che è esattamente l'inversione di responsabilità che il debito di comprensione introduce: il codice diventa la fonte di verità unica, perché la spiegazione non esiste più nella testa di nessuno.

Il problema operativo è che questa erosione non è recuperabile retrospettivamente. Una volta che la decisione architettonica è stata generata da un modello probabilistico che non ha memoria persistente del contesto del progetto, e una volta che lo sviluppatore l'ha accettata senza interrogarla, l'intento originario semplicemente non è mai stato formulato. Non c'è nulla da ricostruire. Nei postmortem questo si manifesta come la frase più costosa che un senior può sentire alle 2 di notte: "non so perché abbiamo scritto questa porzione in questo modo".

La contromisura, quando ti accorgi che la tua codebase ha già accumulato debito di comprensione significativo, non è documentazione retroattiva fatta ancora dall'AI, perché l'AI non può documentare un intento che non possiede. La contromisura è una disciplina di indicizzazione semantica e di governance dei prompt come codice, in cui ogni intervento dell'agente AI viene tracciato insieme al suo contesto decisionale, e le decisioni stesse diventano artifact di prima classe nel repository.

Se gestisci un team di sviluppo che ha adottato AI coding in modo intensivo negli ultimi dodici mesi e vedi le velocity dashboard verdi mentre i postmortem peggiorano, nel mio hub dedicato all'AI per aziende trovi la metodologia che applico per condurre audit di debito di comprensione su codebase reali, con artefatti concreti e KPI misurabili.

Cosa dicono i numeri di GitClear su 211 milioni di righe?

GitClear ha pubblicato a febbraio 2025 un'analisi che è diventata il riferimento empirico per chiunque debba parlare di code quality nell'era AI con dati e non con sensazioni. Il dataset copre 211 milioni di righe di codice modificate tra gennaio 2020 e dicembre 2024, raccolte da repository privati anonimizzati e dai 25 progetti open source più grandi. Le righe analizzate sono già filtrate dal noise (file auto-generati, sub-repo, criteri di esclusione documentati), e quindi rappresentano un campione comparabile nel tempo.

I numeri principali sono questi:

• Il code churn, cioè la percentuale di righe nuove riscritte o cancellate entro due settimane dalla loro stesura, è passato dal 5,5% del 2020 al 7,9% del 2024. È l'indicatore più diretto di quanto codice viene introdotto e poi corretto in modo affrettato perché la prima versione non era effettivamente quello che serviva. Una crescita relativa di circa il 44%.
• La quota di righe copy/pasted (cloni) è cresciuta dall'8,3% del 2020 al 12,3% del 2024, una crescita relativa del 48%.
• La frequenza di blocchi di cinque o più righe duplicati rispetto a codice adiacente è aumentata di otto volte solo nel 2024 rispetto al 2022. Questo è il dato più allarmante sulla qualità strutturale: blocchi più lunghi di duplicato sono il segnale più affidabile che il pattern matching dell'AI sta producendo varianti di codice esistente invece di estrarre l'astrazione condivisa.
• La quota di righe associate a refactoring (linee "moved" nel modello GitClear) è crollata dal 24,1% del 2020 al 9,5% del 2024. Per la prima volta nella storia del dataset, il 2024 segna l'anno in cui l'introduzione di codice ripetuto ha superato l'attività di refactoring. Letteralmente: stiamo costruendo più copie di quante ne stiamo consolidando.

A questi numeri si aggiunge un dato secondario ma rivelatore dello stesso report: la quota di righe revisionate che erano state scritte più di un mese prima è scesa dal 30% del 2020 al 20% del 2024. Tradotto operativamente, stiamo riscrivendo principalmente il codice nuovo, non stiamo migliorando il codice vecchio. Il time-to-revision si comprime, e con esso lo spazio per accumulare quella memoria di progetto che permetteva il refactoring informato.

Tradotto in termini di business per un CTO o direttore tecnico di una PMI italiana: i tuoi sviluppatori stanno producendo più codice e correggendolo più velocemente, e contemporaneamente stanno riscrivendo lo stesso pattern otto volte invece di consolidarlo, e stanno smettendo di refattorizzare quello che hanno scritto sei mesi fa. Il risultato visibile è uno sprint che sembra produttivo. Il risultato strutturale, a sei o nove mesi, è un sistema che diventa progressivamente più costoso da mantenere e che concentra tutta la conoscenza sui pochi senior che riescono ancora a ricostruire l'intento.

Il calcolo economico cambia. Se il codice fosse davvero cheap, l'ottuplicazione dei duplicate blocks sarebbe irrilevante. Ma il costo reale del codice non è la sua scrittura, è la sua manutenzione cumulativa nel tempo, ed è esattamente la manutenzione che si degrada quando il refactoring crolla del 60% in quattro anni. Il codice non è mai stato così costoso, perché non è mai stato così frammentato e così duplicato.

Cos'è l'AI slop, e perché "compila e passa i test" non è più sufficiente?

Il termine AI slop descrive un fenomeno preciso: codice syntactically correct e semantically wrong. Compila, passa i test unitari di superficie, supera il code review se chi lo riguarda non chiede troppo, ma rompe silenziosamente assunzioni architettoniche che il modello non poteva conoscere perché non erano contenute nel suo training data. È l'equivalente software di un contractor edile che costruisce esattamente quello che il blueprint dice, ma il blueprint era stato scritto per un altro edificio: tutto si incastra, niente funziona.

Il meccanismo che produce AI slop è strutturale al modo in cui gli LLM generano codice: pattern matching sui repository pubblici di addestramento. Il modello non sa perché esiste una specifica service boundary nel tuo sistema, non sa che sei mesi fa il product team ha cambiato il significato di un campo del modello dati, non sa quali invarianti il tuo sistema deve mantenere quando un certo evento esterno arriva. Sa solo come, statisticamente, codice simile è stato scritto altrove, in altri contesti, da altre persone con altri vincoli. Quando il tuo contesto coincide con il pattern dominante nel training set, l'output sembra brillante. Quando il tuo contesto è specifico, l'output passa la verifica sintattica ma rompe la semantica.

Perché "compila e passa i test" non è più sufficiente? Perché il test set è sempre stato un sottoinsieme parziale del comportamento atteso del sistema. Negli anni in cui il codice era scritto da umani con memoria del progetto, il gap fra "test pass" e "comportamento corretto" era colmato dall'intuizione del developer che, scrivendo il codice, percepiva istintivamente quando un edge case meritava attenzione anche se non era nei test. Quel ponte umano si rompe quando l'autore del codice è un agente probabilistico senza memoria persistente del dominio. Il test set diventa l'unico oracolo disponibile, e ogni cosa che il test set non controlla diventa terreno di produzione di slop.

Nel mio MCP server interno per task di code review automatizzata ho implementato come gate post-generazione una validazione semantica contro le ADR del repository. Ogni patch generata da un agente AI passa attraverso un check che confronta le decisioni implicite della patch (quali interface vengono toccate, quali invarianti sono potenzialmente rotte, quali service boundary vengono attraversate) contro le decisioni esplicitamente registrate nelle ADR. Se la patch implica una decisione che contraddice un'ADR, il commit viene bloccato e l'agente riceve come feedback la specifica ADR violata. Non è una soluzione perfetta perché richiede che le ADR esistano e siano mantenute, ma è l'unico modo che ho trovato per istituzionalizzare la differenza tra "compila e passa i test" e "è coerente con l'intento del sistema".

Per chi gestisce un team che ha adottato AI coding senza questo tipo di guardrail, il rischio è di vedere il count di patch accettate crescere mentre il numero di postmortem in cui la causa radice è "abbiamo violato un'invariante che pensavamo fosse ovvia" cresce ancora più velocemente. Quando un team comincia a discutere di data sovereignty per il codice AI, o di hardening delle pipeline LLM contro vulnerabilità della supply chain, il discorso si apre naturalmente sulla disciplina di intent management che dovrebbe esserci a monte di qualunque integrazione AI seria.

Se stai gestendo un team di sviluppo che ha adottato AI coding in modo intensivo nell'ultimo anno e i tuoi indicatori di velocità raccontano una storia diversa rispetto ai tuoi indicatori di stabilità, è probabile che il debito di comprensione sia già accumulato a un livello che il prossimo sprint da solo non riassorbirà. La diagnosi precisa di questo debito richiede un audit specifico che combina analisi quantitativa (churn, code clones, refactoring rate sulla traccia GitClear) con valutazione qualitativa dell'intent ownership rimasto nel team. È un lavoro che ho strutturato come servizio dedicato negli ultimi dodici mesi, perché quasi tutte le PMI italiane che adottano AI coding senza disciplina formale arrivano nello stesso punto a cinque-sette mesi dall'introduzione: dashboard verdi, postmortem peggiorati, e nessuno dentro che sappia da dove cominciare a recuperare. Se sospetti di essere a quel punto, il modulo di preventivo gratuito ti permette di descrivere la situazione in due minuti e ti rispondo subito se rientra nel mio perimetro di intervento. Nei prossimi articoli di questa serie analizzo le cascate sistemiche che il debito di comprensione produce su sicurezza e produttività, le contromisure architetturali concrete che applico nelle pipeline che gestisco, e il riposizionamento di carriera che chi gestisce sviluppo AI deve costruire per non diventare il prossimo postmortem.