Quando la documentazione diventa un caos irreversibile

Ti è mai capitato di aprire un vecchio file CLAUDE.md e ritrovarti davanti a un ammasso di istruzioni che nessuno capisce più bene da dove vengano?

Non sei solo. È una storia che si ripete ovunque.

Una ricerca ha analizzato quasi 250.000 istruzioni distribuite su quasi 2.000 repository. Il risultato? I prompt per agenti AI non crescono, esplodono: in media triplicano di dimensione durante il loro ciclo di vita. Ogni singolo commit aggiunge 4,9 istruzioni nette. Il file non si riduce mai. Solo si espande.

E c'è dell'altro. Più un'istruzione resta lì, meno probabilità ha di essere cancellata. È come se il tempo la rendesse immortale. Nessuno sa più se si può toccarla senza rompere qualcosa di importante.

Il problema dell'O(2^|D|)

Come mai succede questo? I ricercatori parlano di "memoria catastrofica", il contrario del famoso "oblio catastrofico" nel machine learning. Ma la spiegazione è più semplice di quanto sembri.

Aggiungere un'istruzione è economico. Vedi un problema, scrivi una soluzione, vai avanti. Il costo immediato è basso.

Rimuoverla? Questo è tutto un altro discorso. Devi capire ogni punto in cui potrebbe avere effetto. Devi ragionare su tutte le interazioni con le altre istruzioni. Devi verificare che non salti fuori qualche bug sottile. Il costo cognitivo cresce in modo esponenziale con il numero di istruzioni esistenti: O(2^|D|).

Quindi i developer fanno quello che chiunque farebbe: la smettono di provarci. Aggiungono, non tolgono mai.

I commenti: l'eroe sottovalutato

Qui arriva la parte interessante. La soluzione non sta in tecniche di prompting più sofisticate o modelli più intelligenti. Sta in qualcosa che esiste da quando esiste la programmazione: i commenti.

I ricercatori hanno creato dei benchmark dove la risposta ottimale era conosciuta. Hanno aggiunto commenti che spiegavano il ragionamento dietro le istruzioni. Risultato? La crescita dei prompt è scesa da +211% a +1,4%. Quasi il 99% in meno.

Ma non finisce qui. Questi commenti hanno anche migliorato del 23% la capacità di seguire le istruzioni su task reali. I commenti non sono confusione organizzativa. Sono strutture portanti che aiutano l'AI a ragionare correttamente sul contesto.

Perché è importante adesso

Stiamo vivendo un cambiamento profondo nel significato di "codice". I ricercatori lo chiedono in modo diretto: se l'inglese è il nuovo codice, perché non abbiamo ancora i commenti?

Per decenni i developer hanno capito che codice senza commenti è debito tecnico. I commenti spiegano il "perché", non solo il "cosa". Catturano l'intenzione, gestiscono i casi limite, conservano la conoscenza istituzionale che non puoi dedurre dalla sintassi.

Eppure, nella corsa a delegare sempre più agli assistenti AI, abbiamo trattato le istruzioni in linguaggio naturale come se fossero diverse. Scriviamo ordini – fai questo, non fare quello, ricordati di controllare X – senza spiegare il ragionamento.

Il risultato sono quei file CLAUDE.md che tutti conosciamo: istruzioni che nessuno capisce del tutto, che forse si contraddicono, e che crescono senza alcun meccanismo di razionalizzazione.

Cosa fare

Se mantieni un file CLAUDE.md o simile, la ricerca suggerisce:

1. Commenta le tue istruzioni, non solo il codice. Spiega perché esiste una regola. Documenta i casi limite. Cattura il ragionamento dietro le decisioni.

2. Fai razionalizzazioni periodiche. Non solo aggiungere—riscrivi. I ricercatori notano esplicitamente che le riscritture complete sono una delle poche cose che fermano la crescita.

3. Tratta le istruzioni AI come documentazione di onboarding. Daresti a un nuovo developer un file di 400 righe senza distinzioni? Il tuo assistente AI merita la stessa chiarezza.

La traiettoria attuale non è sostenibile. Ogni nuovo progetto parte con buone intenzioni e finisce in un disastro ingestibile. Ma forse la soluzione è più semplice del previsto: scrivi per chi leggerà le tue istruzioni tra sei mesi, non solo per chi risponde oggi.

I commenti non sono confusione. Sono l'architettura della comprensione.