Dall'RFC all'ADR: Raggiungere la Decisione e Mantenere il Ragionamento

La decisione che nessuno poteva ricostruire

Il nuovo responsabile tecnico pone una domanda ragionevole: perché ogni servizio comunica con il sistema di fatturazione attraverso quella coda? C'è un ADR — ADR-014, quattro frasi, scritto undici mesi fa. Contesto: "avevamo bisogno di un'integrazione di fatturazione affidabile." Decisione: "usa la coda." Conseguenze: "un po' di latenza aggiuntiva." È tecnicamente un record. Non risponde a nulla.

Eri lì, quindi sai cosa non dice ADR-014: la discussione di tre settimane su due canali Slack e un acceso thread di PR; l'opzione API sincrona che ha perso a causa di un limite di velocità che è stato successivamente aumentato; l'obiezione dell'ingegnere del personale a cui è stata data risposta con un benchmark che nessuno riesce a trovare ora. Il dibattito è avvenuto. Il resoconto è stato scritto successivamente, dalla memoria, da una persona, un venerdì.

Questo è il modo di fallimento documentato, quasi universale, di una pratica genuinamente buona. Le linee guida prescrittive di AWS e i documenti Well-Architected di Microsoft raccomandano entrambi gli ADR — e notano entrambi il dolore: mantenerli aggiornati richiede tempo e gestirli diventa complesso man mano che i team e le scelte si moltiplicano. La causa principale è strutturale: il dibattito e il documento vivono in luoghi diversi, quindi il documento è sempre una trascrizione imprecisa. La soluzione è farli diventare lo stesso luogo. Né la pratica è specifica per l'ingegneria, né tantomeno per gli ADR. Google richiede un documento di design — problema, approccio proposto, alternative considerate, compromessi — scritto e revisionato prima che inizi un lavoro tecnico significativo, una pratica delineata nel Software Engineering at Google della compagnia. È la stessa disciplina di un ADR, applicata un passo prima: l'ADR registra la scelta a cui un documento di design è arrivato. I due falliscono allo stesso modo per la stessa ragione, e entrambi vengono risolti con la stessa mossa — tenere il dibattito dove vive il documento, piuttosto che trascrivere uno nell'altro successivamente. Leggi ogni passo qui sotto come se coprisse entrambi gli artefatti.

Perché gli ADR marciscono

Una frase del materiale della comunità ADR racchiude tutta la diagnosi: un RFC riguarda solitamente il raggiungimento di un accordo; un ADR registra l'accordo una volta raggiunto. Due artefatti, due momenti — e tutto ciò che c'è tra di essi perde. Le alternative che erano "ovviamente" sbagliate non vengono registrate (fino a quando non smettono di essere ovvie). L'obiezione che ha plasmato il design finale sopravvive solo come commento PR in un thread chiuso. La sezione di contesto viene scritta per ultima, nel modo peggiore, da chi ha perso il gioco del non-it. Riunioni che avrebbero dovuto produrre decisioni producono sintesi invece, e il ragionamento che rende una decisione durevole — la cosa su cui dipende l'intera catena di qualità delle decisioni — è esattamente ciò che la trascrizione abbandona.

Passo 1–3: La proposta, il contesto, le opzioni

1. 1Indica la proposta come la rivendicazione principale — la decisione proposta, non una domanda: "Instraderemo tutte le scritture di fatturazione attraverso una coda durevole." Questa frase è il titolo del futuro ADR. Checkpoint: la radice esiste, una frase, scritta dal proponente.
2. 2Contesto come argomenti pro separati. Ogni forza che rende necessaria la decisione — il requisito di affidabilità, il limite di tariffa del sistema di fatturazione, il mandato di audit — è il proprio argomento sotto la radice. Un paragrafo "Contesto" monolitico non può essere messo in discussione; tre affermazioni di contesto separate possono essere ciascuna interrogate, confermate o demolite individualmente. Checkpoint: ≥2 argomenti di contesto, ciascuno una forza.
3. 3Ogni opzione ha il proprio nodo. La coda, l'API sincrona, il lavoro in batch — argomenti fratelli, ognuno con i propri pro e contro. Pro/contro è relativo al genitore, quindi gli svantaggi di un'opzione dipendono da quell'opzione, non dalla decisione. Includi le opzioni che ti aspetti di rifiutare: il fratello rifiutato è ciò che risponde al "perché non abbiamo semplicemente..." dell'anno prossimo. Checkpoint: ogni opzione di cui un lettore potrebbe chiedere esiste.

Passo 4–6: Il giro RFC che lascia un record

Ora il giro di revisione — normalmente la parte che si disperde tra chat, commenti e corridoi. Qui si svolge come tre tipi di scambio strutturato, ciascuno un dialogo a quattro turni tra un revisore e l'autore dell'opzione:

Passo 7: Decidere — e cosa non è la valutazione

I decisori valutano le opzioni: una etichettata con una valutazione ciascuna. La distribuzione è una prova genuina — dove si trovava la stanza, ufficialmente, prima della chiamata. Ma la valutazione non è la decisione. Un umano nominato decide ancora, e se la chiamata va contro la distribuzione, il nodo decisionale è dove questo viene spiegato. (Chi dovrebbe essere quel umano nominato e come assegnare il ruolo prima del dibattito piuttosto che dopo, è una disciplina a sé — vedi il tutorial sui diritti decisionali.)

Passo 8–9: L'ADR che non dovevi scrivere

Ecco il risultato. Il record non è un documento che scrivi successivamente — è il nodo dell'opzione scelta più tutto ciò che è già ad esso allegato: gli argomenti di contesto (Contesto), i fratelli rifiutati (Opzioni Considerate), le catene completate (la discussione, con gli autori), le valutazioni (dove si trovava la stanza) e l'argomento della decisione con la sua motivazione (Decisione). Niente è trascritto, quindi nulla si perde nella trascrizione.

1. 1Registra le conseguenze che stai accettando. Gli svantaggi noti — la latenza aggiuntiva, il carico operativo della coda — continuano come conseguenze della scelta effettuata, riconosciute da chi decide. Scriverle è ciò che rende una scelta una decisione piuttosto che una preferenza. Checkpoint: ≥1 conseguenza accettata registrata.
2. 2Esporta se la tua organizzazione richiede ADR tracciati nel repository. Molte lo fanno, correttamente — l'ADR in markdown accanto al codice rimane l'artefatto di conformità. Scrivi il riassunto in quattro sezioni dall'albero (cinque minuti, non un venerdì), rimanda alla discussione per il dibattito completo. Checkpoint: l'ADR del repository cita l'albero; l'albero contiene il ragionamento.

Discutere e impegnarsi, ufficialmente

Il modello che Amazon ha reso famoso — disaccordo e impegno — ha un problema di leggibilità: come può chiunque sapere in seguito che il disaccordo era reale, ascoltato e risposto, piuttosto che schiacciato? La meccanica della catena lo spiega. Una catena di revisione che ha completato i suoi quattro turni e si è conclusa senza accordo è precisamente la prova: l'obiezione è stata sollevata, risposta, insistita e nuovamente risposta, ufficialmente, prima che il dissenziente si impegnasse. Il dissenziente è documentato come se fosse stato ascoltato — il che rende ragionevole l'impegno successivo piuttosto che semplicemente obbediente.

Passo 10: Sostituzione senza eliminazione

Le decisioni invecchiano. Quando il limite di tasso che ha annullato l'opzione sincrona viene aumentato, la mossa giusta è una nuova decisione che fa riferimento a quella che sostituisce — un nuovo argomento collegato al nodo di ADR-014, che indica cosa è cambiato. La vecchia decisione rimane leggibile; il suo ragionamento è esattamente il motivo per cui la nuova decisione sa cosa sta annullando.

Una lacuna onesta da gestire esplicitamente: non esiste un campo di stato ADR integrato. Proposto / accettato / superato non è uno stato di prima classe su un argomento — la supersessione è modellata tramite collegamenti, e la convenzione spetta a voi mantenerla. Dichiaratelo nell'accordo di lavoro del vostro team piuttosto che assumere che il prodotto lo imponga.

Limitazioni oneste

• ✗Questo non sostituisce gli ADR nel tuo repository se la tua organizzazione richiede che siano versionati accanto al codice. Esporta e committa il riepilogo; usa l'albero per la parte in cui il markdown è carente — il dibattito.
• ✗Nessun campo di stato ADR. Proposto/accettato/sostituito è una convenzione di collegamento che mantieni, non qualcosa che il prodotto impone.
• ✗Una catena è quattro giri. Un profondo disaccordo architettonico richiederà una chiamata; la catena è il registro di ciò che è già stato provato prima di essa.
• ✗Le valutazioni sono un valore etichettato singolo, non un punteggio multi-criterio ponderato.
• ✗Non fa scrivere a nessuno un buon contesto. La struttura abbassa il costo di una buona registrazione; non fornisce il giudizio.

Lezioni pratiche

• ✓Un RFC, una discussione. Resisti all'albero mega che copre l'architettura dell'intero quartiere: i link di supersessione collegano le decisioni meglio del nesting.
• ✓Semina da ciò che esiste. Un verbale ricco di decisioni o il tuo vecchio folder ADR, estratto, dà al dibattito una partenza veloce — etichettato come importato, così gli argomenti dal vivo rimangono distinguibili.
• ✓Metti i nomi dei revisori sulle loro catene e lasciali lì. L'attribuzione è la responsabilità; le obiezioni architettoniche anonime si trasformano in folklore.
• ✓La sezione delle conseguenze è del decisore, di nessun altro. Gli svantaggi accettati scritti dalla persona che li ha accettati hanno un peso diverso rispetto agli avvertimenti di un revisore.

ADR-014, la versione che risponde

Tornando alla domanda del nuovo responsabile tecnico. Nella versione ricostruita, ADR-014 è un nodo: la decisione della coda con la sua motivazione, tre forze contestuali (una ora obsoleta — visibilmente), un fratello API sincrono rifiutato il cui nome fatale indica il vecchio limite di velocità, quattro catene di revisione completate, inclusa quella dell'ingegnere del personale, e il benchmark allegato come prova. Il responsabile tecnico legge per dieci minuti, vede che il limite di velocità è cambiato e apre una proposta sostitutiva collegata al vecchio nodo. Nessuno scava in Slack. Questa è l'intera promessa: le catene raggiungono l'accordo, l'albero lo registra — e il record risponde a domande che non sapevi sarebbero state poste.