Wir haben zwei Wochen damit verbracht, eine Datenbankentscheidung zu debattieren, die wir ein Jahr zuvor bereits getroffen und verworfen hatten. Da entdeckte ich ADRs, und sie haben uns seitdem unzählige Stunden erspart.

Best Practices für Architecture Decision Records (ADRs)

Das Meeting dauerte bereits zwei Stunden. Wir debattierten, ob wir PostgreSQL oder MongoDB für einen neuen Service verwenden sollten. Argumente flogen hin und her — relationale Integrität, flexible Schemas, Team-Vertrautheit, operationale Komplexität.

Dann erwähnte jemand: "Hatten wir nicht genau diese Diskussion letztes Jahr für den User-Service?"

Stille. Hatten wir. Ein Jahr zuvor hatten wir ähnlich viel Zeit damit verbracht, dieselbe Frage zu debattieren, und uns schließlich für PostgreSQL entschieden. Aber niemand erinnerte sich an die Begründung. Der Ingenieur, der diese Diskussion geleitet hatte, hatte das Unternehmen verlassen. Also waren wir hier und führten genau dieselbe Debatte von vorne.

Da entdeckte ich Architecture Decision Records (ADRs), und sie haben uns unzählige Stunden erspart, in denen wir bereits gelöste Debatten erneut führten.

Was ist ein ADR?

Ein ADR ist ein kurzes Dokument, das eine einzelne architektonische Entscheidung festhält. Kein Design-Dokument, das alles über ein System abdeckt, nur eine Entscheidung:

Was wir entschieden haben
Warum wir es entschieden haben
Welche Alternativen wir betrachtet haben
Was die Konsequenzen sind

Das Format ist absichtlich leichtgewichtig. Ein ADR sollte auf eine Seite passen. Wenn es länger ist, dokumentieren Sie wahrscheinlich mehr als eine Entscheidung.

Die Anatomie eines guten ADR

Nachdem ich Dutzende von ADRs geschrieben und Hunderte mehr gelesen habe, habe ich festgestellt, dass die besten einer konsistenten Struktur folgen:

Titel und Nummer

Jeder ADR bekommt eine fortlaufende Nummer und einen prägnanten Titel:

ADR-0042: PostgreSQL für den Order-Service verwenden

Die Nummer ist wichtig. Sie erstellt eine Zeitleiste von Entscheidungen und macht ADRs leicht referenzierbar in Diskussionen: "Wie wir in ADR-42 entschieden haben..."

Status

ADRs haben Lebenszyklus-Status:

Vorgeschlagen: Noch in Diskussion
Akzeptiert: Entscheidung getroffen, wir folgen dem
Veraltet: Nicht mehr relevant (ein neuer ADR ersetzt es)
Abgelehnt: Wir haben es betrachtet, aber dagegen entschieden

Der abgelehnte Status ist besonders wertvoll. Manchmal möchten Sie festhalten, warum Sie etwas nicht getan haben, damit zukünftige Teams nicht dasselbe vorschlagen.

Kontext

Hier beschreiben Sie die Situation, die die Entscheidung ausgelöst hat. Welches Problem lösen wir? Welche Einschränkungen haben wir? Wer ist betroffen?

## Kontext

Der Order-Service benötigt persistenten Speicher für Bestelldaten.
Wir erwarten anfänglich 50.000 Bestellungen pro Tag, wachsend auf
500.000 in zwei Jahren. Bestellungen haben eine wohldefinierte Struktur,
benötigen aber möglicherweise zusätzliche Metadatenfelder im Laufe der Zeit.
Das Team hat Erfahrung mit relationalen und dokumentbasierten Datenbanken.

Seien Sie spezifisch über Einschränkungen. "Wir brauchen ACID-Konformität" ist viel nützlicher als "wir brauchen Zuverlässigkeit." Zukünftige Leser müssen die Kräfte verstehen, die die Entscheidung geformt haben.

Entscheidung

Formulieren Sie die Entscheidung klar. Nicht "wir könnten erwägen" oder "wir sollten erkunden" — was wir tatsächlich entschieden haben.

## Entscheidung

Wir werden PostgreSQL 15 als primäre Datenbank für den Order-Service verwenden.

Wir haben PostgreSQL gewählt, weil:

- ACID-Konformität ist für finanzielle Bestelldaten erforderlich
- JSON-Spalten bieten Schema-Flexibilität für Metadaten
- Unser Infra-Team hat operationale Erfahrung mit PostgreSQL
- Abfragemuster sind gut geeignet für relationale Modellierung

Beachten Sie, dass dies nicht nur die Entscheidung formuliert, sondern kurz die Begründung erklärt. Der nächste Abschnitt geht mehr ins Detail, aber selbst der Entscheidungsabschnitt sollte selbsterklärend sein.

Betrachtete Alternativen

Dies ist der am meisten unterschätzte Abschnitt. Zu dokumentieren, was Sie nicht gewählt haben, ist oft genauso wertvoll wie zu dokumentieren, was Sie gewählt haben.

## Betrachtete Alternativen

### MongoDB

Vorteile:

- Nativer JSON-Speicher
- Einfacheres horizontales Skalieren
- Flexible Schema-Evolution

Nachteile:

- Schwächere Konsistenzgarantien
- Team weniger vertraut mit Betrieb
- Würde zusätzliche Tools für Transaktionen erfordern

### DynamoDB

Vorteile:

- Vollständig verwaltet, minimaler Betrieb
- Ausgezeichnete Skalierungseigenschaften

Nachteile:

- Vendor-Lock-in mit AWS
- Begrenzte Abfragemuster auf Partition/Sort-Key-Zugriff
- Unvorhersehbare Kosten bei großem Umfang

Wenn jemand Neues dem Team beitritt und fragt "warum verwenden wir nicht MongoDB?", haben Sie die Antwort. Sie müssen kein Meeting ansetzen oder die Person finden, die die ursprüngliche Entscheidung getroffen hat.

Konsequenzen

Jede Entscheidung hat Trade-offs. Seien Sie ehrlich darüber.

## Konsequenzen

### Positiv

- Starke Datenintegritätsgarantien
- Team kann vorhandene PostgreSQL-Expertise nutzen
- Gut verstandene betriebliche Eigenschaften

### Negativ

- Schema-Migrationen erfordern mehr Planung als Document Stores
- Horizontales Skalieren komplexer, wenn Single-Node-Kapazität überschritten wird
- Müssen Sharding auf Anwendungsebene implementieren, wenn wir an Grenzen stoßen

### Risiken

- Möglicherweise Überprüfung erforderlich, wenn Bestellvolumen 1M/Tag überschreitet
- JSON-Spaltenabfragen weniger effizient als native Document Stores

Dieser Abschnitt geht um intellektuelle Ehrlichkeit. Keine Entscheidung ist perfekt. Die Nachteile anzuerkennen baut Vertrauen auf und hilft zukünftigen Teams zu verstehen, wann sie die Entscheidung möglicherweise überprüfen müssen.

Wann einen ADR schreiben

Nicht jede technische Wahl braucht einen ADR. Nutzen Sie Ihr Urteilsvermögen, aber hier sind einige Richtlinien:

Schreiben Sie einen ADR, wenn...

Die Entscheidung mehrere Teams oder Services betrifft
Die Entscheidung teuer zu revidieren wäre
Sie zwischen mehreren gangbaren Optionen wählen
Zukünftige Teammitglieder die Wahl hinterfragen könnten
Die Entscheidung eine bedeutende technische Debatte löst

Schreiben Sie keinen ADR, wenn...

Die Wahl offensichtlich und unbestritten ist
Die Entscheidung nur eine Person oder eine Datei betrifft
Sie leicht reversibel ist ohne signifikante Kosten
Es ein Standardmuster ist, dem Ihr Team immer folgt

Zum Beispiel: "Welche JSON-Bibliothek verwenden?" braucht wahrscheinlich keinen ADR. "GraphQL oder REST für unsere öffentliche API verwenden?" definitiv schon.

Echte ADRs aus unseren Projekten

Hier sind einige echte ADRs, die wir geschrieben haben (vereinfacht für diesen Beitrag):

ADR-0007: Event-Driven Kommunikation zwischen Services

Kontext: Unsere Microservices kommunizieren derzeit synchron über HTTP. Das erzeugt enge Kopplung und Kaskadenfehler, wenn Services nicht verfügbar sind.

Entscheidung: Wir werden eine Event-Driven-Architektur mit Apache Kafka für asynchrone Inter-Service-Kommunikation einführen.

Konsequenzen:

Services werden resilienter gegen Ausfälle
Eventual Consistency statt Strong Consistency
Erhöhte betriebliche Komplexität (Kafka-Cluster-Management)
Team braucht Training in Event-Sourcing-Mustern

ADR-0015: Monorepo für Frontend-Anwendungen

Kontext: Wir haben 5 Frontend-Anwendungen in separaten Repositories. Code-Sharing erfordert das Publizieren von Paketen. Die Entwicklererfahrung leidet unter Versionsinkompatibilitäten.

Entscheidung: Alle Frontend-Anwendungen in einem einzelnen Monorepo mit Nx konsolidieren.

Abgelehnte Alternativen:

Separate Repos mit besserem Paketmanagement beibehalten: Abgelehnt, weil Koordinations-Overhead bleibt
Einzelnes Repo ohne Nx: Abgelehnt, weil Build-Zeiten prohibitiv wären

Konsequenzen:

Vereinfachtes Code-Sharing und Konsistenz
Ein einzelner PR kann gemeinsamen Code und alle Konsumenten aktualisieren
Größeres Repository erfordert bessere Tools für Build-Caching
Potenzial für unbeabsichtigte Kopplung zwischen Anwendungen

Häufige Fehler, die ich gemacht habe

Fehler 1: ADRs nachträglich schreiben

Der beste Zeitpunkt, einen ADR zu schreiben, ist während des Entscheidungsprozesses, nicht Wochen später. Wenn Sie nachträglich schreiben, vergessen Sie die Nuancen, die betrachteten Alternativen und die spezifischen Einschränkungen.

Jetzt schreiben wir ADR-Entwürfe als Teil des Entscheidungsprozesses. Die Diskussion findet im ADR-Dokument statt, nicht in Slack-Threads, die verschwinden.

Fehler 2: Sie zu lang machen

Wenn Ihr ADR mehr als eine Seite ist, sind Sie wahrscheinlich:

Dokumentieren mehrerer Entscheidungen (trennen Sie sie in mehrere ADRs)
Schließen Implementierungsdetails ein (heben Sie das für Design-Docs auf)
Über-Erklären offensichtlichen Kontext

Die Disziplin der Kürze erzwingt Klarheit.

Fehler 3: Verwandte ADRs nicht verlinken

Entscheidungen existieren selten isoliert. Als wir Kafka für Event-Driven-Kommunikation wählten (ADR-0007), beeinflusste das unsere Datenbankwahl (ADR-0042), weil wir Eventual Consistency akzeptieren konnten.

Machen Sie Querverweise auf verwandte ADRs:

## Verwandte Entscheidungen

- Siehe ADR-0007 für warum wir Eventual Consistency akzeptieren
- Ersetzt ADR-0003, der MongoDB empfohlen hatte

Fehler 4: Die Praxis aufgeben

ADRs bieten Wert über die Zeit. Ein oder zwei ADRs helfen nicht viel. Ein Korpus von 50+ ADRs, angesammelt über Jahre, wird unglaublich wertvoll. Es ist eine durchsuchbare Geschichte Ihrer architektonischen Evolution.

Die Versuchung ist, aufzuhören sie zu schreiben, wenn es hektisch wird. Widerstehen Sie. Die zehn Minuten, die Sie für das Schreiben eines ADR aufwenden, sparen Stunden von Meetings später.

ADRs zum Teil Ihres Workflows machen

Der schwierigste Teil ist nicht, ADRs zu schreiben — es ist, sie zur Gewohnheit zu machen. Das funktioniert:

Speichern Sie sie mit dem Code

Legen Sie ADRs in Ihr Repository, typischerweise in docs/adr/ oder docs/decisions/. So:

Werden sie mit dem Code versioniert, den sie beschreiben
Erscheinen sie in Code-Reviews
Können sie nicht verwaist in einem Wiki irgendwo liegen

Verwenden Sie ein Template

Erstellen Sie ein Markdown-Template, das alle verwenden. Das reduziert Reibung und stellt Konsistenz sicher:

# ADR-NNNN: Titel

## Status

Vorgeschlagen | Akzeptiert | Veraltet | Abgelehnt

## Kontext

[Was ist das Problem, das wir sehen, das diese Entscheidung motiviert?]

## Entscheidung

[Was ist die Änderung, die wir vorschlagen und/oder machen?]

## Betrachtete Alternativen

[Welche anderen Optionen haben wir betrachtet?]

## Konsequenzen

[Was wird durch diese Änderung einfacher oder schwieriger?]

Überprüfen Sie ADRs vierteljährlich

Setzen Sie eine Kalendererinnerung, um Ihre ADRs jedes Quartal zu überprüfen:

Gibt es Entscheidungen, die nicht mehr relevant sind?
Haben sich die Umstände geändert, die unsere Annahmen ungültig machen?
Gibt es undokumentierte Entscheidungen, die wir festhalten sollten?

Verlinken Sie ADRs mit Architekturdiagrammen

Hier glänzen Tools wie Archyl. Wenn Sie einen ADR mit einer spezifischen Komponente in Ihrem C4-Diagramm verlinken, kann jeder, der diese Komponente betrachtet, sofort die Entscheidungen sehen, die sie geformt haben.

"Warum spricht dieser Service mit Kafka statt direkt mit der Datenbank?" Klicken Sie auf den verlinkten ADR und finden Sie es heraus.

Fazit

Architecture Decision Records sind eine dieser Praktiken, die sich wie Overhead anfühlen, bis Sie sie brauchen. Dann sind sie unschätzbar.

Dieses zweistündige Meeting über PostgreSQL vs MongoDB? Wir haben es in zehn Minuten beendet, sobald jemand den ursprünglichen ADR gefunden hatte. Der gesamte Kontext war da — die Einschränkungen, die Alternativen, die Begründung. Wir haben schnell bestätigt, dass die ursprüngliche Entscheidung noch galt, und sind weitergezogen.

Fangen Sie klein an. Das nächste Mal, wenn Sie eine architektonische Entscheidung treffen, nehmen Sie sich fünfzehn Minuten, um einen ADR zu schreiben. Legen Sie ihn in Ihr Repository. In sechs Monaten, wenn jemand fragt "warum haben wir das so gemacht?", haben Sie die Antwort.

Mehr über Architekturdokumentation erfahren: Einführung in das C4-Modell | Warum Dokumentation wichtig ist | User Flows dokumentieren

Best Practices für Architecture Decision Records (ADRs) - Archyl Blog