Teil 2. Warum Entwicklung nach Spezifikationen

Vibe Coding ist nützlich, wenn Sie eine Idee erkunden, einen Einweg-Prototyp erstellen oder schnell die Form einer Lösung sehen möchten. Aber es hält einem langen Projektleben nicht stand. Im Chat gibt es kein dauerhaftes Gedächtnis, Anforderungen vermischen sich mit Korrekturen, und Architekturentscheidungen entstehen oft zufällig.

SDD löst dieses Problem nicht durch Magie, sondern durch die Verlagerung des Kontexts aus flüchtigen Unterhaltungen in versionierte Dateien. Der Agent erhält nicht nur den Befehl „mach das“, sondern auch eine Karte des Projekts: warum es existiert, welche Entscheidungen bereits getroffen wurden, was gerade gebaut wird, wie die Fertigstellung überprüft wird.

Typische Ausfälle des Vibe Coding

1. Absichtsverschiebung. Sie baten um ein „einfaches Formular“, der Agent fügte komplexes Zustandsmanagement, eine neue Bibliothek und einen anderen Interfacestil hinzu.
2. Kontextzerfall. Nach mehreren Sitzungen vergisst der Agent, warum das Projekt kein ORM verwendet oder warum die API HTML serverseitig rendern muss.
3. Nicht überprüfbares Ergebnis. Der Agent änderte 30 Dateien, und Sie wissen nicht, nach welchen Kriterien Sie das annehmen sollen.
4. Verborgene Entscheidungen. Wichtige Entscheidungen blieben im Chatverlauf und gelangten nicht ins Repository.

1. Reviewer-Ermüdung. Der Agent schreibt schnell, aber der Mensch ermüdet, große Mengen von Änderungen zu prüfen.

SDD macht den Agent nicht fehlerfrei. Es macht Fehler früher, kleiner und überprüfbar.

Was sich in der Arbeit mit Qwen Code ändert

Anstelle einer langen Sitzung wie:

qwen
> Baue die gesamte Anwendung.
> Repariere das.
> Sieht nicht richtig aus.
> Füge Tests hinzu.
> Verwende doch SQLite.

erstellen Sie einen stabilen Zyklus:

qwen
> /clear
> Lies @specs/mission.md @specs/tech-stack.md @specs/roadmap.md.
> Erstelle eine Feature-Spezifikation für die nächste Phase der Roadmap. Stelle mir zuerst Fragen.

Dann in einer neuen Sitzung:

qwen
> /clear
> Lies @specs/mission.md @specs/tech-stack.md und @specs/2026-05-08-reviews-display/plan.md.
> Implementiere nur die Aufgabengruppen 1 und 2. Ändere keine unzusammenhängenden Dateien.

Und separat für die Prüfung:

qwen
> /clear
> Vergleiche die Implementierung mit @specs/2026-05-08-reviews-display/validation.md.
> Liste Abweichungen auf, bevor du Korrekturen vornimmst.

Jede Sitzung erhält genau den Kontext, der für ihre Rolle benötigt wird.

SDD ist nicht gleich Wasserfallmodell

Das klassische Wasserfallmodell versucht, das gesamte System im Voraus zu beschreiben. Bei SDD mit Agenten sind Spezifikationen klein, lebendig und auf ein einzelnes Feature ausgerichtet. Sie schreiben keine 80 Seiten vor dem Start. Sie fixieren genug Kontext für den nächsten sinnvollen Schritt.

Eine gute Feature-Spezifikation sollte sein:

• klein: eine Phase, ein Branch und ein Merge;
• überprüfbar: es gibt Befehle und manuelle Prüfszenarien;
• mit der Roadmap verknüpft;
• für einen neuen Agenten ohne vorherigen Chat verständlich;
• streng genug, damit der Agent keine wichtigen Entscheidungen errät.

Sieben Fragen, die eine gute Spezifikation beantwortet

Um eine Spezifikation nicht auf eine Sammlung von Überschriften zu reduzieren, halten Sie sieben Fragen im Kopf. Wenn auf eine davon keine Antwort vorhanden ist, ist die Spezifikation noch nicht bereit für die Implementierung.

1. Welche Geschäftsabsicht oder Produktaufgabe steht hinter dem Feature? Das heißt, warum wir das tun, nicht „was“ und „wie“.
2. Wer ist der Benutzer und welches Szenario hat er? Wenn das Feature nur ein Administrator nutzt, ist das ein anderer Entscheidungssatz, als wenn es ein Besucher sieht.
3. Was gehört zur Arbeit, was nicht? Explizit aufgeführte Grenzen und explizites „außerhalb der Grenzen“ schützen vor Ausbreitung.

1. Welche Entscheidungen sind bereits getroffen, welche offen? Die Aufzeichnung getroffener Entscheidungen ist nötig, damit der Agent nicht neu wählt. Die Aufzeichnung offener Entscheidungen – damit der Mensch sie bemerkt und vor der Implementierung schließt.
2. Welche Einschränkungen dürfen nicht gelockert werden? Stack, Invarianten, Datenschema, API-Format, Sicherheitsbeschränkungen.
3. Was darf nicht kaputtgehen? Bestehendes Verhalten, das das Feature nicht berühren darf (siehe separater Abschnitt über negative Anforderungen in Teil 7).
4. Wie wird bewiesen, dass das Ergebnis korrekt ist? Befehle, manuelle Szenarien, Kontrollwerte, Anzeichen für Abweichungen. Ohne das ist die Spezifikation ein Wunsch, kein Vertrag.

Diese sieben Fragen diktieren nicht die Dateistruktur. Die Struktur bleibt gleich: requirements.md, plan.md, validation.md. Die sieben Fragen sind eine Inhaltsprüfung.

Wann SDD übermäßig ist

Man braucht keine vollwertige Verfassung für ein einmaliges Shell-Skript oder eine kleine Textkorrektur. Eine leichte Anfrage ist manchmal besser. Praktische Regel:

• wenn die Änderung vollständig in 5 Minuten verstanden und geprüft werden kann, reicht eine normale Anfrage;
• wenn die Änderung Architektur, Daten, Sicherheit, öffentliches Verhalten oder mehrere Dateien berührt, schreiben Sie eine Spezifikation;

• wenn der Agent länger als einige Minuten autonom arbeiten wird, lohnt sich eine Spezifikation fast immer.

Beispiel: Schlechte Zeitersparnis

Sie bitten:

Füge Login hinzu.

Der Agent kann JWT, Cookie-Sessions, OAuth, lokale Benutzer, passwortlose Login-Links, PostgreSQL, SQLite, Prisma, Drizzle, Passwort-Reset, Middleware und Interface wählen. Wenn die Hälfte der Entscheidungen falsch ist, verlieren Sie Zeit für Rollbacks.

Besser beschreiben Sie zuerst:

# Anforderungen – Admin-Login

## Grenzen
- Eine Login-Seite nur für Administratoren.
- Authentifizierung über Cookie-Session.
- Ohne Selbstregistrierung.
- Ohne Passwort-Reset in dieser Phase.

## Entscheidungen
- Einen Admin in SQLite speichern.
- httpOnly-Cookie verwenden.
- Nur `/dashboard` schützen.

## Prüfung
- Nicht authentifizierter GET /dashboard leitet auf /login um.
- Falsches Passwort zeigt allgemeine Fehlermeldung.
- Richtiges Passwort setzt Cookie und leitet auf /dashboard um.
- `npm test` und `npm run typecheck` bestehen.

Jetzt muss der Agent nicht erraten.

Praxis

Nehmen Sie ein beliebiges Feature, das Sie normalerweise in einem Satz erledigt hätten. Schreiben Sie es als Mini-Spezifikation um:

# Anforderungen – <Feature-Name>

## Grenzen

## Außerhalb der Grenzen

## Entscheidungen

## Prüfung

Dann stellen Sie Qwen Code die Frage:

Prüfe @requirements.md als Feature-Spezifikation. Was darin ist unklar genug, dass die Implementierung abweichen könnte?

Bitten Sie nicht um Code, bis die Unklarheit beseitigt ist.

Kontrollfragen

1. Wodurch unterscheidet sich SDD auf Feature-Ebene von großem Vorabdesign?
2. Warum ist „Code funktioniert“ nicht genug für die Annahme von Agent-Änderungen?
3. Welche Entscheidungen in Ihrem Projekt müssen vor der Codegenerierung festgehalten werden?