Glossar

Zusammenfassende Liste der Begriffe des Lehrbuchs. Dient als Referenz in jedem Teil – Definitionen werden hier dupliziert, um Widersprüche im Text zu vermeiden.

SDD-Artefakte

Projektverfassung – drei Dateien in specs/, die langfristige Entscheidungen festhalten: mission.md (warum und für wen), tech-stack.md (wie), roadmap.md (was und in welcher Reihenfolge). Ändert sich nur in der Umplanungsphase.

**mission.md** – Zweck, Zielgruppe, Ton, Erfolgsdefinition.

**tech-stack.md** – Sprache, Umgebung, Framework, Datenbank, Testen, Einschränkungen. Wenn eine Entscheidung hier nicht festgehalten ist, kann sie vom Agent ergänzt werden.

**roadmap.md** – geordnete Phasen mit Status. Jede Phase ist ein Kandidat für einen eigenen Feature-Branch.

Feature-Spezifikation – Ordner specs/YYYY-MM-DD-feature-name/ mit drei Dateien:

• **requirements.md** – Grenzen, was nicht dazugehört, Entscheidungen genau dieser Features, Kontext.
• **plan.md** – nummerierte Aufgabengruppen zur Umsetzung.
• **validation.md** – Sammlung von Fakten und Fertigkeitskriterien (siehe unten).

**QWEN.md** – permanenter Kontext für Qwen Code: Verhaltensregeln des Agenten in diesem Repository.

**AGENTS.md** – allgemeiner Vertrag für jeden KI-Agenten. Qwen Code liest beide Dateien, wenn vorhanden.

**CHANGELOG.md (Projekt)** – Änderungsprotokoll des Lernprojekts. Wird vor dem Merge vom Skill changelog aktualisiert.

Bugfix-Spezifikation – Ordner specs/YYYY-MM-DD-bugfix-name/ mit den Dateien bugfix.md, plan.md, validation.md. Wird anstelle der üblichen Feature-Spezifikation verwendet, wenn die Aufgabe darin besteht, bereits funktionierendes Verhalten zu reparieren, statt Neues hinzuzufügen. In bugfix.md sind die Abschnitte „Aktuelles Verhalten“, „Erwartetes Verhalten“, „Nachweis der Ursache“, „Was sich nicht ändern darf“, „Regressionsszenarien“ obligatorisch. In validation.md ist ein Repro-Fakt obligatorisch: ein Befehl oder Szenario, der vor der Korrektur fehlschlägt und nach der Korrektur durchläuft. Details in Teil 11.

Negative Anforderungen – Abschnitt der Spezifikation, der beschreibt, was sich bei der Umsetzung eines Features oder Bugfixes nicht ändern darf: welche Routen, Verträge, Verhaltensweisen und Daten gleich bleiben. Bei einem normalen Feature der Abschnitt „Außerhalb der Grenzen“, bei einer Bugfix-Spezifikation „Was sich nicht ändern darf“. Schützt vor „Verbesserungen nebenbei“, die der Agent leicht einbauen kann, wenn die Grenze nicht festgeschrieben ist.

Lebenszyklus von Fakten

Fakt – ausführbare oder eindeutig überprüfbare Aussage, anhand derer ein eindeutiges Urteil „bestanden / nicht bestanden“ gefällt werden kann. Durch Befehl, Test, HTTP-Status, Datenbankinvariante.

Fakt-Ebenen in validation.md:

• Beispiel – konkretes Ein-/Ausgabe-Paar.
• Invariante – etwas, das immer wahr ist (nach Aktion, in jedem DB-Zustand usw.).
• Eigenschaft – prüft eine Klasse von Fällen.
• Vertrag – formale Verknüpfung „bei Bedingung X führt Aktion Y zu Z“.

Fakt-Status:

• draft – vorgeschlagen, aber noch nicht akzeptiert.
• spec – als für das Feature verbindlich akzeptiert.
• implemented – es gibt einen Test, Befehl oder manuelle Bestätigung.
• deferred – bewusst in eine zukünftige Phase verschoben.

Beweispaket – Sammlung von Artefakten, die dem Merge-Request beigefügt werden und bestätigen, dass der Branch bereit ist: Link zur Feature-Spezifikation, Vermerke über ausgeführte automatische Prüfungen aus validation.md, Protokoll manueller Prüfungen, bei Bedarf Screenshots, Request-Dumps, Log-Auszüge. Keine separate Datei, sondern eine Struktur des Merge-Request-Kommentars. Nimmt dem Reviewer die Pflicht ab, das gesamte Szenario von Grund auf nachzuvollziehen. Details in Teil 9.

Prozesse

Umplanung – separater Branch zwischen Features, in dem mission.md, tech-stack.md, roadmap.md, Testpolitik, Änderungsprotokoll aktualisiert werden. Implementiert keine Produktfeatures.

MVP-Phase – Zusammenstellung einer minimal lebensfähigen Version aus mehreren Phasen auf einmal. Stresstest der Reife von Spezifikationen; riskanter als ein normales Feature.

KI-Ermüdung (früher als Lehnübersetzung von AI fatigue anzutreffen) – Ermüdung des Menschen durch das Volumen an Änderungen, die der Agent schneller produziert, als der Mensch sie prüfen kann. SDD reduziert sie durch kleine Phasen, explizite Grenzen und Fakt-Prüfung.

Drift (engl. drift) – Abweichung der Implementierung von der Spezifikation. Kann im Code, in den Fakten und in der Spezifikation selbst auftreten (wenn sich die Projektregein geändert haben, das Feature aber nicht).

Eskalationsregeln – in QWEN.md oder in einem Skill festgehaltener Katalog von Situationen, in denen der Agent anhalten und die Kontrolle an den Menschen zurückgeben muss: uneindeutige Anforderungen, fehlender benötigter Fakt in validation.md, Konflikt mit specs/tech-stack.md, Notwendigkeit einer zerstörerischen Aktion, neue Abhängigkeit. Ohne diese Regeln neigt der Agent dazu, stillschweigend Entscheidungen zu treffen, die später zurückgerollt werden müssen. Details in Teil 14.

SDD-Reifeskala – kurze deskriptive Skala des Prozesszustands im Team, von 0 („Vibe-Coding“) bis 4 („lernfähiger Prozess“). Erhebt keinen Kanon-Anspruch; dient als Spiegel, um zu erkennen, welcher Schritt aktuell den größten Nutzen bringt. Ziel des Lehrbuchs ist es, das Team im didaktischen Projekt auf Stufe 2 zu bringen. Details in Teil 21.

Qwen Code Werkzeuge

Skill – Verzeichnis mit SKILL.md, das beschreibt, wann und wie der Agent einen bestimmten Prozess anwenden soll. Persönlich (~/.qwen/skills/) oder projektspezifisch (.qwen/skills/).

Hook – Shell-Befehl, den Qwen Code bei Eintreten eines Ereignisses ausführt (SessionStart, UserPromptSubmit, PreToolUse, PostToolUse, Stop usw.). Nützlich für Logging, Kontextergänzung, Grenzwahrung.

MCP – Model Context Protocol; externe Ebene von Werkzeugen und Datenquellen, die dem Agenten über mcpServers in settings.json oder qwen mcp add angebunden werden.

ACP – Agent Client Protocol; Protokoll für die Kommunikation zwischen Agent und IDE/Client. Wird beispielsweise bei der Arbeit mit Qwen Code aus JetBrains verwendet.

Headless-Modus (engl. headless) – qwen -p "..."; startet den Agenten ohne interaktive Sitzung, für Automatisierung und CI.

Kontextdegradation (engl. context rot) – in Studien beobachtete Qualitätsverschlechterung der Modellantworten mit wachsendem Input: auf langem irrelevantem Kontext werden relevante Stücke schlechter gefunden als auf kurzem fokussiertem. Praktische Konsequenzen im Lehrbuch: /clear zwischen Rollen, Injektion nur relevanter Memory-Einträge in QWEN.md, Begrenzung der Länge des beigemischten Kontexts. Details in Teil 14 und Teil 19.

Externe SDD-Frameworks

GitHub Spec Kit – offenes Framework mit Standardzyklus /constitution → /specify → /clarify → /plan → /tasks → /analyze → /implement.

AWS Kiro – IDE mit eigenem SDD-Modell: Specs (requirements.md + design.md + tasks.md), Steering-Dateien, Agent-Hooks.

Die Übereinstimmung des Lehrbuchs mit Spec Kit und Kiro siehe in Anhang A.

Antipatterns (siehe Teil 20)

• Spezifikation nach dem Code – Artefakt wird für die Berichterstattung geschrieben, nicht für die Steuerung.
• **Riesiges requirements.md** – Spezifikation mit 50 Punkten, die niemand ausführt.
• **validation.md, den niemand ausgeführt hat** – Fakten sind theoretisch.
• Abschwächung von Fakten nach Fehlern – Fakt wird umgeschrieben statt Code korrigiert.
• **Rituelles /clear** – Kontextlöschung ohne Verständnis dessen, was sie wirklich bewirkt.
• Skill als Wunderknopf – Team ruft Skill auf, ohne SKILL.md zu lesen.
• **QWEN.md als Müllhalde** – wird zu unlesbarem Teppich, Agent folgt dem Wesentlichen nicht mehr.
• Hook, der stillschweigend das Projekt ändert – ohne Logging, ohne Rückmeldung an den Menschen.
• Memory als versteckte Wahrheitsquelle – verbindliche Regeln leben nur in SQLite, nicht in Spezifikationen.

• MCP ohne Aufgabe – wird angebunden, weil es möglich ist.
• Zu großes MVP – ohne Reife der Spezifikationen.