ADRs in Agentic Coding: Warum Entscheidungen zum Kontext werden müssen

Warum haben wir zwei CDK Constructs die fast identisch sind in unserer Codebase statt einem konfigurierbaren? Weshalb cachen wir diesen Aufruf nicht, obwohl wir andere cachen? Oder wieso liegt hinter dieser API nur eine Lambda statt mehreren getrennten? Genau hier werden Architecture Decision Records interessant. Ein Teammitglied kann so leichter nachvollziehen, ob und warum etwas entschieden wurde, auf welcher Basis und mit welchen Abwägungen. Und im Zusammenspiel mit KI-Agenten bekommen sie eine Funktion, die sie vorher nicht hatten. Ein Coding-Agent startet jede Session bei null. Er liest zwar den Code und leitet Muster ab, aber warum die Dinge so sind, wie sie sind, und ob dahinter eine bewusste Entscheidung steckt, weiß er nicht. Wenn ADRs dem Agenten zugänglich gemacht werden, können sie helfen, diese Lücke zu schließen.

Was ist überhaupt ein ADR?

Aber fangen wir mal vorne an. Ein ADR hält eine einzelne Architekturentscheidung fest. Das Format ist seit Jahren etabliert und besteht aus vier Teilen: dem Kontext (welches Problem stand an, welche Zwänge gab es), der Entscheidung (was wurde gewählt), den Konsequenzen (was folgt daraus, auch das Negative) und den geprüften Alternativen.

Ein ADR ist bestenfalls kurz - eine halbe Seite. Er wird nicht mehr geändert, sondern bei Bedarf durch einen neuen ADR ersetzt, der den alten als überholt markiert. So entsteht eine Chronik der Entscheidungen und auch das Revidieren oder Ändern früherer Entscheidungen bleibt nachvollziehbar. Hier ein Beispiel für einen ADR:

# ADR-0012: Eine Lambda für die Warenkorb-API

- Datum: 2026-02-08
- Beteiligte: @team

## Kontext
Die Warenkorb-API hat vier Operationen: Warenkorb anlegen,
abrufen, verändern und validieren. Sie arbeiten alle auf
derselben Ressource und werden meist in kurzer Folge
nacheinander aufgerufen.

## Entscheidung
Alle vier Operationen laufen in einer Lambda mit internem Routing.

## Konsequenzen
+ Ein warmer Container bedient die ganze Interaktion, statt
  dass vier Lambdas einzeln kalt starten.
- Gröberes IAM: die Lambda hat die Rechte aller vier Operationen.
  Akzeptiert, weil alle vier ohnehin auf dieselbe Tabelle zugreifen.

## Alternativen
- Vier getrennte Lambdas: verworfen wegen vierfacher Cold Starts
  und mehr Komplexität bei eng gekoppelten Operationen auf derselben Ressource.

Hier haben wir konkret und ohne großen Aufwand eine Entscheidung festgehalten, die dem sonst vorherrschenden Pattern im Projekt entgegensteht. Team und Agent können jetzt nachvollziehen, dass das bewusst so gemacht wurde, und warum. Im Review wird die Abweichung dann nicht fälschlich moniert, und bei ähnlichen Entscheidungen lässt sich prüfen, ob dieselben Kriterien zutreffen.

Der Unterschied bei Agentic-Coding

Für ein menschliches Team ist ein ADR Dokumentation. Man schaut nach, wenn man eine alte Entscheidung hinterfragt oder der typischen "Hä? Soll das wirklich so sein?"-Frage nachgeht, die man sich als Entwickler immer mal wieder stellt, wenn man an bestehendem oder länger nicht angefasstem Code arbeitet.

Für einen Agenten ist ein ADR zweierlei: maschinenlesbarer Kontext und eine Leitplanke.

Ohne diesen Kontext steigt die Wahrscheinlichkeit, dass der Agent die Architektur neu erfindet oder fälschlich umbaut. Du bittest um ein Feature, und er führt dir die beiden fast identischen CDK Constructs aus einem gut gemeinten DRY-Reflex zu einem zusammen, weil er den Grund für die Trennung nicht kennt. Bei Entscheidungen mit größerer Tragweite als einem einzelnen Feature kommt hinzu, dass du immer wieder erklären und gegensteuern musst, weil der Agent es intuitiv anders machen würde und die ursprüngliche Entscheidung nicht mehr im Kontext steht. Die Rationale ist dabei der Teil, der zählt. Im Code steht das Was. Das Warum ist unsichtbar. Genau das hält ein ADR fest. Besonders der Abschnitt "geprüfte Alternativen" ist hilfreich: Er zeigt dem Agenten den Negativraum, also was du verworfen hast und warum. Steht das im ADR, bringt der Agent die verworfene Option nicht als kreativen Vorschlag zurück.

Wie man ADRs für und mit Agenten schreibt, ohne den Developer zu verlieren

Ein guter ADR bedient beide Leser zugleich. Für beide zählt die knappe Begründung und der Negativraum. Auch ein fester Aufbau und ein klar benanntes "verworfen, weil" helfen bei Erstellung und Nachvollziehbarkeit. Ein ADR, den ein Agent sauber verwerten kann, ist also fast immer auch der, den ein Mensch in kurzer Zeit versteht.

Beim Schreiben kann es ebenfalls Hand-in-Hand gehen. Der Agent kann einen Entwurf machen, Kontext, Entscheidung, Konsequenzen und Alternativen aus der gerade geführten Diskussion ableiten, und du bleibst als Human-in-the-loop, der prüft und wie gewohnt freigibt. Das lässt sich auch sauber in die Planungsphase einhängen: Sobald im Gespräch eine tragende Entscheidung fällt, schlägt der Agent einen ADR vor und klärt die Details.

Auch bei der Recherche lassen sich Kräfte bündeln. Du musst einen ADR nicht zwingend suchen, um Code zu verstehen. Eine Frage wie "finde raus, warum xy so ist, wie es ist" reicht, und der Agent zieht den passenden ADR, ergänzt ihn um Commit-Messages und verlinkte Issues und ordnet das Ganze ein. So profitieren beide Seiten vom selben Artefakt: der Agent als Leitplanke beim Bauen, und du als Mensch, der eine alte Entscheidung dank der Aufbereitung durch den Agenten viel schneller versteht. Und weil der Agent seine Antwort auf einen realen ADR stützt, statt sie sich zur Frage passend auszudenken, sinkt zugleich das Halluzinationsrisiko.

ADRs in den Workflow des Agenten verdrahten

Was wir nicht wollen, ist einfach ein Verzeichnis voller Markdown-Dateien, und auch keine neue Daueraufgabe, den Agenten regelmäßig anzuweisen, ADRs zu verfassen. Ein kurzer Abschnitt in der CLAUDE.md oder AGENTS.md, der dem Agent sagt, wie er mit den ADRs umgeht, automatisiert das Ganze. Bei mir sieht das beispielsweise oft so aus:

## Architectural Decision Records

This repo uses ADRs to capture non-trivial architectural and design
decisions. See [`docs/adr/README.md`](docs/adr/README.md) for the full
policy; this section is the short version for agents.

### Before making non-trivial changes

- Read [`docs/adr/README.md`](docs/adr/README.md) (index of existing ADRs).
- Read any ADR that could plausibly constrain or inform the task - in
  particular before removing features, changing emitter architecture,
  picking a library, or altering release/versioning behavior.
- If a change contradicts an existing ADR, **stop and raise it
  explicitly** with the user before proceeding. Do not silently
  contradict a recorded decision.

### When a new ADR is warranted

Draft one when **any** of the following apply:

- A feature or API is being deliberately **removed** or deprecated
- A **viable alternative** was seriously considered before picking the
  chosen approach
- A **stack, library, or runtime** is being adopted or dropped
- A **convention** is being established (e.g. "from now on, all emitters
  use X")
- A **release or versioning strategy** is being decided
- A decision runs counter to what a reader would naively expect and
  needs rationale

Do **not** write an ADR for bugfixes, behavior-preserving refactorings,
or implementation details with obvious rationale.

Heuristic: _Would a new contributor in six months want to revert this
decision without knowing the history?_ If yes, ADR.

### Workflow

1. When a trigger fires, **ask the user explicitly** before drafting:
   "This looks ADR-worthy - should I draft one?" Do not write ADRs
   unprompted.
2. If the user agrees, draft the ADR in the same PR as the code change.
   The ADR and the change belong together.
3. Number: the next free integer (`ls docs/adr | sort | tail -1`, then
   +1). Four-digit zero-padded, kebab-case title.
4. Use [`docs/adr/template.md`](docs/adr/template.md). Keep it short -
   half a page. **No `Status:` field** - Git tracks that.
5. Update the index in [`docs/adr/README.md`](docs/adr/README.md) with
   a one-line entry.
6. If the new ADR supersedes an existing one: add a banner at the top
   of the old ADR (`⚠️ Superseded by [ADR-XXXX](...) on YYYY-MM-DD -
   short reason.`). Never delete old ADRs.

### What not to do

- Do not write ADRs retroactively for decisions that were never
  actually weighed (i.e. no alternative was considered).
- Do not write ADRs to document implementation details ("we used a
  `Map` here"). That is what the code is for.
- Do not let the ADR index grow stale - if you add an ADR file, update
  `docs/adr/README.md` in the same commit.

Drei Regeln tragen das Meiste:

Vor nicht-trivialen Änderungen lesen. Der Agent öffnet den ADR-Index, bevor er Features entfernt, eine Library wählt oder die Architektur anfasst, und liest jeden Record, der die Aufgabe einschränken könnte.

Bei Widerspruch stoppen. Wenn eine Änderung einem bestehenden ADR widerspricht, hält der Agent an und legt es dir offen vor, statt die Entscheidung still zu überschreiben. Das ist die Leitplanke in Aktion.

Neue ADRs nur nach Rückfrage. Wenn ein Trigger feuert (eine Entscheidung mit echten Alternativen, ein Konventionswechsel, ein Library-Wechsel), fragt der Agent "Das sieht ADR-würdig aus, soll ich einen entwerfen?", statt ungefragt loszuschreiben. Das verhindert ADR-Spam für Bugfixes und triviale Refactorings.

Dazu zwei Hygiene-Punkte, die sich bewähren: der ADR gehört in denselben PR wie die Codeänderung, und der Index wird im selben Commit aktualisiert. Sonst veraltet er, und ein veralteter Index ist schlimmer als keiner.

ADRs, Specs und Issues im Zusammenspiel

In der Praxis nutze ich ADRs nicht für sich allein, sondern zusammen mit Designspecs und GitHub-Issues. Die drei haben unterschiedliche Aufgaben. Das Issue beschreibt, was zu tun ist, und hält die Diskussion fest. Die Designspec ist der Ort, an dem ein Entwurf ausgearbeitet wird, bevor Code entsteht. Der ADR ist das destillierte Ergebnis: die getroffene Entscheidung mit Begründung und Alternativen, und er wird mit eingecheckt.

Nachvollziehbarkeit und die Ergebnisse des Agenten haben sich dadurch für mich deutlich verbessert. Der Agent macht weniger Quatsch, weil er an jeder Stelle den passenden Kontext zieht. Und ich muss mich weniger wiederholen, und die Richtung wird besser getroffen, weil der Agent mehr Kontext zur Verfügung hat. Das Issue beschreibt das zu lösende Problem, die Spec enthält den Plan für die Umsetzung, und ADRs dienen als Leitplanken beim Bauen.

Fazit

ADRs lösen für Agenten letztendlich dasselbe Problem wie für Teams. Ein Mensch vergisst Entscheidungen über Monate, ein Agent über die Session-Grenze. Der Unterschied liegt nicht im Format, sondern in der Verdrahtung: ein ADR-Verzeichnis plus ein paar Zeilen in der CLAUDE.md, die den Agent zwingen, vor dem Ändern zu lesen und bei Widerspruch nachzufragen. Der Aufwand ist gering. Ein ADR ist schnell geschrieben, und die Entscheidung hast du ohnehin schon getroffen. Du hältst sie nur fest, bevor der Kontext verloren geht, und gibst dem Agent damit eine weitere Quelle der Wahrheit, die über die Session hinaus Bestand hat.