Teil 3. Überblick über den Prozess

Der SDD-Prozess kann als mehrere Speicherebenen dargestellt werden. Die oberste Ebene ist die Projektverfassung. Die mittlere Ebene umfasst die Feature-Spezifikationen. Die unterste Ebene ist die Implementierung und die Überprüfungen. Zwischen den Features gibt es eine Neugestaltung: Sie aktualisieren die oberen Ebenen, wenn neue Arbeiten zeigen, dass frühere Entscheidungen ungenau waren.

Grundzyklus:

flowchart TD
  A["Verfassung<br/>mission.md<br/>tech-stack.md<br/>roadmap.md"] --> B["Feature-Spezifikation<br/>requirements.md<br/>plan.md<br/>validation.md"]
  B --> C["Implementierung<br/>Code, Tests, Migrationen"]
  C --> D["Überprüfung<br/>automatische und manuelle Fakten"]
  D --> E{"Fakten bestanden?"}
  E -- "ja" --> F["Zusammenführung"]
  F --> G["Neugestaltung<br/>Regeln und Roadmap aktualisieren"]
  G --> A
  E -- "nein" --> B

Rolle der Verfassung

Die Verfassung beantwortet Fragen, die nicht bei jedem Feature neu entschieden werden sollten:

• warum das Projekt existiert;
• für wen es erstellt wird;
• welcher Stack verwendet wird;
• welche architektonischen Einschränkungen bereits akzeptiert wurden;
• welche Phasen geplant, aktiv oder abgeschlossen sind.

In Qwen Code wird diese Ebene durch die Datei QWEN.md ergänzt. Der Unterschied ist folgender: QWEN.md sagt dem Agenten, wie er sich im Repository verhalten soll, während specs/*.md sagt, was das Produkt baut.

Beispielstruktur:

agentclinic/
  QWEN.md
  specs/
    mission.md
    tech-stack.md
    roadmap.md

Rolle der Feature-Spezifikation

Für jede Phase der Roadmap wird ein separater Ordner erstellt:

specs/
  2026-05-10-feedback-form/
    requirements.md
    plan.md
    validation.md

requirements.md dokumentiert die Grenzen, was nicht dazugehört, Entscheidungen und Kontext.

plan.md unterteilt die Arbeit in Aufgabengruppen.

validation.md beschreibt, wie man erkennt, dass ein Branch zusammengeführt werden kann.

Diese Dateien sind wichtiger als der Chatverlauf. Eine neue Qwen Code-Sitzung setzt die Arbeit fort, indem sie nur das Repository liest.

Rolle der Branches

Jede Feature-Phase sollte in einem separaten Git-Branch leben:

git checkout -b phase-1-hello-hono

Dies reduziert die kognitive Belastung bei der Arbeit mit dem Agenten. Wenn der Agent zu viel geändert hat, haben Sie eine klare Grenze: alle Änderungen dieses Branches müssen sich auf einen bestimmten Spezifikationsordner beziehen.

Rolle von /clear

In Qwen Code hilft ein frischer Kontext zu überprüfen, ob die Spezifikation ausreichend ist. Wenn der Agent ein Feature nach /clear implementieren kann, bedeutet dies, dass das nötige Wissen in den Dateien steht und nicht im Chatgedächtnis versteckt ist.

Beispiel:

/clear

Lies @QWEN.md, @specs/mission.md, @specs/tech-stack.md
und @specs/2026-05-10-feedback-form/plan.md.
Implementiere nur Aufgabengruppe 1. Stoppe nach der Liste der geänderten Dateien.

Wenn der Agent nach der Löschung sinnvolle Klärungsfragen stellt, ist das normal. Wenn er beginnt zu raten, ist die Spezifikation unvollständig.

Vier Betriebsmodi mit dem Agenten

1. Interview-Modus. Der Agent stellt Fragen und hilft, die Spezifikation zu schreiben.
2. Implementierungsmodus. Der Agent implementiert konkrete Aufgabengruppen.
3. Überprüfungsmodus. Der Agent sucht nach Abweichungen zwischen Code und Spezifikation.
4. Neugestaltungsmodus. Der Agent aktualisiert die Verfassung, die Roadmap, das Änderungsprotokoll und den Prozess.

Vermischen Sie diese Modi nicht unnötig. Wenn Sie in einer Sitzung zuerst das Produkt diskutieren, dann Code anfordern, dann eine Überprüfung, zieht der Agent alten Kontext dorthin, wo er mit der Datei arbeiten sollte.

Der „Plane – Implementiere – Überprüfe“-Kreislauf

Innerhalb eines Features lassen sich die Modi 2 und 3 bequem als „Plane – Implementiere – Überprüfe“-Kreislauf darstellen (in englischsprachigen Quellen wird dies als Plan-Act-Verify bezeichnet). Der Kreislauf definiert drei Phasen und explizite Einschränkungen für jede:

• Plane. Der Agent listet auf, was er tun wird, welche Dateien er berührt, welche Überprüfungen er ausführt. In diesem Schritt schreibt der Agent keinen Code und ändert keine Dateien. Wenn der Plan Änderungen enthält, die nicht in requirements.md stehen, ist das ein Signal, die Spezifikation zu präzisieren, nicht „lass uns es versuchen“.
• Implementiere. Der Agent ändert Code innerhalb des genehmigten Plans. Den Plan während der Implementierung zu erweitern ist verboten: eine neue Idee wird entweder zu einer separaten Aufgabengruppe oder zu einer Spezifikationskorrektur.
• Überprüfe. Der Agent vergleicht das Ergebnis mit validation.md, listet auf, was bestanden wurde, was fehlgeschlagen ist und was nicht überprüft wurde. In diesem Schritt korrigiert der Agent keinen Code – er schreibt nur einen Bericht.

Es ist nützlich, diese drei Phasen im Kopf zu behalten, sowohl bei der Formulierung von Anfragen als auch beim Lesen der Antworten des Agenten: Wenn die Antwort „ich plane“ und „ich habe bereits getan“ vermischt, verlieren Sie den Kontrollpunkt. In Teil 8 werden diese Einschränkungen zu konkreten Anfragen für jede Phase.

Drei Spezifikationsmodi

Nicht jede Arbeit wird gleich beschrieben. Es ist sinnvoll, drei Modi zu unterscheiden:

• Zuerst Anforderungen (Requirements-First). Der Standardmodus des Lehrbuchs. Wird für Features verwendet, bei denen das Wichtigste ist, was erscheinen soll: eine Bewertungsseite, ein Feedback-Formular, eine neue Route.

• Zuerst Design (Design-First). Wird angewendet, wenn die Anforderungen schon lange klar sind und das Hauptrisiko darin liegt, wie genau implementiert wird: Schema-Migration, Änderung der öffentlichen API, Reorganisation von Modulen. Hier wird zuerst plan.md oder eine separate design.md geschrieben, und erst dann detaillierte Anforderungen.
• Bugfix-Spezifikation. Ein separater Modus für Korrekturen: Statt „was soll erscheinen“ – „was reproduziert den Bug“, „was war das erwartete Ergebnis“, „was soll sich bei der Korrektur nicht ändern“. Details in Teil 11.

Im Lehrprojekt AgentClinic werden Sie fast immer im Modus „Zuerst Anforderungen“ arbeiten. Die Namen der anderen Modi dienen dazu, das erste Template nicht dorthin zu dehnen, wo es stört.

Beispielanfrage an Qwen Code für den Projektüberblick

Du hilfst mir, nach SDD zu arbeiten.
Schreibe noch keinen Code.
Lies @README.md und schau dir die Repository-Struktur an.
Schlage einen initialen specs/-Katalog vor:
- mission.md
- tech-stack.md
- roadmap.md

Stelle vor dem Schreiben der Dateien genau drei gruppierte Fragen:
1. Mission und Zielgruppe
2. Technischer Stack und Einschränkungen
3. Roadmap und erste Phase

Praxis

Erstellen Sie im Lehrprojekt eine leere Struktur:

mkdir -p specs

touch specs/mission.md specs/tech-stack.md specs/roadmap.md

Lassen Sie die Dateien vorerst leer. Im nächsten Teil konfigurieren wir Qwen Code so, dass er die Projektregeln versteht, und füllen dann die Verfassung bewusst aus.

Kontrollfragen

1. Warum ist es besser, die Feature-Spezifikation neben dem Code zu speichern und nicht in einem separaten Dokument?
2. Wann muss man eine Neugestaltung durchführen?
3. Was zeigt eine erfolgreiche Implementierung nach /clear?