Architecture Decision Record
Ein ADR stellt sicher, dass in achtzehn Monaten niemand eine bereits geklärte Frage erneut aufwirft, ohne zu wissen, warum sie damals entschieden wurde. Und dass die Entscheidung bei sich ändernden Rahmenbedingungen bewusst überdacht werden kann.
Wo
docs/adr/NNNN-kurzer-titel.md, fortlaufend nummeriert. Prüfe das Verzeichnis auf die nächste Nummer und die vorhandene Vorlage; folge ihr, falls eine existiert.
Vorlage
# NNNN. <Titel in Form der Entscheidung: „Aurora PostgreSQL für den Orders-Service verwenden“>
Datum: JJJJ-MM-TT
Status: Vorgeschlagen | Akzeptiert | Ersetzt durch NNNN | Veraltet
Entscheider: <Namen oder Team>
## Kontext
<Welche Kräfte wirken: Anforderungen, Einschränkungen, aktuelle Schmerzpunkte, Deadlines, Compliance,
Teamfähigkeiten, Kostenrahmen. Zwei bis vier Absätze. Fakten, keine Meinungen.>
## Entscheidung
<Ein oder zwei Sätze im Präsens: „Wir werden …“>
## Betrachtete Optionen
### Option A: <Name>
Vorteile / Nachteile / Ungefähre Kosten / Betrieblicher Aufwand
### Option B: <Name>
…
## Konsequenzen
<Was wird einfacher, was wird schwieriger, was müssen wir jetzt tun (Migrationen, Schulungen,
neue Runbooks), welches Risiko nehmen wir explizit in Kauf.>
## Folgemaßnahmen
- [ ] <konkrete Aufgaben mit Besitzern, falls bekannt>
Schreibhinweise
- Schreibe den Kontext so, dass ein Neueinsteiger das Problem für real hält, bevor er die Entscheidung liest.
- Vergleiche Optionen anhand derselben Kriterien: Kosten, betriebliche Belastung, Lock-in, Vertrautheit des Teams, Zeit bis zur Auslieferung, Sicherheit/Compliance. Füge Zahlen ein, wo du sie hast (monatliche Kostenschätzung, RTO/RPO, Durchsatz).
- Sei ehrlich über die Stärken der unterlegenen Optionen. Ein ADR, der Alternativen verzerrt darstellt, wird nicht ernst genommen.
- Zu den Konsequenzen gehören auch die negativen. „Wir müssen jetzt zwei Datenbanken sichern“ gehört dorthin.
- Halte dich unter zwei Seiten. Verlinke auf Spikes, Benchmarks und Tickets, anstatt sie ausführlich darzustellen.
- Wenn du einen ADR ersetzt, aktualisiere den Status des alten ADR und verlinke beide Seiten.
Wenn $ARGUMENTS übergeben wird
Verwende es als Titel; leite den Dateinamen daraus ab.