Architecture Decision Records (ADR): La Guida Completa

Ogni sistema software e plasmato da centinaia di decisioni. PostgreSQL invece di MongoDB. REST invece di GraphQL. Monolite invece di microservizi. Event-driven invece di request-response. Ogni scelta vincola le scelte future, e insieme definiscono l'architettura.

Il problema e che le decisioni sono invisibili. Il codice mostra cosa e stato costruito, non perche e stato costruito in quel modo. Sei mesi dopo aver scelto PostgreSQL, nessuno ricorda se il team ha considerato DynamoDB, quali erano i requisiti di performance, o perche la consistenza eventuale era inaccettabile. La decisione e incorporata nel codice, ma il ragionamento si e perso.

Gli Architecture Decision Records (ADR) risolvono questo problema catturando ogni decisione significativa in un breve documento strutturato. Sono una delle pratiche di documentazione a piu alto impatto nell'ingegneria del software -- semplici da adottare, economiche da mantenere e inestimabili quando servono.

Questa guida copre tutto, dalle basi alle pratiche avanzate: cosa sono gli ADR, come scriverli, template da adottare subito, errori comuni e come integrare gli ADR nel vostro workflow con strumenti moderni.

Cos'e un Architecture Decision Record?

Un Architecture Decision Record e un breve documento che cattura una singola decisione architetturale. L'enfasi e su singola e breve:

• Singola: Un ADR, una decisione. "Usare PostgreSQL per il servizio ordini" e un ADR. "Definire l'intera strategia del database" e un documento di design, non un ADR.
• Breve: Un ADR dovrebbe stare in una pagina. Se e piu lungo, probabilmente state documentando piu decisioni o includendo troppi dettagli implementativi.

Il concetto e stato reso popolare da Michael Nygard in un blog post del 2011. Da allora, gli ADR sono stati adottati da organizzazioni che vanno dalle startup ai governi. Il UK Government Digital Service, Spotify e innumerevoli team di ingegneria usano gli ADR come pratica standard.

Cosa Catturano gli ADR

Ogni ADR risponde a quattro domande fondamentali:

1. Qual era il contesto? Quale situazione o problema ha motivato questa decisione?
2. Cosa abbiamo deciso? Qual e la specifica scelta architetturale che abbiamo fatto?
3. Quali alternative abbiamo considerato? Quali altre opzioni erano sul tavolo?
4. Quali sono le conseguenze? Quali trade-off, rischi e implicazioni comporta questa decisione?

Tutto qui. Quattro domande. Un ADR ben scritto puo rispondere a tutte e quattro in meno di una pagina.

Cosa NON Sono gli ADR

• Non sono documenti di design. Gli ADR non descrivono come qualcosa e implementato. Descrivono perche un particolare approccio e stato scelto.
• Non sono RFC. Gli RFC (Request for Comments) sono proposte per la discussione. Gli ADR documentano decisioni concluse (anche se un ADR puo iniziare come proposta e passare ad accettato).
• Non sono verbali di riunione. Gli ADR catturano il risultato, non la discussione che l'ha prodotto.
• Non sono documentazione completa. Gli ADR completano i diagrammi di architettura, le specifiche API e i runbook. Non li sostituiscono.

Il Template ADR Standard

Esistono diversi template ADR, ma la maggior parte sono variazioni della stessa struttura di base. Ecco un template pratico che bilancia completezza e brevita:

# ADR-NNNN: [Breve Titolo che Descrive la Decisione]

## Stato

[Proposto | Accettato | Deprecato | Sostituito da ADR-XXXX]

## Data

[AAAA-MM-GG]

## Contesto

[Descrivete la situazione. Quale problema stiamo risolvendo? Quali vincoli
esistono? Quali forze sono in gioco? Siate specifici -- includete numeri,
scadenze, capacita del team e requisiti tecnici dove rilevante.]

## Decisione

[Enunciate la decisione in modo chiaro e conciso. Usate la voce attiva:
"Useremo X" non "X dovrebbe essere considerato."]

## Alternative Considerate

### [Alternativa 1]
- Pro: ...
- Contro: ...
- Perche scartata: ...

### [Alternativa 2]
- Pro: ...
- Contro: ...
- Perche scartata: ...

## Conseguenze

### Positive
- [Cosa diventa piu facile o migliore]

### Negative
- [Cosa diventa piu difficile o peggiore]

### Rischi
- [Cosa potrebbe andare storto]

## Decisioni Correlate

- [Link ad ADR correlati]

Analisi di Ogni Sezione

Stato traccia il ciclo di vita di una decisione. Il flusso tipico e: Proposto -> Accettato. Se le circostanze cambiano, un ADR diventa Deprecato o Sostituito da un ADR piu recente. Importante: non dovreste mai cancellare gli ADR -- anche le decisioni rifiutate sono preziose perche impediscono ai team futuri di riconsiderare opzioni gia valutate.

Data stabilisce quando la decisione e stata presa. Questo fornisce contesto temporale: "Abbiamo scelto questa tecnologia nel 2024 quando la nostra scala era X. Ora che la nostra scala e 10X, dovremmo rivalutare."

Contesto e la sezione piu importante. Un contesto ben scritto fornisce ai lettori futuri informazioni sufficienti per capire perche questa decisione aveva senso al momento, anche se le circostanze sono cambiate. Includete numeri specifici ("processiamo 50K ordini al giorno"), vincoli ("deve essere conforme a PCI-DSS") e fattori del team ("tre ingegneri hanno esperienza con PostgreSQL, nessuno con MongoDB").

Decisione deve essere inequivocabile. "Useremo PostgreSQL 16 come data store primario per il servizio ordini" va bene. "Dovremmo probabilmente considerare un database relazionale" non e un ADR -- e un suggerimento.

Alternative Considerate e la sezione che fa risparmiare piu tempo nel lungo periodo. Quando un nuovo ingegnere chiede "perche non abbiamo usato MongoDB?", la risposta e proprio qui. Quando il team rivaluta la decisione un anno dopo, puo vedere cosa e stato valutato e perche e stato scartato. Senza questa sezione, i team ridiscutono gli stessi dibattiti all'infinito.

Conseguenze riguarda l'onesta intellettuale. Ogni decisione ha dei trade-off. Riconoscere gli svantaggi costruisce fiducia e aiuta i team futuri a capire quando le circostanze potrebbero giustificare la revisione della decisione.

Un Esempio Completo di ADR

Ecco un ADR realistico che dimostra il template in pratica:

# ADR-0023: Usare Apache Kafka per la Comunicazione Inter-Servizi

## Stato

Accettato

## Data

2025-11-15

## Contesto

La nostra piattaforma e cresciuta da 3 a 12 microservizi nell'ultimo anno.
I servizi attualmente comunicano in modo sincrono tramite chiamate HTTP REST.
Questo crea diversi problemi:

- Fallimenti a cascata: quando il servizio inventario e giu, il servizio
  ordini non puo processare ordini, anche se i controlli di inventario
  potrebbero essere eventuali.
- Accoppiamento stretto: i servizi devono conoscere i contratti API e gli
  endpoint degli altri.
- Colli di bottiglia nelle performance: alcune operazioni innescano catene
  di 4-5 chiamate sincrone, aggiungendo latenza.

Processiamo circa 100K eventi al giorno. Prevediamo che cresca a 500K
entro 12 mesi. Il team ha 8 ingegneri backend, 2 dei quali hanno
esperienza pregressa con Kafka.

## Decisione

Adotteremo Apache Kafka come meccanismo primario per la comunicazione
asincrona inter-servizi. L'HTTP sincrono restera per i pattern
request/response dove il chiamante necessita di un risultato immediato
(es. verifiche di autenticazione).

Useremo Confluent Cloud come provider Kafka gestito per minimizzare
l'overhead operativo.

## Alternative Considerate

### RabbitMQ
- Pro: Piu semplice da operare, curva di apprendimento inferiore,
  supporta multipli pattern di messaggistica (pub/sub, point-to-point,
  routing).
- Contro: Meno adatto per pattern di event sourcing che prevediamo di
  adottare. Capacita di replay/rewind piu deboli. Il momentum della
  community si e spostato verso Kafka per architetture event-driven.
- Perche scartato: Prevediamo di aver bisogno del replay degli eventi per
  audit e debugging. L'architettura basata su log di Kafka e piu adatta.

### AWS SQS + SNS
- Pro: Completamente gestito, nessuna infrastruttura da mantenere,
  integrazione stretta con AWS.
- Contro: Vendor lock-in su AWS. Garanzie limitate sull'ordinamento dei
  messaggi. Nessun processing di stream integrato (servirebbe Kinesis o
  Lambda). Costo per messaggio piu alto al nostro volume previsto.
- Perche scartato: Vogliamo evitare di approfondire il lock-in AWS, e
  abbiamo bisogno di consegna ordinata dei messaggi per eventi finanziari.

### Mantenere HTTP Sincrono (con circuit breaker)
- Pro: Nessuna nuova infrastruttura. Team gia familiare. I circuit breaker
  risolvono i fallimenti a cascata.
- Contro: Non risolve l'accoppiamento stretto. La latenza si accumula
  ancora attraverso le catene di chiamate. I circuit breaker sono un
  cerotto, non una soluzione al problema fondamentale di accoppiamento.
- Perche scartato: Risolve i sintomi, non la causa radice.

## Conseguenze

### Positive
- I servizi diventano disaccoppiati: i produttori non devono conoscere i
  consumatori.
- Fallimenti a cascata eliminati per i workflow asincroni.
- Il replay degli eventi abilita potenti capacita di debugging e audit.
- Base per pattern di event sourcing nei servizi futuri.

### Negative
- La complessita operativa aumenta (cluster Kafka, schema registry,
  gestione consumer group). Mitigato usando Confluent Cloud.
- Il team necessita di formazione sui concetti e pattern Kafka.
- La consistenza eventuale sostituisce la consistenza forte per i flussi
  asincroni. Alcuni workflow necessitano di riprogettazione.
- Il debugging dei flussi asincroni distribuiti e piu difficile che
  tracciare chiamate HTTP sincrone. Avremo bisogno di distributed tracing
  (vedi ADR-0024).

### Rischi
- Se il volume di messaggi supera le fasce di prezzo di Confluent Cloud,
  i costi potrebbero aumentare significativamente. Monitorare e impostare
  alert.
- L'evoluzione degli schema tra servizi richiede disciplina. Prevediamo
  di adottare Avro con schema registry.

## Decisioni Correlate

- ADR-0024: Adottare OpenTelemetry per il Distributed Tracing
- ADR-0018: Contratti di Comunicazione tra Servizi (sostituito da
  questo ADR)

Questo ADR e di circa 400 parole. Ci sono voluti forse 20 minuti per scriverlo. Fara risparmiare ore di riunioni nei prossimi anni.

Quando Scrivere un ADR

Non ogni scelta tecnica necessita di un ADR. Scegliere tra due librerie JSON non lo giustifica. Ma alcune decisioni assolutamente si.

Scrivete un ADR Quando:

• La decisione influenza la struttura del sistema. Tutto cio che cambia come comunicano i servizi, dove risiedono i dati o come sono organizzati i componenti.
• La decisione e costosa da invertire. Scegliere un database, un sistema di messaggistica o una piattaforma di deployment. Se annullare questa decisione richiede piu di uno sprint, documentate perche l'avete presa.
• Esistono piu opzioni valide. Se la scelta e ovvia, nessun ADR necessario. Se avete discusso tra tre opzioni, catturate il ragionamento.
• La decisione attraversa i confini dei team. Qualsiasi scelta architetturale che influenza altri team dovrebbe essere documentata affinche capiscano la logica.
• Il voi del futuro potrebbe mettere in discussione la scelta. Se c'e qualche possibilita che qualcuno (incluso il vostro io futuro) chieda "perche l'abbiamo fatto cosi?", scrivetelo ora.

Saltate l'ADR Quando:

• La scelta segue uno standard consolidato del team (es. "usiamo sempre Go per i servizi backend" non necessita di un nuovo ADR per ogni servizio)
• La decisione e banalmente reversibile (rinominare una variabile, scegliere un formattatore di codice)
• La decisione e puramente estetica (stile del codice, convenzioni di nomenclatura -- queste appartengono a una style guide)

Ciclo di Vita e Governance degli ADR

Il Ciclo di Vita

Gli ADR hanno un ciclo di vita naturale:

1. Bozza/Proposto: Qualcuno identifica una decisione che deve essere presa e scrive una bozza di ADR. Il team discute.
2. Accettato: Il team concorda sulla decisione. Lo stato dell'ADR cambia in Accettato.
3. Attivo: La decisione e in vigore. L'ADR serve come documentazione di riferimento.
4. Sostituito: Una nuova decisione sostituisce questa. Il vecchio ADR riceve lo stato "Sostituito da ADR-XXXX". Il nuovo ADR fa riferimento al vecchio.
5. Deprecato: La decisione non e piu rilevante (forse il sistema a cui si applicava e stato dismesso).

Importante: non cancellate mai gli ADR. Anche quelli deprecati o sostituiti sono preziosi. Formano una timeline dell'evoluzione architetturale.

Numerazione

Usate numeri sequenziali: ADR-0001, ADR-0002, ecc. Il numero fornisce un ordinamento cronologico e rende gli ADR facili da referenziare nelle conversazioni: "come deciso nell'ADR-42."

Alcuni team usano numerazione basata sulla data (ADR-2026-03-27-kafka) ma i numeri sequenziali sono piu semplici e diffusi.

Cadenza di Revisione

Impostate un promemoria trimestrale per revisionare i vostri ADR:

• Ci sono decisioni accettate non piu valide?
• I vincoli sono cambiati invalidando le assunzioni?
• Ci sono decisioni che il team ha preso informalmente e che dovrebbero essere catturate?

Questa revisione previene il deterioramento degli ADR e mantiene la raccolta aggiornata.

Dove Conservare gli ADR

Gli approcci piu comuni, in ordine di raccomandazione:

Nel Repository del Codice

Conservate gli ADR in docs/adr/ o docs/decisions/ all'interno del vostro repository. Questo e l'approccio piu popolare e per buone ragioni:

• Gli ADR sono versionati accanto al codice che descrivono
• Appaiono nelle pull request e nelle code review
• Non possono diventare orfani in qualche wiki
• Sono scopribili tramite grep o ricerca

Convenzione: un file markdown per ADR, nominato con il numero e uno slug:

docs/adr/
  0001-use-postgresql-for-orders.md
  0002-adopt-event-driven-architecture.md
  0003-monorepo-for-frontend.md

In uno Strumento di Architettura Dedicato

Strumenti come Archyl forniscono gestione ADR integrata con capacita aggiuntive:

• Collegare gli ADR direttamente agli elementi del modello C4 (container, componenti, relazioni)
• Cercare e filtrare ADR attraverso tutti i progetti
• Tracciare lo stato e il ciclo di vita degli ADR
• Connettere gli ADR alle regole di conformance che applicano la decisione

Il vantaggio chiave di uno strumento di architettura e il contesto. Quando uno sviluppatore guarda il container PostgreSQL in un diagramma C4, puo cliccare per vedere l'ADR che spiega perche PostgreSQL e stato scelto. La decisione e l'architettura sono connesse, non in silos.

In un Wiki (Non Raccomandato)

I wiki (Confluence, Notion, ecc.) sono dove gli ADR vanno a essere dimenticati. Sono disconnessi dal codice, difficili da scoprire e raramente mantenuti. Se dovete usare un wiki, almeno fate riferimenti incrociati agli ADR dal repository del codice.

Integrare gli ADR nel Vostro Workflow

Rendete gli ADR Parte delle Pull Request

Per cambiamenti architetturali significativi, richiedete un ADR come parte della pull request. Aggiungete una sezione al vostro template PR:

## Impatto Architetturale

- [ ] Nessun cambiamento architetturale
- [ ] ADR creato/aggiornato: [link]

Questo normalizza la creazione di ADR e assicura che le decisioni siano documentate quando vengono prese, non settimane dopo quando il contesto e sfumato.

Usate gli ADR nelle Review dell'Architettura

Durante le review dell'architettura o le discussioni di design, fate riferimento agli ADR esistenti. "Prima di riprogettare questo, controlliamo cosa dice l'ADR-15 sul perche abbiamo scelto questo approccio." Questo da visibilita agli ADR e rafforza l'abitudine di documentare le decisioni.

Connettete gli ADR ai Diagrammi di Architettura

Qui e dove gli ADR diventano davvero potenti. Quando un ADR e collegato a un elemento specifico nel vostro modello C4, crea un grafo di conoscenza navigabile:

• Cliccate sul container Kafka nel vostro diagramma dei Container -> vedete l'ADR-0023 che spiega perche Kafka e stato scelto
• Cliccate sul database PostgreSQL -> vedete l'ADR-0001 che spiega la selezione del database
• Cliccate sull'API Gateway -> vedete l'ADR-0012 che spiega perche Kong e stato scelto rispetto al routing personalizzato

In Archyl, potete collegare gli ADR a qualsiasi elemento C4 -- sistemi, container, componenti o relazioni. Questa connessione significa che le decisioni architetturali non sono documenti fluttuanti; sono ancorate alle parti specifiche dell'architettura che influenzano.

Automatizzate Cio Che Potete

Diversi strumenti possono ridurre l'attrito della gestione ADR:

• adr-tools (di Nat Pryce): Uno strumento da linea di comando per creare e gestire ADR in un repository. Eseguite adr new "Use Kafka for messaging" per generare un nuovo ADR da un template.
• Log4brains: Genera un sito web ricercabile e navigabile dai vostri file markdown ADR.
• Archyl: Gestisce ADR con collegamento agli elementi C4, tracciamento dello stato e ricerca cross-progetto.

Pratiche ADR Avanzate

ADR Leggeri (LADR)

Alcuni team trovano anche il template standard troppo pesante. Un ADR Leggero e composto da tre frasi:

Nel contesto di [situazione],
abbiamo deciso [decisione],
per raggiungere [obiettivo],
accettando [trade-off].

Esempio:

Nel contesto della necessita di comunicazione inter-servizi che tolleri
i downtime dei servizi, abbiamo deciso di usare Apache Kafka tramite
Confluent Cloud, per raggiungere il disaccoppiamento dei servizi e la
capacita di replay degli eventi, accettando una maggiore complessita
operativa e la consistenza eventuale.

Questo formato funziona bene per decisioni abbastanza importanti da documentare ma che non giustificano un ADR completo.

Decision Log

Un decision log e un singolo documento che elenca tutti gli ADR in ordine cronologico con riassunti di una riga. Serve come indice:

Questo da una panoramica rapida di tutte le decisioni senza aprire singoli file ADR.

ADR per Decisioni Non Tecniche

Gli ADR non sono limitati alle scelte tecnologiche. I team li usano per:

• Decisioni di processo: "Faremo pair programming per il codice critico per la sicurezza"
• Decisioni organizzative: "Il team piattaforma possiede tutti i container infrastrutturali"
• Decisioni sui vendor: "Useremo Datadog per il monitoraggio invece di costruirlo in-house"

Se la decisione e significativa e reversibile-ma-costosa, un ADR e appropriato indipendentemente dal fatto che sia strettamente "architetturale."

Errori Comuni

Scrivere ADR a Posteriori

Il momento migliore per scrivere un ADR e durante il processo decisionale. Scriverne uno settimane dopo significa che avete dimenticato le sfumature, le alternative considerate e i vincoli che esistevano. Rendete la scrittura dell'ADR parte del processo decisionale, non un ripensamento.

Farli Troppo Lunghi

Se il vostro ADR supera una pagina, probabilmente state documentando piu decisioni (dividetele) o includendo dettagli implementativi (conservateli per un documento di design). La disciplina della brevita forza la chiarezza.

Non Documentare le Alternative Scartate

La sezione "Alternative Considerate" e la parte piu preziosa di un ADR nel lungo periodo. Senza di essa, i futuri ingegneri proporranno le stesse alternative, ignari che sono gia state valutate e scartate. Spiegate sempre cosa non avete scelto e perche.

Abbandonare la Pratica

Uno o due ADR non forniscono molto valore. Cinquanta ADR accumulati in due anni diventano una base di conoscenza inestimabile. La tentazione di smettere di scrivere ADR quando le cose si fanno frenetiche e forte. Resistete. I 15 minuti spesi a scrivere un ADR risparmieranno ore di riunioni dopo.

Non Revisionare o Aggiornare lo Stato

Una raccolta di ADR dove meta delle decisioni sono obsolete e fuorviante. Programmate revisioni trimestrali. Segnate le decisioni sostituite. Mantenete la raccolta affidabile.

Perche gli ADR Contano di Piu nell'Era dell'IA

Man mano che gli agenti IA diventano partecipanti attivi nello sviluppo software, gli ADR assumono una nuova importanza. Un agente IA che scrive codice puo leggere i vostri ADR e comprendere:

• Perche certe tecnologie sono state scelte (e dovrebbero continuare a essere usate)
• Quali alternative sono state scartate (e non dovrebbero essere riproposte)
• Quali vincoli esistono (requisiti di compliance, soglie di performance)
• Quali trade-off sono stati accettati (consistenza eventuale, dipendenze da vendor)

Attraverso il server MCP di Archyl, agenti IA come Claude Code possono accedere ai vostri ADR prima di formulare suggerimenti architetturali. Invece di proporre MongoDB per un servizio dove avete gia documentato perche PostgreSQL e stato scelto, l'agente rispetta la decisione esistente -- o segnala esplicitamente quando pensa che la decisione dovrebbe essere rivalutata.

Questo rende gli ADR non solo documentazione per gli umani, ma guardrail per l'IA.

Per Iniziare Oggi

Se il vostro team non usa ancora gli ADR, iniziate con questi tre passi:

1. Scegliete una decisione recente. Pensate a una scelta architetturale che il vostro team ha discusso nell'ultimo mese. Scrivete un ADR usando il template qui sopra. Dovrebbe richiedere 15-20 minuti.

2. Conservatelo nel vostro repository. Create una directory docs/adr/ e aggiungete il file. Includetelo nella vostra prossima pull request affinche il team lo veda.

3. Rendetelo un'abitudine. Aggiungete un checkbox "Impatto Architetturale" al vostro template PR. Discutete gli ADR nella vostra prossima riunione sull'architettura. La pratica acquisisce momentum una volta che il team ne vede il valore.

La prossima volta che qualcuno chiedera "perche l'abbiamo fatto cosi?" -- e lo chiedera -- avrete la risposta.

Approfondite la documentazione dell'architettura: Cos'e il Modello C4? | Best Practice per gli ADR | AI-Powered Architecture Discovery. Oppure provate Archyl gratis per gestire ADR collegati direttamente al vostro modello C4.