Architecture Decision Records für Coding Agents: Warum der Agent das Warum braucht

Ein Satz wie „Lies vor Architekturänderungen docs/adr/“ klingt in einer Regeldatei nach einer Vorschrift, ist aber eine Bitte. Laut der Claude-Code-Dokumentation zu CLAUDE.md und Memory behandelt der Agent diese Dateien „as context, not enforced configuration“. Eine AGENTS.md, die nur im Fließtext erwähnt wird, liest er laut Doku erst, wenn er sie von sich aus öffnet. Für docs/adr/ dürfte dasselbe gelten. Das Modell entscheidet also, ob es vor einer Änderung docs/adr/ liest. Wer eine Aktion unabhängig davon blockieren will, braucht laut Doku einen PreToolUse-Hook.

Wie das ausgehen kann, zeigt ein öffentlich dokumentierter Einzelfall. Im Claude-Code-Issue #69455 vom 18. Juni 2026 beschreibt ein Nutzer ein Projekt, dessen große CSV-Uploads laut PROJECT_LOG.md und Memory-Datei über Cloudflare R2 laufen sollten. Laut Issue baute der Agent ein Inline-Feld csv_text ein, laut Codekommentar für die lokale Entwicklung. Das Feld war aber ungeschützt auch in Produktion aktiv und machte den R2-Lesepfad dort zu totem Code. Aufgefallen ist das dem Nutzer erst, als sich im Bucket CSV-Dateien stapelten, während die Builds durchliefen.

Dahinter steckt ein strukturelles Problem: Eine Regeldatei soll knapp sagen, was gilt. Für das Warum und für die Frage, ob eine Regel noch gilt, fehlt ihr der Platz. Dieser Beitrag schlägt deshalb drei Bausteine vor: eine Indexzeile in der Regeldatei, einen ADR mit lesbarem Status und für harte Entscheidungen einen Architekturtest. Eine Garantie für Architekturtreue ist auch das nicht. Den Gesamtrahmen zeigt der Überblick über Regeln, Kontext und Prüfungen für Coding Agents.

Ein ADR hält fest, warum eine Entscheidung gilt

Ein Architecture Decision Record (ADR) ist ein kurzes Dokument, das genau eine Architekturentscheidung samt Begründung festhält. So beschreiben ihn Martin Fowler im Bliki und adr.github.io, wo die Entscheidung selbst als „justified design choice“ gilt. Das Format geht auf Michael Nygards Artikel von 2011 zurück: Titel, Kontext, Entscheidung, Status, Konsequenzen. Als Status sieht Nygard proposed und accepted vor. Kehrt eine spätere Entscheidung die frühere um, wird der alte ADR deprecated oder superseded und verweist auf den Nachfolger.

MADR 4 führt den Status optional im YAML-Frontmatter, neben date und decision-makers. Das Feld status zeigt dem Agenten, ob die Entscheidung noch gilt. Die Begründung im Text erklärt, warum das Team diese Grenze gewählt hat. arc42 empfiehlt in Abschnitt 9 für wichtige Entscheidungen ADRs oder eine Tabelle. Fowler rät, ADRs im Quellcode-Repository abzulegen, ganz im Sinne von Docs as Code. Er ergänzt eine Regel: Ein akzeptierter ADR bleibt unverändert, eine neue Entscheidung bekommt einen eigenen ADR. Die Statuswerte sind nicht einheitlich. MADR kennt etwa zusätzlich rejected. Wie sich ADRs zu Specs verhalten, steht im Beitrag zu Spec-Driven Development und Team-Governance.

CLAUDE.md, AGENTS.md, ADR, Test: wer dem Agenten was sagt

Die zentrale CLAUDE.md im Projektverzeichnis wird bei jedem Start geladen und muss deshalb knapp bleiben (warum, steht im Beitrag zu Context Engineering für Coding Agents). Für ADR-0007 reicht dort eine Zeile: Controller greifen nur über Services auf Daten zu, Begründung in docs/adr/0007-schichten.md. Der ADR liefert Begründung und Status. Gebraucht wird er erst, wenn der Agent in src/**/controller/** arbeitet. Der Test prüft die Regel, gleich was der Agent vorher gelesen hat.

Für die Abgrenzung zwischen ADR und RFC gibt es keine kanonische Definition. In vielen Teams gilt die Konvention aus der Engineering-Doku der Wellcome Collection: Ein RFC ist spekulativ und wägt Optionen ab, ein ADR beschreibt die aktuelle Umsetzung und wird ersetzt, sobald sich etwas ändert. Bei Nygard und Fowler kann allerdings auch ein ADR mit Status proposed noch zur Diskussion stehen.

Nur die unterste Schicht prüft im Build, ob die Regel eingehalten wird.

Manfred Steyer hat ADRs als Agentenkontext angesprochen. In „KI-gestütztes Coding: Architektur als ausführbarer Vertrag“ schreibt er, sämtliche ADRs permanent mitzuliefern ginge „auf Kosten von Übersicht und Tokenbudget“. Er leitet daraus knappe Regeln mit Rückverweis ab und prüft sie mit Sheriff und einem Stop-Hook. Was mit ersetzten Entscheidungen geschieht, behandelt er nicht.

Index und Pfadregel führen zum passenden ADR

ADRs per @docs/adr/0007-schichten.md in die CLAUDE.md zu importieren, spart nichts. Laut derselben Claude-Code-Doku machen Importe eine lange Datei übersichtlicher, senken aber nicht die Kontextkosten („but don't reduce its context cost“). Auch importierte Dateien werden beim Start geladen.

Sinnvoller ist eine Zeile pro gültigem ADR in der Regeldatei: Nummer, Entscheidung in einem Halbsatz, Pfad in Backticks. Anthropic beschreibt in „Effective context engineering for AI agents“ dasselbe Prinzip: kurze Verweise wie Dateipfade im Kontext. Den Inhalt lädt der Agent erst bei Bedarf.

Gezielter geht es mit Pfadregeln. Regeln in .claude/rules/ mit paths:-Frontmatter lädt Claude Code erst, wenn der Agent Read, Write oder Edit auf eine passende Datei anwendet. Skills akzeptieren ebenfalls paths:. Cursor kennt globs in .cursor/rules/*.mdc, Copilot applyTo in .github/instructions/*.instructions.md. Laut AGENTS.md-Spezifikation gilt die nächstgelegene AGENTS.md im Verzeichnisbaum. Claude Code liest AGENTS.md laut Memory-Doku seit v2.1.277 nativ (Stand: Oktober 2026), standardmäßig aber nur, wenn keine CLAUDE.md existiert. In diesem Fall lädt Claude Code alle Dateien entlang des Pfads, nicht nur die nächstgelegene. Bei Pfadregeln lädt Claude Code die Regel selbst, nicht automatisch den darin genannten ADR. Die Regel fordert den Agenten zum Lesen auf, zwingen kann aber auch sie ihn nicht. Für ADR-0007 reicht etwa eine .claude/rules/architektur-controller.md:

---
paths:
  - "src/**/controller/**"
---
ADR-0007 gilt hier: Controller greifen nicht direkt auf Repositories zu.
Lies vor Architekturänderungen `docs/adr/0007-schichten.md`.
Prüfe zuerst den Status. Ist der ADR abgelöst, lies den dort genannten Nachfolger.

Den Index ganz in einen Skill zu verlagern, liegt nahe und ist riskant. In einer Eval von Vercel vom Januar 2026 blieb der Skill in 56 % der Fälle ungenutzt. Die Pass-Rate lag mit Skill bei 53 %, mit komprimiertem Docs-Index in der AGENTS.md bei 100 %. Die Herstellermessung arbeitete mit Framework-Dokumentation statt ADRs. Sie spricht nur gegen Skills als einzigen Einstieg, eine höhere ADR-Treue belegt sie nicht. Eine Pfadregel greift erst, wenn der Agent auf passende Dateien zugreift. Legt er den Datenzugriff in einem Verzeichnis an, das zu keinem Glob passt, bleibt nur die Indexzeile.

Stand der Werkzeugangaben und Studienfassungen: Oktober 2026.

Ersetzte ADRs brauchen einen sichtbaren Nachfolger

Wer im ADR-Verzeichnis superseded liest, blättert weiter. Ein Agent, der per Volltextsuche nach „Repository“ sucht, landet unter Umständen in der alten Datei, deren Text wie eine gültige Regel klingt.

Für ADRs gibt es dazu keine Messung, weder zur Fehlleitung durch ersetzte ADRs noch zum Vergleich mit fehlenden. Die Ableitung stützt sich auf verwandte Befunde. Der HoH-Benchmark (ACL 2025) misst bei faktischem Question Answering mindestens 20 % Leistungseinbuße allein durch veraltete Angaben im Kontext, auch wenn aktuelle danebenstehen. Näher am Code liegt „LLMs Meet Library Evolution“ (ICSE 2025): Mit Kontext aus veralteten Funktionen nutzten die Modelle in 70 bis 90 % der Fälle deprecated APIs, mit aktuellem Kontext in 9 bis 18 %. Die Claude-Code-Doku warnt zudem: „if two instructions contradict each other, Claude may pick one arbitrarily.“ Fehlt ein ADR, fehlt dem Agenten eine Begründung. Liegt ein ersetzter herum, hat er eine, allerdings die falsche.

Laut Dokumentation wertet weder Claude Code noch Copilot ADR-Status nativ aus. ADRs sind darin nicht erwähnt. Der Status muss also dort stehen, wo der Agent tatsächlich liest:

• status im Frontmatter nach MADR 4, beim Ablösen superseded by mit Nummer des Nachfolgers. Im neuen ADR steht ein Rückverweis, etwa ein eigenes Feld supersedes, das nicht Teil von MADR ist.
• Indexzeile und Pfadregel auf den Nachfolger umstellen, sobald er akzeptiert ist.
• Die erste Zeile im Body nennt den Nachfolger vor dem alten Entscheidungstext.

Fowlers Regel bleibt gewahrt: Geändert werden nur Status und Nachfolgerverweis, nicht der Entscheidungstext.

Die alte Datei bleibt als Historie erhalten. Index und Pfadregel verweisen auf den Nachfolger, per Volltextsuche findet der Agent die alte Datei trotzdem.

Harte Entscheidungen brauchen einen Test

Ob der Agent die Schichtregel einhält, zeigt erst der Build, sofern ein Test sie prüft. Dieselbe Trennung zwischen Bitte und Prüfung prägt schon die Prompt-Muster für Enterprise-Codebasen.

Einen Hinweis liefert der Preprint „Architecture as Capability Equalizer for Coding Agents“ vom August 2026: Ohne Architekturvorgabe erreichte Claude Sonnet 4.6 bei der Regeltreue einen Wert von 3,00, mit Vorgabe 8,00. Nur mit TypeScript-Verträgen und ArchUnit-artigen Regeln hielten alle sechs Modelle die Vorgaben vollständig ein. Belastbar ist das nur begrenzt: ein Einzelautor, ein System, drei Läufe pro Zelle, keine Signifikanztests. Studien zu Kontextdateien (ETH Zürich, Khatri) zeigen keine signifikante Verbesserung beim Testerfolg. Architekturtreue messen sie aber nicht.

Für ADR-0007 prüft eine ArchUnit-Regel in Java den Kern der Entscheidung: Controller-Klassen dürfen nicht von Repository-Klassen abhängen. Dass jeder Datenzugriff über einen Service läuft, belegt sie allein nicht.

@ArchTest
static final ArchRule controllerNurUeberServices =
    noClasses().that().resideInAPackage("..controller..")
        .should().dependOnClassesThat().resideInAPackage("..repository..")
        .because("ADR-0007, docs/adr/0007-schichten.md");

Der ArchUnit User Guide nennt because ausdrücklich „good practice“. FreezingArchRule.freeze(rule) friert bestehende Verstöße ein, nur neue lassen den Test scheitern. In TypeScript leistet dependency-cruiser etwa dasselbe: Eine forbidden-Regel hält laut Regelreferenz im Feld comment ihre Begründung fest. Mit severity: "error" endet der Lauf bei Verstößen mit einem Exit-Code ungleich null. Die Pipeline muss den Exit-Code auswerten, damit der Build scheitert. Für .NET heißt das Pendant ArchUnitNET, für Python import-linter.

Den umgekehrten Verweis, vom ADR zum Test, sieht MADR vor: Der Abschnitt „Confirmation“ beschreibt, wie die Einhaltung geprüft wird, und nennt dafür „a test with a library such as ArchUnit“. Ford, Parsons und Kua nennen solche Prüfungen Fitness Functions und beschreiben sie als „objective integrity assessment“ einer Architektureigenschaft. Bei ArchUnit bleibt der Verweis auf den ADR eine Konvention im because-Text: Einen Pull Request für explizite ADR-Unterstützung hat das Projekt im August 2026 ohne Merge geschlossen. Wie ein Agent solche Prüfungen in seiner Arbeitsschleife nutzt, beschreibt der Text zum Verifier-Harness für Coding Agents.

ADR-Template: eine Vorlage für Mensch und Agent

Die ersten drei Felder folgen MADR 4. scope, supersedes, superseded-by und enforced-by sind eigene Zusatzfelder, die kein Werkzeug von sich aus liest. Diese Felder pflegt das Team selbst: Akzeptiert oder ersetzt es einen ADR, gehören Index, Pfadregel und Test in denselben Review.

---
status: accepted
date: 2026-10-06
decision-makers: Architekturrunde Team Kasse
# Eigene Erweiterung, nicht Teil von MADR 4:
scope: ["src/**/controller/**"]
supersedes: []
superseded-by: null
enforced-by: src/test/java/architektur/SchichtenTest.java
---

# ADR-0007: Controller greifen nur über Services auf Daten zu

## Kontext
Controller lesen teils direkt aus Repositories. Das verteilt Validierung und Transaktionsgrenzen auf zwei Stellen.

## Entscheidung
Controller greifen nicht direkt auf Repositories zu. Daten beziehen sie ausschließlich über Services.

## Verworfene Optionen
* Direktzugriff für reine Lesefälle: weniger Code, aber unklare Transaktionsgrenze.

## Konsequenzen
* Gut, weil an einer Stelle validiert wird.
* Schlecht, weil auch triviale Lesefälle einen Service brauchen.

## Confirmation
Die ArchUnit-Regel in `SchichtenTest.java` verbietet Abhängigkeiten von Controller- zu Repository-Klassen. `FreezingArchRule` friert Altverstöße ein. Andere Datenzugriffswege prüft sie nicht.

Die Indexzeile in der Regeldatei:

- ADR-0007 (accepted): Controller nur über Services. Gilt für `src/**/controller/**`, Details in `docs/adr/0007-schichten.md`.

Der Beispiel-ADR verwirft den Direktzugriff auch für reine Lesefälle, weil die Transaktionsgrenze dann unklar ist. Diese Abwägung prüft kein Test. Will ein Agent bei einem trivialen Lesefall abkürzen, findet er sie nur im ADR.

Darf der Agent ADRs selbst schreiben?

Das im August 2026 als Preprint vorgestellte GADR erzeugt ADR-Entwürfe aus Meeting-Transkripten studentischer Projekte. In 52 von 55 Bewertungen stimmten die Prüfer der erfassten Entscheidung zu. Das System erfand aber Zahlen wie „5000+ Daily Active Users“ und machte aus offenen Diskussionen akzeptierte Entscheidungen. Die Autoren sprechen selbst von „reviewable drafts“. In einem Preprint vom September 2026 werden Entscheidungen aus Commits rekonstruiert. Den Ergebnissen fehlt laut Abstract ausgerechnet die Begründung. Den Status accepted setzt deshalb ein Mensch. Wie sich Entscheidungen aus Altcode bergen lassen, zeigt der Beitrag zum Refaktorieren von Legacy-Monolithen mit Coding Agents.

Der Test prüft nur, was jemand formuliert hat

Im Issue #69455 war der R2-Upload dokumentiert. Der Agent baute dennoch einen zweiten Weg, der in Produktion lief. Eine Abhängigkeitsregel wie die für ADR-0007 hätte das nicht erkannt: Ein zusätzliches Request-Feld verletzt keine Schichtgrenze. Der erste Schritt ist trotzdem klein: eine harte Entscheidung wählen, Status und Begründung im ADR prüfen, Index und Pfadregel darauf verweisen lassen, die Grenze als Test in den Build aufnehmen.