Spec-driven Development: Spec und Kontext — Cheat Sheet

Der Spickzettel zum Seminar Spec-driven & Agentic Software Development, erster Teil: was festgelegt wird, bevor ein Agent die erste Datei anfasst — Absicht, Spezifikation, Projektkontext, Architektur, Schnitt. Umsetzung, Review und Governance stehen auf dem zweiten Blatt, Umsetzung und Prüfung. Werkzeugnamen und Skill-Bezeichnungen ändern sich schnell; maßgeblich bleibt die Dokumentation des jeweiligen Werkzeugs. Das Blatt hält Entscheidungen fest — die Methode bringt es nicht bei.

Stufen und Begriffe

Stufe	Eingabe	Ergebnis
Vervollständigung	Cursorposition	die nächsten Zeilen
Chat	Frage im Fenster	Vorschlag zum Übernehmen
Agent	Ziel und Repository	geänderte Dateien, Testlauf

Erst ab der dritten Stufe entsteht Arbeit, die jemand prüfen muss, statt sie zu lesen. Die vier Begriffe, die dabei am häufigsten durcheinandergehen:

Begriff	Bedeutung
Skill	benannter Arbeitsablauf, den man aufruft
Agentenrolle	Persona mit Zuständigkeit, bleibt im Gespräch
Subagent	eigener Thread für eine Teilaufgabe, meist lesend
Orchestrator	wählt die nächste Arbeitseinheit und koordiniert

Ein Skill ist ein Ablauf, eine Rolle eine Haltung, ein Subagent ein zweiter Kontext. Wer die drei vermischt, sucht Fehler an der falschen Stelle.

Modul: Vom Coding Assistant zum Engineering-System

Spontan oder strukturiert

Situation	Spontan	Strukturiert
Tippfehler in einer Fehlermeldung	ja	nein
neue Pflichtangabe im Formular	meist	Kriterien notieren
Warteliste für belegte Räume	nein	Spec und Stories
Wechsel des Anmeldeverfahrens	nein	Architektur und Review

Die Grenze verläuft an Risiko und Reichweite, nicht an der Zeilenzahl. Denselben Maßstab legt die Pfadwahl an:

Pfad	Umfang	Artefakte
direkt bauen	eine Sitzung	Diff und Testlauf
Epic	mehrere Sitzungen	Spec und geordnete Stories
Projekt	viele Sitzungen	Spec je Epic, Koordination

Hohes Risiko hebt den Pfad an, auch wenn der Umfang klein bleibt.

Module: Vom Coding Assistant zum Engineering-System · Spec-driven Development verstehen

Artefakte und ihr Zweck

Artefakt	Beantwortet	Entsteht
Product Brief	Lohnt sich das?	vor der Planung
PRD	Worauf einigen wir uns?	bei mehreren Epics
Feature Spec	Was gilt als fertig?	vor dem Bauen
Architecture Spine	Was darf nicht kollidieren?	vor der Zerlegung
Story	Was baue ich als Nächstes?	aus der Spec
Testspezifikation	Woran messen wir?	mit der Spec
Entscheidungstagebuch	Warum so?	fortlaufend

Wer alle sieben immer erzeugt, hat den Ansatz missverstanden. Ein PRD lohnt sich, wenn mehrere Menschen sich einig werden müssen, mehrere Epics zueinander passen sollen oder eine Entscheidung außerhalb des Entwicklungsteams fällt — für alles Kleinere führt der kurze Weg direkt zur Feature Spec.

Warum überhaupt Dateien statt Prompts:

Merkmal	Chatverlauf	Spezifikation
Lebensdauer	eine Sitzung	das Projekt
Sichtbar für	eine Person	das Team
Prüfbar	nur im Nachhinein	im Review vorab
Wiederverwendbar	nein	als Kontext jeder Sitzung

Modul: Spec-driven Development verstehen

Die fünf Felder einer Spec

Feld	Frage	Beispiel
Warum	Welches Problem?	Anfragen gehen verloren
Fähigkeiten	Was kann das System?	eintragen, nachrücken
Randbedingungen	Was darf sich nicht ändern?	Buchungsmodell
Nicht-Ziele	Was bleibt draußen?	Benachrichtigung
Erfolgssignal	Woran messen wir?	keine offene Anfrage

Jede Fähigkeit trägt ihre eigene Erfolgsbedingung, sonst ist sie nicht prüfbar. In Kurzform:

# Warteliste
Why:           belegte Räume verlieren heute Anfragen
Capabilities:  eintragen, nachrücken, absagen
Constraints:   keine Änderung am Buchungsmodell
Non-goals:     Benachrichtigung per E-Mail
Success:       keine Anfrage bleibt unbeantwortet

Davor steht der Intent — die Übersetzung einer Anfrage in eine überprüfbare Absicht. Die wertvollste Zeile ist die offene Frage: Sie verhindert eine erfundene Entscheidung.

Anfrage: "Wir brauchen sowas wie eine Warteliste."
Intent:  Wer einen belegten Raum anfragt, wird
         eingetragen und rückt automatisch nach.
Nicht:   Benachrichtigung, Bezahlung, Stornofristen
Fest:    Buchungsmodell bleibt unverändert
Offen:   Wie lange gilt ein Nachrückangebot?

Modul: Von der Anforderung zur Spezifikation

Wer entscheidet was

Frage	Zuständig
Namen von Feldern und Endpunkten	Agent schlägt vor
Frist eines Nachrückangebots	Fachseite
Zusätzliche Tabelle oder Spalte	Architektur
Wer fremde Buchungen stornieren darf	Security und Fachseite

Wer entscheidet, gehört in die Spec — sonst wird die Frage zweimal geklärt. Zu viele Freigabepunkte lähmen allerdings die Arbeit und werden bald übergangen.

Modul: Von der Anforderung zur Spezifikation

Projektkontext: Regeldatei

In die Regeldatei	Nicht in die Regeldatei
wörtliche Bau- und Testbefehle	Verzeichnisbäume
Abweichungen vom Ökosystem-Standard	Aufzählung des Tech-Stacks
gesperrte Pfade, generierte Dateien	was der Linter ohnehin erzwingt
beobachtete, wiederkehrende Fehler	Prosa über die Architektur

Wer beschreibt, was im Code steht, verbraucht Kontext ohne Gegenwert. Zwanzig bis dreißig Zeilen sind ein guter Startpunkt; die eingelesene Menge ist begrenzt (bei AGENTS.md standardmäßig 32 KiB), lange Referenztexte gehören verlinkt.

Rang	Ort	Zweck
1	~/.codex/AGENTS.md	eigene Gewohnheiten
2	Git-Wurzel	Regeln des Projekts
3	Unterverzeichnis	Regeln des Bereichs
4	Auftrag im Chat	schlägt alle Dateien

Eine AGENTS.override.md davor greift, wenn man global etwas vorübergehend ausschaltet. Gepflegt wird aus drei Anlässen — und häufiger gestrichen als ergänzt:

Anlass	Auslöser	Handlung
Auffrischen	Umbau im Code	Regeln gegenprüfen
Festhalten	Agent macht denselben Fehler	Regel ergänzen
Prüfen	Regeln wirken alt	streichen und kürzen

Modul: Context Engineering für Coding Agents

BMad: Rollen und Skills

Rolle	Zuständig für
Analyst	Recherche, Einordnung, Ideenprüfung
Product Manager	Anforderungen, PRD, Abstimmung
Architect	Entscheidungen, Grenzen, Konsequenzen
Developer	Umsetzung, Tests, Selbstreview
UX Designer	Erscheinung und Verhalten der Oberfläche

Die Rollen bündeln Zuständigkeit — sie ersetzen sie nicht. Entschieden hat immer ein Mensch, auch wenn die Persona überzeugend klingt.

Skill	Ergebnis
bmad-help	Empfehlung für den nächsten Schritt
bmad-project-context	geprüfter Block in AGENTS.md
bmad-spec	SPEC.md, optional stories.yaml
bmad-architecture	Entscheidungen als Architecture Spine
bmad-build	Implementierung, Tests, Commit
bmad-code-review	Befunde aus mehreren Review-Linsen
bmad-qa-generate-e2e-tests	API- und E2E-Tests
bmad-retrospective	Abgleich am Ende eines Epics

Im Alltag genügen vier: Kontext, Spec, Build, Review. Wohin installiert wird, entscheidet, welches Werkzeug die Abläufe überhaupt sieht:

Werkzeug	Verzeichnis
Claude Code	.claude/skills/
Codex, Cursor, Windsurf	.agents/skills/
Cline	.cline/skills/

npx bmad-method install     # führt durch Module und Tool
npx bmad-method install --list-tools
# im Coding Agent, nicht in der Shell:
bmad-help                   # empfiehlt den nächsten Skill

Modul: BMad Method – Rollen und Skills

Architecture Spine

In den Spine	In den Code
Grenzen zwischen Modulen	Ordnerstruktur
Zustandsübergänge einer Buchung	Feldnamen
wer die Daten besitzt	vollständiges Schema
Entscheidung samt Alternative	Wahl der Bibliothek

Faustregel: nur was an einer Epic-Grenze wehtut, wenn es fehlt. Fünf Zeilen je Entscheidung reichen — was länger wird, gehört meist in die Spec.

Entscheidung: Warteliste als eigene Tabelle
Alternative:  Statusfeld an der Buchung
Grund:        Buchungsmodell bleibt unberührt
Folge:        Nachrücken braucht eine Transaktion
Grenze:       src/buchung besitzt beide Tabellen

Modul: Architektur und Zerlegung

Schnitt der Arbeitseinheiten

Waagerecht	Senkrecht
erst alle Tabellen	Eintragen von Ende zu Ende
dann alle Endpunkte	Nachrücken von Ende zu Ende
dann die Oberfläche	Absagen von Ende zu Ende
Erst am Ende prüfbar	Nach jedem Schnitt prüfbar

Der senkrechte Schnitt kostet etwas Doppelarbeit und spart die Integrationsschmerzen. Jede Einheit braucht Akzeptanzkriterium, Vorgänger und die Angabe, was parallel laufen darf — entscheidend ist, ob zwei Einheiten dieselben Dateien schreiben.

Story	Ergebnis	Checkpoint
Eintragen	Anfrage landet in der Liste	danach
Anzeigen	Position ist sichtbar	danach
Nachrücken	Platz wird zugeteilt	davor und danach
Absagen	Eintrag verfällt	danach

Modul: Architektur und Zerlegung

Typische Fallen

Verlorener Kontext. Was im Chat vereinbart war, ist beim nächsten Start weg — und taucht als erfundene Entscheidung wieder auf.
Die Spec wiederholt den Code, statt die Absicht zu benennen. Und Akzeptanzkriterien, die niemand messen kann, klingen nur nach Sorgfalt.
Übermäßige Spezifikation legt Technik fest, die niemand verlangt hat; Randfälle fehlen dagegen, weil nur der glückliche Pfad beschrieben wurde.
Dieselbe Aussage in drei Dokumenten läuft dort auseinander. Ein PRD für ein Zwei-Tage-Feature bindet mehr Zeit, als es einspart.
Offene Fragen als Annahmen getarnt. Sie sind dann nicht mehr sichtbar — und der Agent füllt die Lücke selbst.
Veraltete Regeln führen aktiv in die Irre — schlimmer als gar keine Regel. Widersprüche zwischen zwei Ebenen fallen niemandem auf, bis das Ergebnis abweicht.
Regeln sind Text, keine Zusicherung. Sie können missachtet werden; die Grenze setzen Sandbox und Rechte.
Skills im falschen Verzeichnis bleiben unsichtbar, ohne Fehlermeldung.
Stories nach Dateien statt nach Wirkung schneiden. Abhängigkeiten fallen dann erst beim Bauen auf.
Der Prozess wird auf jede Kleinigkeit angewandt und erstickt am eigenen Umfang; Artefakte, die niemand liest, sind reine Zeremonie.

Zum Seminar Spec-driven & Agentic Software Development