Gli agenti non “scrivono male” il codice: siamo noi che gli diamo un codebase ingestibile

Negli ultimi mesi molti team stanno scoprendo un paradosso: più usi agenti per produrre codice velocemente, più rischi di costruire un codebase che rende gli stessi agenti lenti, costosi e imprecisi.

Non perché “l’AI scrive male” in assoluto, ma perché tende a ottimizzare per far funzionare la singola richiesta. Se non le imponi vincoli (struttura, riuso, confini, test, lint), spesso ottieni una sorta di vibe coding industriale: tanto output, poca architettura.

Il risultato è prevedibile: quando chiedi una modifica, l’agente deve leggere mezza codebase (o un file enorme), “sporcare” il contesto e spendere una quantità di token sproporzionata solo per capire dove mettere le mani.

Il problema reale: non è la scrittura, è la lettura

Gli agenti moderni passano una parte enorme del loro budget in:

• ricerca dei file rilevanti
• caricamento del contesto (file interi, dipendenze, porzioni ripetute)
• ricostruzione mentale di flussi e invarianti

Quando il progetto è strutturato male, la strategia più “sicura” per l’agente diventa includere troppo contesto. È un meccanismo difensivo: se non capisco dove sta la logica, mi porto dietro tutto.

Ed è qui che il clean code smette di essere solo una questione estetica o di manutenzione umana: diventa un’ottimizzazione diretta dei costi e delle prestazioni del coding assistito.

Un segnale chiarissimo: file monolitici e duplicazione

Un caso tipico (e sorprendentemente comune) è quello del “file-dio”:

• un singolo file da decine di migliaia di righe
• layer interi (es. data access, API, logica di dominio) mischiati
• porzioni copiate/incollate invece di funzioni riusabili
• nessun confine stabile (interfacce, moduli, responsabilità)

Quando l’agente deve cambiare “una cosa” lì dentro, non può ragionare per moduli: deve ragionare per scansione.

In uno scenario reale, la riduzione del file più grande (da ~17k righe a ~3k, tramite estrazioni e separazione in moduli) ha fatto crollare gli input token per change da circa 159k a ~27k: un risparmio nell’ordine dell’83%. Un dato interessante: gli output token sono rimasti relativamente stabili—segno che l’efficienza si guadagna soprattutto in lettura e contesto, non in scrittura.

Clean code per agenti: cosa cambia davvero

È importante essere onesti: “ripulire” il codice non garantisce automaticamente che l’agente risolva più task.

Studi controllati su repository “puliti vs resi sloppy” mostrano che la pass rate sui test nascosti tende a rimanere simile. In altre parole: un codebase più pulito non è magicamente più “corretto”.

Ma cambia altro, e spesso è ciò che paghi ogni giorno:

• meno input token (meno contesto necessario)
• meno revisite ai file (navigazione più efficiente)
• meno messaggi/iterazioni (minor “giro a vuoto”)
• tempo alla prima modifica più basso

Tradotto: costi minori, latenza minore, e meno probabilità che l’agente inventi collegamenti inesistenti perché il contesto è rumoroso o ridondante.

Perché i file grandi “inquinano” il contesto

Gli agenti devono decidere cosa caricare nella finestra di contesto. Se:

• una feature è sparsa senza un’API interna chiara
• la stessa logica è duplicata in 5 punti
• non esistono moduli con responsabilità definite

…l’agente non ha un “percorso” affidabile. E tende a fare la cosa più costosa: portarsi dietro l’intero file o intere porzioni di progetto.

Più contesto non significa più intelligenza: significa spesso più ambiguità. E l’ambiguità è il terreno perfetto per le allucinazioni.

Un approccio pragmatico: refactoring a piccoli passi, misurando

Un errore comune è chiedere: “ripulisci il codebase”. Gli agenti non sono bravi a scegliere in autonomia quali refactor siano sensati qui e ora senza una guida e senza vincoli.

Funziona molto meglio un ciclo disciplinato:

1. Definisci un obiettivo misurabile (es. ridurre dimensione dei file principali, deduplicare, creare moduli stabili).
2. Scegli un change rappresentativo (la stessa piccola feature/bugfix) e misura una baseline: token, tempo, file letti.
3. Applica un solo refactor per volta (estrazione funzioni, separazione moduli, creazione interfacce, ecc.).
4. Ripeti lo stesso change rappresentativo e confronta le metriche.
5. Procedi finché il rapporto costo/beneficio del refactor resta positivo.

Questo ha due vantaggi enormi:

• eviti mega-refactor rischiosi
• capisci quali interventi riducono davvero il “contesto necessario”

Cosa fare subito in un progetto “agent-first”

Se stai costruendo o ereditando un progetto dove gli agenti scrivono gran parte del codice, queste mosse hanno impatto quasi immediato:

• imporre limiti alla dimensione dei file (soft limit + refactor quando si sfora)
• deduplicare senza pietà (se l’agente copia/incolla, è un bug di processo)
• estrarre un data access layer vero con interfacce chiare
• modularizzare per responsabilità (non per “tipi di file”)
• aggiungere lint/format e test minimi: non per perfezionismo, ma per stabilizzare il terreno sotto i refactor

Sintesi: il clean code è diventato un acceleratore per l’AI

In un mondo in cui una parte del lavoro è “pagare” token e latenza per far capire all’agente cosa succede, la qualità strutturale del codice è una leva economica e operativa.

Il punto non è rendere il codice elegante: è renderlo leggibile a macchina e a umani, con confini netti e poco rumore. Così l’agente carica meno contesto, trova prima il punto giusto, sbaglia meno strada—e tu spendi meno per ottenere lo stesso risultato.

Se oggi il tuo codebase è un monolite pieno di duplicazioni, non stai solo accumulando debito tecnico: stai costruendo un progetto token-inefficiente. E quello, alla lunga, lo paghi a ogni singola modifica.