Issue 9999
Le decisioni architetturali hanno bisogno di contesto
Una decisione senza razionale diventa il mistero di domani.
· 4 min
Obiettivo
Riconoscere perché una decisione architetturale deve conservare contesto, alternative valutate e conseguenze attese.
La decisione da sola non basta
Molti team documentano cosa è stato scelto, ma non spiegano perché. Il risultato è che, dopo qualche mese, nessuno sa più se quella scelta sia ancora valida o se fosse legata a vincoli temporanei. Per esempio, un team può decidere di usare un database relazionale invece di un database documentale, ma senza indicare che la scelta dipendeva da vincoli di reporting, competenze interne e necessità di transazioni forti. Quando il prodotto cresce, un nuovo team potrebbe mettere in discussione quella decisione senza capire il contesto originale.
Cattura il ragionamento
Una buona decisione architetturaleGlossarioDecisione architetturaleUna scelta progettuale significativa il cui contesto e i cui effetti devono restare comprensibili nel tempo.Apri la voce completa dovrebbe raccontare il problema, il contesto, le alternative valutate, la scelta fatta e le conseguenze previste. Questo va fatto mentre la discussione è ancora fresca, non settimane dopo. Ad esempio, se un'organizzazione decide di introdurre eventi asincroni tra CRM, OMS e sistemi di fulfillment, dovrebbe spiegare non solo che userà una coda o un event bus, ma anche perché il modello sincrono non era più sostenibile, quali rischi introduce l'asincronia e come verranno gestiti retryGlossarioRetryUn nuovo tentativo eseguito dopo un fallimento che potrebbe essere transitorio.Apri la voce completa, idempotenzaGlossarioIdempotenzaLa proprietà per cui ripetere un’operazione non produce effetti aggiuntivi indesiderati.Apri la voce completa e osservabilitàGlossarioOsservabilitàLa capacità di comprendere il comportamento di un sistema a partire dai segnali che produce.Apri la voce completa. • Descrivi il problema, i vincoli tecnici, i vincoli organizzativi e il contesto di business. • Nomina le alternative considerate, anche quelle scartate, spiegando perché non sono state scelte. • Rendi esplicite le conseguenze positive e negative, inclusi costi operativi, complessità, rischi e impatti sui team. • Indica quali condizioni future potrebbero rendere necessario rivedere la decisione.
Una piattaforma di pagamento cambia provider
Immagina una piattaforma enterprise che gestisce pagamenti digitali per più canali: e-commerce, call center e vendite assistite in negozio. Il team decide di passare da un'integrazione custom con un vecchio payment provider a una soluzione più moderna basata su redirect sicuro e verifica server-to-server. La decisione viene documentata spiegando il contesto: requisiti PCI, riduzione della gestione diretta di dati sensibili, migliore supporto a wallet digitali, necessità di tracciamento end-to-end e integrazione con sistemi come OMS, CRM e piattaforme di marketing automation. Vengono anche registrate le alternative scartate, come mantenere il provider esistente o introdurre un layer interno di orchestrazione pagamenti. Sei mesi dopo, quando emerge un problema di latenza nella conferma dei pagamenti, il team non deve ricostruire tutto da memoria o chat sparse: può leggere l'ADRGlossarioADRUn record durevole di una decisione architetturale e del ragionamento che l’ha guidata.Apri la voce completa e capire quali compromessi erano stati accettati e quali condizioni giustificano una revisione.
Mantieni la documentazione proporzionata
Non ogni scelta richiede un documento lungo. Decidere il nome di una tabella o il formato di una label non ha lo stesso peso di scegliere il database master di un dominioGlossarioDominioLa parte del mondo reale, del business o dell’organizzazione che un sistema deve supportare.Apri la voce completa, il modello di autenticazione o il pattern di integrazione tra sistemi core. Il punto non è scrivere tanto, ma scrivere abbastanza. Una decisione piccola può bastare in poche righe dentro un decision log. Una decisione che influenza qualità architetturali come scalabilità, sicurezza, manutenibilità, costo operativo o autonomia dei team merita invece un ADR completo. La domanda pratica è: se tra sei mesi qualcuno dovesse modificare questa scelta, avrebbe abbastanza informazioni per farlo senza danneggiare il sistema?
Riferimenti
Una fonte esterna autorevole per approfondire il formato degli Architecture Decision Record e il valore del contesto decisionale. • Michael Nygard, Documenting Architecture Decisions — https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions