Von RFC zu ADR: Die Entscheidung treffen und die Begründung bewahren

Die Entscheidung, die niemand rekonstruieren konnte

Der neue technische Leiter stellt eine vernünftige Frage: Warum kommuniziert jeder Dienst über diese Warteschlange mit dem Abrechnungssystem? Es gibt eine ADR — ADR-014, vier Sätze, vor elf Monaten geschrieben. Kontext: "wir benötigten eine zuverlässige Abrechnungsintegration." Entscheidung: "verwende die Warteschlange." Konsequenzen: "einige zusätzliche Latenz." Es ist technisch ein Protokoll. Es beantwortet nichts.

Du warst dort, also weißt du, was ADR-014 nicht sagt: die dreiwöchige Diskussion über zwei Slack-Kanäle und einen hitzigen PR-Thread; die synchronous-API-Option, die wegen eines Ratenlimits verloren hat, das inzwischen erhöht wurde; der Einwand des leitenden Ingenieurs, der mit einem Benchmark beantwortet wurde, den jetzt niemand mehr finden kann. Die Debatte fand statt. Der Bericht wurde danach, aus dem Gedächtnis, von einer Person, an einem Freitag, verfasst.

Dies ist der dokumentierte, nahezu universelle Fehlermodus einer wirklich guten Praxis. Die vorschreibenden Richtlinien von AWS und die Well-Architected-Dokumente von Microsoft empfehlen beide ADRs — und beide weisen auf das Problem hin: Sie aktuell zu halten, kostet Zeit, und ihre Verwaltung wird komplex, je mehr Teams und Entscheidungen hinzukommen. Die Wurzel des Problems ist strukturell: die Debatte und das Protokoll leben an verschiedenen Orten, sodass das Protokoll immer eine verlustbehaftete Transkription ist. Die Lösung besteht darin, sie am selben Ort zu haben. Auch ist die Praxis nicht engineering-spezifisch oder sogar ADR-spezifisch. Google verlangt ein Design-Dokument — Problem, vorgeschlagener Ansatz, berücksichtigte Alternativen, Abwägungen — das geschrieben und überprüft wird bevor signifikante technische Arbeiten beginnen, eine Praxis, die im eigenen Software Engineering bei Google des Unternehmens festgelegt ist. Es ist dieselbe Disziplin wie ein ADR, die einen Schritt früher angewendet wird: Das ADR dokumentiert die Wahl, zu der das Design-Dokument argumentiert hat. Die beiden scheitern auf die gleiche Weise aus demselben Grund, und beide werden durch denselben Schritt behoben — halte das Argument dort, wo das Protokoll lebt, anstatt eines in das andere nachträglich zu transkribieren. Lies jeden Schritt unten so, dass er beide Artefakte abdeckt.

Warum ADRs verrotten

Ein Satz aus dem eigenen Material der ADR-Community trägt die gesamte Diagnose: ein RFC geht normalerweise darum, eine Einigung zu erzielen; ein ADR dokumentiert die Einigung, sobald sie erreicht ist. Zwei Artefakte, zwei Momente — und alles dazwischen leckt. Die Alternativen, die "offensichtlich" falsch waren, werden nicht aufgezeichnet (bis sie nicht mehr offensichtlich sind). Der Einwand, der das endgültige Design prägte, überlebt nur als PR-Kommentar in einem geschlossenen Thread. Der Kontextabschnitt wird zuletzt, am schlechtesten, von dem geschrieben, der das Spiel von nicht-ich verloren hat. Meetings, die Entscheidungen hätten produzieren sollen, produzieren Stichpunkte stattdessen, und die Begründung, die eine Entscheidung dauerhaft macht — das, worauf die gesamte Entscheidungsqualitätskette angewiesen ist — ist genau das, was die Transkription fallen lässt.

Schritt 1–3: Der Vorschlag, der Kontext, die Optionen

1. 1Formuliere den Vorschlag als die Hauptbehauptung — die vorgeschlagene Entscheidung, keine Frage: "Wir werden alle Abrechnungsanfragen über eine dauerhafte Warteschlange leiten." Dieser Satz ist der Titel des zukünftigen ADR. Checkpoint: Wurzel existiert, ein Satz, verfasst vom Vorschlagenden.
2. 2Kontext als separate Pro-Argumente. Jede Kraft, die die Entscheidung notwendig macht — das Zuverlässigkeitsanforderung, die Abrechnungssystem-Ratenbegrenzung, das Prüfungsmandat — ist ihr eigenes Argument unter der Wurzel. Ein monolithischer "Kontext"-Absatz kann nicht angefochten werden; drei separate Kontextansprüche können jeweils einzeln in Frage gestellt, bestätigt oder widerlegt werden. Checkpoint: ≥2 Kontextargumente, jede eine Kraft.
3. 3Jede Option erhält ihren eigenen Knoten. Die Warteschlange, die synchrone API, der Batch-Job — Geschwisterargumente, jedes mit seinen eigenen Vor- und Nachteilen. Pro/Contra ist relativ zum Elternteil, sodass die Nachteile einer Option von dieser Option abhängen, nicht von der Entscheidung. Schließen Sie die Optionen ein, die Sie voraussichtlich ablehnen werden: das abgelehnte Geschwister ist es, was die Frage des nächsten Jahres beantwortet: "Warum haben wir nicht einfach…". Checkpoint: jede Option, nach der ein Leser fragen könnte, existiert.

Schritt 4–6: Die RFC-Runde, die einen Nachweis hinterlässt

Jetzt die Überprüfungsrunde — normalerweise der Teil, der sich über Chats, Kommentare und Flure verteilt. Hier läuft es als drei Arten von strukturiertem Austausch, jeweils ein Vier-Wendungs-Dialog zwischen einem Gutachter und dem Autor der Option:

Schritt 7: Entscheiden — und was die Bewertung nicht ist

Entscheidungsträger bewerten die Optionen: jede mit einer beschrifteten Bewertung. Die Verteilung ist ein echtes Beweisstück — wo der Raum stand, im Protokoll, vor dem Anruf. Aber die Bewertung ist nicht die Entscheidung. Ein benannter Mensch entscheidet immer noch, und wenn der Anruf gegen die Verteilung geht, ist der Entscheidungs-Knoten der Ort, an dem das erklärt wird. (Wer dieser benannte Mensch sein sollte und wie man die Rolle vor der Debatte und nicht danach zuweist, ist eine eigene Disziplin — siehe das Tutorial zu Entscheidungsrechten.)

Schritt 8–9: Die ADR, die Sie nicht schreiben mussten

Hier ist die Auszahlung. Der Datensatz ist kein Dokument, das Sie danach schreiben — es ist der Knoten der gewählten Option plus alles, was bereits daran angehängt ist: die Kontextargumente (Kontext), die abgelehnten Geschwister (Berücksichtigte Optionen), die abgeschlossenen Ketten (die Diskussion, mit Autoren), die Bewertungen (wo der Raum stand) und das Entscheidungsargument mit seiner Begründung (Entscheidung). Nichts wird transkribiert, sodass nichts in der Transkription verloren geht.

1. 1Dokumentieren Sie die Konsequenzen, die Sie akzeptieren. Bekannte Nachteile — die zusätzliche Latenz, die betriebliche Belastung der Warteschlange — gehen als Nebenfolgen der gewählten Option weiter, anerkannt vom Entscheider. Sie aufzuschreiben, macht es zu einer Entscheidung und nicht zu einer Vorliebe. Checkpoint: ≥1 akzeptierte Konsequenz im Protokoll.
2. 2Exportieren Sie, wenn Ihre Organisation repo-verfolgte ADRs benötigt. Viele tun dies, und das ist richtig – das Markdown-ADR neben dem Code bleibt das Compliance-Artefakt. Schreiben Sie die Zusammenfassung in vier Abschnitten aus dem Baum (fünf Minuten, nicht am Freitag), verlinken Sie zurück zur Diskussion für die vollständige Debatte. Checkpoint: das Repo-ADR zitiert den Baum; der Baum enthält die Begründung.

Nicht einverstanden und verpflichten, offiziell

Das Muster, das Amazon berühmt gemacht hat — nicht einverstanden sein und sich verpflichten — hat ein Lesbarkeitsproblem: Wie kann später jemand wissen, dass die Meinungsverschiedenheit echt, gehört und beantwortet wurde, anstatt überrollt zu werden? Die Kettenmechanik beantwortet es. Eine Überprüfungskette, die ihre vollen vier Runden durchlief und ohne Zustimmung abgeschlossen wurde, ist genau der Beweis: Der Einwand wurde geäußert, beantwortet, vorgebracht und erneut beantwortet, protokolliert, bevor der Abweichler sich verpflichtete. Der Abweichler ist dokumentiert, dass er gehört wurde — was es sinnvoll macht, sich danach zu verpflichten, anstatt lediglich gehorsam zu sein.

Schritt 10: Ersetzen ohne Löschen

Entscheidungen altern. Wenn die Rate-Limit, die die synchrone Option getötet hat, erhöht wird, ist der richtige Schritt eine neue Entscheidung, die auf diejenige verweist, die sie ersetzt — ein neues Argument, das mit dem Knoten von ADR-014 verknüpft ist und angibt, was sich geändert hat. Die alte Entscheidung bleibt lesbar; ihre Begründung ist genau der Grund, warum die neue Entscheidung weiß, was sie aufhebt.

Eine ehrliche Lücke, die ausdrücklich verwaltet werden muss: es gibt kein integriertes ADR-Statusfeld. Vorgeschlagen / akzeptiert / ersetzt ist kein erstklassiger Zustand für ein Argument — die Ablösung wird durch Verlinkung modelliert, und die Konvention liegt in Ihrer Verantwortung. Formulieren Sie es in der Arbeitsvereinbarung Ihres Teams, anstatt anzunehmen, dass das Produkt es durchsetzt.

Ehrliche Einschränkungen

• ✗Dies ersetzt keine ADRs in deinem Repository, wenn deine Organisation sie versionskontrolliert neben dem Code benötigt. Exportiere und committe die Zusammenfassung; benutze den Baum für den Teil, in dem Markdown schlecht ist – die Debatte.
• ✗Kein ADR-Statusfeld. Vorgeschlagen/akzeptiert/aufgehoben ist eine Verknüpfungskonvention, die Sie pflegen, nicht etwas, das das Produkt durchsetzt.
• ✗Eine Kette besteht aus vier Umdrehungen. Tiefgreifende architektonische Meinungsverschiedenheiten erfordern einen Anruf; die Kette ist der Nachweis dessen, was bereits zuvor versucht wurde.
• ✗Bewertungen sind ein einzelner beschrifteter Wert, kein gewichtetes Mehrkriterien-Scoring.
• ✗Es bringt niemanden dazu, guten Kontext zu schreiben. Struktur senkt die Kosten für eine gute Aufzeichnung; sie liefert nicht das Urteil.

Praktische Lektionen

• ✓Ein RFC, eine Diskussion. Widerstehen Sie dem Mega-Baum, der die gesamte Architektur des Viertels abdeckt — Supersession-Links verbinden Entscheidungen besser als Verschachtelung.
• ✓Saat aus dem, was existiert. Ein entscheidungsintensives Protokoll oder dein alter ADR-Ordner, extrahiert, gibt der Debatte einen Vorsprung — gekennzeichnet als importiert, damit lebendige Argumente unterscheidbar bleiben.
• ✓Setzen Sie die Namen der Gutachter auf ihre Ketten und lassen Sie sie dort. Die Zuschreibung ist die Verantwortung; anonyme architektonische Einwände verwandeln sich in Folklore.
• ✓Der Abschnitt über die Konsequenzen gehört dem Entscheider, niemand anderem. Akzeptierte Nachteile, die von der Person, die sie akzeptiert hat, niedergeschrieben wurden, haben ein anderes Gewicht als die Warnungen eines Gutachters.

ADR-014, die Version, die antwortet

Zurück zur Frage des neuen technischen Leiters. In der überarbeiteten Version ist ADR-014 ein Knoten: die Warteschlangenentscheidung mit ihrer Begründung, drei Kontextkräfte (eine jetzt veraltet — sichtbar), ein abgelehntes synchrones API-Geschwister, dessen fatale Konvention das alte Rate-Limit benennt, vier abgeschlossene Review-Ketten, einschließlich der des leitenden Ingenieurs, und der Benchmark, der als Beweis angehängt ist. Der technische Leiter liest zehn Minuten, sieht, dass das Rate-Limit geändert wurde, und eröffnet einen übergeordneten Vorschlag, der mit dem alten Knoten verknüpft ist. Niemand gräbt in Slack. Das ist das gesamte Versprechen: die Ketten erreichen die Vereinbarung, der Baum zeichnet sie auf — und der Eintrag beantwortet Fragen, von denen du nicht wusstest, dass sie gestellt werden würden.