Il Registro delle Decisioni di Architettura: Perché il Tuo Team ne ha Bisogno
Tutti i team di ingegneria hanno avuto questa conversazione. Uno sviluppatore apre un modulo, guarda un'implementazione che sembra inutilmente complessa e chiede: "Perché è stato costruito così?" Il silenzio cala nella stanza. La persona che ha preso la decisione è andata via otto mesi fa. Nessuno può spiegare il ragionamento reale.
Il team fa una di due cose. O lascia com'è per paura ("probabilmente c'era una ragione"). O lo refactoring, reintroducendo inconsapevolmente esattamente il problema che l'implementazione originale era progettata per evitare.
Gli Architecture Decision Record risolvono questo problema. Sono una delle pratiche più semplici e con il maggior ROI che un team di ingegneria possa adottare, e la maggior parte dei team non le usa.
Cos'è Davvero un ADR
Un ADR è un documento breve — di solito meno di una pagina — che cattura una singola decisione architettturale. Non un documento di design. Non un RFC. Solo un registro di cosa è stato deciso, perché è stato deciso e quali sono le conseguenze attese.
Il formato è deliberatamente minimale. La struttura più utilizzata, basata sulla proposta originale di Michael Nygard, ha cinque sezioni:
- Titolo. Una breve frase nominale.
- Stato. Proposto, Accettato, Deprecato o Sostituito.
- Contesto. Qual è la situazione? Quali forze sono in gioco?
- Decisione. Cosa abbiamo deciso? Dichiaralo chiaramente.
- Conseguenze. Cosa deriva da questa decisione? Sia positive che negative.
Perché la Sezione del Contesto è Tutto
La decisione stessa di solito è evidente guardando il codice. Quello che non puoi vedere è il perché. Ed è lì che risiede tutto il valore.
Un buon contesto cattura il panorama decisionale del momento: le alternative esistenti, i vincoli in cui il team operava, i compromessi valutati.
Esempi di Buoni Argomenti per gli ADR
La soglia che uso: se la decisione è difficile da invertire, riguarda più parti del sistema, o sarà messa in discussione dai futuri membri del team, scrivi un ADR.
Esempi:
- Scelta del database. "ADR-003: Usare PostgreSQL per i dati transazionali e Redis per lo storage delle sessioni."
- Approccio all'autenticazione. "ADR-007: Implementare autenticazione stateless basata su JWT con token di aggiornamento."
- Selezione di servizi terzi. "ADR-015: Usare Stripe per l'elaborazione dei pagamenti."
Dove Vivono gli ADR
Questo è non negoziabile: gli ADR vivono nel repository del codice. Non in Confluence. Non in Google Docs. Nel repository, in una directory come /docs/adr/, versionata insieme al codice che descrivono.
Il Costo della Mancanza di ADR
Conoscenza tribale. Le decisioni architetturali vivono nelle teste di chi le ha prese. Quando quelle persone vanno via, la conoscenza va con loro.
Dibattiti ripetuti. Senza un registro del perché, i team rivisitano le stesse discussioni ogni pochi mesi.
Attrito nell'onboarding. Un nuovo membro del team deve fare reverse engineering di tutta la logica architettturale.
Iniziare Senza Burocrazia
La prossima volta che il tuo team prende una decisione architettturale significativa, fai sì che la persona che l'ha guidata passi 20 minuti a scriverla in formato a cinque sezioni. Mettila in una PR. Revisionala. Fai il merge. Questo è il tuo primo ADR.
In Conectia, abbiamo visto gli ADR fare una differenza particolarmente grande nei team distribuiti. Quando i nostri ingegneri senior si uniscono al team di un cliente, gli ADR esistenti permettono loro di capire la logica architettturale in giorni invece di settimane.
Stai costruendo un team che prende solide decisioni architetturali e le documenta? Parla con un CTO — i nostri ingegneri senior LATAM portano la disciplina del processo decisionale strutturato alla tua codebase fin dal primo giorno.
