Pubblicato il 22 Settembre 2026 · di Ismail Nasry
In breve: Guida pratica agli Architecture Decision Record: come documentare contesto, alternative, trade-off, reversibilità e condizioni di revisione senza creare burocrazia.
Un’Architecture Decision Record non serve a dimostrare che una decisione era “giusta”. Serve a conservare abbastanza contesto da permettere a chi arriva dopo di capire perché quella decisione aveva senso in quel momento, quali alternative erano state scartate e quali conseguenze erano state accettate.
Quando manca questo contesto, le architetture diventano difficili da evolvere. Una scelta fatta sei mesi prima può sembrare arbitraria, una dipendenza può essere rimossa senza capire quale problema risolveva, oppure una soluzione temporanea può trasformarsi in vincolo permanente perché nessuno ricorda più perché era stata introdotta.
Gli ADR servono proprio a ridurre questa perdita di memoria tecnica.
Che cos’è davvero un ADR
Un Architecture Decision Record è un documento breve che registra una decisione architetturale significativa. Non è la documentazione completa del sistema e non è un verbale di riunione. Il suo compito è più specifico: fissare una decisione, il contesto in cui è stata presa e le conseguenze attese.
Un ADR utile dovrebbe permettere di rispondere almeno a queste domande: quale problema stavamo cercando di risolvere? Quali vincoli avevamo? Quali alternative abbiamo considerato? Perché abbiamo scelto questa opzione? Quali conseguenze accettiamo? Cosa dovrebbe farci riconsiderare la decisione?
Se il documento non aiuta a rispondere a queste domande, rischia di diventare burocrazia invece che memoria tecnica.
Quali decisioni meritano un ADR
Non tutto richiede un documento dedicato. Registrare ogni dettaglio rende il sistema inutilizzabile. Un ADR ha senso quando la decisione ha conseguenze durevoli, coinvolge più componenti o persone, modifica un vincolo importante oppure sarà costosa da invertire.
Esempi tipici sono la scelta di un database principale, l’introduzione di una coda di messaggi, la strategia di autenticazione, la separazione di un monolite, l’adozione di un provider cloud, la scelta tra elaborazione sincrona e asincrona o una modifica importante al modello di dati.
Un criterio pratico è chiedersi: se tra un anno qualcuno volesse cambiare questa decisione, avrebbe bisogno di sapere perché l’abbiamo presa? Se la risposta è sì, probabilmente vale la pena registrarla.
Parti dal contesto, non dalla soluzione
L’errore più comune è iniziare un ADR scrivendo direttamente la decisione: “useremo PostgreSQL”, “passiamo a Kubernetes”, “introduciamo Redis”. Il problema è che una soluzione senza contesto perde rapidamente significato.
Il contesto dovrebbe descrivere la situazione che rende necessaria una decisione. Quale problema esiste? Quali vincoli tecnici, organizzativi o economici contano? Quale pressione temporale c’è? Quali requisiti non possono essere violati?
Un contesto utile non deve raccontare tutta la storia del progetto. Deve conservare solo ciò che influenza davvero la decisione.
Registra le alternative considerate
Un ADR è molto più utile quando mostra che la scelta non è stata valutata nel vuoto. Non serve documentare ogni possibilità teorica, ma almeno le alternative realistiche che il team ha considerato.
Per ciascuna alternativa è sufficiente esplicitare i trade-off principali. Una soluzione può essere più semplice da operare ma meno flessibile. Un’altra può ridurre il lock-in ma richiedere più competenze interne. Un’altra ancora può essere tecnicamente migliore ma incompatibile con tempi o budget.
L’obiettivo non è costruire una matrice infinita. È rendere comprensibile perché una certa opzione è stata preferita alle altre nelle condizioni reali del progetto.
Documenta i trade-off, non una giustificazione retrospettiva
Un buon ADR non dovrebbe sembrare una difesa della decisione presa. Dovrebbe mostrare ciò che si guadagna e ciò che si perde.
Ogni decisione architetturale significativa produce conseguenze. Alcune sono desiderate, altre accettate come costo. Una scelta può migliorare affidabilità ma aumentare complessità operativa; può ridurre il time-to-market ma aumentare dipendenza da un provider; può semplificare lo sviluppo ma rendere più difficile una futura migrazione.
Esplicitare questi costi rende il documento molto più utile quando il contesto cambia.
Aggiungi il grado di reversibilità
Non tutte le decisioni hanno lo stesso costo di inversione. Distinguere tra decisioni facilmente reversibili e decisioni difficili da cambiare aiuta anche a decidere quanta analisi fare prima di procedere.
Per un cambiamento facilmente reversibile può bastare un ADR leggero. Per una decisione che coinvolge dati persistenti, contratti, competenze, infrastruttura o integrazioni critiche serve più attenzione.
Nel documento puoi indicare in modo semplice se la decisione è facilmente reversibile, reversibile con costo significativo oppure difficilmente reversibile. Non serve una scala sofisticata: serve rendere visibile il costo del ripensamento.
Definisci le condizioni di revisione
Una decisione architetturale non deve essere trattata come eterna. Molte scelte sono corrette solo finché restano validi certi presupposti.
Per questo un ADR dovrebbe indicare anche quali eventi richiedono una revisione. Per esempio: il volume supera una certa soglia, il provider cambia condizioni economiche, il team non riesce più a sostenere la complessità operativa, emergono nuovi requisiti normativi oppure cambia il modello di distribuzione del prodotto.
Questo passaggio trasforma l’ADR da documento statico a strumento decisionale nel tempo.
Mantieni stato e cronologia
Gli ADR diventano più utili quando hanno uno stato chiaro. Una struttura semplice può distinguere tra proposto, accettato, sostituito e deprecato.
Quando una decisione cambia, evita di riscrivere il documento originale fino a cancellarne la storia. È meglio creare un nuovo ADR che sostituisce il precedente e collegare i due documenti. In questo modo il team conserva la sequenza delle decisioni e può capire come l’architettura si è evoluta.
Un template minimo che resta utile
Un ADR può essere molto breve. Una struttura essenziale può includere:
- Titolo della decisione.
- Stato.
- Contesto.
- Decisione.
- Alternative considerate.
- Trade-off e conseguenze.
- Reversibilità.
- Condizioni di revisione.
- Collegamenti ad ADR precedenti o successivi.
Questo è sufficiente nella maggior parte dei casi. Se servono diagrammi, benchmark o analisi dettagliate, possono essere collegati invece di trasformare l’ADR in un documento enorme.
Dove conservare gli ADR
Gli ADR funzionano meglio quando sono vicini al codice o alla documentazione tecnica che descrivono. Un repository Git è spesso una scelta pratica perché offre versioning, review e collegamento con le modifiche al sistema.
Una directory come docs/adr/ o architecture/decisions/ permette di mantenere una sequenza ordinata e consultabile. La convenzione è meno importante della facilità con cui il team riesce a trovare e aggiornare i documenti.
Il requisito reale è che gli ADR siano accessibili a chi prende decisioni tecniche e che facciano parte del normale flusso di lavoro, non di un archivio separato che nessuno consulta.
ADR e documentazione architetturale non sono la stessa cosa
La documentazione architetturale descrive come è fatto il sistema oggi. Gli ADR spiegano perché alcune parti sono state costruite in un certo modo.
Le due cose si completano. Un diagramma può mostrare che esiste una coda di messaggi tra due servizi. L’ADR può spiegare perché è stata introdotta, quali alternative erano state considerate e quali problemi dovrebbe risolvere.
Senza documentazione architetturale, gli ADR diventano frammenti difficili da collegare. Senza ADR, la documentazione descrive la struttura ma perde il ragionamento che l’ha generata.
ADR e changelog hanno scopi diversi
Un changelog registra cosa è cambiato. Un ADR registra perché una decisione importante è stata presa.
Il changelog può dire che il sistema di autenticazione è stato sostituito. L’ADR dovrebbe spiegare perché il precedente approccio non era più sufficiente, quali alternative sono state considerate e quali conseguenze introduce la nuova soluzione.
Confondere i due strumenti porta a documenti che registrano molti eventi ma conservano poco contesto decisionale.
Evita tre forme di burocrazia
La prima è creare ADR per ogni dettaglio. Se tutto è una decisione architetturale, niente lo è davvero.
La seconda è richiedere documenti lunghi prima di poter sperimentare. Un ADR dovrebbe aiutare il team a ragionare, non bloccare l’esplorazione.
La terza è trattare il template come obiettivo. Se una sezione non aggiunge informazione utile, non deve essere compilata solo per rispettare un formato.
La qualità di un ADR dipende dalla capacità di conservare il ragionamento necessario per il futuro, non dal numero di campi completati.
Un esempio ipotetico
Immaginiamo un team che debba decidere come gestire l’elaborazione di report pesanti. La soluzione attuale esegue tutto in modo sincrono e alcune richieste superano il timeout.
Il team considera tre opzioni: aumentare i timeout, ottimizzare il processo mantenendolo sincrono oppure introdurre una coda asincrona.
La decisione è usare una coda perché i report possono richiedere diversi minuti e non devono bloccare una richiesta HTTP. Il costo accettato è una maggiore complessità operativa e la necessità di gestire stato, retry e notifiche.
L’ADR specifica anche che la decisione andrà rivista se il volume resta molto basso, se l’infrastruttura della coda diventa sproporzionata rispetto al beneficio oppure se il prodotto richiede risultati realmente interattivi.
Tra un anno, chi legge il documento non trova solo “abbiamo introdotto una coda”, ma il problema, le alternative, i costi accettati e le condizioni che potrebbero rendere quella scelta non più valida.
Il criterio finale: rendere le decisioni interrogabili
La vera utilità degli ADR emerge quando qualcuno mette in discussione una scelta esistente. In quel momento il team dovrebbe poter risalire rapidamente al contesto originale, distinguere i vincoli ancora validi da quelli scomparsi e decidere se mantenere o sostituire la soluzione.
Un buon ADR non congela l’architettura. Fa il contrario: rende più sicuro cambiarla, perché conserva il ragionamento necessario per capire cosa stai modificando e perché.
