Zum Hauptinhalt springen

ADR (Architecture Decision Record)

Ein ADR dokumentiert warum eine Architekturentscheidung getroffen wurde –
nicht nur was entschieden wurde.

Architektur entsteht durch Entscheidungen.
Ohne Dokumentation entsteht implizite Architektur.

Ein ADR macht Entscheidungen:

  • nachvollziehbar
  • überprüfbar
  • diskutierbar
  • korrigierbar

1. Was ist ein ADR?​

Ein ADR ist ein kurzes, strukturiertes Dokument, das eine relevante technische oder architektonische Entscheidung festhält.

Ein ADR beantwortet:

  • Welches Problem bestand?
  • Welche Optionen gab es?
  • Warum wurde diese Lösung gewählt?
  • Welche Konsequenzen entstehen daraus?

Ein ADR ist kein Roman.
Er ist ein bewusstes Entscheidungsprotokoll.

2. Warum ADRs wichtig sind​

2.1 Entscheidungen werden sonst vergessen​

Nach 6–12 Monaten weiß oft niemand mehr:

  • warum Technologie X gewählt wurde
  • warum Pattern Y eingeführt wurde
  • warum Option Z verworfen wurde

Ohne ADR entstehen:

  • Wiederholungsdiskussionen
  • inkonsistente Richtungswechsel
  • „Das haben wir schon mal probiert“-Momente

2.2 ADRs verhindern implizite Architektur​

Jede größere Entscheidung verändert die Struktur eines Systems.

Wenn diese Entscheidung nicht dokumentiert wird, entsteht:

  • implizite Annahme
  • historisch gewachsene Kopplung
  • schwer erklärbare Struktur

ADRs machen Architektur explizit.

2.3 ADRs verbessern die Qualität der Entscheidung​

Das Schreiben eines ADRs zwingt zu:

  • systematischer Abwägung von Optionen
  • expliziter Begründung
  • Reflektion über Konsequenzen

Oft verbessert sich die Entscheidung allein durch die Strukturierung.

3. Minimale Struktur eines ADR​

Ein ADR sollte leichtgewichtig bleiben.

1. Titel
2. Datum
3. Status (proposed, accepted, rejected, deprecated, superseded)
4. Kontext (Problem / Ausgangssituation)
5. Optionen (inkl. verworfene Alternativen)
6. Entscheidung
7. Konsequenzen (positiv & negativ)

Wichtig:
Konsequenzen müssen ehrlich sein – auch Nachteile.

4. Beispiel (Kurzform)​

Titel: Datenbank für Reporting
Status: accepted
Kontext: Reporting benötigt schnelle Aggregationen über große Datenmengen
Optionen: PostgreSQL, ClickHouse, BigQuery
Entscheidung: ClickHouse
Konsequenzen:

  • Neue Betriebsanforderungen
  • Schulung für Team erforderlich
  • Separate Infrastruktur nötig

5. Wann sollte man ein ADR schreiben?​

Ein ADR ist sinnvoll, wenn:

  • eine Entscheidung schwer rückgängig zu machen ist
  • mehrere Teams betroffen sind
  • hohe Kosten oder Risiken entstehen
  • neue Technologien eingeführt werden
  • Architekturprinzipien beeinflusst werden
  • langfristige Wartbarkeit betroffen ist

Nicht jedes Ticket braucht ein ADR.
Aber jede strukturprägende Entscheidung sollte eines haben.

6. Lebenszyklus eines ADR​

ADRs sind keine statischen Dokumente.

Mögliche Stati:

  • proposed
  • accepted
  • rejected
  • deprecated
  • superseded (ersetzt durch neues ADR)

Architektur ist evolutionär.
ADRs dokumentieren diese Evolution.

7. Typische Anti-Patterns​

  • ADRs erst nachträglich schreiben („Retro-ADR“ ohne echte Diskussion)
  • nur Entscheidung dokumentieren, nicht Alternativen
  • keine negativen Konsequenzen nennen
  • keine Aktualisierung bei Richtungswechsel
  • zu lange, akademische Dokumente

Ein ADR sollte in wenigen Minuten lesbar sein.

8. ADRs im Qualitäts- und Governance-Kontext​

Ab Stufe 2 (Team-Standard) sollten ADRs:

  • versioniert im Repository liegen
  • referenzierbar aus PRs sein
  • mit relevanten Issues verlinkt werden

Ab Stufe 4+ können ADRs Teil der Traceability werden.

ADRs sind ein Baustein für:

  • Nachvollziehbarkeit
  • Auditierbarkeit
  • organisatorisches Lernen

9. Definition of Done für Architekturentscheidungen​

Eine Architekturentscheidung gilt nicht als abgeschlossen, wenn:

  • keine Alternativen betrachtet wurden
  • keine Begründung dokumentiert ist
  • keine Konsequenzen benannt sind
  • spätere Diskussionen nicht referenzieren können

Kernaussage​

ADRs sind kein Dokumentations-Overhead.

Sie sind das Gedächtnis eines Systems.

Ohne ADRs entstehen Entscheidungen trotzdem –
aber ihre Gründe gehen verloren.

Mit ADRs wird Architektur explizit, nachvollziehbar und evolvierbar.