Das Architecture Decision Record: Eine Vorlage, die Entwickler wirklich ausfüllen
Jedes Engineering-Team, das eine Codebasis geerbt hat, kennt die Frage ohne Antwort: Warum ist das so gebaut? Jemand hat sich für Row-Level Security in Postgres statt Tenant-Checks auf Anwendungsebene entschieden. Jemand hat eine Message Queue für einen Workload gewählt, den ein Cronjob erledigt hätte. Die Person, die die Entscheidung getroffen hat, ist weg, die Pull-Request-Beschreibung sagt "refactor auth", und die Begründung ist verloren. Architecture Decision Records existieren, um genau dieses Problem zu lösen, und fast kein Team pflegt sie länger als ein Quartal.
Die Gründe sind vorhersehbar. Die Vorlage ist zu lang, der Prozess fühlt sich nach Zeremonie an, und der historische Kontext verfällt, bis die Aufzeichnungen zu einem Friedhof von Entscheidungen werden, die niemand liest. Also überspringen Teams ADRs entweder komplett oder führen einen schwergewichtigen Prozess ein, der innerhalb weniger Sprints unter seinem eigenen Gewicht zusammenbricht. Keins von beidem bewahrt das Einzige, was zählt: eine dauerhafte Aufzeichnung, warum eine Entscheidung getroffen wurde, welche Alternativen abgewogen wurden und was du als Konsequenz akzeptiert hast.
Dieser Beitrag ist das praktische Gegenargument. Ein leichtgewichtiger ADR-Prozess, der den Kontakt mit einem liefernden Team überlebt, sieht ganz anders aus als die ausufernden Vorlagen in den meisten Leitfäden. Er ist kurz genug, um ihn in der Zeit zu schreiben, die es braucht, die Entscheidung laut zu beschreiben, liegt nah genug am Code, dass er nicht verrottet, und wird durch klare Regeln ausgelöst, damit niemand darüber streitet, ob eine bestimmte Wahl einen verdient.
Wofür Architecture Decision Records da sind
Ein Architecture Decision Record ist ein kurzes Dokument, das eine bedeutende technische Entscheidung festhält: den Kontext, der die Wahl erzwungen hat, die Entscheidung selbst, die verworfenen Optionen und die akzeptierten Konsequenzen. Der Wert liegt nicht im Dokument. Er liegt in der Begründung, die das Dokument bewahrt.
Betrachte den Unterschied zwischen zwei Arten von Wissen. "Wir nutzen Symfony Messenger mit einem Doctrine-Transport" ist ein Fakt, den du in dreißig Sekunden aus der Codebasis ablesen kannst. "Wir haben den Doctrine-Transport statt RabbitMQ gewählt, weil unser Durchsatz unter 500 Jobs pro Minute liegt und wir keinen Broker für einen Workload betreiben wollten, der in Postgres passt, in dem Wissen, dass wir migrieren müssen, wenn das Volumen über diese Grenze wächst" ist eine Begründung, die du aus dem Code überhaupt nicht rekonstruieren kannst. Das Erste ist auffindbar. Das Zweite ist verloren, sobald der Autor es vergisst, und er wird es vergessen.
Das ist es, was ADRs schützen. Nicht die Entscheidung, die der Code bereits kodiert, sondern die Form des Denkens drumherum: die Randbedingungen, die damals real waren, der Kompromiss, der bewusst eingegangen wurde, und die Bedingung, unter der die Entscheidung überdacht werden sollte. Wenn ein neuer Entwickler fragt, warum das System so funktioniert, lautet die ehrliche Antwort meist "es gab drei Optionen und wir haben diese gewählt, aus Gründen, die im März Sinn ergeben haben." Ein ADR ist der Ort, an dem diese Gründe leben.
Die minimale Vorlage
Die meisten ADR-Vorlagen scheitern, weil sie zu viel verlangen. Status, Entscheider, konsultierte Parteien, informierte Parteien, Links zu technischen Stories, positive Konsequenzen, negative Konsequenzen, neutrale Konsequenzen und eine Pro-und-Contra-Tabelle für jede Option. Beim dritten Feld hat der Autor entschieden, dass sich das nicht lohnt, und er hat recht.
Die Vorlage, die Teams wirklich ausfüllen, hat vier Teile und passt in fünf Zeilen:
# ADR-014: Doctrine-Transport für Symfony Messenger
Kontext: Was erzwingt jetzt eine Entscheidung? Die echte Randbedingung, kein Hintergrundrauschen.
Entscheidung: Was wir tun. Ein Satz, Aktiv.
Betrachtete Optionen: Was wir verworfen haben und der eine Grund, warum jede Option verloren hat.
Konsequenzen: Was wir dadurch akzeptieren, inklusive des Auslösers für eine Neubewertung.
Das ist alles. Die Disziplin steckt in der Zeile "Betrachtete Optionen", denn dieses Feld hält fest, was du aufgegeben hast. Eine Entscheidung, die ohne ihre Alternativen dokumentiert ist, ist nur eine Dokumentation des Status quo. Eine Entscheidung mit ihren verworfenen Optionen sagt einem zukünftigen Leser, dass RabbitMQ auf dem Tisch lag, warum es verloren hat, und damit, was sich ändern müsste, damit die Antwort kippt.
Nummeriere die Records fortlaufend und verwende eine Nummer nie doppelt. Wenn eine Entscheidung später zurückgenommen wird, editierst du das alte ADR nicht. Du schreibst ein neues, das es ablöst, und ergänzt im alten Record eine einzige Zeile, die nach vorne zeigt. Die Kette abgelöster Entscheidungen ist selbst wertvolle Geschichte: Sie zeigt, wie sich die Randbedingungen des Systems entwickelt haben.
Was ein ADR auslöst und was eine Pull-Request-Beschreibung bleibt
Der häufigste Fehlermodus nach der Einführung ist Über-Dokumentation. Ein Team, das für jede nicht-triviale Änderung ein ADR schreibt, ertrinkt in Records und gibt die Praxis innerhalb eines Monats auf. Der umgekehrte Fehler, gar nichts festzuhalten, ist nur das ursprüngliche Problem. Die Grenze dazwischen ist ein einfacher Test.
Schreibe ein ADR, wenn die Entscheidung teuer rückgängig zu machen ist und mehr betrifft als den Code direkt vor dir. Die Wahl einer Authentifizierungsbibliothek, eines API-Stils, eines Tenancy-Modells, eines Deployment-Ziels oder eines Logging-Formats sind alles Entscheidungen, die durch die Codebasis strahlen und echtes Geld kosten, wenn man sie zurückdreht. Die bekommen ein ADR. Einen Service umzubenennen, einen Helper zu extrahieren oder einen Komponentenbaum umzustrukturieren lebt gut in einer Pull-Request-Beschreibung, weil die Umkehr billig ist und der Wirkungsradius lokal.
Eine nützliche Heuristik: Wenn du die Begründung in zwei Jahren wissen willst, wenn die Person, die entschieden hat, weg ist, ist es ein ADR. Wenn Git Blame und die PR-Beschreibung reichen, ist es keins. Entscheidungen über deine Gesamtarchitektur und technische Richtung, die Art, die wir mit Teams in unseren Engagements zur Tech-Stack-Strategie durcharbeiten, fallen fast immer in die erste Kategorie. Sie prägen alles, was danach gebaut wird, und ihre Begründung verdampft als Erstes.
Wo du sie ablegst, damit sie nicht verrotten
ADRs sterben, wenn sie weit weg von dem Code leben, den sie regeln. Ein Confluence-Space, ein Shared Drive, eine Notion-Datenbank: All das startet gut und verfällt, weil niemand, der den Code ändert, dort hineinschaut. Die Lösung ist, ADRs im Repository abzulegen, als Markdown, in einem Verzeichnis docs/adr/, das mit dem Code ausgeliefert wird.
Nähe ist, was sie am Leben hält. Wenn die Records im Repo liegen, tauchen sie im Code Review auf, sie werden zusammen mit der Änderung versioniert, die sie motiviert hat, und ein Entwickler, der das Auth-Modul liest, findet das Auth-ADR, ohne seinen Editor zu verlassen. Record und Code bewegen sich gemeinsam durch jeden Branch, Merge und Revert. Eine im Code zurückgenommene Entscheidung ist eine Entscheidung, deren ADR direkt daneben liegt, um abgelöst zu werden.
Es gibt einen zweiten Vorteil, ADRs im Repository zu halten: Sie werden reviewbar. Ein ADR, das als Teil eines Pull Requests eingereicht wird, ist ein Gespräch, kein Dekret. Reviewer können die Begründung hinterfragen, bevor die Entscheidung festgezurrt ist, und genau dann ist dieses Feedback billig. Das ist eines der Dinge, auf die ein gründliches Review im Code-Quality-Consulting achtet: ob die bedeutenden Entscheidungen einer Codebasis offen durchdacht wurden oder einseitig getroffen und später von demjenigen entdeckt, der die Konsequenzen geerbt hat.
Vergangene Entscheidungen dokumentieren, ohne Archäologie-Projekt
Teams, die ADRs auf einer bestehenden Codebasis einführen, reden sich das oft aus, weil sie sich vorstellen, jede historische Entscheidung zu rekonstruieren. Das ist das falsche Ziel und wird das Team erschöpfen, bevor es einen einzigen Record geschrieben hat, der hilft. Du brauchst nicht die Geschichte. Du brauchst die Entscheidungen, die noch tragen.
Beginne mit den Fragen, die neue Entwickler beim Onboarding tatsächlich stellen. Warum diese Datenbank? Warum dieses Deployment-Setup? Warum wird Autorisierung hier durchgesetzt und nicht dort? Jede dieser Fragen entspricht einer Entscheidung, die das System noch prägt, und jede Antwort ist ein ADR, das sich rückwirkend zu schreiben lohnt. Schreib fünf davon, datiert mit dem ungefähren ursprünglichen Entscheidungsdatum und einem Hinweis, dass sie nachträglich rekonstruiert wurden. Das reicht, um die Entscheidungen abzudecken, nach denen ständig gefragt wird, und kostet einen Nachmittag statt einen Sprint. Es ist außerdem der schnellste Weg, auf einem System produktiv zu werden, das du nicht gebaut hast, weshalb es in unserer Arbeit zur Legacy-Code-Optimierung auftaucht.
Von da an ist der Prozess rein additiv. Du schreibst ein neues ADR, wenn eine auslösende Entscheidung ansteht, und die Sammlung wächst organisch um echte Entscheidungen herum statt um ein Backfill-Projekt, für das niemand Zeit hat.
Die ADRs, die du zuerst schreiben solltest
In den Symfony- und Next.js-SaaS-Projekten, an denen wir arbeiten, kommen einige Entscheidungen auf fast jeder Codebasis vor und zahlen den Aufwand des Festhaltens stärker zurück als alle anderen. Der Ansatz für Authentifizierung und Autorisierung, ob selbst gebaut oder als Bibliothek übernommen, ist das wertvollste einzelne ADR, weil er später am schwersten zu ändern ist und Fehler dort am gefährlichsten sind. Der API-Stil, REST versus GraphQL versus etwas dazwischen, prägt jede Integration, die danach gebaut wird. Das Tenancy-Modell, Shared Schema versus Schema pro Tenant versus Datenbank pro Tenant, bestimmt deine Isolationsgarantien und deine Skalierungsgrenze. Das Deployment-Ziel und das Logging-Format runden das Set ab.
Wenn du nur fünf ADRs schreibst, schreibe diese fünf. Sie decken die Entscheidungen ab, nach denen neue Entwickler fragen, die Käufer in einer Due Diligence prüfen und die am meisten kosten, wenn die Begründung dahinter verloren gegangen ist. Alles andere ist Bonus.
Der Sinn eines Architecture Decision Records ist nicht Dokumentation um ihrer selbst willen. Er ist eine kleine, bewusste Investition in die Fähigkeit deines zukünftigen Teams, das System mit Zuversicht statt Angst zu verändern. Eine Codebasis, deren große Entscheidungen festgehalten sind, ist eine Codebasis, die du weiterentwickeln kannst. Eine, deren Entscheidungen Folklore sind, ist eine, bei der du nur raten kannst.
Wenn du ein System erbst, dessen Begründungen dunkel geworden sind, oder eine Engineering-Praxis aufbaust, die ihre Gründer überdauern soll, helfen wir Teams, genau diese Art von Struktur zu etablieren. Melde dich unter hello@wolf-tech.io oder lies mehr darüber, wie wir arbeiten, auf wolf-tech.io.