Architekturdokumentation veraltet schnell, aber Entscheidungen bleiben relevant. Wer in einem Projekt mit „Warum ist das eigentlich so gebaut?" konfrontiert wird, will keine Systembeschreibung, sondern den Kontext der Entscheidung.
Genau dafür gibt es Architecture Decision Records (ADRs), ein Format, das Michael Nygard 2011 vorgestellt hat.
Das Prinzip
- Eine Entscheidung pro Datei, Markdown, im selben Repository wie der Code.
- Kurz: eine Seite, nicht zehn.
- Unveränderlich: Eine überholte Entscheidung wird nicht gelöscht, sondern als ersetzt markiert und verweist auf die neue.
- Nummeriert:
0007-postgres-statt-mongodb.md
Eine Vorlage
# 7. PostgreSQL als primäre Datenbank
Datum: 2026-11-07
Status: akzeptiert
## Kontext
Welche Kräfte wirken? Anforderungen, Einschränkungen, Team-Wissen.
## Entscheidung
Was haben wir entschieden? Ein Satz, aktiv formuliert.
## Alternativen
Was wurde ernsthaft erwogen, und warum nicht gewählt?
## Konsequenzen
Was wird einfacher? Was wird schwerer? Welche Risiken nehmen wir in Kauf?
Der Abschnitt Alternativen ist der wertvollste. Er verhindert, dass dieselbe Diskussion alle sechs Monate neu geführt wird.
Faustregel
Schreibe einen ADR, wenn eine Entscheidung teuer zu ändern ist oder wenn du dich dabei ertappst, sie jemandem erklären zu müssen.
Typische Fehler
| Fehler | Besser |
|---|---|
| ADR erst Monate später rückwirkend schreiben | Direkt im Pull Request mit der Änderung |
| Nur die Entscheidung, kein Kontext | Kontext und Alternativen gehören zwingend dazu |
| Zu viele ADRs für Kleinigkeiten | Nur Entscheidungen mit Architektur-Wirkung |
| ADRs in einem Wiki, getrennt vom Code | Im Repository, wird im Review mit geprüft |
Fazit
ADRs kosten pro Entscheidung zehn bis fünfzehn Minuten. Dafür sparen sie jedem neuen Teammitglied und dir selbst in zwei Jahren viele Stunden Detektivarbeit.