Was vorher fertig sein muss
Bei kontroversen oder weitreichenden Entscheidungen liegt ein durchdiskutiertes RFC vor. Daraus übernimmst du Kontext, geprüfte Optionen und die ausgewählten Tradeoffs.
Liegt vor, wenn die Entscheidung primär durch Qualitätsanforderungen getrieben wird. Daraus übernimmst du den Utility Tree und priorisierte Quality Attributes als Bewertungsraster.
Ein konkretes Ticket, ein Incident oder eine Issue-ID, an der der ADR aufhängt.
Was vor Start vorliegen muss
ADR-Template (MADR oder Nygard-Stil) im Repo unter `docs/adr/`; Markdown- oder Wiki-Editor; Link auf den Issue-Tracker (Linear, Jira, GitHub Issues).
Ein Decider mit Vor- und Nachname (kein „Team“, keine Gilde); ein bis zwei Reviewer aus den betroffenen Teams; Verfasser optional dieselbe Person wie der Decider.
Issue-ID oder Trigger; Nummer des nächsten freien ADR im Repo; relevante frühere ADRs zur Verknüpfung; mindestens zwei identifizierte Optionen inklusive Status quo.
15–30 min Schreiben; 24–72 h asynchrone Reviewfrist; 1 min Statussetzen nach Ablauf.
Nächste freie Nummer im Verzeichnis prüfen; Branch nach Muster `adr/NNNN-kurztitel` anlegen; Reviewer im Pull Request oder Linear-Ticket taggen; Reviewfrist als Datum im PR-Beschreibungsfeld benennen.
Die eine Frage, die diese Methode beantwortet
Welche Architekturentscheidung trifft das Team jetzt, vor welchen Alternativen, und welche Konsequenzen akzeptiert es dafür?
Marker: Sektion
| Schritt | Dauer | Aktion | Hinweis |
|---|---|---|---|
1Header | 2 min | Titel als Entscheidung formulieren, Status auf `proposed`, Datum und Decider eintragen, Trigger-ID referenzieren. | Titel ist die Entscheidung, nicht das Thema. „PostgreSQL statt MySQL für Order-Service“ ist gut, „Datenbankwahl“ ist es nicht. |
2Kontext | 5–10 min | Forces benennen: Lastannahmen, Constraints, Quality Attributes, bestehende ADRs. Zahlen und Zeitpunkte konkret. | 3–5 Sätze reichen. Geschichte relationaler Datenbanken gehört nicht hierhin; ein Architektur-Wikipedia-Eintrag ist ein Warnsignal. |
3Optionen | 5–10 min | Mindestens zwei Optionen mit je einem Pro und einem Contra; Status quo („nichts ändern“) explizit aufnehmen. | Wenn nur eine Option mit Pros aufgeführt ist, ist das eine Begründung und kein Record. Zweite Option auch dann erzwingen, wenn sie verworfen wird. |
4Entscheidung | 3–5 min | Eine Option benennen, ohne Konjunktiv: „Wir entscheiden uns für Option 1.“ | Konjunktive sind hier verbotenes Stilmittel. „Wir würden bevorzugen“ gehört in den Review-Kommentar, nicht in den Record. |
5Konsequenzen | 3–5 min | Positive und negative Folgen, neue Risiken, Folge-ADRs benennen, die aus dieser Entscheidung entstehen. | Wenn keine negative Konsequenz einfällt, einen Skeptiker im Team fragen. Reine Pro-Listen sind ein Warnsignal für ungeprüfte Annahmen. |
6Review | 24–72 h | Reviewer per PR oder Linear taggen; Frist im Kommentar benennen; Schweigen nach Frist gilt als Zustimmung. | Aktives Veto bedeutet Re-Diskussion, nicht stiller Statuswechsel. Veto-Begründung als Risiko in den Konsequenzen-Block übernehmen. |
7Status | 1 min | Nach Frist Status auf `accepted`, `rejected` oder `withdrawn` setzen; Datum aktualisieren. | Status `draft` über mehrere Tage bedeutet, niemand ist verantwortlich. Ein ADR ohne gesetzten Status hat keinen Wert. |
Was am Ende rauskommt
Eine Markdown-Datei mit Header (Titel, Status, Datum, Decider, Trigger) und fünf Sektionen in fester Reihenfolge: Kontext, Optionen, Entscheidung, Konsequenzen, optional Referenzen. Dateiname nach Muster `NNNN-kurztitel.md` mit fortlaufender Nummer.
Idealerweise im Code-Repository neben dem betroffenen Bereich, damit Entscheidung und Implementation zusammen versioniert werden; Owner ist der Decider; angenommene ADRs werden nicht editiert. Änderungen entstehen als neuer ADR, der den alten als `superseded by NNNN` markiert.
Kompakte Vorlage für Architecture Decision Records im Repository oder Wiki.
Status: proposed Datum: YYYY-MM-DD Decider: Vorname Nachname Trigger: Ticket, Incident oder RFC
Welche Situation macht die Entscheidung nötig? Welche Constraints, Quality Attributes oder früheren Entscheidungen sind relevant?
Wir entscheiden uns für ...
Positive Folgen:
Negative Folgen und Risiken:
Folge-ADRs oder Tickets:
Konkret gefülltes Szenario, fiktives Beispiel
Konkret gefülltes Szenario, fiktives Beispiel
Status: accepted Datum: 2026-05-17 Decider: Lena König (Tech Lead Order-Domain) Trigger: ORD-2148 — Auswahl der Persistenzschicht für den neuen Order-Service
Der Order-Service ersetzt das Monolith-Modul order-legacy, das bisher
gegen MySQL 5.7 läuft. Bis Q3/2026 werden ~1,2 Mio. Bestellungen pro Monat
erwartet, transaktionale Schreiblast in Bursts (Sale-Phasen bis 350
Writes/s), JSONB-Felder für variable Promo-Strukturen, PITR-Backups als
Compliance-Vorgabe aus 0028.
Bestehende ADRs zur Verknüpfung: 0028 (Cloud-Provider AWS), 0033 (Container-Plattform EKS).
Wir entscheiden uns für Option 1: PostgreSQL 16 auf RDS.
Tragend sind drei Punkte: die vertraute SQL-Toolchain reduziert Onboarding der drei Junior-Engineers um geschätzt zwei Sprints, JSONB deckt die Promo-Modellierung ohne Schema-Migrationen ab, und die PITR-Strategie aus 0028 bleibt ohne Anpassung wiederverwendbar.
Positiv:
Negativ:
Folge-ADRs:
order-legacy → Order-Service (Dual Write
vs. Replay).Symptome erkennen, gegensteuern
Im Abschnitt „Optionen“ steht direkt die spätere Wahl, ohne Vergleich, oder nur eine Option mit Pros und ohne Contra.
Status quo als zweite Option erzwingen, auch wenn unrealistisch; mindestens ein Pro und ein Contra pro Option formulieren.
Der Konsequenzen-Block liest sich wie ein Vendor-Pitch.
Mindestens zwei negative Folgen oder neue Risiken einfordern; wenn keine einfallen, hat das Team die Optionen nicht durchdacht. Einen Skeptiker im Team explizit nach Risiken fragen.
Der Branch lebt zwei Wochen, niemand reviewt, Code ist aber längst im Main-Branch.
Reviewfrist hart auf 48–72 Stunden setzen, Reviewer namentlich pingen, nach Ablauf der Frist Status auf `accepted` ziehen. Schweigen gilt als Zustimmung, das muss vorher kommuniziert sein.
Jemand ändert die Entscheidung in einem existierenden ADR.
Alten ADR auf `superseded by NNNN` setzen, neuen ADR mit eigener Nummer anlegen. Die Git-Historie reicht nicht; sie ist nicht navigierbar und nicht im Wiki sichtbar.
Im Header steht kein konkreter Name.
Eine Person mit Vor- und Nachname als Decider eintragen, die im Streitfall einsteht. Konsens muss nicht aus dem Header hervorgehen, Verantwortung schon.
Ein ADR mit Titel wie „Wir nutzen Tabs statt Spaces“ oder „Variable umbenennen“.
ADR zurückziehen oder löschen. ADRs sind für Entscheidungen mit mindestens sechs Monaten Wirkungshorizont oder Rollback-Kosten von mehr als einem Sprint.
„Aktuell haben wir Probleme mit der Performance“ ohne Zahl, ohne Datum.
Werte und Zeitpunkte konkret nennen: „Im Februar 2026 lag die p95-Latenz auf `/orders` bei 1.8 s, Ziel <500 ms“. Ein Leser in 18 Monaten muss den Kontext rekonstruieren können.
Done-Signale, in unter einer Minute prüfbar
Zum Steckbrief für Zweck, ähnliche Methoden und Quellen oder direkt zur nächsten Methode im Katalog.