Lernleitfaden: Teil 1. Einführung

Thema: Teil 1. Einführung in die spezifikationsgesteuerte Entwicklung (SDD)

Schwierigkeitsgrad: Mittel

Geschätzte Lernzeit: 8-10 Stunden

Voraussetzungen: Grundlegende Programmierkenntnisse in JavaScript oder TypeScript

Verständnis der Prinzipien der Arbeit mit Terminal und Kommandozeile

Erste Erfahrung mit Versionskontrollsystemen (Git)

Kenntnisse über Webentwicklungsprinzipien (HTML, CSS, Datenbanken)

Bereitschaft zur Einarbeitung in eine neue Methodologie der Arbeit mit KI-Agenten

Lernziele: Die Definition von SDD formulieren und die prinzipiellen Unterschiede zum traditionellen „Vibe-Coding"-Ansatz mit KI-Agenten erklären

Die Rolle der Spezifikation als Hauptartefakt der Entwicklung identifizieren und den Prozess der Erstellung einer Projektverfassung beschreiben

Die SDD-Methodik zur Initialisierung des Übungsprojekts AgentClinic unter Einhaltung aller strukturellen Anforderungen anwenden

Die Unterschiede zwischen einer „schlechten" freien Anfrage und einer Anfrage im SDD-Stil analysieren und eigene Beispiele erstellen

Die Bereitschaft des Projekts zur Zusammenarbeit mit einem Agenten-Tool anhand einer Checkliste der Erfolgskriterien bewerten

Übersicht: Teil 1 „Einführung" stellt die grundlegenden Konzepte der Methodik Specification-Driven Development (SDD) – der spezifikationsgesteuerten Entwicklung – vor. Das Lernmaterial macht mit der prinzipiellen Verschiebung des Steuerungspunkts in der Entwicklung vertraut: vom chaotischen Umgang mit KI-Agenten im „Vibe-Coding"-Modus zu einem strukturierten Prozess, in dem die Spezifikation zur Hauptquelle der Wahrheit wird. Das Konzept des Agenten-Tools (am Beispiel von Qwen Code CLI) wird eingeführt, die Aufgabenteilung zwischen Mensch und Maschine erklärt sowie ein Überblick über das Übungsprojekt AgentClinic gegeben – eine satirische Webanwendung, die sich über den gesamten Lehrbuchverlauf hinweg entwickeln wird. Besondere Aufmerksamkeit gilt den terminologischen Vereinbarungen, der Klassifizierung von Aussagen nach Stärke (Standard, Empfehlung, Frontier) und dem Mindestwortschatz der Schlüsselkonzepte von SDD. Das Material bereitet auf die praktische Erstellung einer Projektverfassung, von Feature-Spezifikationen und der Organisation der Arbeit mit dem Agenten vor.

Schlüsselkonzepte: Sdd (specification-driven development): Entwicklungsmethodik, bei der die Spezifikation das Hauptsteuerungsartefakt ist. Code wird vom Agenten auf Basis der Spezifikation und nicht auf Basis einer freien Anfrage generiert. Der Mensch ist verantwortlich für Intention, Einschränkungen und Akzeptanzkriterien; der Agent für Geschwindigkeit, Code-Suche und Routineimplementierung. Der Ansatz ermöglicht die Bewahrung des Projektwissens zwischen Sitzungen und Agenten.

Vibe-Coding (vibe coding): Informeller Ansatz der Interaktion mit einem KI-Agenten, bei dem der Entwickler eine kurze freie Anfrage schreibt (z. B. „mach mir ein Feedback-Formular") und das Ergebnis „nach Gefühl" akzeptiert. Gekennzeichnet durch schnelle Code-Generierung mit anschließender Reihe von Korrekturen. Funktioniert für Prototypen, skaliert aber schlecht auf große Systeme: Entscheidungen bleiben im Chat, die Architektur driftet auseinander.

Feature-Spezifikation: Dokument, das Anforderungen, Implementierungsplan und Prüfkriterien für eine Funktionalität enthält. Umfasst die Dateien requirements.md, plan.md und validation.md. Dient als Eingabedatei für den Agenten und bestimmt die Qualität des Ergebnisses. Wird vor der Code-Erstellung angelegt und nach Abschluss der Phase aktualisiert.

Projektverfassung: Gesamtheit der Dokumente, die die Identität des Projekts definieren: Mission (mission.md), Technologie-Stack (tech-stack.md), Roadmap (roadmap.md) und wesentliche Vereinbarungen. Wird beim Start jeder Sitzung geladen und gewährleistet die Kontinuität des Projektverständnisses.

Qwen.md: Datei mit dauerhaftem Kontext für Qwen Code CLI, die Regeln für die Arbeit mit dem Projekt enthält. Wird automatisch beim Start einer Agenten-Sitzung geladen. Kann auf Benutzer- oder Projektebene abgelegt werden.

Agenten-Tool: Software-Tool (Qwen Code CLI, Claude Code, Codex CLI, Cursor u. a.), das Spezifikationen liest und Code generiert. Im Kontext des Lehrbuchs bezeichnet der Begriff „Agent" genau ein solches Tool und nicht die Charaktere der Klinik AgentClinic.

Aufgabenteilung: Grundprinzip von SDD: Der Mensch ist verantwortlich für die Formulierung der Intention, die Definition von Einschränkungen, die Validierung der Ergebnisse und die Aktualisierung der Spezifikationen. Der Agent ist verantwortlich für Ausführungsgeschwindigkeit, Code-Suche, Routineimplementierung und mechanische Änderungen. Beide Seiten erledigen die Arbeit, für die sie am besten geeignet sind.

Skill (skill.md): Wiederholbare Anweisung für den Agenten in standardisiertem Format. Wird im Verzeichnis .qwen/skills/ gespeichert. Beispiel: Skill für Feature-Spezifikationen, den der Agent ohne zusätzliche Anweisungen mehrfach anwenden kann.

Akzeptanzkriterien: Konkrete, überprüfbare Bedingungen, die die Implementierung erfüllen muss. Werden vor der Code-Erstellung definiert und in validation.md aufgenommen. Ermöglichen eine objektive Bewertung, ob die Aufgabe korrekt erledigt wurde.

Replanning: Prozess der Aktualisierung von Verfassung und Roadmap zwischen Features. Wird durchgeführt, wenn sich das Projektverständnis im Laufe der Arbeit ändert. Gewährleistet die Aktualität der Dokumentation.

Validierung: Bestätigung der Übereinstimmung der Implementierung mit der Spezifikation. Wird vom Menschen auf Basis der Kriterien aus validation.md durchgeführt. Ist unabhängig vom Entwicklungsprozess und stellt eine formelle Qualitätsbestätigung dar.

Wichtige Termine: Standard (standard): Festgelegtes Verhalten eines Tools oder allgemein anerkannte SDD-Praxis. Nicht diskussionswürdig.

Empfehlung (recommendation): Bewährte Praxis, die in den meisten Fällen funktioniert, aber vernünftige Ausnahmen zulässt.

Frontier (frontier): Ansatz, der angewendet wird, aber sich noch nicht etabliert hat; das Ergebnis hängt stark vom konkreten Team ab.

Übungsaufgaben: Name: Analyse der Unterschiede zwischen Ansätzen

Problem: Lesen Sie zwei Varianten von Anfragen an den Agenten: eine „schlechte" Anfrage „Füg eine Bewertungsseite hinzu" und eine „gute" Anfrage im SDD-Stil. Erstellen Sie eine Tabelle, in der Sie vergleichen: (1) die Anzahl der Unbestimmtheiten in jeder Anfrage, (2) die Risiken für das Projekt, (3) was der Agent in jedem Fall selbstständig entscheiden muss, (4) was nach der Ausführung der Anfrage im Chat verbleibt.

Lösung: 1. Schlechte Anfrage: erzeugt zahlreiche Unbestimmtheiten – wo Daten speichern, Bewertungen nötig, Formular, Validierung, Navigation, Tests. Der Agent trifft alle Entscheidungen selbstständig, was der Projektarchitektur widersprechen kann. Entscheidungen verbleiben im Chat und gehen bei Sitzungswechsel verloren.

1. Gute Anfrage im SDD-Stil: enthält explizite Anweisung zur Verfassungslektüre, Fragen zu stellen, Artefakte im Repository zu erstellen. Der Agent schreibt keinen Code, sondern bereitet eine Spezifikation vor. Alle Entscheidungen werden dokumentiert und gespeichert.

1. Vergleichstabelle:

Komplexität: intermediate

Name: Initialisierung des Projekts AgentClinic

Problem: Erstellen Sie ein leeres Verzeichnis für das Übungsprojekt AgentClinic. Initialisieren Sie ein Git-Repository. Erstellen Sie einen vorläufigen README.md mit Projektbeschreibung, einschließlich: (1) Projektname, (2) Zweck, (3) drei Teilnehmergruppen (Engineering-Team, Produktteam, Marketing) mit deren Wünschen. Schreiben Sie noch keinen Code und bitten Sie Qwen Code nicht um Hilfe.

Lösung: 1. Verzeichnis erstellen und Git initialisieren: mkdir agentclinic cd agentclinic git init

1. Vorläufigen README.md erstellen:

# AgentClinic

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

## Wünsche der Projektbeteiligten

### Engineering-Team

• Verständlicher Übungscode in TypeScript
• Saubere Architektur mit Aufgabenteilung
• Vorhandensein von Tests und Dokumentation

### Produktteam

• Funktionalität: Agenten-Patienten, Leiden, Therapien, Terminvereinbarung
• Bewertungen und Feedback
• Warteschlangen-Management-System

### Marketing

• Einprägsames Browser-Erlebnis
• Attraktive Benutzeroberfläche
• Markenästhetik der Klinik

Komplexität: beginner

Name: Klassifizierung von Aussagen

Problem: Nachfolgend sind Aussagen aus dem Lehrbuch aufgeführt. Bestimmen Sie, welche davon Standard, Empfehlung oder Frontier sind: (a) QWEN.md wird beim Start einer Qwen Code-Sitzung geladen; (b) eine Phase mit einer Länge von mehr als zwei Tagen sollte in zwei aufgeteilt werden; (c) vollständige Automatisierung des Reviews durch eine Multi-Agenten-Pipeline; (d) Spezifikation ist die Eingabedatei für die Maschine; (e) der Agent kann ohne Verlust des Projektwissens ersetzt werden.

Lösung: a) Standard – festgelegtes Verhalten des Tools, durch Dokumentation bestätigt.

b) Empfehlung – auf Erfahrung basierende Praxis. Die zweitägige Phasendauer ist optimal, aber Ausnahmen möglich (z. B. bei sehr kleinem Feature).

c) Frontier – Ansatz befindet sich im Experimentierstadium, Ergebnis hängt stark vom konkreten Team und Kontext ab.

d) Standard – grundlegende Definition, die in SDD anerkannt ist.

e) Empfehlung – Ziel, bei richtiger Organisation der Spezifikationen erreichbar, aber nicht automatisch garantiert.

Komplexität: intermediate

Name: Erstellung einer Checkliste der Erfolgskriterien

Problem: Erstellen Sie auf Basis des Abschnitts „Was als Erfolg gilt" eine Checkliste mit 10 Punkten zur Überprüfung der Repository-Bereitschaft für die Arbeit mit einem Agenten-Tool. Jeder Punkt sollte ein Aktionsverb (vorhanden, erstellt, geschrieben usw.) enthalten und überprüfbar sein.

Lösung: Checkliste der Repository-Bereitschaft:

1. Es gibt eine Datei QWEN.md mit Arbeitsregeln für Qwen Code
2. Das Verzeichnis specs/ wurde erstellt
3. Es gibt specs/mission.md mit Projektmissionsbeschreibung
4. Es gibt specs/tech-stack.md mit Technologieverzeichnis
5. Es gibt specs/roadmap.md mit Entwicklungsplan
6. Jedes große Feature beginnt mit requirements.md
7. Jedes Feature enthält plan.md mit Implementierungsplan
8. Jedes Feature enthält validation.md mit Prüfkriterien
9. Implementierung erfolgt in einem separaten Branch (nicht main/master)
10. Prüfkriterien werden vor dem Code geschrieben
11. Nach der Phase werden Roadmap und Spezifikationen aktualisiert
12. Es gibt eine Datei .qwen/skills/feature-spec/SKILL.md
13. Änderungsprotokoll wird geführt und ist aktuell

Komplexität: advanced

Name: Überarbeitung einer freien Anfrage

Problem: Wandeln Sie die folgende freie Anfrage in eine Anfrage im SDD-Stil um: „Mach mir ein Registrierungsformular für neue Patienten in der Klinik AgentClinic". Die Anfrage soll: (1) eine Anweisung zur Lektüre entsprechender Dokumente enthalten, (2) eine Anweisung zum Stellen von Fragen vor der Arbeit beinhalten, (3) festlegen, welche Artefakte zu erstellen sind, (4) ein Verbot der Code-Erstellung in der ersten Phase enthalten.

Lösung: Anfrage im SDD-Stil:

„Beginne eine neue Feature-Spezifikation für die nächste Phase der Roadmap: Patientenregistrierung in der Klinik.

Lies zunächst specs/mission.md, specs/tech-stack.md und specs/roadmap.md. Stelle sicher, dass du die Projektmission und den aktuellen Technologie-Stack verstehst.

Stelle mir dann Fragen zu folgenden Themen:

• Welche Patientendaten müssen erfasst werden (Name, Kontakte, Leidensgeschichte)?
• Ist eine Feldvalidierung nötig (E-Mail-Format, Namenslänge)?
• Soll das Formular Autospeicherung unterstützen?
• Welche Datensicherheitsbeschränkungen sind zu berücksichtigen?

Nach Erhalt der Antworten erstelle folgende Artefakte im neuen Verzeichnis specs/YYYY-MM-DD-patient-registration/:

• requirements.md – Anforderungen an die Funktionalität
• plan.md – Implementierungsplan mit Phasenschätzung
• validation.md – Prüfkriterien

Schreibe noch keinen Code. Warte auf meine Freigabe der Spezifikation."

Komplexität: intermediate

Fallstudien: Name: Migration eines Startups vom „Vibe-Coding" zu SDD: Erfahrung des Teams CloudFlow

Szenario: Das vierköpfige Startup-Team CloudFlow arbeitete an einer Cloud-Plattform für Projektmanagement. In frühen Phasen basierte die Interaktion mit Claude Code auf „Vibe-Coding": kurze Anfragen, schnelle Korrekturen, minimale Dokumentation. Bei Erreichen von 10.000 Codezeilen stieß das Team auf ernsthafte Probleme: die Codebasis wurde unmanagebar, der Agent gab in verschiedenen Sitzungen widersprüchliche Ratschläge, und die Integration eines neuen Entwicklers dauerte Wochen.

Aufgabe: Hauptprobleme: (1) architektonische Entscheidungen wurden vom Agenten ohne Dokumentation getroffen, (2) beim Sitzungswechsel erinnerte sich der Agent nicht an den Kontext vorheriger Entscheidungen, (3) das Refactoring einer Funktion betraf aufgrund mangelnder Abstimmung 15+ verbundene Stellen, (4) zwei Entwickler erhielten von verschiedenen Agenten-Sitzungen widersprüchliche Implementierungen desselben Features.

Lösung: Das Team führte eine dreiwöchige Migration durch: (1) Erstellung einer Projektverfassung mit mission.md, tech-stack.md, roadmap.md; (2) Verfassen eines QWEN.md mit expliziten Arbeitsregeln; (3) Überarbeitung des Backlogs in Feature-Spezifikationen; (4) Einführung der Regel: jedes Feature durchläuft die Phasen requirements → plan → validation → code; (5) Erstellung eines Skills SPEC.md zur Standardisierung des Prozesses; (6) Einrichtung von CI mit obligatorischen Kriterien aus validation.md.

Ergebnis: Zwei Monate nach der Migration: Onboarding-Zeit für neue Entwickler von 3 Wochen auf 3 Tage reduziert; Fehleranzahl pro Release um 60% gesenkt; Geschwindigkeit der Feature-Hinzufügung um 30% gesteigert (paradoxerweise trotz zusätzlicher Phasen); Möglichkeit der Agenten-Ersetzung ohne Kontextverlust bei Wechsel von Claude Code auf Qwen Code bestätigt.

Gewonnene Erkenntnisse: Spezifikation ist keine Bürokratie, sondern eine Investition in die Projektsteuerbarkeit; die Kosten der Spezifikationsschreibung amortisieren sich bei Skalierung vielfach

Verwandte Konzepte: SDD (spezifikationsgesteuerte Entwicklung)

Projektverfassung

Feature-Spezifikation

Aufgabenteilung Mensch-Agent

Akzeptanzkriterien

Lerntipps: Beginnen Sie mit dem Verständnis des „Warum" – bevor Sie die Mechanik von SDD durchgehen, erkennen Sie die Grenzen von „Vibe-Coding" in großen Projekten

Arbeiten Sie praktisch am Übungsprojekt: das Erstellen von Verzeichnissen und Dateien ist weitaus wichtiger als theoretisches Verständnis

Achten Sie auf die Markierung von Aussagen (Standard, Empfehlung, Frontier) – dies hilft zu verstehen, wo experimentiert werden kann und wo nicht

Üben Sie die Umwandlung freier Anfragen in Anfragen im SDD-Stil – dies ist eine Schlüsselfähigkeit, die Übung erfordert

Merken Sie sich den Mindestwortschatz: Verfassung, Feature-Spezifikation, Validierung, Replanning, Skill – ohne diese Begriffe ist eine effektive Kommunikation im Rahmen von SDD unmöglich

Studieren Sie das Tool Qwen Code CLI vor den praktischen Übungen – das Verständnis der Agenten-Fähigkeiten hilft, Anfragen besser zu formulieren

Versuchen Sie nicht, SDD sofort auf ein bestehendes Projekt anzuwenden – beginnen Sie mit dem Übungsprojekt AgentClinic, um reine Erfahrung zu sammeln

Diskutieren Sie das Material mit Kollegen: Klassifizierung von Aussagen und Anfragenanalyse sind gute Themen für paarweises Durchgehen

Führen Sie Notizen über Ihr Verständnis – das Verfassen eines Exzerpts mit eigenen Worten hilft, Verständnislücken aufzudecken

Haben Sie keine Angst, in der Spezifikationsphase „langsam" zu wirken – die Beschleunigung erfolgt in der Implementierungsphase, wenn die Spezifikation die Unbestimmtheit beseitigt hat

Zusätzliche Ressourcen: Qwen code cli documentation: Offizielle Dokumentation von Qwen Code CLI, einschließlich Beschreibung von QWEN.md, Betriebsmodi und verfügbaren Befehlen

Agentclinic repository: Übungsprojekt auf GitHub, das den vollständigen SDD-Zyklus von Spezifikation bis Implementierung demonstriert

Sdd methodology overview: Überblick über die Methodik Specification-Driven Development mit Anwendungsbeispielen in Teams

Beispiele für Skills (.qwen/skills/): Sammlung von SKILL.md-Dateien zur Standardisierung wiederholbarer Agenten-Operationen

Artikel „Vom Chat zum Artefakt": Betrachtung zur Transformation der Rolle des KI-Agenten vom Code-Generator zum Spezifikationsausführer

Zusammenfassung: Teil 1 „Einführung" legt das Fundament für die Arbeit mit der SDD-Methodik. Schlüsselerkenntnis: Spezifikation ist kein bürokratisches Dokument, sondern eine Eingabedatei für die Maschine, die die Qualität des Ergebnisses bestimmt. SDD unterscheidet sich prinzipiell vom „Vibe-Coding" durch die Verschiebung des Steuerungspunkts: anstelle einer Serie von Iterationen „Anfrage – Korrektur" wird ein strukturierter Prozess mit Projektverfassung, Feature-Spezifikationen und klarer Aufgabenteilung geschaffen. Der Mensch ist verantwortlich für Intention, Einschränkungen und Akzeptanzkriterien; der Agent für Routineimplementierung. Das Übungsprojekt AgentClinic dient als stabiles Modell für die Praxis; nach Beherrschung der Methodik kann es durch ein beliebiges eigenes Projekt ersetzt werden. Endziel – ein Repository, in dem der Agent ohne Verlust des Projektwissens ersetzt werden kann, und Spezifikationen, die wiederholbare Qualität gewährleisten.