Traccia le tue decisioni
16 marzo 2026
C'è un tipo specifico di confusione che si prova solo quando si torna al proprio codice dopo una lunga assenza. Non la confusione ordinaria di una sintassi dimenticata o di una logica oscura — quella si chiarisce in pochi minuti. Questa è la confusione di trovare un pattern che sembra sbagliato, senza sapere se sia davvero sbagliato o se ci fosse una ragione che non ricordi più.
Puoi leggere il git log. Puoi vedere che il file è cambiato quattordici mesi fa, in un commit che dice "refactor auth flow." Puoi vedere cosa è cambiato. Quello che non puoi vedere è perché hai fatto quella scelta specifica invece dell'alternativa ovvia — o se il vincolo che la rendeva corretta esista ancora.
Quel contesto mancante è la cosa più costosa nello sviluppo software di cui nessuno parla.
Cosa git non traccia
Git traccia il tuo codice. Non traccia il tuo ragionamento.
Il ragionamento è la parte che decade. Il codice è ancora lì, congelato esattamente come lo hai lasciato. Il contesto che lo rendeva corretto — il vincolo che stavi aggirando, l'alternativa che hai considerato e scartato, la cosa che era vera del sistema in quel momento — vive nella tua testa, e svaporisce.
In un contesto di team questo è un problema ben compreso. Gli Architecture Decision Records (ADR) esistono proprio per affrontarlo: documenti brevi che catturano una decisione, il contesto in cui è stata presa, le alternative considerate e i compromessi accettati. I team che li usano possono cercare perché un sistema è strutturato in un certo modo senza dover ricostruire il ragionamento da zero.
Gli sviluppatori in solitaria non lo fanno quasi mai. L'assunzione è che te lo ricorderai, o che il codice sia abbastanza ovvio. Nessuna delle due tende a essere vera dopo sei mesi.
Il contesto è la parte preziosa
Un ADR non deve essere lungo. La versione minima utile è un paragrafo che risponde a tre domande: cosa hai deciso, tra cosa stavi scegliendo, e cosa ti ha portato a questa conclusione.
In Barba Studio, a un certo punto ho deciso di memorizzare il prezzo dell'appuntamento al momento della prenotazione invece di fare riferimento al prezzo corrente del servizio. Il codice è chiaro su cosa fa — il prezzo incorporato è lì nel documento. Quello che il codice non spiega è il perché: che cambiare il prezzo di un servizio non dovrebbe alterare retroattivamente quanto concordato in una prenotazione passata, e che questo comportamento è rilevante in un contesto di fatturazione.
Senza quel contesto, la prossima persona che tocca quel codice — incluso me tra diciotto mesi — potrebbe guardare la denormalizzazione, assumere che fosse una svista, e "correggerla". La correzione introdurrebbe un vero bug. Il codice sembrava sbagliato. Non era sbagliato. La differenza era invisibile.
Non serve un framework
L'overhead degli strumenti formali per gli ADR è il motivo per cui la maggior parte delle persone salta la pratica completamente. Serve un registro delle decisioni, e un registro può essere una directory di file Markdown numerati, una sezione del wiki del progetto, o anche un commento ben posizionato nel codice che dica: "questo è intenzionale, ecco perché."
Il formato che ha funzionato per me è un semplice file: la decisione, la data, le alternative che ho considerato, il vincolo che le ha escluse, e una nota su cosa mi farebbe rivalutarla. Quest'ultima parte è importante. Le decisioni non sono permanenti. Il vincolo che rendeva corretto un approccio potrebbe sparire — il sistema potrebbe cambiare, la scala potrebbe spostarsi, il requisito potrebbe evolvere. Sapere cosa osservare è utile quanto sapere perché hai fatto la scelta originale.
La cosa per cui ti ringrazierai
La versione di questa pratica più facile da iniziare è anche la più efficace: scrivi una nota ogni volta che fai una scelta non ovvia. Non per ogni funzione che scrivi — per i momenti in cui hai considerato due approcci e ne hai scelto uno. Dove hai aggirato un vincolo. Dove hai accettato un compromesso deliberatamente.
Richiede tre minuti. Ripaga ogni volta che torni a quella parte del codebase e non devi scavare il ragionamento da zero. Ripaga ancora di più quando stai per cambiare qualcosa, trovi la nota, e ti rendi conto che il vincolo intorno a cui era stata scritta è ancora lì.
Il codice è un registro di decisioni. La maggior parte di esse — specialmente quelle importanti — non lascia traccia del ragionamento che le ha prodotte. Risolvere questo non richiede processo o strumenti. Richiede l'abitudine di scrivere il perché, nel momento in cui lo sai ancora.
Te lo dimenticherai. Scrivilo.