Debito tecnico cos'è: guida pratica per il builder indie

Il debito tecnico cos e come gestirlo sono le due domande più frequenti per chi fa build da solo. Partendo dalla definizione: è il costo accumulato di ogni scorciatoia che hai scelto per spedire più in fretta. Ward Cunningham ha coniato il termine nel 1992 come metafora del debito finanziario: prendi ora, paghi gli interessi dopo. La differenza rispetto al codice semplicemente brutto è l'intento: uno scambio, consapevole o meno, tra velocità immediata e manutenibilità nel tempo.

Se hai mai lasciato un TODO in un file, hardcodato un valore perché dovevi consegnare entro venerdì, o copiato una funzione invece di estrarre un modulo condiviso, hai contratto debito tecnico. La maggior parte dei side project è costruita su di esso. E la maggior parte dei developer indie ne porta più di quanto pensa.

Perché i builder indie accumulano debito più in fretta dei team

Nei team c'è attrito incorporato. Code review, discussioni di architettura, documenti di standard: rallentano tutto, ma rallentano anche l'accumulo del debito. Da solo non hai questo attrito. Prendi ogni decisione in autonomia, in tempo reale, alle 23 quando vuoi solo vedere la cosa funzionare.

Il risultato è un codebase che rispecchia ogni compromesso fatto sotto pressione. Non è un difetto caratteriale. È la realtà strutturale di costruire da soli.

Il problema è che il debito si moltiplica. Una API key hardcodata è un'ora di lavoro. Quando ne hai venti sparse su sei file perché il pattern si è propagato, diventa un'intera giornata di archeologia prima ancora di poter iniziare a correggere.

C'è anche una forma più sottile: il debito architetturale. Le decisioni prese quando il progetto era piccolo spesso non reggono quando prende piede. Un file JSON piatto come database va bene a zero utenti. Diventa un problema a cinquecento. Chi gestisce side project in parallelo al lavoro da dipendente lo sa bene: ottimizza per la velocità di consegna, assorbi il debito, rinegozialo dopo. Se c'è un dopo.

I quattro tipi di debito tecnico che contano davvero

Non tutto il debito è uguale. Ecco una sintesi pratica per i side project.

Debito di codice. Il più comune. Copre le scorciatoie nel codice stesso: logica duplicata, funzioni che fanno troppe cose, variabili chiamate temp2 ancora lì sei mesi dopo. È il debito che senti ogni volta che aggiungi una feature e passi trenta minuti solo a capire cosa fa il codice esistente prima di poterlo modificare.

Debito di documentazione. Sottovalutato dai builder solitari perché non c'è nessun altro da confondere. Poi stai tre settimane lontano dal progetto, torni e perdi quattro ore a capire perché hai costruito l'API in quel modo. La tua memoria di due mesi fa ti è diventata estranea: la presunzione di ricordare il contesto è quasi sempre sbagliata.

Debito di sicurezza. Si accumula quando salti la validazione degli input, lasci le route admin non protette durante lo sviluppo e poi dimentichi di bloccarle, o continui a usare una libreria con una vulnerabilità critica patchata sei versioni fa. Su un side project sembra a basso rischio finché non hai utenti reali. A quel punto non è più teorico.

Debito di tooling. Quello di cui i builder parlano meno. Nessuna pipeline di deployment. Passi manuali per ogni release. Un .env che esiste solo sul tuo laptop senza un formato documentato. Quando qualcosa si rompe in produzione, è questo debito che trasforma una correzione da trenta minuti in un recupero da tre ore durante il quale stai anche ricostruendo il contesto di come viene deployato tutto.

Quando indebitarsi tecnicamente ha senso

Ecco cosa sbaglia la letteratura enterprise sul software: tratta il debito come uniformemente negativo. Per un builder indie o un indie hacker, un certo debito è la decisione giusta.

Hai un side project da validare in due settimane. Scrivere una suite di test completa prima di sapere se la cosa ha degli utenti non è disciplina ingegneristica: è procrastinazione con un nome rispettabile. Saltare i test a zero utenti e aggiungerli quando hai dieci clienti paganti è una scelta deliberata e ragionevole. Ward Cunningham stesso l'ha chiamato debito "prudente e deliberato": sai che lo stai contraendo, ne capisci le conseguenze, e pianifichi di ripagarlo.

Il problema è quando i builder accumulano debito senza accorgersene, o lo fanno deliberatamente senza pianificare mai il rimborso. Debito senza un piano è entropia.

La regola che funziona in pratica: il debito va bene quando è circoscritto. Un valore di configurazione hardcodato è gestibile. Lo stesso pattern applicato a trenta file diversi è un codebase in cui nessuno riesce a lavorare, nemmeno tu.

Ecco cosa si inceppa davvero: la maggior parte dei builder indie non traccia il proprio debito. Esiste come un disagio vago nel retro della testa. Questo è il vero problema: non il debito in sé, ma la mancanza di visibilità su cosa sia realmente e quanto costerebbe correggere.

Come rendere il debito visibile prima che ti costi caro

La forma più economica di gestione del debito è renderlo visibile. Non richiede un processo complesso. Un semplice file DEBT.md nella root del repo dove annoti i compromessi mentre li fai richiede trenta secondi per voce e risparmia ore di riscoperta in seguito.

Una voce tipica potrebbe essere:

## [2026-08-03] Stringa di connessione DB hardcodata in api/users.ts
Perché: dovevo consegnare la demo entro venerdì.
Costo: specifica dell'ambiente, si rompe se qualcun altro gira il progetto in locale.
Fix: spostare su variabile d'ambiente con dotenv. Stima: 20 min.
Priorità: Alta, prima che si unisca qualsiasi collaboratore.

È tutto. Il formato non conta. L'atto di scriverlo conta, perché ti forza ad articolare il compromesso in modo esplicito invece di lasciarlo evaporare nel codice dove accumulerebbe interessi in silenzio.

Gli strumenti di analisi statica fanno una versione diversa di questo automaticamente. Strumenti come SonarQube o CodeClimate scansionano il codebase e segnalano code smell, duplicazioni, hotspot di sicurezza e punteggi di complessità. Sono più utili per intercettare debito che non sapevi di stare creando: il tipo involontario che emerge da un pattern applicato dodici volte senza accorgersene.

CodeScene fa un passo in più analizzando la storia dei commit per identificare quali file cambiano insieme e quali hotspot vengono toccati ripetutamente sotto pressione. Per un progetto solitario, questo tipo di segnale è più utile di uno snapshot statico: ti mostra dove hai fatto compromessi ripetuti, non solo dove il codice sembra brutto adesso.

Tre modi per rimborsarlo senza fermare il lavoro

L'errore classico è trattare il rimborso del debito come uno sprint dedicato che pianifichi per il mese prossimo e non fai mai. L'approccio giusto è pagarlo continuamente in piccole quantità, integrato nel flusso normale.

La Boy Scout Rule applicata al codice. Lascia il file che modifichi leggermente meglio di come l'hai trovato. Rinomina la variabile confusa mentre sei già lì. Estrai la logica duplicata in una funzione mentre la stai già toccando. Costa dai cinque ai quindici minuti per sessione e si accumula significativamente nel corso di mesi di lavoro costante.

Budget del debito durante lo sviluppo attivo. Se stai costruendo una nuova feature, dedica il 20% del tempo a correggere il debito nel codice adiacente. Non il debito che scopri in una parte distante del codebase: quello che tocca direttamente quello che stai costruendo adesso. Questo previene il pattern comune in cui le nuove feature peggiorano il debito vecchio perché ci vengono costruite sopra.

Triage per blast radius. Non tutto il debito merita la stessa attenzione. Il debito nel codice che tocchi ogni settimana conta di più di quello in un modulo che non apri da quattro mesi. Quando decidi cosa affrontare, chiediti: se questo si rompe o deve cambiare, quante altre cose coinvolge? Alto blast radius, alta priorità. Il debito a basso blast radius in un angolo che visiti raramente può stare lì.

Una regola tre-a-uno funziona nello sviluppo attivo: per ogni tre sessioni dedicate a nuove feature, una sessione dedicata al rimborso del debito. Questo mantiene il rapporto sotto controllo senza bloccare i progressi.

Cosa ti dice la distribuzione del debito nel tuo codebase

A sei mesi di progetto, la distribuzione del debito nel tuo codebase è una mappa abbastanza accurata delle decisioni prese sotto pressione. Molto debito nel modulo di autenticazione significa che eri di fretta quando l'hai costruito. Duplicazione massiva nel layer API significa che stavi validando feature velocemente senza fermarti a consolidare. Complessità densa in un singolo file di solito significa che quel file è diventato un cestino quando l'architettura non era ancora chiara.

Questa è informazione genuinamente utile. Ti mostra quali parti del codebase sono state costruite con sicurezza e quali con incertezza. Le parti costruite con incertezza sono spesso anche quelle che non hanno contato: feature validate velocemente e poi deprioritizzate. Il debito lì potrebbe non dover mai essere pagato perché quei percorsi non portano da nessuna parte.

Le parti che hanno contato davvero, flussi utente core, modello dei dati, contratti API, autenticazione: sono quelle dove il rimborso del debito rende. Non stai cercando di scrivere codice perfetto ovunque. Stai cercando di identificare i muri portanti e tenerli puliti.

Se il tuo codebase ha raggiunto il punto in cui aggiungere qualsiasi feature richiede più tempo a debuggare il comportamento esistente che a scrivere codice nuovo, questo è il segnale. Non un segnale per fermarsi e riscrivere tutto: si stima che le riscritture richiedano il doppio del tempo previsto. È un segnale per dedicare le prossime tre o quattro settimane alla riduzione mirata del debito nei moduli specifici che causano il rallentamento.

Riscrivere o fare refactoring? Quasi sempre refactoring

Questa è la domanda che i builder indie affrontano quando il debito inizia a sembrare ingestibile. La risposta è quasi sempre fare refactoring, non riscrivere.

Le riscritture richiedono il doppio del tempo stimato. E perdono la conoscenza accumulata incorporata nel codice esistente: i casi limite gestiti, i bug corretti, i workaround per le stranezze delle API di terze parti che hai scoperto a tue spese. Paghi il debito originale due volte: una volta quando l'hai portato, e di nuovo quando devi riscoprire tutto mentre ricostruisci.

Il refactoring funziona quando è mirato. Scegli il modulo che causa il dolore più concreto: il più lento da modificare, quello da cui originano più bug, il più difficile da capire. Ottieni un quadro completo di cosa fa prima di cambiare qualsiasi cosa. Aggiungi test ai confini così puoi fare refactoring in sicurezza senza rompere il comportamento adiacente. Fai le modifiche in modo incrementale in più sessioni, non in un unico sprint eroico che lascia tutto a metà se finisci l'energia.

Tre ragioni per fare refactoring, una per non farlo. Fai refactoring quando il debito è in un'area ad alto traffico del codebase, quando stai per costruirci sopra, o quando sta causando bug reali. Salta il refactoring quando il modulo è stabile, cambia raramente e il debito è circoscritto a sé stesso.

Non è un'idea perfetta. È un'idea realizzabile: la versione sostenibile della gestione del debito tecnico non è zero debito. È debito che capisci, che sai articolare, e sul quale stai prendendo una decisione attiva: portarlo o rimborsarlo. Questa chiarezza è l'obiettivo reale.