Architecture Decision Record
Ein Architecture Decision Record hält eine prägende technische Entscheidung samt Kontext und Folgen fest. Er macht später nachvollziehbar, welche Optionen geprüft und aus welchen Gründen gewählt wurden.
- KontextWarum jetzt eine Entscheidung nötig ist.
- OptionenMindestens zwei Varianten vergleichen.
- FolgenWas die Wahl nach sich zieht.
Einordnung
Warum das wichtig ist
Ohne festgehaltene Gründe fragt später niemand mehr, warum der Shop so gebaut wurde, und Entscheidungen werden unbemerkt oder doppelt revidiert. Ein ADR macht Kontext, Optionen und Folgen nachlesbar. Wie du zu einer Entscheidung kommst, zeigt Architekturentscheidung.
Dieser Baustein dokumentiert eine Architekturentscheidung. Der Auswahlprozess liegt bei Architekturentscheidung und Trade-off-Analyse; ein ADR hält Beschluss und Begründung fest.
Auf einen Blick · Entscheidung samt Kontext
ADR: Shop als modularer Monolith
Der Shop muss Bestell-, Zahlungs- und Versandlogik entwickeln und betreiben. Das Team entscheidet zwischen modularer Anwendung und unabhängig bereitgestellten Services.
So liest du das Bild
- Kontext Abschnitt „Kontext“: kleines Team, keine getrennte Rufbereitschaft, keine unabhängige Skalierung.
- Optionen Abschnitt „Optionen“: A modularer Monolith, B Services für Bestellung, Zahlung und Versand.
- Folgen Abschnitt „Folgen“: gemeinsamer Releaseprozess, Servicevariante bei belegtem Autonomiebedarf neu bewerten.
- Status
- Angenommen – Entscheidung gilt für die nächste Produktphase.
- Kontext
- Ein kleines Team betreibt Shop, Bestellverwaltung, Zahlung und Versand. Getrennte Rufbereitschaft und unabhängige Skalierung sind aktuell nicht erforderlich.
- Optionen
- A: Modularer Monolith mit Modulverträgen. B: Services für Bestellung, Zahlung und Versand mit Netzwerkverträgen.
- Entscheidung
- Der Shop wird als modularer Monolith umgesetzt; Zahlungsanbieter bleibt ein externer Dienst.
- Begründung
- Ein Artefakt und lokale Modulaufrufe passen zum Teamzuschnitt. Klare Datenhoheit hält spätere Extraktion gezielt möglich.
- Folgen
- Ein gemeinsamer Releaseprozess bleibt erforderlich. Module erhalten eigene Tests und Schreibverantwortung; bei belegtem Autonomiebedarf wird eine gezielte Servicevariante neu bewertet.
Nutzen & Grenzen
Hilft, wenn
- Folgenreiche Entscheidungen mit Wirkung auf Komponenten, Ziele oder Teams benötigen später nachvollziehbaren Kontext.
- Versionierte Begründungen und Status helfen, wiederkehrende Diskussionen und ersetzte Optionen einzuordnen.
Grenzen
- Ein ADR belegt weder Umsetzung noch Betriebszustand; er braucht Verknüpfung mit Verträgen, Code und Runbooks.
- Triviale Entscheidungen überladen das Register; dokumentiert werden Wahlen mit langfristigen Folgen oder offenen Annahmen.
- Die Gründe stehen im ADR, die Abwägung davor in Trade-offs; ob die Regel hält, prüfen Fitness Functions.
In der Praxis
- Entscheidungskontext übernehmen. Erfasse die bereits geklärten Anforderungen, Randbedingungen und Annahmen als Ausgangslage des ADR. Benenne offene Punkte und verweise für Auswahlprozess und Abwägung auf Architekturentscheidung und Trade-off-Analyse. Das Ergebnis ist ein belastbarer Dokumentationskontext.
- Alternativen und Begründung dokumentieren. Übernimm die betrachteten Optionen und den festgehaltenen Grund der Wahl aus dem Entscheidungsprozess. Verweise für Auswahl und Abwägung auf Architekturentscheidung und Trade-off-Analyse. So bleibt die Dokumentation von der Entscheidungsarbeit abgegrenzt.
- Status und Verknüpfungen pflegen. Markiere vorgeschlagen, akzeptiert oder ersetzt und verweise auf Implementierung, Sichten und operative Informationen. Bei Richtungswechseln ergänze einen neuen Eintrag. Das Ergebnis ist eine lesbare Entscheidungshistorie mit erkennbarem gültigem Stand.
Ausführliche Erklärung lesen
Ein Architecture Decision Record (ADR) beschreibt eine konkrete Entwurfsfrage, den relevanten Kontext und die gewählte Antwort. Alternativen machen sichtbar, welche Optionen geprüft wurden; Konsequenzen benennen Nutzen und Verpflichtungen. Ein ADR ist die Dokumentationsform einer Architekturentscheidung und kann mit relevanten Architektursichten verknüpft werden.
Status und Bezug auf ersetzte Entscheidungen halten den gültigen Stand nachvollziehbar. Ändert sich eine tragende Annahme, ergänzt ein neuer ADR die Historie; frühere Gründe und ihr damaliger Geltungsbereich bleiben nachvollziehbar. ADRs werden nahe an Code und Architektur versioniert. Sie ersetzen keine aktuelle Betriebsanleitung, Schnittstellendokumentation oder Umsetzung; Verweise verbinden die Entscheidung mit diesen Quellen.
Michael Nygard hat das Format 2011 in dem Beitrag „Documenting Architecture Decisions“ vorgeschlagen.
Selbst prüfen
Teste dich in drei Stufen
AblesenIm Bild nachsehen
Welche Entscheidung trifft der ADR im Abschnitt „Entscheidung“?
Lösung mit Begründung ansehen
Der Shop wird als modularer Monolith umgesetzt; der Zahlungsanbieter bleibt ein externer Dienst.
AnwendenAuf eine neue Lage übertragen
Das Team führt später eine Servicevariante für Versand ein. Was ergänzt du am ADR?
Lösung mit Begründung ansehen
Ein neuer ADR hält die Entscheidung fest und verweist auf diesen. Der alte erhält einen aktualisierten Status, damit die Historie nachvollziehbar bleibt.
BewertenEine Alternative abwägen
Reicht eine kurze Notiz „Wir nehmen den Monolithen“ statt eines ADR? Wäge ab.
Lösung mit Begründung ansehen
Die Notiz ist schnell geschrieben. Ohne Kontext, verworfene Option und Folgen lässt sich die Wahl später aber nicht mehr prüfen, etwa wenn Autonomiebedarf entsteht.
Vertiefen
Diese Bausteine führen die Gedanken dieser Seite weiter.
Quellen
- Michael Nygard – Documenting Architecture Decisions (öffnet in neuem Tab)Originalbeitrag zu kurzen Entscheidungsprotokollen mit Kontext und Konsequenzen.
- MADR – Markdown Architectural Decision Records (öffnet in neuem Tab)Bietet eine konkrete Vorlage für Optionen, Entscheidung und Folgen.
- AWS – Architectural decision records (öffnet in neuem Tab)Erklärt Einführung, Lebenszyklus und Zusammenarbeit mit ADRs.