Architecture Entscheidungsmethode

Architecture Decision Record

Ein Architecture Decision Record hält eine Architekturentscheidung und ihre Begründung auffindbar fest.

Ein Architecture Decision Record dokumentiert entscheidenden Kontext, gewählte Lösung und Folgen in einer kurzen, auffindbaren Notiz. So bleibt die Entscheidung für heutige und spätere Beteiligte nachvollziehbar.

Kernfrage

Welche Architekturentscheidung treffen wir in diesem Kontext, warum wählen wir sie und welche Folgen nehmen wir damit an?

Entscheidungsarbeit planen Methodenanleitung

Vergleich starten

Feedback gebenHilft dir diese Methode?

Teilnehmende: 1-3
Zeit: 15–45 min für einen Entwurf; Untersuchung und Review zusätzlich

Ein ADR hält eine Entscheidung fest. Untersuchung und Abstimmung können mehrere Termine benötigen; ihr Umfang folgt der Bedeutung und Unsicherheit der Frage.

Papierillustration mit zwei betrachteten Optionen, die zu einem Entscheidungsdokument mit markiertem Status und sichtbaren Konsequenzen führen.

Frame
Entscheidung und Kontext klären
Die architektonische Frage präzise eingrenzen.
Compare
Relevante Optionen abwägen
Entscheidende Unterschiede und Unsicherheiten sichtbar machen.
Decide
Entscheidung prüfen und festhalten
Wahl, Begründung und Folgen ausdrücklich vereinbaren.
Maintain
Folgen verfolgen und Historie erhalten
Die Entscheidung auffindbar halten und bei verändertem Kontext prüfen.

Bei neuen Erkenntnissen den Status und die Folgen prüfen. Eine geänderte Entscheidung in einem neuen, verknüpften ADR begründen und den Vorgänger als ersetzt markieren.

Geeignet, wenn

Eine architektonisch bedeutsame Entscheidung soll mit ihren Gründen auffindbar bleiben, etwa zu Strukturen, Schnittstellen, Abhängigkeiten oder Qualitätsanforderungen.

Ideal für

Architecture Governance
Team Memory
High-Change-Codebases

Nicht gut für

Triviale Entscheidungen
Lange Spezifikationen

Ergebnisse

Entscheidungsnotiz
Kontext, Entscheidung, Status und Folgen in einer kurzen Referenz.
Begründete Abwägung
Relevante Optionen und die entscheidenden Unterschiede.
Erhaltene Historie
Verknüpfte Entscheidungen und nachvollziehbare Statuswechsel.

Aufbau eines ADR

Fiktives Lehrbeispiel

Fiktiver Entwurf zur gemeinsamen Verwaltung von Werkzeugreservierungen. Er zeigt die Dokumentstruktur und hat noch keine Annahme erhalten.

Kennung, Titel und Status

Stabile Kennung, Entscheidungsfrage, Datum, Beteiligte, Verantwortung und aktuellen Status notieren.

Fiktiv: ADR-007 · Gemeinsame Reservierungsverwaltung · vorgeschlagen · Datum offen · Alex koordiniert den Review.

Kontext und Entscheidungsfaktoren

Warum ist diese Entscheidung nötig? Welche Anforderungen und Einschränkungen bestimmen sie?

Fiktiv: Online-Zugang und Ausgabestelle vergeben dieselben Werkzeuge. Die verfügbare Menge muss bei beiden Zugängen berücksichtigt werden.

Betrachtete Optionen

Relevante Optionen, entscheidende Unterschiede, Quellen und Unsicherheiten knapp vergleichen.

Fiktiv: A nutzt einen zentralen Reservierungsdienst. B führt getrennte Listen mit regelmäßigem Abgleich. Zu prüfen: Konflikte bei gleichzeitigen Anfragen.

Entscheidung und Begründung

Die gewählte Option und ihre entscheidenden Gründe festhalten. Im Entwurf den Vorschlagsstatus kenntlich machen.

Fiktiver Vorschlag: A, damit die Vergabe einen gemeinsamen Entscheidungspunkt erhält. Technische Konfliktvermeidung wird gesondert geprüft.

Konsequenzen und Folgeaufgaben

Relevante positive und nachteilige Folgen, Unsicherheiten und konkrete Folgeaufgaben beschreiben.

Fiktiv: Gemeinsame Prüfregeln; zugleich Abhängigkeit von Erreichbarkeit und Betrieb des Dienstes. Offen: Ausfallverfahren und Nachweis konfliktfreier Vergabe.

Review, Statuswechsel und Verknüpfungen

Reviewweg, ausdrückliche Entscheidung und Datum dokumentieren. Quellen sowie Vorgänger oder Nachfolger verlinken.

Fiktiv: Produkt und Betrieb prüfen den Vorschlag. Status bleibt vorgeschlagen, bis die vereinbarte Entscheidung dokumentiert ist.

Die Vorlage verbindet Nygards kurze Kernstruktur mit hilfreichen Feldern für Abwägung und Review. Detailtiefe und Ablauf folgen dem Entscheidungsbedarf.

Nach Michael Nygard, ergänzt um Optionen und Review

Erster Schritt

Formuliere eine konkrete Entscheidungsfrage und den Kontext, der diese Entscheidung erforderlich macht. Benenne Beteiligte und Entscheidungsverantwortung.

Zur Methodenanleitung

Davor sinnvoll

Architecture

Quality Attribute Workshop

Liefert priorisierte Qualitätsszenarien, die eine Entscheidung erfordern.

Wie geht es weiter?

Architecture

arc42

Verankert die getroffene Entscheidung in der laufenden Architekturdokumentation.

Architecture

C4 Model

Spiegelt die Entscheidung in den betroffenen Architektursichten.

Vertiefung

Zweck

Ein ADR hält eine Architekturentscheidung mit Kontext, Abwägung und Konsequenz dauerhaft fest. Es schafft Anschlussfähigkeit für spätere Änderungen, weil der Entscheidungsweg nachvollziehbar bleibt.

Funktionsweise

Zuerst werden Problem, Ziele und Rahmenbedingungen präzise beschrieben. Danach dokumentiert das Team die Optionen, die gewählte Lösung und die wichtigsten Tradeoffs. Abschließend wird der Eintrag mit Datum, Status und Verweis auf Folgearbeit versioniert.

Im Detail

Ein ADR wirkt, weil Architekturentscheidungen dadurch nicht nur festgehalten, sondern mitsamt Kontext und Folgen später wieder lesbar werden. Gute Nutzung dokumentiert die eigentliche Spannung zwischen Optionen und benennt die Tragweite der gewählten Richtung offen. So verhindert das Format, dass Teams Monate später nur noch das Ergebnis kennen, aber weder Anlass noch bewusste Tradeoffs nachvollziehen können.

Durchführung

Sammle vor dem Schreiben die echte Entscheidungsfrage, die wichtigsten Alternativen und die Qualitätsziele, die unter Spannung stehen. Seinen Wert zeigt das Format genau dort, wo die gewählte Option eine klare Konsequenz für Betrieb, Entwicklung oder Kopplung bekommt. Schließe mit präzisem Status, klarer Begründung und einem Verweis darauf, wann eine Revision fällig wäre.

Die Methodenanleitung führt mit 4 Phasen, Zeitrahmen, 4 Stolperfallen und klaren Abbruchkriterien durch die Umsetzung.

Methodenanleitung öffnen

Deine Einschätzung

Hilft dir diese Methode für dein Vorhaben?

Mit deinem Feedback hilfst du, den Methodatlas weiterzuentwickeln.

Quellen und Themen

Themen

Architektur Begründung Dokumentation Governance

Quellen

Documenting Architecture Decisions · Michael Nygardcognitect.comOriginalreferenz für kurze Entscheidungsnotizen mit Kontext, Status, Entscheidung und Konsequenzen sowie erhaltener Historie.Markdown Architectural Decision Records · MADRadr.github.ioErgänzende Vorlagenvariante für Entscheidungsfaktoren und betrachtete Optionen. Der angebotene Arbeitsweg und das Beispiel sind redaktionelle Anleitung.

In Playbooks

Architekturentscheidung vorbereitenVon unscharfem technischen Problem zu dokumentierter, nachvollziehbarer Architekturentscheidung.

Artefakt-Vorlagen

Architecture Decision Record: ArbeitsvorlagePlane die Arbeit an einem ADR vom Kontext über die Abwägung bis zum vereinbarten Review.

markdown

adr-markdown.md

Plane die Arbeit an einem ADR vom Kontext über die Abwägung bis zum vereinbarten Review.

Architecture Decision Record: Arbeitsvorlage

Fragestellung

Noch zu klären

Gewünschtes Ergebnis

Noch zu klären

Rahmen

Einen ADR vorbereiten und abstimmen Zeit: Entwurf und Review getrennt vereinbaren

Diese Vorlage während der Arbeit auf Papier oder in einem eigenen Dokument ausfüllen.

Vorbereitung für diesen Umfang

Methodische Grundausstattung

Materialien: Kurze Textvorlage, relevanter Architekturkontext, Quellen zu betrachteten Optionen und eine versionierte, für Beteiligte auffindbare Ablage.
Rollen: Eine verantwortliche Person verfasst den Entwurf. Betroffene Engineering-, Architektur-, Produkt- oder Betriebsrollen prüfen relevante Folgen. Die vereinbarte Entscheidungsverantwortung nimmt die Entscheidung ausdrücklich an.
Vorab-Infos: Entscheidungsfrage, bestehende Architektur, betroffene Qualitätsanforderungen und bekannte Einschränkungen sammeln. Frühere einschlägige ADRs und Quellen verlinken.
Gesamter Zeitbedarf: 15 bis 45 Minuten für einen fokussierten Entwurf als Orientierung. Untersuchung, Diskussion und Review kommen hinzu und können asynchron erfolgen. Einen passenden Rückmeldetermin gemeinsam vereinbaren.
Setup: Stabile Kennung und kurzen Titel vergeben, Status vorgeschlagen setzen und die Notiz in der gemeinsamen Ablage anlegen. Entscheidungs- und Reviewweg mit den Beteiligten klären.

Für die Arbeitsschritte bereitstellen

Frame: Entscheidung und Kontext klären

Architekturfrage und bestehender Systemkontext

Compare: Relevante Optionen abwägen

Entscheidungskontext und realistische Optionen

Decide: Entscheidung prüfen und festhalten

Entwurf, Abwägung und betroffene Perspektiven

Maintain: Folgen verfolgen und Historie erhalten

ADR mit geklärtem Status und Folgeaufgaben

Aufbau eines ADR

Kennung, Titel und Status

Stabile Kennung, Entscheidungsfrage, Datum, Beteiligte, Verantwortung und aktuellen Status notieren.

...

Kontext und Entscheidungsfaktoren

Warum ist diese Entscheidung nötig? Welche Anforderungen und Einschränkungen bestimmen sie?

...

Betrachtete Optionen

Relevante Optionen, entscheidende Unterschiede, Quellen und Unsicherheiten knapp vergleichen.

...

Entscheidung und Begründung

Die gewählte Option und ihre entscheidenden Gründe festhalten. Im Entwurf den Vorschlagsstatus kenntlich machen.

...

Konsequenzen und Folgeaufgaben

Relevante positive und nachteilige Folgen, Unsicherheiten und konkrete Folgeaufgaben beschreiben.

...

Review, Statuswechsel und Verknüpfungen

Reviewweg, ausdrückliche Entscheidung und Datum dokumentieren. Quellen sowie Vorgänger oder Nachfolger verlinken.

...

Mit Status vorgeschlagen beginnen. Annahme ausdrücklich dokumentieren. Eine geänderte Entscheidung als neuen ADR verknüpfen und die ursprüngliche Begründung erhalten.

Nach Michael Nygard, ergänzt um Optionen und Review