ADR und Spezifikation: 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 war eine Beobachtung über Dokumentation überhaupt:

Large documents are never kept up to date. (externe Seite, cognitect.com)

Daraus folgt die Länge:

The whole document should be one or two pages long. (externe Seite, cognitect.com)

Martin Fowler hat den Begriff im März 2026 in sein Lexikon aufgenommen und setzt denselben Schwerpunkt:

The most important thing to bear in mind here is brevity. (externe Seite, martinfowler.com)

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 gleich mitbeantwortet. Einen Eintrag bekommen bei ihm die Entscheidungen,

those that affect the structure, non-functional characteristics, dependencies, interfaces, or construction techniques. (externe Seite, cognitect.com)

Das ist ein Filter mit fünf Fragen. MADR, eine der verbreiteten Vorlagen, fasst ihn weiter:

Since we believe that any (important) decision should be captured in a structured way, we offer the MADR template to capture any decision. (externe Seite, adr.github.io)

In der Klammer um das Wort important steckt die ganze Unschärfe der Frage. Olaf Zimmermann, der seit Jahren über Architekturentscheidungen schreibt, beschreibt, wohin es führt, wenn der Filter nachgibt:

A lot of detailed information about the architecture is stuffed into several multi-page ADRs serving as documentation master (or monster?). (externe Seite, ozimmer.ch)

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 sieht für diesen Fall etwas anderes vor:

If a decision is reversed, we will keep the old one around, but mark it as superseded. (externe Seite, cognitect.com)

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 aufgemacht:

The more documentation the greater the burden, the greater the burden the less useful the documentation. (externe Seite, newsletter.kentbeck.com)

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. Die mittlere Stufe beschreibt sie so:

The spec is kept even after the task is complete, to continue using it for evolution and maintenance of the respective feature. (externe Seite, martinfowler.com)

Ihr Befund zum Einsatz im Kleinen fiel deutlich aus. Kiro machte aus einem kleinen Fehler vier User Stories mit zusammen 16 Akzeptanzkriterien:

it quickly became clear that the workflow was like using a sledgehammer to crack a nut. (externe Seite, martinfowler.com)

Spec Kit an einer Aufgabe, die ein Team auf drei bis fünf Punkte geschätzt hätte:

this again felt like overkill for the size of the problem. (externe Seite, martinfowler.com)

Und zu den langen Vorgaben selbst:

I frequently saw the agent ultimately not follow all the instructions. (externe Seite, martinfowler.com)

Den Grundsatz, zuerst eine Spezifikation zu schreiben, hält sie trotzdem für richtig:

So the general principle of spec-first is definitely valuable in many situations (externe Seite, martinfowler.com)

Die Werkzeuge haben seit ihrer Erprobung nachgesteuert, und zwar in genau diese Richtung. Spec Kit hat einen eigenen Weg für die Fehlerbehebung, der ohne den vollen Ablauf auskommt:

You do not need to run the SDD feature workflow first. (externe Seite, github.github.io)

Kiro schreibt zu seinem Planmodus:

For quick, well-understood changes, skip planning and work directly with the default agent. (externe Seite, kiro.dev)

Und Anthropic gibt für Claude Code eine Faustregel, die sich auf alle drei übertragen lässt:

If you could describe the diff in one sentence, skip the plan. (externe Seite, code.claude.com)

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 Änderung, die in einen Satz passt, kostet sie mehr, als sie bringt. Was eine Vorgabe am Ergebnis messbar ändert, und ab wie vielen gleichzeitigen Bedingungen die Leistung eines Agenten fällt, 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, im Juni 2024 und damit vor dem Schlagwort. Über den Rat, zuerst die Spezifikation zu schreiben, heißt es dort:

It’s part of the neo-waterfall movement rising recently. (externe Seite, newsletter.kentbeck.com)

Anfang 2026 hat Fowler einen Satz von Beck zu Spec-Driven Development zitiert:

The descriptions of Spec-Driven development that I have seen emphasize writing the whole specification before implementation. (externe Seite, martinfowler.com)

Daneben stellt Fowler, worauf es beim Einsatz von KI in der Entwicklung ankommt:

It strikes me that the key to making the full use of AI in software development is how to use it to accelerate the feedback loops. (externe Seite, martinfowler.com)

Böckeler zieht eine zweite Linie, zur modellgetriebenen Entwicklung (MDD), bei der Code aus Modellen erzeugt wurde:

Ultimately, MDD never took off for business applications, it sits at an awkward abstraction level and just creates too much overhead and constraints. (externe Seite, martinfowler.com)

Im Technology Radar von Thoughtworks steht Spec-Driven Development seit November 2025 in der Stufe Assess, also unter den Techniken, die man erkunden sollte, mit einem Vorbehalt:

We find this space fascinating, though the workflows remain elaborate and opinionated. (externe Seite, thoughtworks.com)

Die Gegenrede kommt aus demselben Haus. Ein Blogbeitrag von Thoughtworks vom Dezember 2025 hält fest, woran der Wasserfall gescheitert ist, und dass ein Agent genau diese Schleife verkürzt:

The problem with traditional waterfall development is its excessively long feedback cycles. (externe Seite, thoughtworks.com)

Thoughtworks begleitet Firmen bei der Einführung solcher Methoden, das gehört zu dieser Stimme dazu. Derselbe Beitrag räumt ein:

Experienced programmers may find that over-formalized specs can cause unnecessary trouble, and slow down change and feedback cycles (externe Seite, thoughtworks.com)

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 drei Modelle an. Eines davon behandelt jede Spezifikation als abgeschlossen:

Use flow-forward when each feature directory should remain a historical record. (externe Seite, github.github.io)

Für das Modell, in dem Spezifikation und Code nebeneinander fortgeschrieben werden, nennt dieselbe Seite die Gefahr, dass

future contributors may not know which artifact to trust (externe Seite, github.github.io)

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 Entscheidungseinträgen mit anderem Namen. Die zweite Form ist die, die sich halten lässt, und sie kommt dem ADR näher als dem Wasserfall.

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 in der Stufe Caution:

As instructions grow, the likelihood increases that important rules are ignored. (externe Seite, thoughtworks.com)

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 08.

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, der den Wasserfall anspricht:

Passing tests are guaranteed to be in sync with the code. (externe Seite, newsletter.kentbeck.com)

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:

Describe how the implementation of/compliance with the ADR can/will be confirmed. (externe Seite, adr.github.io)

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 Entscheidungschronik 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.