ADR und Spe­zi­fi­ka­tion: wie viel Papier ein Agent braucht

Wer mit einem Codingagenten baut, schreibt mehr auf als früher. Der Agent beginnt jede Sitzung ohne Erinnerung, und was er wissen soll, muss irgendwo stehen. Zwei Formen sind dafür im Gespräch, beide älter als die Agenten: der Architecture Decision Record, kurz ADR, und die Spezifikation, von der das Schlagwort Spec-Driven Development seinen Namen hat.

Die Frage dieses Textes ist die nach der Dosis. Was gehört in welches Artefakt, ab wann wird es zu viel, und welche Orte gibt es sonst.

Zwei Artefakte, zwei Zeitrichtungen

Eine Spezifikation schaut nach vorn. Sie beschreibt, was entstehen soll, und hat ihren Zweck erfüllt, sobald es entstanden ist, es sei denn, jemand pflegt sie weiter. Ein ADR schaut zurück. Er hält fest, warum etwas so ist, und wird wertvoll, wenn Monate später jemand dieselbe Frage stellt.

Den ADR hat Michael Nygard 2011 beschrieben, als kurze Notiz je Entscheidung mit Kontext, Entscheidung, Status und Folgen. Seine Begründung (externe Seite, cognitect.com) war eine Beobachtung über Dokumentation überhaupt: Große Dokumente werden nie auf dem aktuellen Stand gehalten.

Daraus folgt die Länge: Das ganze Dokument soll nach Nygard (externe Seite, cognitect.com) ein bis zwei Seiten lang sein.

Martin Fowler hat den Begriff im März 2026 in sein Lexikon (externe Seite, martinfowler.com) aufgenommen und setzt denselben Schwerpunkt: Das Wichtigste, woran man dabei denken soll, ist die Kürze.

Neu ist mit dem Agenten der Leser. Ein Kollege erinnert sich an das Gespräch von vor drei Wochen, ein Agent kennt nur, was dasteht. Wie die Datei aufgebaut ist, die er bei jedem Start liest, beschreibt Vibe-Coding / Agentic Engineering, Kapitel 03; wie er zwischen zwei Sitzungen behält, was er gelernt hat, steht in Vibe-Coding / Agentic Engineering, Kapitel 05.

Nur die wichtigen Entscheidungen

Ob es reicht, nur die wichtigen Schritte festzuhalten, hat Nygard im selben Text (externe Seite, cognitect.com) gleich mitbeantwortet. Einen Eintrag bekommen bei ihm die Entscheidungen, die die Struktur, nichtfunktionale Eigenschaften, Abhängigkeiten, Schnittstellen oder Bauweisen betreffen.

Das ist ein Filter mit fünf Fragen. MADR, eine der verbreiteten Vorlagen, fasst ihn weiter: Weil nach Überzeugung ihrer Autoren jede (wichtige) Entscheidung strukturiert festgehalten werden sollte, ist die MADR-Vorlage (externe Seite, adr.github.io) für jede Entscheidung gedacht.

In der Klammer um das Wort wichtig, im Original important, steckt die ganze Unschärfe der Frage. Olaf Zimmermann, der seit Jahren über Archi­tek­tur­ent­schei­dungen schreibt, beschreibt in einem Beitrag über ADRs (externe Seite, ozimmer.ch), wohin es führt, wenn der Filter nachgibt: Viele Einzelheiten der Architektur werden in mehrere mehrseitige ADRs gestopft, die dann als Hauptquelle der Dokumentation dienen, als Master oder, wie er mit Fragezeichen nachschiebt, als Monster.

Wie schnell das geht, zeigt mein eigenes Diktier-Projekt, beschrieben in Mac-Diktat. Zwischen dem 18. April und dem 19. Juni 2026 entstanden dort 99 Einträge, in neun Wochen. Der mittlere ist 889 Wörter lang, 38 liegen über 1.000 Wörtern, neun über 2.000. In 23 Einträgen stehen zusammen 40 Nachträge, mit denen eine Entscheidung im selben Eintrag geändert wurde. Nygard (externe Seite, cognitect.com) sieht für diesen Fall etwas anderes vor: Wird eine Entscheidung zurückgenommen, bleibt der alte Eintrag erhalten und wird als abgelöst markiert.

Gezählt ist das am 23.09.2026 an den Dateien selbst, ohne Kopfzeilen.

Der Grund liegt auf der Hand. Einen Eintrag schreibt der Agent in einer Minute mit, und wo das Schreiben nichts kostet, entfällt die Frage, ob es sich lohnt. Der Filter hängt dann allein am Menschen, der den Auftrag gibt. Kent Beck hat die Gegenrechnung (externe Seite, newsletter.kentbeck.com) aufgemacht: Je mehr Dokumentation, desto größer die Last, und je größer die Last, desto weniger nützt die Dokumentation.

Die Antwort lautet also ja, nur die wichtigen, und die Arbeit liegt darin festzulegen, was wichtig heißt. Nygards fünf Arten sind dafür eine brauchbare Liste. Ein Eintrag, der über zwei Seiten wächst, ist meist zwei Einträge, oder er ist ein Handbuch geworden.

Wann eine Spezifikation hilft, und wann sie zu viel ist

Für die Spezifikation vor dem Code hat sich 2025 der Name Spec-Driven Development durchgesetzt, mit Kiro von AWS und Spec Kit von GitHub als Anlass. Birgitta Böckeler hat beide im September 2025 ausprobiert und drei Stufen unterschieden: Die Spezifikation steht vor dem Code, sie bleibt danach erhalten, oder sie ist selbst die Quelle, aus der der Code entsteht. Bei der mittleren Stufe bleibt die Spezifikation nach ihrer Beschreibung (externe Seite, martinfowler.com) auch nach Abschluss der Aufgabe erhalten, damit man sie für die Weiterentwicklung und Pflege des jeweiligen Features weiter nutzt.

Ihr Befund (externe Seite, martinfowler.com) zum Einsatz im Kleinen fiel deutlich aus. Kiro machte aus einem kleinen Fehler vier User Stories mit zusammen 16 Akzep­tanz­kri­te­rien, und schnell sei klar gewesen, dass der Ablauf hier dem Vorschlaghammer glich, mit dem man eine Nuss knackt.

Spec Kit an einer Aufgabe, die ein Team auf drei bis fünf Punkte geschätzt hätte, wirkte auf sie erneut überdimensioniert für die Größe des Problems.

Zu den langen Vorgaben selbst hält ihr Erfahrungsbericht (externe Seite, martinfowler.com) fest, dass sie häufig sah, wie der Agent am Ende nicht alle Anweisungen befolgte.

Den Grundsatz, zuerst eine Spezifikation zu schreiben, hält sie trotzdem in vielen Situationen für eindeutig wertvoll.

Die Werkzeuge haben seit ihrer Erprobung nachgesteuert, und zwar in genau diese Richtung. Spec Kit hat einen eigenen Weg für die Fehlerbehebung (externe Seite, github.github.io), der ohne den vollen Ablauf auskommt: Der SDD-Ablauf für Features muss dafür nicht vorher durchlaufen werden.

Kiro rät zu seinem Planmodus (externe Seite, kiro.dev), bei schnellen, gut verstandenen Änderungen die Planung zu überspringen und direkt mit dem Standard-Agenten zu arbeiten.

Anthropic setzt in den Empfehlungen für Claude Code (externe Seite, code.claude.com) beim gewöhnlichen Fall an: Meist tue schon der erste schlichte Prompt in einer frischen Sitzung das Richtige. Den Schritt vor dem Code sieht die Seite für den Fall vor, dass man noch nicht genau weiß, was man will. Dann befragt Claude einen, bis die Antworten eine Spezifikation ergeben.

Damit beschreiben die Hersteller die Dosis inzwischen selbst. Eine Spezifikation lohnt sich, wo eine Änderung mehrere Stellen berührt, wo die Anforderung erst geklärt werden muss oder wo andere mitentscheiden. Für die kleine, gut verstandene Änderung kostet sie mehr, als sie bringt. Was eine Vorgabe am Ergebnis messbar ändert, und wie die Leistung eines Agenten mit wachsenden strukturellen Anforderungen sinkt, steht in Vibe-Coding / Agentic Engineering, Kapitel 10.

Der Vorwurf vom Wasserfall, am Original

Der Vorwurf lautet, Spec-Driven Development hole das Wasserfallmodell zurück: erst alles aufschreiben, dann bauen. Im Original steht er bei Kent Beck, in einem Text über Dokumentation (externe Seite, newsletter.kentbeck.com) vom Juni 2024 und damit vor dem Schlagwort. Über den Rat, zuerst die Spezifikation zu schreiben, heißt es dort, er gehöre zu der Neo-Wasserfall-Bewegung, die sich in letzter Zeit ausbreite.

Anfang 2026 hat Fowler in einem Fragment (externe Seite, martinfowler.com) einen Satz von Beck zu Spec-Driven Development zitiert: Die Beschreibungen, die Beck davon gesehen hat, betonen, die ganze Spezifikation vor der Umsetzung zu schreiben.

Daneben stellt Fowler (externe Seite, martinfowler.com), worauf es beim Einsatz von KI in der Entwicklung ankommt: Der Schlüssel, um KI in der Soft­ware­ent­wick­lung voll zu nutzen, liegt für ihn darin, mit ihr die Feedbackschleifen zu beschleunigen.

Böckeler zieht eine zweite Linie, zur modellgetriebenen Entwicklung (MDD), bei der Code aus Modellen erzeugt wurde. Nach ihrem Befund (externe Seite, martinfowler.com) hat sich MDD für Geschäfts­an­wen­dungen am Ende nie durchgesetzt: Es liegt auf einer ungünstigen Abstraktionsebene und erzeugt schlicht zu viel Aufwand und zu viele Einschränkungen.

Im Technology Radar (externe Seite, thoughtworks.com) von Thoughtworks steht Spec-Driven Development seit November 2025 in der Stufe Assess, also unter den Techniken, die man erkunden sollte, mit einem Vorbehalt: Das Feld sei faszinierend, die Abläufe blieben aber aufwendig und von festen Vorstellungen geprägt.

Die Gegenrede kommt aus demselben Haus. Ein Blogbeitrag von Thoughtworks (externe Seite, thoughtworks.com) vom Dezember 2025 hält fest, dass das Problem der klassischen Was­ser­fall­ent­wick­lung ihre übermäßig langen Feedbackzyklen sind, und dass ein Agent genau diese Schleife verkürzt.

Thoughtworks begleitet Firmen bei der Einführung solcher Methoden, das gehört zu dieser Stimme dazu. Derselbe Beitrag (externe Seite, thoughtworks.com) räumt ein, dass erfahrene Programmierer übermäßig formalisierte Spezifikationen als unnötigen Ärger erleben können, der Änderungen und Feedbackzyklen verlangsamt.

Entschieden wird der Streit an einer Stelle, die beide Seiten erst spät nennen: was mit der Spezifikation nach dem Bau geschieht. Spec Kit legt sich dabei ausdrücklich nicht fest: Die Einleitung zur Methode (externe Seite, github.github.io) lässt offen, ob die drei Dateien einer Spezifikation nach einer geänderten Anforderung erhalten oder umgeschrieben werden, und die Doku bietet dafür vier Modelle an. Alle vier teilen denselben Lieferablauf und unterscheiden sich nur darin, was danach bleibt und gepflegt wird. Eines davon behandelt jede Spezifikation als abgeschlossen: Das Modell flow-forward (externe Seite, github.github.io) ist für den Fall gedacht, dass jedes Feature-Verzeichnis ein historischer Eintrag bleiben soll.

Für das Modell, in dem Spezifikation, Plan, Aufgaben und Code einander nachführen dürfen (bei Spec Kit flow-back), nennt dieselbe Seite (externe Seite, github.github.io) die Gefahr: Wird ein tieferes Artefakt geändert, ohne dass die Entscheidung in die Spezifikation zurückfließt, wissen künftige Beteiligte nicht, welchem Artefakt sie trauen sollen.

Wer die Spezifikation weiterpflegt, hat das Problem jedes großen Dokuments, das Nygard 2011 in einem Satz beschrieben hat. Wer sie abschließt und für die nächste Änderung eine neue anlegt, hat einen Stapel von Ent­schei­dungs­ein­trägen mit anderem Namen. Die zweite Form ist die, die sich halten lässt, und sie kommt dem ADR näher als dem Wasserfall.

Das vierte Modell der Doku, constitution-only, geht noch einen Schritt weiter: Von den Artefakten einer Lieferung bleiben im Repository nur die Projektgrundsätze, der Rest wird danach archiviert oder verworfen. Was bleiben soll, gehört vorher an einen vereinbarten Ort wie die Pro­dukt­do­ku­men­ta­tion, Entwurfsdokumente oder den Issue-Tracker. Die Seite verlangt das ausdrücklich, bevor die Artefakte gehen.

Die übrigen Orte, nach Lebensdauer

Zwischen Spezifikation und ADR liegen weitere Orte, an denen etwas festgehalten werden kann. Sortiert nach der Zeit, die das Festgehaltene gilt:

Die Commit-Nachricht gehört zu einer einzigen Änderung und steht dort, wo man beim Nachforschen im Verlauf landet. Was hineingehört, steht in Vibe-Coding / Agentic Engineering, Kapitel 04.

Der Vorgang im Issue-Tracker gilt, bis er geschlossen ist. Er ist der Ort für die offene Frage. Die Antwort, die bleiben soll, wandert von dort in einen der Orte weiter unten.

Die Spezifikation gilt für ein Feature, solange es entsteht, und danach nur, wenn jemand sie pflegt.

Der ADR gilt, bis ein neuer Eintrag ihn ablöst.

Die Projektanweisung, also CLAUDE.md oder AGENTS.md, liest der Agent bei jedem Start. Deshalb muss sie kurz bleiben. Thoughtworks führt aufgeblähte Anweisungen seit April 2026 im Technology Radar (externe Seite, thoughtworks.com) in der Stufe Caution: Je weiter die Anweisungen wachsen, desto wahrscheinlicher werden wichtige Regeln übergangen.

Wie man sie klein hält, den Rest in Fähigkeiten auslagert, die erst bei Bedarf geladen werden, und warum die Regel selbst dabei in der Anweisung bleibt, beschreibt Vibe-Coding / Agentic Engineering, Kapitel 12.

Der Test gilt, solange er läuft, und er ist das einzige dieser Artefakte, das bei jedem Lauf gegen den Code gehalten wird. Beck schreibt dazu in demselben Text (externe Seite, newsletter.kentbeck.com), der den Wasserfall anspricht: Bestandene Tests stimmen garantiert mit dem Code überein.

Wie ein Test zur Vorgabe für einen Agenten wird, beschreibt der Beitrag Erst der rote Test, die Prüfung von außen Vibe-Coding / Agentic Engineering, Kapitel 07.

Zwei Befunde aus dem eigenen Betrieb

Ein Status belegt eine Entscheidung. Im Diktier-Projekt plant Eintrag 4 vom 18. April eine Ersetzung von Fachbegriffen über zwei phonetische Verfahren, Kölner Phonetik und Double Metaphone. Er steht bis heute auf angenommen. Im Quelltext kommt Double Metaphone nicht vor, und die Stelle, die Begriffe ersetzt, beschreibt sich selbst als Abgleich ganzer Wörter ohne phonetische Kniffe. Spätere Einträge haben die Phonetik für diese Aufgabe ausdrücklich verworfen; die Kölner Phonetik gibt es im Code, an anderer Stelle und für eine andere Aufgabe. Ob eine Entscheidung gebaut ist, zeigt erst der Code. MADR hat dafür ein eigenes, freiwilliges Feld (externe Seite, adr.github.io): Dort steht, wie die Umsetzung des ADR oder seine Einhaltung bestätigt werden kann oder wird.

Eine Zusammenfassung läuft ihren Einträgen davon. Die Projektanweisung desselben Projekts listet die Sprachmodelle der Nachbearbeitung mit ihren Einträgen. Bei ihrer letzten Änderung am 19. Mai verwies sie für den ersten Platz auf einen Eintrag, der seit dem 19. April abgelöst war, und nannte für den dritten Platz Qwen 2.5 7B, obwohl ein Eintrag vom 25. April auf Gemma 4 26B-A4B gewechselt hatte. Im Code steht Gemma. Dasselbe gilt für die Ent­schei­dungs­chronik dieser Seite: Die Anweisung, die der Agent zu Beginn jeder Sitzung liest, nannte bis zum 23.09.2026 240 Einträge, an diesem Tag waren es über 700.

Beide Befunde führen auf dieselbe Arbeitsregel. Die Datei, die der Agent immer liest, verweist auf die Einträge, statt sie abzuschreiben. Und ob etwas gebaut ist, beantwortet ein Test oder eine Suche im Quelltext, bevor ein Statusfeld es behauptet.