Architecture Decision Records: Come Documentare le Decisioni che Durano

In questo articolo:

• Cos’è Davvero un Architecture Decision Record
• Il Formato ADR che Funziona in Pratica
• Dove gli ADR si Inseriscono nella Roadmap di Architettura
• Standard Ingegneristici: Rendere gli ADR un’Abitudine del Team
• Quando Aggiornare o Sostituire un ADR
• Conclusione

Un architecture decision record (ADR) è un documento breve che cattura una decisione architettonica significativa: qual era la decisione, perché è stata presa e quali trade-off sono stati accettati. Il concetto è semplice. La disciplina di usare gli ADR in modo coerente è dove la maggior parte dei team di ingegneria ha difficoltà. Questo articolo spiega il formato, il workflow e le condizioni specifiche che rendono gli ADR preziosi anziché solo un ulteriore overhead documentale.

Cos’è Davvero un Architecture Decision Record

Un ADR non è un documento di design. Non è una spec. È una voce di log per una decisione abbastanza conseguente da richiedere che i futuri ingegneri capiscano perché il codebase appare come appare.

La necessità degli ADR diventa ovvia quando si è chiamati a modificare qualcosa in un sistema e si trova del codice che sembra sbagliato o obsoleto. Non si riesce a capire se fosse una scelta deliberata, un hack che nessuno ha mai corretto, o un pattern obsoleto di una versione del framework di tre anni fa. Senza un ADR, si passa un’ora in git blame e nella cronologia di Slack cercando di ricostruire il ragionamento. O peggio, si fa la modifica senza capire i vincoli e si reintroduce un problema già risolto.

Gli ADR esistono all’intersezione di due modalità di fallimento che amplificano il debito tecnico:

Decisioni non documentate creano conoscenza tribale. Quando l’ingegnere che ha preso la decisione se ne va, il ragionamento va con lui. I nuovi ingegneri prendono decisioni in conflitto e l’architettura deriva in modo incoerente.

Dibattiti ripetuti sprecano tempo. I team senza ADR rimettono in discussione le stesse domande architetturali ogni pochi mesi perché non esiste un registro autorevole di cosa è stato deciso e perché.

Il Formato ADR che Funziona in Pratica

Il formato più adottato proviene dalla proposta originale di Michael Nygard e sta in una pagina. Ogni sezione deve essere concisa.

Titolo. Una breve frase che descrive la decisione. ADR-001: Usare PostgreSQL per la persistenza primaria.

Stato. Proposto, Accettato, Deprecato o Sostituito. Lo stato è critico per la gestione del ciclo di vita.

Contesto. Quali forze hanno portato a questa decisione? Quali vincoli esistevano? Quali alternative sono state considerate? Questa sezione dovrebbe essere letta come una descrizione neutrale del problema, non una giustificazione.

Decisione. Cosa è stato deciso, dichiarato direttamente. Una o due frasi.

Conseguenze. Cosa diventa più facile grazie a questa decisione? Cosa diventa più difficile? Quale nuovo debito tecnico viene accettato? Questa sezione è dove vive l’onestà intellettuale. Se una decisione ha dei veri trade-off, elencateli chiaramente.

Opzionale ma utile: Alternative considerate con una breve nota sul perché ciascuna è stata rifiutata. Questo previene che le stesse alternative vengano proposte di nuovo senza nuove informazioni.

L’intero ADR dovrebbe essere leggibile in meno di cinque minuti. Se è più lungo, la decisione probabilmente deve essere divisa in più ADR o la sezione delle conseguenze sta facendo troppo lavoro.

Dove gli ADR si Inseriscono nella Roadmap di Architettura

Una roadmap di architettura descrive dove sta andando il sistema. Gli ADR documentano le decisioni prese lungo il percorso. Sono complementari, non ridondanti.

La roadmap indica la destinazione. Gli ADR spiegano perché sono state prese certe svolte. Quando un ingegnere si unisce a metà percorso, la roadmap gli dice l’obiettivo; la storia degli ADR gli dice quali vincoli hanno modellato il percorso.

Per i team che fanno legacy modernization, gli ADR sono particolarmente importanti durante il periodo di transizione. Una migrazione con lo strangler fig pattern genera dozzine di decisioni: quale modulo estrarre per primo, come gestire i dati condivisi, quando effettuare il cutover. Senza ADR, ognuna di quelle decisioni esiste solo nelle teste delle persone che le hanno prese. Con gli ADR, il piano di migrazione è ispezionabile e trasferibile.

La roadmap di architettura dovrebbe fare riferimento agli ADR pertinenti. Quando una milestone della roadmap richiede una decisione tecnica significativa, quella decisione dovrebbe avere un ADR prima che inizi l’implementazione, non dopo. Gli ADR scritti post-hoc tendono a essere giustificazioni piuttosto che registri onesti dei trade-off.

Standard Ingegneristici: Rendere gli ADR un’Abitudine del Team

Gli ADR funzionano solo se il team li usa in modo coerente. Questo richiede di rendere il processo abbastanza a bassa frizione da far sì che gli ingegneri li scrivano davvero.

Tre pratiche che fanno attecchire l’adozione degli ADR:

Conservare gli ADR come codice. Tenere gli ADR nel repository, in una directory /docs/adr/, come file markdown. Vengono revisionati e uniti tramite pull request, proprio come il codice. Questo dà loro la stessa visibilità, versioning e processo di revisione del codice che documentano.

Definire una soglia di decisione. Non ogni decisione ha bisogno di un ADR. La domanda soglia è: un futuro ingegnere avrà bisogno di capire perché è stato fatto così? Trigger utili: scelte tra framework o librerie concorrenti, decisioni sui confini dei servizi, modifiche ai modelli di dati che non possono essere facilmente invertite, scelte che implicano rischi accettati o trade-off noti.

Rendere la creazione di ADR parte del processo di pull request per le modifiche qualificanti. Quando una PR introduce una modifica architettonica significativa, la checklist di revisione dovrebbe includere: questa ha bisogno di un ADR? In caso affermativo, l’ADR viene unito insieme al codice.

Una cosa da evitare: richiedere ADR per decisioni banali. Questo crea lo stesso problema di overhead che fa fallire tutti i processi di documentazione. La soglia dovrebbe essere abbastanza chiara che gli ingegneri possano autoselezionarsi senza aver bisogno di approvazione per scrivere o saltare un ADR.

Quando Aggiornare o Sostituire un ADR

Gli ADR sono immutabili per convenzione. Non si modifica un ADR accettato. Si scrive uno nuovo che lo sostituisce. Questo preserva il registro storico e rende chiaro che una decisione è cambiata, non che era sempre ciò che dice il nuovo ADR.

Quando una decisione viene sostituita, aggiornare lo stato dell’originale a “Sostituito da ADR-NNN” e creare il nuovo ADR con un riferimento al vecchio. Gli ingegneri che leggono il vecchio ADR vedranno che è stato sostituito e sapranno di leggere il sostituto.

La deprecazione è diversa dalla sostituzione. Un ADR deprecato copre una decisione che non è più rilevante perché il contesto è cambiato. Ad esempio, un ADR su un servizio di terze parti che è stato dismesso. Gli ADR deprecati dovrebbero rimanere nel repository per il contesto storico.

Il processo di software due diligence spesso fa emergere ADR mancanti come un segnale di rischio significativo. Quando un codebase ha scelte architetturali che non possono essere spiegate, è quasi sempre perché le decisioni non sono mai state documentate. I team che ereditano un sistema affrontano mesi di lavoro di reverse-engineering che una raccolta di ADR avrebbe eliminato.

Conclusione

Gli architecture decision record funzionano perché risolvono un problema concreto: il divario tra il codice che esiste e il ragionamento che lo ha prodotto. Il formato è semplice. La disciplina è più difficile. Conservare gli ADR come codice, definire una soglia chiara per quando sono richiesti, e renderli parte del processo di revisione per le modifiche significative. Nel tempo, la storia degli ADR diventa la documentazione più affidabile che il sistema abbia, perché riflette decisioni reali piuttosto che design aspirazionali.

Hai un codebase con questi problemi? Parliamo del tuo sistema