Abbiamo passato due settimane a discutere una scelta di database che avevamo gia fatto e rifiutato un anno prima. E stato allora che ho scoperto gli ADR, e da allora ci hanno risparmiato innumerevoli ore.

Best Practice per i Record delle Decisioni Architetturali (ADR)

La riunione durava da due ore. Stavamo discutendo se usare PostgreSQL o MongoDB per un nuovo servizio. Gli argomenti volavano avanti e indietro — integrita relazionale, schema flessibili, familiarita del team, complessita operativa.

Poi qualcuno ha detto: "Non abbiamo avuto esattamente questa stessa discussione l'anno scorso per il servizio utenti?"

Silenzio. L'avevamo avuta. Un anno prima, avevamo passato una quantita simile di tempo a discutere la stessa questione, scegliendo alla fine PostgreSQL. Ma nessuno ricordava il ragionamento. L'ingegnere che aveva guidato quella discussione aveva lasciato l'azienda. Quindi eccoci li, a fare esattamente lo stesso dibattito da zero.

E stato allora che ho scoperto i Record delle Decisioni Architetturali (ADR), e da allora ci hanno risparmiato innumerevoli ore di ri-dibattiti su questioni gia risolte.

Cos'e un ADR?

Un ADR e un breve documento che cattura una singola decisione architetturale. Non un documento di design che copre tutto su un sistema, solo una decisione:

Cosa abbiamo deciso
Perche l'abbiamo deciso
Quali alternative abbiamo considerato
Quali sono le conseguenze

Il formato e deliberatamente leggero. Un ADR dovrebbe stare in una pagina. Se e piu lungo, probabilmente stai documentando piu di una decisione.

L'Anatomia di un Buon ADR

Dopo aver scritto dozzine di ADR e averne letti centinaia, ho scoperto che i migliori seguono una struttura coerente:

Titolo e Numero

Ogni ADR riceve un numero sequenziale e un titolo conciso:

ADR-0042: Usare PostgreSQL per il Servizio Ordini

Il numero conta. Crea una timeline delle decisioni e rende gli ADR facili da referenziare nelle discussioni: "Come abbiamo deciso nell'ADR-42..."

Stato

Gli ADR hanno stati del ciclo di vita:

Proposto: Ancora in discussione
Accettato: Decisione presa, la stiamo seguendo
Deprecato: Non piu rilevante (un nuovo ADR lo sostituisce)
Rifiutato: Lo abbiamo considerato ma abbiamo deciso contro

Lo stato rifiutato e particolarmente prezioso. A volte vuoi catturare perche non hai fatto qualcosa, cosi i team futuri non propongono la stessa cosa.

Contesto

Qui descrivi la situazione che ha motivato la decisione. Quale problema stiamo risolvendo? Quali vincoli abbiamo? Chi e coinvolto?

## Contesto

Il servizio ordini necessita di storage persistente per i dati degli ordini.
Prevediamo di elaborare 50.000 ordini al giorno inizialmente, crescendo
a 500.000 entro due anni. Gli ordini hanno una struttura ben definita ma
potrebbero necessitare di campi di metadati aggiuntivi nel tempo. Il team
ha esperienza sia con database relazionali che documentali.

Sii specifico sui vincoli. "Abbiamo bisogno della conformita ACID" e molto piu utile di "abbiamo bisogno di affidabilita."

Decisione

Dichiara la decisione chiaramente. Non "potremmo considerare" o "dovremmo esplorare" — cosa abbiamo effettivamente deciso.

## Decisione

Useremo PostgreSQL 15 come database primario per il servizio ordini.

Abbiamo scelto PostgreSQL perche:

- La conformita ACID e richiesta per i dati finanziari degli ordini
- Le colonne JSON forniscono flessibilita di schema per i metadati
- Il nostro team infrastruttura ha esperienza operativa con PostgreSQL
- I pattern di query sono adatti alla modellazione relazionale

Alternative Considerate

Questa e la sezione piu sottovalutata. Documentare cosa non hai scelto e spesso prezioso quanto documentare cosa hai scelto.

## Alternative Considerate

### MongoDB

Pro:

- Storage JSON nativo
- Scaling orizzontale piu semplice
- Evoluzione dello schema flessibile

Contro:

- Garanzie di consistenza piu deboli
- Team meno familiare con le operazioni
- Richiederebbe strumenti aggiuntivi per le transazioni

### DynamoDB

Pro:

- Completamente gestito, operazioni minime
- Eccellenti caratteristiche di scalabilita

Contro:

- Vendor lock-in su AWS
- Pattern di query limitati all'accesso per chiave di partizione/ordinamento
- Costo imprevedibile su larga scala

Conseguenze

Ogni decisione ha dei trade-off. Sii onesto al riguardo.

## Conseguenze

### Positive

- Forti garanzie di integrita dei dati
- Il team puo sfruttare l'expertise esistente su PostgreSQL
- Caratteristiche operative ben comprese

### Negative

- Le migrazioni dello schema richiedono piu pianificazione rispetto ai document store
- Lo scaling orizzontale e piu complesso se superiamo la capacita del singolo nodo
- Necessita di implementare sharding a livello applicativo se raggiungiamo i limiti

### Rischi

- Potrebbe essere necessario rivedere se il volume ordini supera 1M/giorno
- Le query sulle colonne JSON sono meno efficienti dei document store nativi

Quando Scrivere un ADR

Non ogni scelta tecnica necessita di un ADR. Usa il tuo giudizio, ma ecco alcune linee guida:

Scrivi un ADR Quando...

La decisione influenza piu team o servizi
La decisione sarebbe costosa da invertire
Stai scegliendo tra piu opzioni valide
I futuri membri del team potrebbero mettere in discussione la scelta
La decisione risolve un dibattito tecnico significativo

Non Scrivere un ADR Quando...

La scelta e ovvia e incontestata
La decisione influenza solo una persona o un file
E facilmente reversibile senza costi significativi
E un pattern standard che il team segue sempre

Errori Comuni Che Ho Fatto

Errore 1: Scrivere ADR a Posteriori

Il momento migliore per scrivere un ADR e durante il processo decisionale, non settimane dopo. Quando scrivi dopo, dimentichi le sfumature, le alternative considerate e i vincoli specifici.

Ora scriviamo bozze di ADR come parte del processo decisionale. La discussione avviene nel documento ADR, non nei thread Slack che scompaiono.

Errore 2: Farli Troppo Lunghi

Se il tuo ADR e piu di una pagina, probabilmente stai:

Documentando decisioni multiple (dividi in piu ADR)
Includendo dettagli implementativi (conservali per i documenti di design)
Spiegando eccessivamente contesto ovvio

La disciplina della brevita forza la chiarezza.

Errore 3: Non Collegare ADR Correlati

Le decisioni raramente esistono in isolamento. Quando abbiamo scelto Kafka per la comunicazione event-driven (ADR-0007), questo ha influenzato la nostra scelta del database (ADR-0042) perche potevamo accettare la consistenza eventuale.

Fai riferimenti incrociati agli ADR correlati.

Errore 4: Abbandonare la Pratica

Gli ADR forniscono valore nel tempo. Uno o due ADR non aiutano molto. Un corpus di 50+ ADR, accumulati negli anni, diventa incredibilmente prezioso. E una storia ricercabile della tua evoluzione architetturale.

La tentazione e smettere di scriverli quando le cose si fanno frenetiche. Resisti. I dieci minuti spesi a scrivere un ADR risparmieranno ore di riunioni dopo.

Rendere gli ADR Parte del Tuo Workflow

La parte piu difficile non e scrivere ADR — e farli diventare un'abitudine. Ecco cosa funziona:

Conservali Con il Codice

Metti gli ADR nel tuo repository, tipicamente in docs/adr/ o docs/decisions/. In questo modo:

Sono versionati con il codice che descrivono
Appaiono nelle code review
Non possono diventare orfani in qualche wiki

Usa un Template

Crea un template markdown che tutti usano. Riduce l'attrito e garantisce coerenza.

Revisiona gli ADR Trimestralmente

Imposta un promemoria per revisionare i tuoi ADR ogni trimestre:

Qualche decisione non e piu rilevante?
Le circostanze sono cambiate invalidando le nostre assunzioni?
Ci sono decisioni non documentate che dovremmo catturare?

Collega gli ADR ai Diagrammi Architetturali

E qui che strumenti come Archyl brillano. Quando colleghi un ADR a un componente specifico nel tuo diagramma C4, chiunque guardi quel componente puo vedere istantaneamente le decisioni che lo hanno plasmato.

"Perche questo servizio parla con Kafka invece che direttamente col database?" Clicca sull'ADR collegato e scoprilo.

Conclusione

I Record delle Decisioni Architetturali sono una di quelle pratiche che sembrano overhead finche non ne hai bisogno. Allora sono inestimabili.

Quella riunione di due ore su PostgreSQL vs MongoDB? L'abbiamo conclusa in dieci minuti quando qualcuno ha trovato l'ADR originale. Tutto il contesto era li — i vincoli, le alternative, il ragionamento. Abbiamo rapidamente confermato che la decisione originale era ancora valida e siamo andati avanti.

Inizia in piccolo. La prossima volta che prendi una decisione architetturale, prenditi quindici minuti per scrivere un ADR. Mettilo nel tuo repository. Tra sei mesi, quando qualcuno chiedera "perche l'abbiamo fatto cosi?", avrai la risposta.

Scopri di piu sulla documentazione dell'architettura: Introduzione al Modello C4 | Perche la Documentazione e Importante | Documentare i Flussi Utente

Best Practice per i Record delle Decisioni Architetturali (ADR) - Archyl Blog