MethodenanleitungArchitecture

Architecture Decision Record

Die Anleitung zur Methode: Voraussetzungen und Materialien klären, den gesamten Ablauf verstehen und Ergebnisse, Stolperfallen sowie Abbruchkriterien nachschlagen.

KomplexitätNiedrig

Zeit15-45 min

Teilnehmende1-3

FormatAsync

ReifegradCanonical

Entscheidungsarbeit planen

Vorbedingung

Was vorher fertig sein muss

Vorher abschließenEine konkrete Entscheidung

Die Frage, ihre architektonische Bedeutung und die betroffenen Bereiche sind benannt.

Mehrere unabhängige Entscheidungen brauchen getrennte, gegebenenfalls verknüpfte ADRs.

Vorher abschließenKontext und relevante Optionen

Anforderungen, Einschränkungen und realistische Handlungsoptionen sind zugänglich; Unsicherheiten bleiben sichtbar.

Bei entscheidender Unsicherheit ist zunächst eine gezielte Untersuchung sinnvoll.

Vorher abschließenEntscheidungs- und Reviewweg

Betroffene Perspektiven, Entscheidungsverantwortung und die Form der ausdrücklichen Annahme sind geklärt.

Ein gespeicherter Entwurf hat zunächst den Status vorgeschlagen.

Vorbereitung

Was vor Start vorliegen muss

Materialien

Kurze Textvorlage, relevanter Architekturkontext, Quellen zu betrachteten Optionen und eine versionierte, für Beteiligte auffindbare Ablage.

Personen / 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.

Vorabinfos

Entscheidungsfrage, bestehende Architektur, betroffene Qualitätsanforderungen und bekannte Einschränkungen sammeln. Frühere einschlägige ADRs und Quellen verlinken.

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.

Kernfrage

Die eine Frage, die diese Methode beantwortet

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

Ablauf

Phasen mit Ziel, Durchführung, Ergebnis und Stolperfalle

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.

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

1
Frame
Entscheidung und Kontext klären
Ziel
Die Notiz erklärt, warum eine Entscheidung erforderlich ist.
Voraussetzungen für diesen Schritt
- Architekturfrage und bestehender Systemkontext
Durchführung
- Eine konkrete Entscheidungsfrage formulieren. Anforderungen, Einschränkungen, betroffene Bereiche und relevante frühere Entscheidungen erfassen.
- Kennung und Titel vergeben. Entwurfsstatus, Beteiligte und Entscheidungsverantwortung festhalten.
Ergebnis
Entscheidungskontext
Frage · Bedeutung · Rahmen · Verantwortung
Qualitätscheck
Kann eine spätere Person die Ausgangslage verstehen?
Stolperfalle
Der Titel nennt eine Technologie, aber die Entscheidungsfrage bleibt unklar. Den konkreten Entscheidungsbedarf und seine Rahmenbedingungen beschreiben.
Zeitlicher Rahmen: Ein kurzer Entwurfsblock bei bekanntem Kontext.
2
Compare
Relevante Optionen abwägen
Ziel
Die Wahl kann anhand des Kontexts begründet werden.
Voraussetzungen für diesen Schritt
- Entscheidungskontext und realistische Optionen
Durchführung
- Relevante Optionen mit ihren Vor- und Nachteilen am konkreten Kontext prüfen. Bestehenden Zustand einbeziehen, wenn er eine reale Handlungsoption ist.
- Entscheidende Annahmen und Quellen festhalten. Bei wesentlicher Unsicherheit eine gezielte Untersuchung vor der Wahl planen.
Ergebnis
Nachvollziehbare Abwägung
Option · relevante Wirkung · Unsicherheit · Quelle
Qualitätscheck
Werden reale Optionen am selben Kontext betrachtet?
Stolperfalle
Ungeeignete Scheinoptionen sollen die bevorzugte Wahl besser aussehen lassen. Realistische Alternativen und die wirklich entscheidenden Unterschiede dokumentieren.
Zeitlicher Rahmen: Aufwand folgt der Unsicherheit; Recherche oder ein Versuch können zusätzliche Arbeit benötigen.
3
Decide
Entscheidung prüfen und festhalten
Ziel
Status und Entscheidungsverantwortung sind nachvollziehbar.
Voraussetzungen für diesen Schritt
- Entwurf, Abwägung und betroffene Perspektiven
Durchführung
- Einen klaren Entscheidungsvorschlag mit Begründung und relevanten positiven wie nachteiligen Folgen formulieren. Offene Folgeaufgaben zuordnen.
- Review im vereinbarten Verfahren durchführen. Ausdrückliche Annahme, Verwerfung oder nötige Überarbeitung sowie Datum und Verantwortung festhalten.
Ergebnis
ADR mit geklärtem Status
Wahl · Gründe · Folgen · Status · Datum
Qualitätscheck
Ist die Entscheidung ausdrücklich bestätigt und dokumentiert? Sind relevante Folgen und offene Aufgaben verständlich?
Stolperfalle
Ein Entwurf gilt nach einer Wartezeit automatisch als angenommen. Status vorgeschlagen erhalten, bis die vereinbarte Entscheidung ausdrücklich dokumentiert ist.
Zeitlicher Rahmen: Entwurf etwa 15 bis 45 Minuten; Review und Entscheidung zusätzlich vereinbaren.
4
Maintain
Folgen verfolgen und Historie erhalten
Ziel
Neue Entscheidungen erklären ihre Verbindung zu früheren.
Voraussetzungen für diesen Schritt
- ADR mit geklärtem Status und Folgeaufgaben
Durchführung
- Die Notiz an Architektur, Umsetzung und relevante Nachweise verlinken. Offene Folgen im passenden Arbeitskontext verfolgen.
- Bei verändertem Kontext prüfen, ob eine neue Entscheidung nötig ist. Neuen ADR anlegen, Vorgänger verlinken und seinen Status auf ersetzt setzen; ursprüngliche Begründung erhalten.
Ergebnis
Verknüpfte Entscheidungshistorie
Folgeaufgabe · Anlass · Vorgänger · Nachfolger
Qualitätscheck
Sind die frühere Begründung und der aktuelle Status auffindbar?
Stolperfalle
Die alte Entscheidung wird rückwirkend an die neue Lösung angepasst. Eine neue Entscheidung mit Rückverweis dokumentieren und die frühere Fassung erhalten.
Zeitlicher Rahmen: Kurze Pflege bei relevanten Änderungen; keinen pauschalen Wiederholungsrhythmus erzwingen.

Artefakt

Was am Ende rauskommt

Skizze: so sieht das Artefakt aus

Architecture Decision Record · EntscheidungsrationaleKontext, Optionen, Entscheidung, Konsequenzen und Status versioniert festhalten

Form

Ein versionierter ADR mit Kennung, Titel, Status, Datum, Kontext, relevanter Abwägung, Entscheidung und Folgen. Verknüpfungen halten Quellen und ersetzte Entscheidungen auffindbar.

Versionierung / Ownership

Status wie vorgeschlagen, angenommen, verworfen oder ersetzt explizit führen und Übergänge datieren. Angenommene Gründe historisch erhalten. Für eine geänderte Entscheidung einen neuen ADR mit Rückverweis anlegen; den Vorgänger als ersetzt kennzeichnen.

Tool-Alternativen

Markdown-Datei im Projekt-Repository
Versioniertes Architektur-Wiki
Vorlage in einer gemeinsam zugänglichen Dokumentablage

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

Frame: Entscheidung und Kontext klären

Erwartetes Artefakt: Entscheidungskontext

Frage · Bedeutung · Rahmen · Verantwortung

Eintrag:

...

Kann eine spätere Person die Ausgangslage verstehen?

Compare: Relevante Optionen abwägen

Erwartetes Artefakt: Nachvollziehbare Abwägung

Option · relevante Wirkung · Unsicherheit · Quelle

Eintrag:

...

Werden reale Optionen am selben Kontext betrachtet?

Decide: Entscheidung prüfen und festhalten

Erwartetes Artefakt: ADR mit geklärtem Status

Wahl · Gründe · Folgen · Status · Datum

Eintrag:

...

Ist die Entscheidung ausdrücklich bestätigt und dokumentiert?
Sind relevante Folgen und offene Aufgaben verständlich?

Maintain: Folgen verfolgen und Historie erhalten

Erwartetes Artefakt: Verknüpfte Entscheidungshistorie

Folgeaufgabe · Anlass · Vorgänger · Nachfolger

Eintrag:

...

Sind die frühere Begründung und der aktuelle Status auffindbar?

Offene Fragen und nächste Schritte

...

Methodenanleitung: https://methodatlas.meierhoff-systems.de/de/methods/adr/run-sheet

Beispielausgabe

Konkret gefülltes Szenario, fiktives Beispiel

Fiktives Beispiel zur Orientierung. Die genannten Mengen und Zeiten beschreiben diesen Fall und sind keine allgemeine Vorgabe.

adr-beispiel.md

Konkret gefülltes Szenario, fiktives Beispiel

Fiktives Lehrbeispiel: Reservierungen gemeinsam verwalten

Alle Angaben sind erfunden. Es handelt sich um einen vorgeschlagenen ADR, keine getroffene Projektentscheidung.

ADR-007 · Status: vorgeschlagen

Kontext: Ein Werkzeugverleih nimmt Reservierungen online und an der Ausgabestelle an. Beide Zugänge müssen dieselbe Verfügbarkeit berücksichtigen.

Optionen: A: beide Zugänge nutzen einen zentralen Reservierungsdienst. B: getrennte Listen werden regelmäßig abgeglichen.

Vorschlag: Option A, weil die Vergabe über einen gemeinsamen Entscheidungspunkt erfolgen soll. Die technische Durchsetzung konfliktfreier Vergabe muss zusätzlich geprüft werden.

Folgen: Gemeinsame Zuständigkeit und einheitliche Prüfregeln; zugleich Abhängigkeit von Erreichbarkeit und Betrieb des Dienstes. Ein Ausfallverfahren ist zu klären.

Review: Betroffene Produkt- und Betriebsrollen prüfen den Vorschlag. Alex dokumentiert die ausdrückliche Entscheidung und den Zeitpunkt. Schweigen ändert den Status nicht.

Stolperfallen

Symptome erkennen, gegensteuern

Kurzüberblick, vollständiger Text steht in der jeweiligen Phase im Ablauf

Entscheidung und Kontext klärenDer Titel nennt eine Technologie, aber die Entscheidungsfrage bleibt unklar.In der Phase ansehen
Relevante Optionen abwägenUngeeignete Scheinoptionen sollen die bevorzugte Wahl besser aussehen lassen.In der Phase ansehen
Entscheidung prüfen und festhaltenEin Entwurf gilt nach einer Wartezeit automatisch als angenommen.In der Phase ansehen
Folgen verfolgen und Historie erhaltenDie alte Entscheidung wird rückwirkend an die neue Lösung angepasst.In der Phase ansehen

Abbruchkriterien

Wann du anhalten, Voraussetzungen klären oder einen anderen Ansatz wählen solltest

Die Entscheidungsfrage bleibt unklar: Gegenstand und Bedeutung zuerst eingrenzen.

Mehrere unabhängige Fragen wachsen zu einem Großdokument: in verknüpfte ADRs aufteilen.

Eine zentrale Annahme trägt die Wahl noch nicht: Untersuchung und offene Frage dokumentieren.

Entscheidungsverantwortung oder relevante Beteiligung fehlen: Reviewweg klären und Status vorgeschlagen erhalten.

Eine bereits angenommene Entscheidung wird inhaltlich geändert: neuen ADR anlegen und Historie verknüpfen.

Wie geht es weiter?

Architecture

arc42

Verankert die getroffene Entscheidung in der laufenden Architekturdokumentation.

Architecture

C4 Model

Spiegelt die Entscheidung in den betroffenen Architektursichten.

Im Playbook ansehenArchitekturentscheidung vorbereitenVon unscharfem technischen Problem zu dokumentierter, nachvollziehbarer Architekturentscheidung.

Methodenanleitung durchgearbeitet?

Zum Steckbrief für Zweck, ähnliche Methoden und Quellen oder direkt zur nächsten Methode im Katalog.

Zum Steckbrief Weitere Methoden