ADR: Architectural Decision Records - vom Markdown-Template zur Plattform

Was sind Architectural Decision Records?

Ein Architectural Decision Record (ADR) ist ein kurzes, strukturiertes Dokument, das eine einzelne Architekturentscheidung festhält. Das Konzept wurde 2011 von Michael Nygard in seinem Blogpost „Documenting Architecture Decisions" popularisiert und hat sich seither in der Softwareentwicklung als Best Practice etabliert. Statt Entscheidungen in langen Architekturdokumenten zu vergraben, erhält jede Entscheidung ein eigenes, schlankes Dokument.

Dadurch wird jede Entscheidung einzeln auffindbar, nachvollziehbar und überprüfbar. In der Praxis werden ADRs typischerweise als Markdown-Dateien in einem docs/adr/-Verzeichnis im Git-Repository abgelegt. Tools wie adr-tools von Nat Pryce automatisieren die Erstellung und Nummerierung. Das ADR-Format hat die Art verändert, wie Entwicklungsteams über Architekturentscheidungen nachdenken - weg vom monolithischen Architekturdokument, hin zu diskreten, versionierten Entscheidungseinheiten.

Geschichte und klassisches Format

Vor ADRs dokumentierten Teams Architekturentscheidungen in umfangreichen Dokumenten, die selten aktualisiert wurden und schnell veralteten. Nygards Durchbruch bestand darin, das Granularitätsproblem zu lösen: Eine Entscheidung, ein Dokument. Diese Idee verbreitete sich über ThoughtWorks, wurde von der agilen Community aufgegriffen und ist heute Standard in vielen Unternehmen von Startups bis zu DAX-Konzernen.

Ein ADR nach Nygard besteht aus fünf klar definierten Abschnitten:

Dieses Format ist bewährt und einfach. Genau darin liegt seine Stärke - und seine Grenze. Denn ein ADR in Markdown ist eine statische Datei. Es gibt kein Verfallsdatum, keine automatische Erinnerung, keinen Abhängigkeitsgraphen. Die Entscheidung wird dokumentiert, aber nicht verwaltet.

Die Grenzen von Markdown-basierten ADRs

Markdown-ADRs funktionieren gut in kleinen Teams mit wenigen Entscheidungen. Aber ab einer gewissen Größenordnung stoßen sie an ihre Grenzen, die den ursprünglichen Nutzen untergraben:

• Kein Health Score: Es gibt keinen Mechanismus, der anzeigt, ob eine Entscheidung noch aktuell ist. Ein ADR von 2019 sieht genauso aus wie einer von gestern - obwohl sich die Welt grundlegend verändert hat.
• Kein Abhängigkeitsgraph: Welche Entscheidungen hängen voneinander ab? In Markdown müssen Sie das manuell durch Links abbilden - und diese Links veralten, wenn Dateien umbenannt oder verschoben werden.
• Keine Review-Erinnerungen: Niemand wird automatisch daran erinnert, eine Entscheidung zu überprüfen. Reviews passieren nur, wenn jemand zufällig daran denkt oder beim Durchblättern stolpert.
• Nur für Entwickler zugänglich: ADRs im Git-Repo sind für Produktmanager, Geschäftsführung und QM-Teams unsichtbar. Business-Entscheidungen werden dort nicht dokumentiert.
• Keine KI-Unterstützung: Jedes ADR muss manuell verfasst werden. Bei fünf Entscheidungen pro Woche wird das schnell zum Engpass, der dazu führt, dass Entscheidungen undokumentiert bleiben.

Diese Grenzen bedeuten nicht, dass ADRs schlecht sind - im Gegenteil. Das Prinzip ist exzellent. Aber das Medium (statische Dateien) wird dem Prinzip nicht gerecht. Entscheidungen brauchen eine aktive Verwaltung, nicht nur passive Speicherung. Das ist der Kern von Decision Decay: Ohne aktive Pflege zerfällt der Kontext.

Von der Datei zur Plattform: ContextDecay erweitert ADRs

ContextDecay übernimmt die bewährte Struktur von ADRs - Kontext, Entscheidung, Konsequenzen - und erweitert sie um die fehlenden Dimensionen:

• Health Score: Jede Entscheidung erhält einen Score von 0 bis 100, der über die Zeit abnimmt. Faktoren: Alter, letzter Review, Abhängigkeitsänderungen, Teamfeedback.
• Dependency Graph: Verknüpfen Sie Entscheidungen miteinander. Wenn sich eine ändert, sehen Sie sofort den Impact auf abhängige Beschlüsse.
• Automatische Reviews: Review-Intervalle pro Entscheidung. Bei Fälligkeit erhalten die Verantwortlichen eine Benachrichtigung per E-Mail oder Teams/Slack.
• KI-Erfassung: Entscheidungen aus Meeting-Protokollen, E-Mails oder Jira-Tickets automatisch extrahieren.
• Für die ganze Organisation: Nicht nur für Entwickler, sondern für alle Abteilungen - von IT über QM bis zur Geschäftsführung.

Wenn Sie bereits ADRs nutzen, können Sie Ihre bestehenden Records in ContextDecay importieren und sofort von Health Scores und Review-Workflows profitieren. Wenn Sie noch keine ADRs nutzen, ist ContextDecay der einfachste Einstieg - dank KI-Erfassung ohne manuelle Template-Pflege. Alle Details zu den Funktionen finden Sie auf unserer Seite zu Paketen und Preisen.

ADRs für die gesamte Organisation

Die größte Limitation klassischer ADRs ist ihr enger Fokus auf Architekturentscheidungen. Aber Organisationen treffen täglich Entscheidungen auf allen Ebenen: strategische Beschlüsse der Geschäftsführung, Prozessentscheidungen im Qualitätsmanagement, Vendor-Auswahl im Einkauf, Personalentscheidungen in HR. All diese Entscheidungen unterliegen demselben Problem: Decision Decay.

ContextDecay nimmt das bewährte ADR-Prinzip - eine Entscheidung, ein Dokument, mit Kontext und Konsequenzen - und macht es zugänglich für jeden Bereich. Die IT-Leitung dokumentiert Technologie-Entscheidungen, das QM-Team hält Prozessänderungen fest, und die Geschäftsführung verfolgt strategische Beschlüsse - alles in einer Plattform mit einheitlichen Health Scores und Workflows. Weitere Praxistipps finden Sie in unseren 7 Best Practices für Entscheidungsmanagement.