Architecture Decision Records: Entscheidungen festhalten
Ein Architecture Decision Record ist ein kurzes, datiertes Dokument zu genau einer technischen Entscheidung: in welcher Lage sie fiel, was entschieden wurde und welche Folgen das hat. ADRs liegen nummeriert im Repository neben dem Code und machen auch Jahre später nachvollziehbar, warum ein System so gebaut ist.
In jedem Softwareprojekt fallen Entscheidungen, die später niemand mehr erklären kann: warum diese Datenbank, warum dieser Zahlungsanbieter, warum die Schnittstelle so geschnitten ist. Die Begründung steckte in einem Gespräch, einem Chatverlauf oder im Kopf eines Entwicklers, der nicht mehr im Projekt ist. Der Softwarearchitekt Michael Nygard hat 2011 ein leichtes Format vorgeschlagen, um das zu ändern. Bei uns landet jede tragende Entscheidung als ADR im Repository, so beschreibt es auch die Seite zu unserer Arbeitsweise.
Was ein Architecture Decision Record ist und was nicht
Ein Architecture Decision Record, kurz ADR, hält eine einzelne Entscheidung fest, die die Struktur eines Systems prägt und sich später nur mit Aufwand ändern lässt. Nygard beschreibt ihn als Dokument von ein bis zwei Seiten, geschrieben in ganzen Sätzen, als Gespräch mit einem Entwickler, der das Projekt in Zukunft übernimmt.
Ein ADR ist nicht:
ein Protokoll: Er hält das Ergebnis und die Gründe fest, nicht den Verlauf einer Besprechung.
eine vollständige Architekturdokumentation: Ein ADR beschreibt eine Entscheidung, nicht das ganze System. Viele ADRs zusammen ergeben die Geschichte der Architektur.
für jede Kleinigkeit gedacht: Der Name einer Variable oder die Wahl einer Hilfsbibliothek braucht keinen ADR. Ein guter Prüfstein ist die Frage, ob eine Rücknahme der Entscheidung mehr als ein paar Tage Arbeit kosten würde.
Ein Grundsatz unterscheidet ADRs von anderen Dokumenten: Sie werden nicht nachträglich umgeschrieben. Ändert sich eine Entscheidung, entsteht ein neuer ADR, und der alte bekommt den Status „ersetzt durch“ mit Verweis auf den neuen. So bleibt sichtbar, dass es einmal anders war und warum.
Die Vorlage: Kontext, Entscheidung, Folgen
Nygards ursprüngliche Vorlage hat fünf Teile:
Titel: eine kurze Bezeichnung mit fortlaufender Nummer, etwa „ADR 7: PostgreSQL als Datenbank“. Nummern werden nie wiederverwendet.
Status: vorgeschlagen, angenommen, abgelöst oder ersetzt durch einen späteren ADR.
Kontext: die Lage, in der entschieden wird, mit allen Kräften, die wirken: fachliche Anforderungen, technische Grenzen, Budget, Wissen im Team. Neutral beschrieben, ohne schon zu werten.
Entscheidung: in aktiver Form, „Wir verwenden ...“.
Folgen: alle Folgen, auch die unbequemen. Was wird leichter, was schwerer, was ist damit ausgeschlossen?
Eine verbreitete Weiterentwicklung ist MADR, das Markdown Architectural Decision Record, aktuell in Version 4.0.0 vom September 2024. MADR ergänzt unter anderem die betrachteten Optionen mit ihren Vor- und Nachteilen und Entscheidungskriterien. Für viele Projekte ist das sinnvoll, weil die verworfenen Optionen später die häufigste Rückfrage sind: „Habt ihr auch X angeschaut?“
Der wichtigste Abschnitt ist der Kontext. Eine Entscheidung, die im Rückblick falsch aussieht, war oft unter den damaligen Bedingungen richtig. Nur wer den Kontext kennt, kann beurteilen, ob sich die Bedingungen so geändert haben, dass eine neue Entscheidung nötig ist.
Vorlage zum Kopieren
Diese Vorlage verbindet Nygards fünf Teile mit den betrachteten Optionen aus MADR. Legen Sie sie als Datei in den Ordner für Entscheidungen und kopieren Sie sie für jeden neuen ADR. Die Zeile „Neu prüfen, wenn“ ist kein Pflichtteil der beiden Formate. Wir ergänzen sie, weil sie bei einer späteren Überprüfung die erste Frage beantwortet: Gilt die Entscheidung noch?
# ADR 0000: Titel der Entscheidung
Status: vorgeschlagen | angenommen | abgelöst | ersetzt durch ADR 00xx
Datum: TT.MM.JJJJ
Entschieden von: Namen oder Rollen
## Kontext
Lage, in der entschieden wird: fachliche Anforderungen, technische
Grenzen, Budget, Wissen im Team. Neutral beschrieben, ohne Wertung.
## Betrachtete Optionen
- Option A: Vorteile, Nachteile
- Option B: Vorteile, Nachteile
## Entscheidung
Wir verwenden ..., weil ...
## Folgen
- Leichter wird: ...
- Schwerer wird: ...
- Ausgeschlossen ist: ...
- Neu prüfen, wenn: ...
Wo ADRs liegen sollten
ADRs gehören in das Repository des Projekts, als Markdown-Dateien in einem eigenen Ordner. MADR schlägt docs/decisions vor, mit Dateinamen nach dem Muster 0007-postgresql-als-datenbank.md. Das hat drei Vorteile:
Versionierung: Jede Änderung ist mit Datum und Autor nachvollziehbar, wie beim Code.
Nähe zum Code: Wer den Code übernimmt, bekommt die Entscheidungen automatisch mit. Ein Wiki oder ein Dokumentenordner beim Auftraggeber geht bei einem Wechsel des Dienstleisters leicht verloren.
Prüfung im Ablauf: Ein neuer ADR kommt als Änderungsvorschlag, als Pull Request, ins Repository und wird dort wie Code geprüft und kommentiert.
Am meisten bringt der dritte Punkt. Liegt der ADR im selben Pull Request wie der Code, der die Entscheidung umsetzt, ist er fertig, wenn der Code fertig ist. Ein ADR, der Wochen später nachgeschrieben werden soll, konkurriert mit allen anderen Aufgaben und wird leicht vergessen.
Hilfreich ist außerdem eine kurze Übersicht im selben Ordner, etwa eine README mit allen ADRs, ihrem Status und einem Satz zum Inhalt. Wer neu ins Projekt kommt, liest diese Liste zuerst und weiß nach zehn Minuten, welche Grundsatzentscheidungen gelten und welche abgelöst sind.
Beispiel: Datenbankwahl als ADR
Ein gekürztes Beispiel, frei erfunden für ein Kundenportal, zeigt, wie knapp ein ADR sein kann:
ADR 3: PostgreSQL als Datenbank des Kundenportals. Status: angenommen am 12.03.2026.
Kontext: Das Portal speichert Verträge mit vielen optionalen Feldern, die je nach Produkt unterschiedlich sind. Kunden sollen Dokumente per Volltext durchsuchen. Das bestehende CRM des Auftraggebers läuft auf MySQL, das Team hat mit beiden Datenbanken Erfahrung. Das Hosting unterstützt beide.
Entscheidung: Wir verwenden PostgreSQL. Optionale Vertragsfelder speichern wir als JSONB-Spalte mit Index, die Volltextsuche lösen wir mit der eingebauten Textsuche von PostgreSQL.
Betrachtete Optionen: MySQL, weil das CRM es nutzt. Verworfen, weil die Anforderungen an Indizes auf JSON-Feldern und an die Volltextsuche mit PostgreSQL ohne Zusatzsystem abgedeckt sind.
Folgen: Datenaustausch mit dem CRM läuft über die Schnittstelle, nicht über direkte Datenbankzugriffe. Weil dasselbe Team auch den Betrieb des CRM verantwortet, brauchen Backups und Überwachung künftig zwei Datenbanksysteme statt einem. Sollte die Suche später sehr große Dokumentmengen umfassen, wird ein eigenes Suchsystem erneut geprüft.
Der letzte Satz zeichnet gute ADRs aus: Er nennt die Bedingung, unter der die Entscheidung neu zu prüfen ist. Welche Kriterien bei der Wahl zwischen den beiden Datenbanken sonst zählen, vergleicht der Beitrag MySQL oder PostgreSQL. Wie man PostgreSQL in Laravel-Anwendungen mit passenden Indizes ausstattet, beschreibt PostgreSQL Indexing für Laravel-Apps.
Was Auftraggeber davon haben
ADRs schreiben Entwickler, den größten Nutzen haben aber oft die Auftraggeber:
Unabhängigkeit: Wechselt der Dienstleister oder fällt ein Entwickler aus, kann ein neues Team die Gründe nachlesen statt sie zu erraten. Das senkt das Risiko, das der Beitrag Bus-Faktor beschreibt.
Bessere Entscheidungen: Wer die Folgen aufschreiben muss, denkt sie gründlicher durch. Schwache Begründungen fallen beim Schreiben auf.
Nachweise: In regulierten Branchen dienen ADRs als Beleg dafür, wer wann warum entschieden hat. Als wir das Backend-Team einer FinTech-Tochter im Versicherungsumfeld für einige Monate verstärkt haben, gehörten ADRs zu den größeren Abzweigungen deshalb zur Übergabe an das interne Team.
Weniger Wiederholung: Grundsatzdiskussionen, die schon geführt wurden, lassen sich mit einem Verweis auf den ADR abkürzen.
Fragen Sie Ihren Dienstleister, wo die Entscheidungen Ihres Projekts dokumentiert sind. Die Antwort sagt viel darüber aus, wie gut Sie das Projekt ohne ihn weiterführen könnten. Wie ADRs bei uns in den Projektablauf eingebunden sind, beschreibt die Seite Methodik und Prozess.
Kurz beantwortet
Häufige Fragen
-
Die Person, die die Entscheidung vorbereitet, meist ein Entwickler oder Architekt im Projekt. Beteiligt sind alle, die die Folgen tragen, bei geschäftlich relevanten Entscheidungen auch der Auftraggeber. Wer die Entscheidung trifft, steht im ADR.
-
So kurz wie möglich, meist eine Seite, selten mehr als zwei. Ein ADR, der länger wird, beschreibt oft mehrere Entscheidungen und sollte geteilt werden. Entscheidend ist, dass Kontext und Folgen vollständig sind.
-
Das geht, und für bestehende Systeme ist es ein guter Einstieg. Halten Sie die wichtigsten Entscheidungen fest, die noch wirken, und vermerken Sie, dass der ADR nachträglich geschrieben wurde und wann. Gründe, die niemand mehr kennt, stehen dann offen als unbekannt im Text.
Entscheidungen nachvollziehbar machen
In unseren Projekten entsteht zu jeder tragenden Entscheidung ein ADR im Repository. Für bestehende Systeme können wir die wichtigsten nachträglich anlegen.
Nachweise
Quellen und Stand
Geprüft am 02.11.2026: Format nach Michael Nygard und aktuelle Version von MADR. Das ADR-Beispiel ist frei erfunden.
Artikel teilen