Viele technische Entscheidungen sind im Code sichtbar. Ihre Gründe sind es nicht. Ein Repository zeigt, dass PostgreSQL verwendet wird, eine Anwendung serverseitig läuft oder ein bestimmter Authentifizierungsdienst angebunden ist. Es erklärt selten, welche Alternativen geprüft wurden, welche Einschränkungen bestanden und unter welchen Bedingungen die Entscheidung neu bewertet werden sollte.
Menschen nennen das später „historisch gewachsen“. Eine KI nennt es möglicherweise „offensichtlich“ und erfindet eine plausible Begründung. Beides hilft nicht.
Architecture Decision Records, kurz ADRs, halten eine einzelne bedeutsame Entscheidung samt Kontext und Konsequenzen fest.
Was ein ADR beantwortet
Ein ADR sollte mindestens vier Fragen klären:
- Welches Problem oder welche Anforderung bestand?
- Welche Entscheidung wurde getroffen?
- Warum wurde diese Option gewählt?
- Welche Folgen und Kompromisse entstehen daraus?
Je nach Vorlage kommen Status, Datum, Alternativen, Beteiligte oder Bedingungen für eine Neubewertung hinzu. Entscheidend ist nicht die perfekte Schablone, sondern die nachvollziehbare Begründung.
Ein Satz wie „Wir verwenden Next.js“ ist keine vollständige Entscheidung. Ein ADR erklärt beispielsweise, dass serverseitiges Rendering, statische Inhaltsseiten, ein gemeinsames React-Komponentenmodell und ein Node.js-Betrieb benötigt werden – und dass dadurch zugleich eine Laufzeitumgebung sowie regelmäßige Framework-Aktualisierungen erforderlich sind.
Warum KI ohne ADRs raten muss
Ein Agent, der Code verändert, kann den aktuellen Zustand analysieren. Er kann aber nur begrenzt erkennen, welche Eigenschaften absichtlich sind.
Ohne Entscheidungskontext entstehen typische Fehlvorschläge:
- Eine Abhängigkeit wird entfernt, obwohl sie eine bewusst gewählte Betriebsanforderung erfüllt.
- Ein lokales Dateiformat wird durch eine bequemere Cloud-Datenbank ersetzt, obwohl Portabilität das Ziel war.
- Zwei scheinbar doppelte Systeme werden zusammengelegt, obwohl sie unterschiedliche Verantwortungen besitzen.
- Ein Sicherheitsmechanismus wird vereinfacht, weil seine ursprüngliche Bedrohung nicht dokumentiert ist.
- Eine frühere Alternative wird erneut vorgeschlagen, obwohl sie bereits aus guten Gründen verworfen wurde.
Der Code zeigt, was existiert. Das ADR erklärt, warum es existiert.
Eine einfache ADR-Struktur
Für viele Projekte reicht diese Form:
# ADR 0007: Markdown als kanonisches Inhaltsformat
- Status: Akzeptiert
- Datum: 2026-07-31
## Kontext
Welche Anforderungen, Einschränkungen und Kräfte wirken auf die Entscheidung?
## Entscheidung
Was wird verbindlich festgelegt?
## Konsequenzen
Welche positiven und negativen Folgen entstehen?
## Alternativen
Welche realistischen Optionen wurden geprüft und warum nicht gewählt?
Ein ADR sollte kurz genug bleiben, um gelesen zu werden. Es ist keine nachträgliche Doktorarbeit über jede Bibliothek im Projekt.
Welche Entscheidungen ein ADR verdienen
Nicht jede Änderung ist architektonisch bedeutsam. Ein ADR lohnt sich besonders, wenn eine Entscheidung:
- mehrere Komponenten oder Teams betrifft,
- schwer oder teuer rückgängig zu machen ist,
- Sicherheit, Datenschutz oder Betrieb verändert,
- einen dauerhaften Standard einführt,
- wiederholt diskutiert wird,
- einen bewussten Kompromiss enthält.
Die Farbe eines einzelnen Buttons gehört meist nicht hinein. Die Entscheidung für ein gemeinsames Designsystem möglicherweise schon.
Entscheidungen werden nicht überschrieben
Ein akzeptiertes ADR beschreibt den damaligen Beschluss. Ändert sich die Architektur, wird das alte Dokument nicht stillschweigend umgeschrieben. Ein neues ADR ersetzt oder verwirft die frühere Entscheidung und verweist darauf.
So bleibt die Geschichte nachvollziehbar:
- ADR 0003 wird akzeptiert.
- Neue Anforderungen entstehen.
- ADR 0011 ersetzt ADR 0003 mit begründetem neuen Beschluss.
- Beide Dokumente bleiben erhalten.
Für KI ist diese Kette wichtig. Sie erkennt nicht nur den aktuellen Stand, sondern auch, welche Annahmen sich verändert haben.
ADRs als Teil des Arbeitsablaufs
Ein pragmatischer Prozess sieht so aus:
- Eine bedeutsame offene Entscheidung wird erkannt.
- Kontext, Anforderungen und realistische Optionen werden gesammelt.
- Ein ADR-Entwurf macht die Abwägung sichtbar.
- Die zuständigen Personen entscheiden.
- Status und Konsequenzen werden aktualisiert.
- Code, Dokumentation und Aufgaben verweisen auf die Entscheidung.
- Bei veränderten Voraussetzungen entsteht ein neues ADR.
KI kann Optionen strukturieren, Widersprüche erkennen und Konsequenzen ergänzen. Sie sollte die Entscheidung nicht ohne Mandat treffen und keine nicht belegten Gründe in den historischen Kontext schreiben.
Ein guter Prompt beginnt mit den Entscheidungen
Bevor ein Agent einen größeren Umbau vorschlägt, sollte er die relevanten ADRs lesen. Ein sinnvoller Arbeitsauftrag lautet beispielsweise:
Prüfe zuerst alle akzeptierten ADRs zu Hosting, Authentifizierung und Datenhaltung. Schlage anschließend die kleinste Änderung vor, die das Problem löst, ohne diese Entscheidungen zu unterlaufen. Benenne ausdrücklich, wenn eine bestehende Entscheidung neu bewertet werden müsste.
Damit wird aus „Mach es irgendwie moderner“ eine kontrollierte technische Aufgabe.
Grenzen von ADRs
ADRs ersetzen weder aktuelle Betriebsdokumentation noch Aufgabenplanung. Sie sind auch kein Schutz gegen schlechte Entscheidungen. Ein hervorragend dokumentierter Irrtum bleibt ein Irrtum – lässt sich aber wenigstens gezielt korrigieren.
Problematisch werden ADRs, wenn:
- sie erst lange nach der Entscheidung geschrieben werden,
- nur die gewählte Option gelobt wird,
- Konsequenzen fehlen,
- ihr Status unklar bleibt,
- niemand sie bei späteren Änderungen liest.
Die Dokumente müssen in den tatsächlichen Arbeitsablauf eingebunden sein. Ein Ordner docs/adr, den Menschen und Agenten ignorieren, ist nur ordentlich abgelegte Reue.
Fazit
Architecture Decision Records bewahren nicht nur Beschlüsse, sondern deren Logik. Sie machen technische Systeme verständlicher, schützen bewusste Grenzen und verhindern, dass alte Diskussionen ohne neuen Anlass wiederholt werden.
Für KI schaffen ADRs einen seltenen, besonders wertvollen Kontext: nicht nur den sichtbaren Zustand, sondern die Gründe, Alternativen und Konsequenzen dahinter. Genau dort beginnt verantwortbare technische Assistenz.
