Teil 1. Einführung

Spezifikationsbasierte Entwicklung, oder SDD, verlagert den Steuerungspunkt in der Entwicklung von den Agenten. Im gewohnten „Vibe-Coding“-Modus – wenn der Entwickler eine kurze, freie Anfrage wie „mach mir ein Feedback-Formular“ schreibt und das Ergebnis nach Gefühl annimmt – generiert der Agent schnell Code, und dann beginnt eine Serie von Korrekturen. Das funktioniert für einen Prototyp, aber skaliert schlecht auf ein großes System: Entscheidungen bleiben im Chat, die Architektur driftet auseinander, und der nächste Agent oder die nächste Sitzung weiß nicht mehr, warum der Code genau so aussieht.

Bei SDD wird die Spezifikation zum Hauptartefakt. Der Code bleibt wichtig, erscheint aber als Ergebnis der Ausführung der Spezifikation. Der Mensch ist verantwortlich für Absicht, Einschränkungen, Akzeptanzkriterien und Qualitätskontrolle. Der Agent ist verantwortlich für Geschwindigkeit, Code-Suche, routinemäßige Implementierung und mechanische Änderungen.

In diesem Lehrbuch werden wir Qwen Code CLI verwenden. Die SDD-Methodik selbst ist nicht an einen bestimmten Agenten gebunden: Sie lässt sich in Qwen Code, Claude Code, Codex CLI, Cursor, JetBrains AI Assistant umsetzen. Qwen Code eignet sich für diese Arbeit, weil es vom Terminal aus startet, Projektdateien liest, QWEN.md, @file-Befehle, Shell-Befehle über !, den Headless-Modus, Projektskills und MCP unterstützt.

Terminologische Vereinbarung. Im Text bedeutet das Wort „Agent“ Qwen Code CLI (oder sein Analogon) – ein Tool, das Spezifikationen liest und Code schreibt. Das Lernprojekt AgentClinic hat seine eigenen domänenspezifischen „Agenten“ – fiktive KI-Persönlichkeiten, die Patienten der Klinik sind. Wenn aus dem Kontext nicht offensichtlich ist, wird die Präzisierung „Agent-Tool“ oder „Klinik-Persönlichkeit“ verwendet.

Wie man die Behauptungen des Lehrbuchs liest

Das Lehrbuch stützt sich auf Behauptungen unterschiedlicher Stärke. Um „wie Qwen Code genau funktioniert“ nicht mit „wie es im Team üblich ist“ und mit „was gerade erst ausprobiert wird“ zu vermischen, werden an strittigen Stellen Markierungen gesetzt:

• Standard. Festgelegtes Verhalten des Tools oder allgemein anerkannte SDD-Praxis. Beispiel: „QWEN.md wird beim Start einer Qwen Code-Sitzung geladen“ – Standard.

• Empfehlung. Bewährte Praxis, die in den meisten Fällen funktioniert, aber vernünftige Ausnahmen zulässt. Beispiel: „eine Phase länger als zwei Tage sollte in zwei aufgeteilt werden“ – Empfehlung.
• Frontier. Ein Ansatz, der angewendet wird, aber sich noch nicht etabliert hat; das Ergebnis hängt stark vom Team ab. Beispiel: „vollständige Automatisierung des Reviews über eine Multi-Agent-Pipeline“ – Frontier.

Wenn keine Markierung vorhanden ist, gilt die Behauptung entweder als Standard oder als Empfehlung. Frontier wird explizit markiert.

Was Sie bauen werden

Das Lernprojekt heißt AgentClinic. Es ist eine satirische Webanwendung: KI-Agenten kommen in eine Klinik, um sich von der Arbeit mit Menschen zu erholen. Das Beispiel ist inhaltlich lustig, aber technisch ernst gemeint: TypeScript, Hono, serverseitiges JSX, SQLite, Vitest, CSS, Feature-Spezifikationen und Änderungsprotokoll.

Sie müssen dieses Projekt nicht wörtlich kopieren. Seine Rolle ist es, ein solides Lernmodell zu bieten. Nach dem Durchlaufen können Sie AgentClinic durch Ihren eigenen Service, internes Tool, Analyseanwendung oder Legacy-Projekt ersetzen.

Was als Erfolg gilt

Am Ende des Lehrbuchs sollten Sie ein Repository haben, in dem:

• eine QWEN.md mit Arbeitsregeln für Qwen Code vorhanden ist;

• specs/mission.md, specs/tech-stack.md, specs/roadmap.md existieren;
• jede große Feature mit requirements.md, plan.md, validation.md beginnt;
• die Implementierung in einem separaten Branch erfolgt;
• die Prüfkriterien vor dem Code geschrieben werden;
• nach der Phase Roadmap, Spezifikationen und Änderungsprotokoll aktualisiert werden;
• der wiederholbare Prozess der Feature-Spezifikation als .qwen/skills/feature-spec/SKILL.md dokumentiert ist;
• der Agent ohne Verlust des Projektgedächtnisses ausgetauscht werden kann.

Grundlegende Rolle des Menschen

Bei SDD verschwindet der Entwickler nicht. Seine Arbeit wird eher der eines Architekten und Editors auf der Ebene der Absichten:

• formulieren, was gebaut werden muss;
• entscheiden, welche Einschränkungen nicht verhandelbar sind;
• angeben, wo der Agent selbstständig entscheiden darf;
• nicht nur den Code, sondern auch die Übereinstimmung des Codes mit der Spezifikation prüfen;
• Spezifikationen aktualisieren, wenn das Projektverständnis sich ändert.

Der häufigste Fehler ist, die Spezifikation als Bürokratie zu betrachten. In der Entwicklung mit Agenten ist die Spezifikation kein Papier für den Manager. Sie ist die Eingabedatei für die Maschine, die die Qualität des Ergebnisses bestimmt.

Minimales Vokabular

Konstitution – Projektverfassung: Mission, Stack, Roadmap, zentrale Vereinbarungen.

Feature-Spezifikation – Anforderungen, Plan und Prüfkriterien für ein Feature.

Validierung – Bestätigung, dass die Implementierung mit der Spezifikation übereinstimmt.

Replanning – Aktualisierung der Konstitution und Roadmap zwischen Features.

Skill – wiederholbare Anweisung für den Agenten im Format SKILL.md.

QWEN.md – permanenter Kontext von Qwen Code für das Projekt oder den Benutzer.

Erstes Beispiel: schlechte und gute Anfrage

Schlechte Anfrage:

Füge eine Bewertungsseite hinzu.

Problem: Der Agent entscheidet selbst, wo Bewertungen gespeichert werden, ob Bewertungen nötig sind, ob ein Formular nötig ist, wie Felder validiert werden, wie die Navigation aktualisiert wird, ob Tests nötig sind.

Anfrage im SDD-Stil:

Starte eine neue Feature-Spezifikation für die nächste Phase der Roadmap: Anzeige von Bewertungen.
Lies zuerst specs/mission.md, specs/tech-stack.md und specs/roadmap.md.
Stelle mir dann Fragen zu Grenzen, Entscheidungen und Kontext.
Nach den Antworten erstelle specs/YYYY-MM-DD-reviews-display/requirements.md,
plan.md und validation.md. Schreibe noch keinen Code.

Der Unterschied liegt nicht in der Länge der Anfrage, sondern in der Steuerung. Im zweiten Fall springt der Agent nicht direkt in den Code; er hilft, ein Artefakt zu erstellen, das im Repository leben wird.

Praxis

Erstellen Sie ein leeres Verzeichnis für das Lernprojekt:

mkdir agentclinic
cd agentclinic
git init

Erstellen Sie eine Entwurfsdatei README.md:

# AgentClinic

AgentClinic – eine fiktive Klinik, in der KI-Agenten sich von der Arbeit mit Menschen erholen.

Wünsche der Projektbeteiligten:
- Das Engineering-Team möchte verständlichen Lern-Code in TypeScript;
- Das Produktteam möchte Agenten, Beschwerden, Therapien, Terminbuchungen, Bewertungen und Feedback;
- Das Marketing braucht ein unvergessliches Browser-Erlebnis.

Bitten Sie Qwen Code noch nicht, Code zu schreiben. In dieser Phase ist die Aufgabe, die Projektidee festzuhalten und den Boden für die Konstitution vorzubereiten.

Kontrollfragen

1. Wo befindet sich in SDD die Hauptquelle der Wahrheit: im Code, im Chat oder in der Spezifikation?
2. Warum kann dieselbe Änderung über eine Spezifikation billiger sein als eine Serie von „Anfrage – Korrektur“-Iterationen?
3. Was sollte der Mensch tun, wenn der Agent eine technisch funktionierende, aber produktmäßig falsche Lösung vorschlägt?