Architekturentscheidungen als ADRs festhalten: mit KI-Unterstützung und ohne Pflegeschuld

Eine Entwicklerin schlägt im Chat vor, die Nachrichtenwarteschlange zu wechseln. Zwei Kollegen stimmen zu, ein Ticket entsteht, der Code ändert sich. Ein Jahr später fragt ein neues Teammitglied, warum hier nicht das Produkt läuft, das der Rest der Organisation nutzt. Niemand weiß es mehr genau. Der Chat ist archiviert, das Ticket enthält nur den Arbeitsauftrag, und die Person, die damals den Ausschlag gab, hat die Firma verlassen.

Solche Szenen sind der Normalfall, nicht die Ausnahme. Architekturentscheidungen entstehen im Alltag: in Besprechungen, in Kommentaren zu Codeänderungen, in Chats. Was fehlt, ist der Ort, an dem Kontext und Begründung landen. Architecture Decision Records, kurz ADRs, sind ein etabliertes Mittel dafür. Diese Anleitung beschreibt, wie man sie als Markdown-Dateien im Repository führt, wie Sprachmodelle beim Entwurf helfen und wie man vermeidet, dass daraus eine weitere Dokumentation entsteht, die nach einem halben Jahr niemand mehr pflegt.

Das Problem: Entscheidungen gehen verloren

Michael Nygard hat das Muster 2011 in einem Blogbeitrag beschrieben, der bis heute als Ursprung der ADR-Idee gilt. Seine Beobachtung: Große Architekturdokumente lösen das Problem nicht, denn "Nobody ever reads large documents, either." Sie werden einmal geschrieben, selten gelesen und veralten, weil jede Änderung am System eine manuelle Änderung am Dokument verlangt.

Nygard nennt zwei typische Reaktionen, wenn Begründungen fehlen. Entweder akzeptiert das Team eine Entscheidung blind, obwohl die Umstände sich geändert haben. Oder es ändert sie blind, ohne zu verstehen, welches Problem sie ursprünglich gelöst hat. Beides kostet, nur zu unterschiedlichen Zeitpunkten.

Das Institut für Wirtschaftsinformatik der JKU Linz hält in einer Projektbeschreibung fest, dass das Aktuellhalten von Dokumentation weiterhin zu den Herausforderungen zählt und ADRs noch immer manuell erstellt werden müssen. Genau an dieser Stelle setzt die Unterstützung durch Sprachmodelle an: nicht beim Entscheiden, sondern beim Aufschreiben.

Was ein ADR leisten soll

Das MADR-Projekt definiert eine Architekturentscheidung als "a justified software design choice that addresses a functional or non-functional requirement of architectural significance". Zwei Wörter sind hier wichtig: begründet und bedeutsam. Ein ADR hält genau eine Entscheidung fest und erklärt, warum sie so getroffen wurde.

Nygards Minimalform umfasst fünf Abschnitte: Titel, Status, Kontext, Entscheidung und Konsequenzen. Das ganze Dokument soll laut Nygard ein bis zwei Seiten lang sein. Die MADR-Vorlage, aktuell in Version 4.0.0 vom 17. September 2024, erweitert das um Entscheidungstreiber, betrachtete Optionen und deren Vor- und Nachteile. In der Praxis bewährt sich diese erweiterte Form, weil sie das Team zwingt, Alternativen überhaupt zu benennen.

Nicht jede Entscheidung braucht ein Record. Prüfen Sie mit drei Fragen, ob eine Entscheidung architektonisch bedeutsam ist:

• Betrifft sie die Struktur des Systems, also Schnitte, Schnittstellen, Datenflüsse?
• Beeinflusst sie ein zentrales Qualitätsmerkmal wie Sicherheit, Verfügbarkeit, Wartbarkeit oder Kosten?
• Ist sie schwer umkehrbar, weil Daten migriert, Verträge geschlossen oder mehrere Teams umgestellt werden müssten?

Trifft mindestens eine Frage zu, schreiben Sie ein ADR. Trifft keine zu, reicht ein Kommentar im Code oder im Ticket.

Ablage im Repository, versioniert mit dem Code

Das Repository ist der Ort, an dem der Quellcode mit seiner Änderungshistorie liegt. ADRs gehören dorthin, weil sie dann denselben Prüf- und Freigabeweg durchlaufen wie der Code selbst. Die JKU Linz beschreibt ADRs entsprechend als Markdown-Dateien mit vordefinierter Struktur, die als Teil des Repositorys abgelegt und mit dem Code verwaltet werden.

So richten Sie die Ablage ein:

1. Legen Sie einen festen Ordner an, zum Beispiel docs/adr/. Ein Ordner pro Repository, nicht pro Team.
2. Nummerieren Sie die Dateien fortlaufend: 0001-postgresql-als-primaere-datenbank.md, 0002-ereignisse-ueber-message-queue.md. Eine Nummer wird nie wiederverwendet.
3. Legen Sie eine Vorlage als 0000-vorlage.md ab, damit niemand die Struktur erfinden muss.
4. Führen Sie jedes ADR über einen Pull Request ein, also den üblichen Vorschlag einer Codeänderung, den andere prüfen und freigeben, bevor er übernommen wird. Idealerweise im selben Pull Request wie der Code, der die Entscheidung umsetzt.
5. Pflegen Sie eine Indexdatei README.md im Ordner, die Nummer, Titel und Status jedes Records auflistet. Diese Liste kann ein kleines Skript erzeugen.

Ein Grundprinzip ist entscheidend: Records werden nicht überschrieben. Das Azure Well-Architected Framework formuliert es so: "The ADR serves as an append-only log. Don't go back and edit accepted records. If a decision changes, write a new record that supersedes the original and link the two together." Der Status macht den aktuellen Stand sichtbar: Vorgeschlagen, Akzeptiert, Ersetzt durch ADR-NNNN, Verworfen.

KI-Unterstützung: Entwurf, Alternativen, Lücken

Ein Sprachmodell, oft als LLM für Large Language Model bezeichnet, erzeugt aus einer Texteingabe einen Text als Ausgabe. Für ADRs ist das nützlich, weil der Rohstoff einer Entscheidung meist schon als Text vorliegt, nur verstreut: in Chatverläufen, Besprechungsnotizen, Tickets, Kommentaren. In der Praxis bewähren sich drei Einsätze.

Entwurf aus Rohmaterial. Kopieren Sie den relevanten Chatverlauf, das Ticket und Ihre Notizen in eine Anfrage und lassen Sie das Modell daraus einen Entwurf in Ihrer Vorlage erstellen. Eine brauchbare Anweisung lautet: "Erstelle aus den folgenden Notizen ein ADR nach der beigefügten Vorlage. Erfinde keine Fakten. Wo Informationen fehlen, schreibe in eckigen Klammern OFFEN und nenne, was fehlt." Der letzte Satz ist wichtig. Ohne ihn füllt das Modell Lücken mit plausibel klingenden Annahmen.

Alternativenvergleich. Lassen Sie das Modell die betrachteten Optionen mit Vor- und Nachteilen in Bezug auf Ihre Entscheidungstreiber auflisten. Das Ergebnis ist eine Diskussionsgrundlage, kein Urteil. Das Team ergänzt Optionen, die fehlen, streicht Argumente, die für den eigenen Kontext nicht zutreffen, und korrigiert Behauptungen über Produkte, die das Modell aus veraltetem Wissen zieht.

Lückenerkennung. Geben Sie dem Modell den fertigen Entwurf und bitten Sie es um Rückfragen: Welche Annahmen sind nicht benannt? Welche Konsequenzen fehlen? Unter welchen Bedingungen müsste die Entscheidung zurückgenommen werden? Wer ist betroffen, wird aber nicht erwähnt? Diese Fragen beantwortet ein Modell in der Regel brauchbar, weil sie strukturell sind und kein Wissen über das konkrete System erfordern.

Die Grenze ist empirisch belegt. Dhar, Vaidhyanathan und Varma haben 2024 in einer explorativen Studie untersucht, ob Sprachmodelle Architekturentscheidungen generieren können. Ihr Befund: Modelle wie GPT-4 erzeugen relevante und zutreffende Designentscheidungen, die aber "fall short of human-level performance". Weitere Forschung sei nötig, um menschliches Niveau zu erreichen.

Zwei Einschränkungen gehören dazu. Erstens ist die Studie vom März 2024, und Modelle haben sich seitdem weiterentwickelt; die konkrete Qualitätslücke von damals ist eine Momentaufnahme, nicht ein Naturgesetz. Zweitens gilt das auch für diese Anleitung: Die Aufteilung, welche Arbeit man dem Modell gibt und welche man selbst behält, verschiebt sich mit jeder Modellgeneration. Was daraus folgt, ist nicht Abwarten, sondern eine Prozessregel, die von der Modellqualität unabhängig ist: Der Entwurf eines Modells ist eine Vorlage für die Prüfung, kein Ergebnis. Diese Regel bleibt sinnvoll, auch wenn die Entwürfe besser werden, weil sie die Verantwortung festlegt und nicht die Fähigkeit.

Verantwortung bleibt beim Team

Ein ADR dokumentiert eine Entscheidung, die Menschen getroffen haben und vertreten. Damit das auch bei KI-Entwürfen klar bleibt, helfen drei Regeln.

Erstens: Jedes ADR nennt eine verantwortliche Person oder ein Gremium sowie die Beteiligten. Wer die Entscheidung trägt, steht im Record, nicht nur in der Commit-Historie.

Zweitens: Ein KI-Entwurf hat den Status Vorgeschlagen und bleibt dort, bis Menschen ihn geprüft und übernommen haben. Die Ausgabe eines Modells ist kein Beschluss. Erst die Freigabe im Pull Request durch die benannten Verantwortlichen setzt den Status auf Akzeptiert.

Drittens: Kennzeichnen Sie die Herkunft. Ein kurzer Vermerk am Ende des Records genügt, etwa: "Entwurf durch Sprachmodell aus Ticket 4711 und Chatverlauf vom 12.03., geprüft und ergänzt durch M. Berger und T. Nowak." Spätere Leser können so einordnen, wie der Text entstanden ist, und wissen, an wen sie sich bei Rückfragen wenden.

Das Azure Well-Architected Framework ergänzt einen Punkt, der bei KI-Entwürfen besonders leicht verloren geht: "Always include context and rationale. A record without justification loses its value over time." Ein Modell kann Kontext nur aus dem ableiten, was man ihm gibt. Fehlt die Begründung im Rohmaterial, fehlt sie auch im Entwurf, oder schlimmer, sie wird erfunden. Die Prüfung muss deshalb immer die Frage stellen: Steht hier wirklich, warum das Team so entschieden hat?

Ohne Pflegeschuld arbeiten

Pflegeschuld entsteht, wenn Dokumentation Arbeit verlangt, die niemand eingeplant hat. ADRs vermeiden das durch vier Entscheidungen, die man bewusst treffen sollte.

Kein Nachpflegen des Bestands. Beginnen Sie mit der nächsten Entscheidung, die ohnehin anliegt. Den Altbestand zu rekonstruieren ist verlockend, aber teuer und oft spekulativ. Wenn ein altes Thema wieder aufkommt, weil es geändert werden soll, schreiben Sie dann ein ADR, das den bisherigen Stand als Kontext beschreibt.

Ersetzen statt Ändern. Ein veraltetes ADR ist kein Pflegefall. Es bekommt den Status Ersetzt und einen Verweis auf das neue Record. Das alte bleibt stehen, weil es erklärt, warum das System eine Zeit lang so aussah, wie es aussah. Niemand muss alte Texte auf Aktualität prüfen.

Erstellung im gewohnten Workflow. Der KI-Entwurf landet direkt im Pull Request, zusammen mit dem Code. Die Prüfung findet dort statt, wo das Team ohnehin prüft. Ein separates Dokumentationswerkzeug mit eigenem Login und eigener Freigabe schafft einen zweiten Prüfweg, den in der Praxis kaum jemand geht.

Keine Design-Leitfäden. Das Azure Well-Architected Framework rät ausdrücklich: "Avoid making decision records design guides." Ein ADR beschreibt die Entscheidung, nicht die Anleitung zur Umsetzung. Ergänzende Dokumente werden verlinkt, aber das Record muss ohne sie verständlich bleiben. Sonst veraltet es mit jedem verlinkten Dokument mit.

Einführung in vier Schritten

1. Vorlage festlegen. Nehmen Sie die MADR-Struktur oder Nygards Minimalform und passen Sie sie einmal an. Ergänzen Sie Felder für Verantwortliche und Herkunft. Danach ändern Sie die Vorlage ein Jahr lang nicht.
2. Erste drei Entscheidungen. Wählen Sie Entscheidungen, die im kommenden Monat ohnehin anstehen. Lassen Sie den Entwurf vom Sprachmodell erstellen, prüfen Sie ihn gemeinsam und reichen Sie ihn per Pull Request ein.
3. Rückfragen-Prompt standardisieren. Hinterlegen Sie die Anweisung zur Lückenerkennung im Repository, damit jedes Teammitglied dieselben Prüffragen stellt. Prüfen Sie den Prompt bei jedem Modellwechsel neu, denn was ein Modell von sich aus leistet, ändert sich schneller als die Vorlage.
4. Nach drei Monaten bewerten. Prüfen Sie, ob die Records gelesen werden, ob neue Teammitglieder sie finden und ob die Prüfung im Pull Request tatsächlich stattfindet oder nur abgenickt wird.

Anhang: Vorlage und Beispiel

Die Vorlage orientiert sich an MADR und ergänzt die Felder für Verantwortung und Herkunft:

ADR-NNNN: Titel als Aussage

Status: Vorgeschlagen | Akzeptiert | Ersetzt durch ADR-NNNN | Verworfen
Datum: JJJJ-MM-TT
Verantwortlich: Name oder Gremium
Beteiligt: Namen

## Kontext und Problemstellung
Was ist die Situation, welches Problem muss gelöst werden?

## Entscheidungstreiber
- Treiber 1 (zum Beispiel Betriebskosten, vorhandenes Wissen im Team)
- Treiber 2

## Betrachtete Optionen
- Option A
- Option B

## Entscheidung
Gewählt wurde Option A, weil ...

## Konsequenzen
- Positiv: ...
- Negativ: ...
- Rücknahmebedingung: Wenn ..., ist die Entscheidung zu prüfen.

## Vor- und Nachteile der Optionen
Je Option: gut, weil ... / schlecht, weil ...

## Herkunft
Entwurf durch Sprachmodell aus ..., geprüft durch ...

Ein verkürztes Beispiel zeigt, wie knapp ein Record sein kann:

ADR-0007: Ereignisse zwischen Diensten über die bestehende Message-Queue statt direkter HTTP-Aufrufe

Status: Akzeptiert
Datum: 2026-10-14
Verantwortlich: Architekturrunde Plattform
Beteiligt: M. Berger, T. Nowak, S. Yilmaz

## Kontext und Problemstellung
Drei Dienste rufen sich gegenseitig synchron auf. Fällt einer aus, blockieren die anderen. Die Bestellabwicklung war im September zweimal betroffen.

## Entscheidungstreiber
- Ausfallsicherheit der Bestellabwicklung
- Vorhandenes Betriebswissen für die Queue im Team
- Keine zusätzliche Infrastruktur

## Betrachtete Optionen
- Direkte HTTP-Aufrufe mit Retry-Logik beibehalten
- Ereignisse über die bereits betriebene Queue
- Neue Streaming-Plattform einführen

## Entscheidung
Ereignisse über die bestehende Queue. Sie läuft bereits, das Team kennt den Betrieb, und die Entkopplung löst das Blockierungsproblem.

## Konsequenzen
- Positiv: Dienste bleiben bei Ausfall eines Nachbarn arbeitsfähig.
- Negativ: Daten sind zwischen den Diensten nur verzögert konsistent (Eventual Consistency); die Reihenfolge der Ereignisse muss im Konsumenten behandelt werden.
- Rücknahmebedingung: Wenn der Durchsatz die Kapazität der Queue dauerhaft übersteigt, ist die Einführung einer Streaming-Plattform neu zu bewerten.

## Herkunft
Entwurf durch Sprachmodell aus Ticket PLT-412 und Chatverlauf vom 09.10., geprüft und um die Streaming-Option ergänzt durch M. Berger.

Was bleibt

Die Arbeitsteilung ist einfach zu beschreiben: Das Sprachmodell strukturiert, vergleicht und fragt nach. Das Team entscheidet, prüft und verantwortet. Das Repository hält fest, was entschieden wurde und warum, in derselben Historie wie der Code. Veraltung wird nicht bekämpft, sondern durch neue Records abgelöst.

Offen bleibt, was die genutzten Quellen nicht belegen: wie viel Zeit die KI-Unterstützung im konkreten Team spart und ob die Records tatsächlich gelesen werden, wenn es darauf ankommt. Beides lässt sich nur in der eigenen Organisation prüfen. Und die Grenze zwischen dem, was man dem Modell überlässt, und dem, was man selbst schreibt, wird sich verschieben; diese Anleitung ist eine Zeitaufnahme vom Oktober 2026. Was bleiben sollte, ist der Teil, der nicht von der Modellqualität abhängt: eine Vorlage, ein Ordner im Repository, ein benannter Verantwortlicher und die nächste Entscheidung, die ohnehin getroffen werden muss.