Issue 10084
Quale artefatto serve davvero?
Parti dall'incertezza da ridurre e dalla decisione da abilitare, non dal template disponibile.
· 5 min
Obiettivo
Saper scegliere un artifact a partire dall'incertezza da ridurre, dalla persona che deve consumarlo e dalla decisione o attività che deve abilitare, invece di applicare un template standard.
Prima la domanda, poi l'artefatto
Un artifact architetturale è utile quando consente a qualcuno di decidere o agire senza dover ricostruire il ragionamento. Prima di aprire un template, chiarisci cinque aspetti: quale incertezza vuoi ridurre, chi consumerà il risultato, quale decisione o attività deve abilitare, per quanto tempo dovrà restare valido e quale formato minimo rende l'informazione non ambigua. Per allineare sponsorGlossarioSponsorChi può sostenere o fermare il lavoro perché ne porta il rischio o il risultato, distinto da chi ha solo aperto la richiesta.Apri la voce completa e responsabili di dominioGlossarioDominioLa parte del mondo reale, del business o dell’organizzazione che un sistema deve supportare.Apri la voce completa può bastare una vista di contesto; per coordinare due team serve forse una specifica del contratto versionata; per conservare una scelta e le sue conseguenze è più adatto un ADRGlossarioADRUn record durevole di una decisione architetturale e del ragionamento che l’ha guidata.Apri la voce completa. Scegli poi il dettaglio minimo sufficiente. Puoi fermarti quando aggiungere informazioni non cambia una decisione, non elimina un'ambiguità rilevante e non riduce un rischio concreto.
Meno documenti, ma con un costo esplicito
Un artifact leggero accelera l'esplorazione e costa poco da aggiornare, ma può lasciare interpretazioni diverse quando più team devono implementare la stessa scelta. Un artifact preciso, versionato o machine-readable riduce l'ambiguità e facilita verifica e automazione, ma richiede ownership e manutenzione. Anche la durata conta: una matrice temporanea evita di istituzionalizzare ipotesi ancora fragili; un ADR conserva invece motivazioni e conseguenze di una decisione durevole. Il compromesso non è tra documentare e non documentare, ma tra il costo dell'artifact e il costo futuro dell'incertezza che resta.
La stessa integrazione, tre consumatori diversi
Un'impresa sta separando il processo ordini da un ERP e introduce un servizio dedicato. Il comitato di programma deve capire confini, dipendenze e rischi di migrazione: una vista di contesto con pochi flussi è sufficiente. I team ERP e piattaforma devono implementare lo scambio degli eventi: servono schema versionato, regole di compatibilità, esempi e gestione degli errori. Il responsabile di architettura deve rendere tracciabile la scelta tra chiamate sincrone ed eventi: un ADR registra alternative, motivazioni e conseguenze operative. Produrre un unico diagramma molto dettagliato non soddisferebbe bene nessuno dei tre bisogni. Tre artifact mirati, con profondità e durata differenti, riducono invece tre incertezze distinte.
Per approfondire
Fonti autorevoli per approfondire la scelta e la gestione degli artifact architetturali. • Architecture Decision Records - Architectural Decision Records community - https://adr.github.io/ • C4GlossarioC4Un modello di diagrammi di architettura a quattro livelli: Context, Container, Component e Code.Apri la voce completa model - Simon Brown - https://c4model.com/