Architecture Decision Records: das Warum festhalten, nicht nur das Was

In jeder Codebasis gibt es Entscheidungen, die von außen seltsam aussehen. Warum steht zwischen diesen beiden Services eine Message Queue? Warum nutzt dieses Modul nicht das ORM, das alle anderen verwenden? Jemand hatte einen Grund, und ein Jahr später erinnert sich niemand mehr daran. Das Team lässt die Auffälligkeit aus Vorsicht stehen oder baut sie aus und erfährt dann, wozu sie da war.

Ein Architecture Decision Record (ADR) ist ein kurzer Text, der eine Frage beantwortet: Warum haben wir uns dafür entschieden? Er wird geschrieben, wenn die Entscheidung fällt, liegt neben dem Code und wird danach nicht mehr umgeschrieben.

Was ein ADR enthält

Michael Nygard hat das Format 2011 im Artikel „Documenting Architecture Decisions“ vorgeschlagen, und die meisten Vorlagen folgen ihm bis heute:

• Titel: eine kurze Nominalphrase mit Nummer, zum Beispiel „0007 PostgreSQL als einzigen Datenspeicher verwenden“.
• Status: vorgeschlagen, angenommen, abgelehnt, veraltet oder ersetzt durch einen anderen Eintrag.
• Kontext: die Situation und die wirkenden Kräfte. Anforderungen, Einschränkungen, was das Team damals wusste.
• Entscheidung: was beschlossen wurde, in ganzen Sätzen.
• Konsequenzen: was einfacher wird, was schwieriger wird und womit wir künftig leben müssen.

Die Vorlage MADR (Markdown Any Decision Records) ergänzt eine Liste der erwogenen Optionen mit Vor- und Nachteilen. Diese Ergänzung finde ich sinnvoll: Wer die verworfenen Optionen benennt, erspart dem Nächsten, sie noch einmal vorzuschlagen.

Ein Eintrag passt auf eine Bildschirmseite. Wenn das Schreiben länger als eine Stunde dauert, ist die Entscheidung vermutlich noch nicht klar, und auch das ist eine nützliche Erkenntnis.

Ein kurzes Beispiel

# 0007 PostgreSQL als einzigen Datenspeicher verwenden

Status: angenommen (12.03.2026)

## Kontext

Das erste Release braucht Bestellungen, Kunden und Rechnungen mit
starker Konsistenz. Das Team besteht aus drei Entwickler:innen, und
niemand hat Erfahrung mit dem Betrieb einer zweiten Datenbank. Wir
erwarten im ersten Jahr weniger als 50 Bestellungen pro Tag.

## Betrachtete Optionen

- Nur PostgreSQL
- PostgreSQL plus Redis für Sessions und Caching
- Eine Dokumentendatenbank für Bestellungen

## Entscheidung

Wir speichern alle persistenten Daten in PostgreSQL, auch Sessions.
Weitere Datenspeicher kommen nur dazu, wenn ein gemessenes Problem
es verlangt.

## Konsequenzen

- Ein System, das wir sichern, überwachen und lernen müssen.
- Sessions in der Datenbank erzeugen pro Anfrage etwas Last.
- Wächst das Bestellvolumen um den Faktor 100, muss Caching neu
  bewertet werden.

Nichts daran ist raffiniert. Genau das ist der Punkt: Der Eintrag hält Situation, Optionen, Wahl und Preis fest.

Wann man einen schreibt

Nicht jede Entscheidung braucht einen Eintrag. Eine brauchbare Regel: Schreiben Sie einen, wenn mindestens eines davon zutrifft:

• Die Entscheidung ist teuer rückgängig zu machen (Datenspeicher, Authentifizierung, Hosting, eine öffentliche API).
• Sie betrifft mehr als ein Team oder mehr als einen Teil des Codes.
• Es gab echten Streit, und eine Begründung war nötig, um ihn zu beenden.
• Sie können sich vorstellen, dass in einem Jahr ein neuer Kollege fragt: „Warum ist das so?“

Die Wahl einer Datumsbibliothek, einer Lint-Regel oder eines Ordnernamens zählt nicht dazu. Wenn die Einträge überwiegend klein sind, liest niemand die wichtigen.

Lebenslauf eines Eintrags

Die Regel, die das Ganze trägt: Ein angenommener Eintrag wird nie bearbeitet. Ändert sich die Entscheidung, schreiben Sie einen neuen Eintrag, markieren den alten als „ersetzt durch 0019“ und verlinken beide gegenseitig. So bleibt die Geschichte erhalten, warum die Architektur so aussieht, wie sie aussieht, auch mit den Entscheidungen, die sich als falsch herausgestellt haben.

Wo man sie ablegt und wie man sie prüft

Legen Sie die Einträge im Repository ab, zum Beispiel unter docs/adr/0007-use-postgresql.md, und behandeln Sie sie wie Code:

1. Die Autorin eröffnet einen Pull Request, der nur den Eintrag enthält.
2. Das Team diskutiert im Pull Request. Hier gehört die Meinungsverschiedenheit hin: schriftlich, mit den Optionen vor Augen.
3. Der Eintrag wird als „angenommen“ gemergt, wenn die Betroffenen zustimmen oder wenn die verantwortliche Person entschieden und die Begründung festgehalten hat.

Zwei praktische Ergänzungen helfen. Begrenzen Sie die Diskussion zeitlich (eine Woche reicht für die meisten Entscheidungen) und benennen Sie eine Person, die entscheidet, wenn die Gruppe sich nicht einigt. Ohne beides werden aus Einträgen endlose Threads.

Wer Werkzeuge möchte: adr-tools legt Dateien auf der Kommandozeile an und nummeriert sie, Log4brains macht aus einem Ordner voller Einträge eine durchsuchbare Seite. Nötig ist beides nicht. Ein Ordner und eine Vorlage genügen.

Warum Teams aufhören, sie zu schreiben

Die meisten ADR-Gewohnheiten sterben aus denselben Gründen:

• Die Einträge sind zu lang. Zwei Seiten Hintergrund liest niemand. Beschränken Sie den Kontext auf das, was ein neuer Kollege braucht, um der Entscheidung zu folgen.
• Sie entstehen nachträglich oder gar nicht. Den Eintrag beim Entscheiden zu schreiben kostet zehn Minuten. Ihn später zu rekonstruieren kostet eine Diskussion. Nachträgliche Einträge lohnen sich trotzdem für die Entscheidungen, nach denen am häufigsten gefragt wird. Datieren Sie sie ehrlich.
• Niemand verlinkt sie. Nennen Sie den Eintrag im Pull Request, der die Entscheidung umsetzt, und in einem Code-Kommentar an der Stelle mit der auffälligen Wahl.
• Der Abschnitt „Konsequenzen“ fehlt. Ein Eintrag, der nur Vorteile aufzählt, ist Werbung. Die negativen Konsequenzen brauchen spätere Leser am dringendsten.
• Niemand schaut später wieder hinein. Setzen Sie ein Prüfdatum, wenn die Entscheidung von einer Annahme wie Last oder Teamgröße abhängt.

Ab dieser Woche

Sie brauchen dafür keinen Prozess-Workshop. Legen Sie den Ordner docs/adr/ an. Schreiben Sie Eintrag 0001: „Wir halten Architekturentscheidungen in diesem Repository fest“, nach der obigen Vorlage. Schreiben Sie dann drei nachträgliche Einträge zu den Fragen, die neue Teammitglieder am häufigsten stellen. Danach schreiben Sie bei jeder nächsten echten Entscheidung einen Eintrag und prüfen, ob der zweite leichter fällt als der erste.