ADR, PRD, BDD und Spec sind keine konkurrierenden Formate, sondern eine Kette. Jedes Dokument beantwortet genau eine Frage, und erst zusammen ergeben sie den Kontext, aus dem ein KI Agent verlässlich arbeitet. Wer alle vier im Repo hat, versioniert und aktuell, bekommt reproduzierbare Ergebnisse statt Zufallstreffer.

Die Abkürzungen stammen aus verschiedenen Jahrzehnten und verschiedenen Disziplinen. PRD kommt aus dem Produktmanagement, ADR aus der Softwarearchitektur, BDD aus dem Testing, Spec Driven Development aus der aktuellen Agenten Welle. Genau deshalb gehen sie im Alltag durcheinander. Diese Seite sortiert die Begriffe und zeigt, wie sie im KI Workflow ineinandergreifen.

Bei Never Code Alone entsteht Code täglich mit KI Agenten. Sulu, Symfony und Astro Projekte laufen bei uns mit OpenCode und offenen Modellen, abgesichert über PHPStan, Rector, PHPUnit und Cypress. Aus dieser Praxis wissen wir, welche Dokumente ein Agent wirklich liest und welche nur Speicherplatz kosten. Roland Golla arbeitet seit über 20 Jahren an Softwarequalität und ist Cypress Ambassador.

Wir helfen Teams, diese Kette aufzubauen und im Alltag am Leben zu halten. Der Einstieg läuft über unser Vibe Coding Consulting, für bestehende Projekte über NCA Agentic AI Coding Guardrails und den Codebase Audit für KI generierten Code. Ganze Teams begleiten wir über die KI Weiterbildung für Entwicklerteams. Die technische Absicherung beschreiben wir in den Quality Gates für KI Code und in den NCA PHP AI Coding Guidelines.

Die häufigste Frage im Team lautet: Welches Dokument brauchen wir denn nun? Falsche Frage. In einem aktiven Projekt liegen alle gleichzeitig im Repo. Sie unterscheiden sich nicht in der Wichtigkeit, sondern im Zeitpunkt und in der Flughöhe.

Ein PRD entsteht einmal am Anfang und ändert sich selten. ADRs kommen laufend dazu, eines pro Entscheidung, datiert und unveränderlich. Specs werden pro Feature geschrieben und wandern nach der Umsetzung ins Archiv. BDD Szenarien leben so lange wie das Feature. Und die AGENTS.md ist der Einstiegspunkt, der auf alles andere zeigt.

Der Agent liest nicht alles auf einmal. Er liest die AGENTS.md, folgt von dort aus den Verweisen und zieht sich nur, was er für die aktuelle Aufgabe braucht. Genau darum ist die Struktur wichtiger als die Menge, ein Zusammenhang, den wir auch im Context Window Management ausführlich beschreiben.

Ein Product Requirements Document beschreibt das Produkt für Menschen. Es klärt Zielgruppe, Nutzen, Abgrenzung und was ausdrücklich nicht gebaut wird. Für einen Agenten ist genau dieser letzte Teil der wertvollste: Ein sauber formulierter Nicht Scope verhindert, dass ein Modell in freundlicher Absicht Features dazuerfindet.

Ein PRD ist aber keine Umsetzungsvorlage. Es lässt Lücken, weil menschliche Leser sie aus dem Kontext füllen. Ein Agent füllt diese Lücken auch, nur eben mit Annahmen, die niemand geprüft hat. Wer ein PRD direkt in einen Coding Agenten kippt, bekommt genau das zurück.

Das Concept Doc oder RFC sitzt dazwischen. Es beschreibt zwei bis drei Wege zum Ziel und wiegt sie gegeneinander ab. Im KI Workflow ist das der Punkt, an dem ein Modell tatsächlich hilfreich ist: Optionen ausformulieren, Nachteile benennen, Vergleichstabellen bauen. Die Entscheidung trifft danach ein Mensch.

Architecture Decision Records gehen auf Michael Nygard und seinen Beitrag von 2011 zurück. Eine Entscheidung, eine Datei, ein Datum. Der Aufbau ist immer gleich: Titel, Status, Kontext, Entscheidung, Konsequenzen. Ein bis zwei Seiten, mehr nicht.

Im KI Coding ist das der wirksamste Baustein der ganzen Kette. Ein Agent startet jede Session ohne Gedächtnis. Ohne ADRs schlägt er in Woche drei genau die Bibliothek vor, die das Team in Woche eins bewusst verworfen hat. Mit ADRs im Repo findet er die Begründung und respektiert sie.

Wichtig ist die Unveränderlichkeit. Ein akzeptierter ADR wird nicht umgeschrieben, sondern durch einen neuen ersetzt, der den alten auf superseded setzt. Das kostet nichts und erhält die Historie. Ein Agent, der beide liest, versteht nicht nur den aktuellen Stand, sondern auch, warum er sich geändert hat.

Die Spec ist das Dokument, das der Agent tatsächlich umsetzt. Sie beschreibt nicht das Produkt, sondern das Verhalten: Eingaben, Ausgaben, Vorbedingungen, Fehlerfälle, Zustandsübergänge. Alles, was ein Modell sonst raten würde, steht hier ausgeschrieben.

Genau darum ist Spec Driven Development in den letzten Jahren so schnell gewachsen. Werkzeuge wie OpenSpec oder das GSD Framework geben dem Ganzen eine Struktur, die Agenten zuverlässig lesen können. Die BMAD Method setzt an derselben Stelle an, allerdings mit deutlich mehr Prozess drumherum. Wir helfen Teams, diese Ansätze gegen direktes Vibe Coding einzuordnen, statt sie pauschal einzuführen.

Eine gute Spec ist kürzer, als die meisten erwarten. Sie beschreibt einen Ausschnitt, nicht das System. Wer ein 40 Seiten Dokument schreibt, hat kein Spec Driven Development betrieben, sondern ein Lastenheft in neuer Verpackung.

Behaviour Driven Development ist deutlich älter als der aktuelle KI Hype und passt trotzdem perfekt hinein. Ein Szenario in Given When Then ist gleichzeitig fachliche Beschreibung und Testvorlage. Ein Mensch versteht es, ein Agent kann es in Code übersetzen.

Das ist der Punkt, an dem die Kette messbar wird. Aus dem Szenario entsteht ein Cypress Test, der in der Pipeline läuft. Ab da diskutiert niemand mehr, ob ein Feature fertig ist. Der Test ist grün oder er ist es nicht. Wie das in der Praxis aussieht, zeigen wir bei den Vibe Coding CI CD Pipelines und beim Accessibility Testing mit Cypress.

Wichtig: Der Agent schreibt die Szenarien nicht allein. Er formuliert Vorschläge, ergänzt Randfälle und findet Lücken. Welche Fälle fachlich wirklich zählen, entscheidet das Team.

Die AGENTS.md ist kein weiteres Dokument in der Reihe, sondern die Klammer darum. Sie sagt dem Agenten, wie in diesem Projekt gearbeitet wird, welche Befehle er ausführen darf, welche Tabus gelten und wo die anderen Dokumente liegen.

Kurz halten. Eine AGENTS.md, die alles wiederholt, was schon in Spec und ADR steht, verbrennt Kontext und veraltet sofort. Verweise sind besser als Kopien. Wie das im Detail aussieht, steht in unserem Beitrag zu rules.md und AGENTS.md. Für wiederkehrende Arbeitsschritte lohnt sich zusätzlich das SKILL.md Format.

Dokumente sind Absichtserklärungen. Durchgesetzt werden sie von der Pipeline. PHPStan und Psalm prüfen Typen, Rector räumt mechanisch auf, PHPUnit sichert die Logik, Cypress prüft die Szenarien im Browser. Erst wenn diese Gates greifen, ist die Kette mehr als Papier.

Der Effekt ist doppelt. Der Agent bekommt sofortiges Feedback statt eines Reviews drei Tage später, und das Team bekommt eine Grenze, die nicht verhandelbar ist. Details dazu stehen in den Quality Gates für KI Code und im Beitrag zur Code Qualität mit KI Agenten. Für den Review Schritt selbst hilft automatisiertes KI Code Review, etwa mit CodeRabbit.

Ein Hinweis, der in der Praxis oft untergeht: Coding Inferenz läuft in der Cloud, die lokale Entwicklungsumgebung arbeitet mit Fake Daten. Echte Kundendaten haben in diesem Workflow nichts verloren. Für Teams mit hohen Anforderungen führt der Weg über EU souveräne Inferenz oder Ollama mit lokalen Modellen für die Datenverarbeitung.

Es gibt einen bekannten Cartoon von Thom Holwerda aus dem Jahr 2008, der über Robert C. Martins Buch Clean Code seinen Weg in jedes zweite Entwicklerbüro gefunden hat. Zwei Code Reviews, links guter Code, rechts schlechter, gemessen in WTFs pro Minute. Bis heute die verlässlichste Metrik der Branche.

Der Punkt dahinter ist unbequem. Keine noch so saubere Dokumentenkette rettet Code, den niemand lesen will. Wenn ein Reviewer nach drei Minuten aufgibt, hilft auch der beste ADR nicht mehr. Die Kette macht Review nicht überflüssig, sie macht ihn überhaupt erst möglich, weil der Reviewer nicht mehr raten muss, was gewollt war.

Praktisch heißt das: Wer KI Output ungelesen durchwinkt, tauscht nur die Quelle des Chaos aus. Was daraus wird, beschreiben wir im Beitrag zu technischen Schulden durch Vibe Coding und beim AI Slop Refactoring.

Die ehrliche Gegenrede: Die meisten Teams, die ADRs einführen, schreiben nach einem halben Jahr keine mehr. Das liegt selten am Format und fast immer am Prozess. Wer keinen festen Moment hat, in dem ein ADR entsteht, schreibt keinen.

Drei Muster sehen wir immer wieder:

• Dokumentation als Alibi. Es wird geschrieben, aber nie gelesen, weder von Menschen noch von Agenten. Erkennbar daran, dass keine AGENTS.md auf die Dokumente verweist.
• Spec statt Denken. Das Team lässt das Modell die Spec schreiben, liest sie quer und übernimmt sie. Damit ist die Spec kein Kontrollpunkt mehr, sondern nur eine längere Version des Prompts.
• Zu viel auf einmal. Wer PRD, RFC, ADR, Spec und BDD gleichzeitig einführt, blockiert das Team. Ein Format, sauber eingeführt, schlägt fünf halbherzige.

Unser Rat für den Start: ADRs und eine kurze AGENTS.md. Das kostet wenig und wirkt sofort. Alles andere kommt, wenn es weh tut.

Wir arbeiten selbst mit dieser Kette, in Sulu und Symfony Projekten genauso wie in Astro Anwendungen. Die Erfahrung dahinter reicht weiter zurück als der KI Hype: über 20 Jahre Testing und Refactoring, Cypress mit Cypress Cloud im Alltag, PHPStan und Rector in jeder Pipeline.

Wer tiefer einsteigen will, findet die passenden Bausteine im Glossar und in den Best Practices. Die Grundlagen stehen bei Agentic Coding und den Agentic Coding Patterns. Für den disziplinierten Gegenentwurf zum freien Prompten lohnt Exact Coding und Vise Coding mit Guardrails. Wie ein Agent überhaupt arbeitet, erklärt Agent Looping. Wo Grenzen liegen, zeigt Skalierbarkeit und Wartbarkeit sowie blindes Iterieren vermeiden.

Für die Ablage der Dokumente selbst eignen sich einfache Markdown Dateien im Repo. Wer mehr Komfort braucht, findet Optionen bei Obsidian und GitBook. Als Agent nutzen wir OpenCode mit offenen Modellen, die Auswahl dazu steht bei den Vibe Coding Modellen.

Die Fragen, die im Team am häufigsten aufkommen, wenn die Dokumentenkette zum ersten Mal aufgebaut wird.