Per anni abbiamo trattato il codice come l’asset principale di un prodotto software. Lo misuravamo, lo difendevamo, lo versionavamo con cura, lo consideravamo il cuore del valore. Se un’azienda aveva tanto codice proprietario, sembrava avere un patrimonio. Se un team produceva tanto codice, sembrava stare costruendo qualcosa di solido.
Questa idea sta diventando rapidamente falsa. Con gli strumenti AI che ormai fanno parte del lavoro quotidiano — Claude Code, Codex, Cursor e tutto quello che arriverà dopo — il costo di scrivere codice sta scendendo in modo molto netto. Non a zero, ma abbastanza da cambiare la gerarchia delle cose che vale la pena proteggere.
Il codice non sparisce. Semplicemente, smette di essere la parte più rara del sistema. La parte rara si sposta altrove: si sposta sul perché.
Il codice non è più la cosa costosa
Per capire cosa sta cambiando, basta guardare come lavorava un team anche solo due anni fa. Una nuova feature significava analisi, implementazione, test, rifinitura, refactoring, magari qualche giorno perso su dettagli secondari. Il codice costava tempo, e il tempo costava soldi. Quindi quel codice diventava qualcosa da preservare, da ottimizzare, da non buttare.
Oggi la situazione è diversa. Un senior con strumenti AI produce in un’ora quello che fino a poco tempo fa richiedeva una giornata. Chi usa davvero questi strumenti lo vede tutti i giorni, e non serve farne una religione per riconoscere che la produttività sulla parte esecutiva è salita tantissimo.
Quando il costo marginale di produrre codice crolla, il codice si svaluta. Non nel senso che diventa inutile, ma nel senso che diventa meno raro. E quando una cosa diventa meno rara, smette di essere il centro del valore.
Cosa resta raro
Se il codice si può rigenerare, cosa non si può rigenerare facilmente? Non il repository, non la sintassi, non nemmeno la struttura superficiale del sistema. La cosa davvero difficile da ricostruire è il contesto che ha portato a una decisione: perché quel modulo è fatto così, perché quella dipendenza non è stata sostituita, perché quel flusso apparentemente brutto esiste, perché una soluzione più elegante è stata scartata, perché una certa stranezza non è un errore ma la risposta a un vincolo reale.
Questa roba non vive nel codice. Il codice mostra cosa hai fatto, molto raramente spiega perché l’hai fatto. Ed è proprio lì che sta l’asset.
Il problema dei sistemi che nessuno capisce più
Chiunque abbia lavorato su un software con qualche anno sulle spalle conosce la scena. Apri un modulo e trovi una scelta strana, e la prima reazione è: “questa cosa va rifatta”. Poi chiedi a chi c’era allora, e scopri che quella scelta era legata a un bug in produzione, a un cliente enorme, a un vincolo fiscale, a un’integrazione esterna assurda, a una limitazione del sistema di allora.
Quella informazione non era nel codice. Era nella testa di qualcuno. Se quella persona se ne va, il sistema perde valore anche se il repository resta identico.
Ed è qui che il discorso AI diventa serio: se domani rigeneri quel modulo da capo con un assistente che scrive codice meglio e più velocemente di te, ma non hai il contesto dietro quella scelta, rigeneri qualcosa di più pulito e probabilmente più sbagliato. Il rischio vero è perdere il motivo per cui il codice era fatto in quel modo, più che il codice stesso.
Il perché è l’unica cosa che sopravvive alla riscrittura
Questa è la vera inversione. Per anni abbiamo pensato: il codice è l’asset, la documentazione è un costo. Oggi il rapporto si sta ribaltando: il codice si può rigenerare, il perché no. O meglio: il perché si può ricostruire solo se qualcuno lo ha registrato mentre prendeva la decisione. Se non l’ha fatto, sparisce. E quando sparisce, il progetto entra in modalità archeologia.
Ogni modifica diventa più lenta, ogni refactoring è più rischioso, ogni nuovo ingresso nel team richiede mesi, ogni AI lavora su un sistema formalmente leggibile ma sostanzialmente muto. Il codice di oggi serve a produrre il software di oggi; il perché di oggi serve a produrre il software di domani.
Ecco perché la documentazione smette di essere “overhead”
Qui bisogna intendersi: non sto parlando della wiki aziendale piena di pagine morte che nessuno apre da mesi. Quella è arredamento, non documentazione.
Sto parlando di artefatti che catturano decisioni mentre sono ancora vive: un ADR scritto bene, che spiega quale scelta architetturale è stata fatta e perché; una sezione di explanation che chiarisce il contesto di un modulo; un commit message che non dice “fix bug”, ma spiega quale problema reale è stato corretto e cosa si è scelto di non fare. Queste cose sembrano piccole, in realtà sono l’unico modo per conservare il valore vero del sistema.
Diátaxis è utile proprio per questo: perché separa i tipi di documentazione e impedisce di mischiare tutto in un blob inutile. Ma il framework, in fondo, è secondario. Il punto è un altro: il contesto va estratto dalle teste e messo accanto al codice. Altrimenti, alla prima riscrittura seria, lo perdi.
Il cambiamento strategico per chi decide
Se questa lettura è corretta, cambia anche il modo in cui un’azienda dovrebbe investire. Per anni il budget è andato quasi tutto nella produzione di codice; la documentazione, quando andava bene, era il 5% del lavoro. Il ragionamento era semplice: il codice è il prodotto, il resto è supporto.
Ora quel ragionamento non regge più. Il codice conta ancora, ovviamente: un codice scritto male resta un problema. Ma il punto non è se il codice conta. Il punto è cosa conviene proteggere di più.
E oggi conviene proteggere il contesto decisionale, perché è quello che non puoi ricomprare dopo: non con un altro team, non con un assistente AI, non con una settimana di reverse engineering. Se un’azienda accumula per anni comprensione del dominio, eccezioni dei clienti, vincoli normativi, ragioni dietro le scelte, e lascia tutto dentro le teste dei senior, sta trattando come sottoprodotto il suo asset principale.
I due errori ugualmente pericolosi
Qui vedo due estremi. Il primo è continuare come prima: trattare il codice come patrimonio duraturo, sottovalutare la documentazione, lasciare che le decisioni restino implicite. È l’errore più diffuso, e il più costoso nel medio periodo.
Il secondo è l’errore opposto: pensare che allora basti documentare tutto e lasciare il resto all’AI. Neanche questo funziona, perché il fatto che il codice si svaluti non significa che il gusto tecnico si svaluti. Anzi: se hai persone che non sanno riconoscere una buona decisione da una cattiva, documenteranno male, leggeranno male la documentazione, useranno male l’AI e produrranno rumore a velocità maggiore.
Il codice diventa commodity, il giudizio no. Il perché diventa asset, ma solo se c’è qualcuno capace di scriverlo, leggerlo e rimetterlo in discussione quando serve.
Dove conviene investire oggi
Se dovessi semplificarlo brutalmente, direi così: meno energia nel proteggere il codice come oggetto da museo, più energia nel catturare il contesto che permette di rigenerarlo bene.
Questo significa:
- ADR per le decisioni vere, non per ogni dettaglio
- explanation documentata per i moduli strani o sensibili
- reference accurata dove serve davvero
- commit e pull request che spieghino il motivo del cambiamento, non solo il cambiamento
- review che valutino anche la qualità del ragionamento, non solo del codice
Sembrano dettagli. In realtà sono la differenza tra un sistema che può essere rigenerato e uno che deve essere scavato.
La scelta si fa adesso
Il modo in cui un team documenta oggi determina quanto sarà facile usare bene l’AI tra uno, due o tre anni. Chi avrà contesto ben catturato potrà rigenerare velocemente codice buono; chi avrà solo montagne di codice e poco perché dovrà prima ricostruire la storia del sistema, e quella parte sarà lenta, costosa e piena di errori.
La scelta, in fondo, è molto semplice. Puoi continuare a trattare il codice come il bene da proteggere, oppure puoi iniziare a proteggere quello che rende il codice sostituibile senza perdere il sistema.
Il codice è il cosa di oggi. Il perché è il capitale che ti permette di ricostruire il cosa domani.
Simone Giusti
Consulente software strategico
