Teil 21. Abschluss und funktionierendes System

SDD ist kein Haufen Dateien um der Dateien willen. Es ist ein funktionierendes System, das einem Menschen hilft, die Kontrolle zu behalten, wenn ein Agent in Minuten das ändern kann, was früher Stunden gedauert hat. Die wichtigste Fähigkeit besteht nicht darin, maximal lange Prompts zu schreiben, sondern die richtigen Grenzen zwischen Absicht, Planung, Umsetzung und Überprüfung zu ziehen.

Wenn man eine Formel behalten soll, lautet sie so:

Die Spezifikation speichert die langfristige Absicht.
Fakten entscheiden, ob ein Branch gemerged werden darf.
Der Agent führt schnell aus.
Der Mensch trägt die Verantwortung für das Urteil.

Oder noch kürzer:

Spezifikationen leiten.
Fakten erlauben das Mergen.

Endgültige Repository-Struktur

agentclinic/
  AGENTS.md
  QWEN.md
  README.md
  CHANGELOG.md
  package.json
  tsconfig.json
  .qwen/
    settings.json
    hooks/
      pre_tool_guard.py
      log_tool_result.py
      inject_sdd_context.py
    memory/
      agent-memory.db
    skills/
      feature-spec/
        SKILL.md
      changelog/
        SKILL.md
  specs/
    mission.md
    tech-stack.md
    roadmap.md
    2026-05-01-hello-hono/
      requirements.md
      plan.md
      validation.md
    2026-05-02-agents-ailments/
      requirements.md

plan.md
      validation.md
  src/
  tests/
.github/
  pull_request_template.md

Betriebszyklus

Vor jedem Feature:

git checkout main
git pull --ff-only
git status --short
npm test
npm run typecheck

In Qwen Code:

/clear
Verwende den Skill feature-spec, um das nächste Feature aus der Roadmap zu beginnen.
Implementiere keinen Code.

Nach der Spezifikation:

git add specs/YYYY-MM-DD-feature-name
git commit -m "Add <feature> spec"

Umsetzung:

/clear
Lies @QWEN.md, @specs/mission.md, @specs/tech-stack.md
und @specs/YYYY-MM-DD-feature-name/plan.md.
Implementiere nur Aufgabengruppe 1.
Stoppe nach dem Bericht über geänderte Dateien und Prüfbefehlen.

Überprüfung:

/clear
Vergleiche die Umsetzung mit @specs/YYYY-MM-DD-feature-name/validation.md.
Liste bestätigte Fakten, fehlgeschlagene Fakten, fehlende Fakten
und mehrdeutige Prüfpunkte auf.
Ändere keine Dateien.

Merge:

Verwende den Skill changelog, um @CHANGELOG.md für diesen Branch zu aktualisieren.

npm test
npm run typecheck
git checkout main
git merge <feature-branch>
git branch -d <feature-branch>

Neuplanung:

/clear

Prüfe @specs/mission.md, @specs/tech-stack.md, @specs/roadmap.md,
jüngste Feature-Spezifikationen und @CHANGELOG.md.
Was muss vor dem nächsten Feature aktualisiert werden?
Ändere keine Dateien, bis ich es genehmige.

Entscheidungsgrenzen

Schreibe in mission.md:

• Zielgruppe;
• Produktsinn;
• Ton;
• Erfolgsdefinition.

Schreibe in tech-stack.md:

• Sprache;
• Laufzeitumgebung;
• Framework;
• Datenbank;
• Testen;
• Bereitstellungsbeschränkungen;
• verbotene oder zurückgestellte Technologien.

Schreibe in roadmap.md:

• Phasenreihenfolge;
• Phasenstatus;
• kleine lieferbare Ergebnisse;
• was als nächster Schritt gilt.

Schreibe in die Feature-Spezifikation:

• Grenzen und was nicht dazugehört;
• Entscheidungen genau für dieses Feature;
• Aufgabengruppen;
• Faktensammlung in validation.md;
• Prüfbefehle mit erwarteten Ergebnissen;
• Faktenstatus: Entwurf, verpflichtend, umgesetzt, zurückgestellt;
• manuelle Prüfungen.

Schreibe in QWEN.md oder AGENTS.md:

• Agent-Verhaltensregeln;
• Prüfbefehle;
• Verbot spekulativer Refactorings;
• Anforderung, zuerst Spezifikationen und dann Code zu schreiben.

Häufigste Fehler

1. Zu großes erstes Feature. Beginne mit einer Infrastrukturvorlage, nicht mit einem MVP.

1. Spezifikation ist geschrieben, wird aber im Umsetzungsprompt nicht verwendet.
2. Überprüfung beschränkt sich auf "sieht normal aus" statt auf Fakten.
3. Neuplanung wird übersprungen, und Spezifikationen veralten.
4. Dem Agent wird alter Chat-Kontext statt Dateien gegeben.
5. Skills werden zu früh erstellt, bevor der Prozess verstanden ist.
6. In QWEN.md wird alles Mögliche reingepackt, und der Agent hört auf, dem Wichtigsten zu folgen.
7. MCP wird ohne klare Aufgabe angebunden.

Wie man in einem echten Team einführt

Beginne nicht mit einem 20-seitigen Prozess, sondern mit einer einzigen Regel:

Kein mehrdateiliges Feature ohne requirements.md, plan.md und validation.md.

Füge dann hinzu:

• kurzes AGENTS.md;
• specs/mission.md;
• specs/tech-stack.md;
• Roadmap für die nächsten 3–5 Phasen;
• einen Projektskill für Feature-Spezifikation;
• einen Skill für das Änderungsprotokoll;
• verpflichtende Prüfliste im Merge-Request.

Nach 2–3 Features führe eine Retrospektive durch:

• wo der Agent geraten hat;
• welche Spezifikationen nutzlos waren;
• welche Prüfungen echte Fehler gefunden haben;
• welche Prüfpunkte Wünsche statt Fakten waren;
• was automatisiert werden sollte.

Minimale SDD-Vorlage

specs/
  mission.md
  tech-stack.md
  roadmap.md
  YYYY-MM-DD-feature/

requirements.md
    plan.md
    validation.md

Das reicht für den Anfang. Man muss nicht auf das perfekte Framework warten.

SDD-Reifegradskala

Um zu verstehen, wo man steht und wohin man sich bewegt, ist es hilfreich, den SDD-Prozess in einem Team anhand einer kurzen Skala von 0 bis 4 zu beschreiben. Diese Skala erhebt keinen Anspruch auf Kanon; sie hilft zu erkennen, welcher Schritt jetzt den größten Nutzen bringt.

• Stufe 0 — Vibe-Coding. Ein langer Chat mit dem Agent. Entscheidungen bleiben in der Sitzungshistorie. Es gibt keine Spezifikationen, die Überprüfung lautet "schau, wie es läuft".
• Stufe 1 — Spezifikationen erscheinen, aber fakultativ. Bei großen Features schreibt das Team requirements.md, bei kleinen nicht. validation.md ähnelt meist einer Wunschliste. /clear zwischen Rollen wird vergessen.
• Stufe 2 — SDD als Standard-Default. Jedes mehrdateilige Feature beginnt mit einer Spezifikation. validation.md enthält ausführbare Fakten. /clear zwischen Rollen ist zur Gewohnheit geworden. Neuplanung findet zwischen Features statt.
• Stufe 3 — kodifizierter Prozess. Wiederholte Prompts sind in Skills ausgelagert. Schutzhooks prüfen gefährliche Operationen automatisch. Review läuft in vier Ebenen (Teil 16). Antipatterns (Teil 20) werden erkannt und schnell behoben.

• Stufe 4 — lernfähiger Prozess. Das Team wandelt Beobachtungen regelmäßig in neue Regeln um (Teil 10, Kodifizierungsschritt). Agentenspeicher wird dort angebunden, wo er wirklich nützlich ist, und entfernt, wo er überflüssig ist. Agentenersetzbarkeit (Teil 15) ist praktisch geprüft: Das Team hat das Tool gewechselt und den Prozess nicht verloren.

Die meisten Lern-Teams befinden sich zwischen Stufe 0 und 2. Das Ziel dieses Handbuchs ist es, Ihr Team in einem didaktischen AgentClinic-Projekt auf Stufe 2 zu bringen. Stufen 3 und 4 betreffen dann das konkrete Team, das konkrete Produkt und das konkrete Jahr. Sie sollten nicht Selbstzweck sein.

Zeichen, dass man von Stufe 1 auf 2 gewechselt ist: Ein neues Feature im Team beginnt standardmäßig mit einer Spezifikation, nicht mit der Bitte "schreib Code".

Zeichen, dass man von Stufe 2 auf 3 gewechselt ist: Wenn sich ein wiederkehrender Agent-Fehler zeigt, sagt jemand ruhig "lassen wir eine Regel in QWEN.md hinzufügen", und diese Regel erscheint tatsächlich.

Abschlussübung

Nehmen Sie Ihr reales Projekt und fügen Sie nur hinzu:

1. AGENTS.md oder QWEN.md;
2. specs/mission.md;
3. specs/tech-stack.md;
4. specs/roadmap.md;
5. Spezifikation eines kleinen Features.

Bitten Sie Qwen Code:

Handle wie ein neuer Agent ohne vorherigen Kontext.

Lies die projektbezogenen SDD-Artefakte.
Sag, ob du das nächste Feature sicher umsetzen kannst.
Liste fehlende Informationen auf, bevor du Code schreibst.

Wenn der Agent gute Fragen stellt, sind Sie auf dem richtigen Weg.

Kontrollfragen

1. Welche Dateien sollten einem neuen Agenten ermöglichen, das Projekt zu verstehen?
2. Was tun, wenn die Umsetzung die Tests besteht, aber nicht der Spezifikation entspricht?
3. Welcher kleinste SDD-Prozess kann morgen eingeführt werden?