Teil 10. Neugestaltung des Projekts

Nach dem ersten Feature möchte man sofort das nächste bauen. Im SDD ist eine Pause besser. Die Neugestaltung ist der Moment, in dem Sie die Projektdokumente aktualisieren, solange die Abweichung noch gering ist. Je schneller der Agent Code schreibt, desto wichtiger ist es, regelmäßig zu den Projektregeln zurückzukehren.

Die Neugestaltung beantwortet folgende Fragen:

• Was haben wir nach der vorherigen Phase gelernt;
• Muss der Technologie-Stack aktualisiert werden;
• Ist die Roadmap veraltet;
• Welche Prüfungen sollten verpflichtend werden;
• Gibt es einen wiederholbaren Prozess, der sich automatisieren lohnt.

Beispiel einer Neugestaltung nach Hello Hono

Nach dem ersten Feature kann man erkennen:

• Vitest wird für Prüfungen benötigt;
• Responsives Design wird als Projektregel benötigt;
• CHANGELOG.md wird benötigt;
• Die Roadmap ist zu zersplittert oder umgekehrt zu grob;
• Die Anfrage an Qwen Code für die Feature-Spezifikation wiederholt sich und lädt zu einem Skill ein.

Erstellen Sie einen Branch:

git checkout -b replanning-after-hello-hono

Anfrage:

/clear
Lies @specs/mission.md, @specs/tech-stack.md, @specs/roadmap.md
und die abgeschlossene Spezifikation des Features Hello Hono.

Wir führen eine Neugestaltungsphase durch.
Implementiere keine neuen Produktfeatures.
Schlage Änderungen vor für:

1. Testrichtlinie mit Vitest;
2. Responsives Design als allgemeine Produktanforderung;
3. Führung eines Änderungsprotokolls;
4. Größe der Phasen in der Roadmap.

Liste die vorgeschlagenen Dateiänderungen vor der Bearbeitung auf.

Aktualisierung von tech-stack.md

Fügen Sie die Testrichtlinie hinzu:

## Testen

- Vitest prüft Routen, Komponenten und Datenbank.
- `npm test` muss `vitest run` starten.
- In Feature-Prüfdateien müssen verpflichtende automatische Prüfungen benannt sein.

Fügen Sie die Einschränkung für die Benutzeroberfläche hinzu:

## Benutzeroberfläche

- HTML wird serverseitig über Hono JSX gerendert.
- Normales CSS, wenn keine neue Abhängigkeit explizit genehmigt wird.
- Seiten müssen bei mobiler Breite 375px und Desktop-Breite 1280px funktionieren.

Aktualisierung alter Spezifikationen

Wenn sich Projektregeln ändern, können alte Feature-Spezifikationen unvollständig werden. Bitten Sie Qwen Code:

Aktualisiere bestehende Feature-Spezifikationen an die neue Testrichtlinie
und das responsive Design.
Ändere die Implementierung noch nicht, es sei denn, die aktualisierte Prüfung erfordert es.
Zeige vor der Bearbeitung eine kurze Zusammenfassung.

Das ist wichtig: Die Spezifikationsgeschichte muss erklären, welche Regeln zum Zeitpunkt der Implementierung galten.

Änderungsprotokoll als Kommunikation

CHANGELOG.md ist nicht nur für Menschen nützlich. Der Agent kann es auch als kurze Projektgeschichte lesen.

Beispiel:

# Änderungsprotokoll

## 2026-05-01

- Projektverfassung für SDD hinzugefügt.
- Basis-Feature Hello Hono implementiert.
- Mockup, statisches CSS und strenge TypeScript-Prüfung hinzugefügt.

Anfrage:

Erstelle oder aktualisiere @CHANGELOG.md.
Verwende Überschriften mit Datumsangaben.
Stütze dich auf die Git-Historie und Änderungen des aktuellen Branches.
Schreibe kurz und verständlich für Stakeholder.

Änderung der Phasengröße in der Roadmap

Schlechte Roadmap:

## Phase 2: Alle App-Features bauen

Zu weit gefasst. Der Agent wird viele Änderungen vornehmen, für den Menschen wird die Prüfung schwierig.

Schlechte Roadmap:

## Phase 2: Einen CSS-Abstand hinzufügen

Zu kleinteilig. Mehr Overhead als Nutzen.

Gute Roadmap:

## Phase 2: Agenten und Krankheiten

Ziel: Basis-Domänenmodell und rein lesbare Seiten hinzufügen.

- [ ] SQLite-Schema für Agenten und Krankheiten hinzufügen.
- [ ] Anfangliche fiktive Daten hinzufügen.
- [ ] Seiten /agents und /ailments hinzufügen.
- [ ] Routen- und Komponententests hinzufügen.

Kodifizierungsschritt: Was zu einer Regel machen

Die Neugestaltung ist der Moment, in dem Sie einmalige Beobachtungen in dauerhafte Regeln verwandeln. Wenn Sie das nicht tun, wird jedes nächste Feature denselben Fehler wiederholen, und der Agent wird jedes Mal neu raten.

Kodifizierung ist die Aufzeichnung einer Beobachtung als eines von vier Artefakten:

• **Regel in QWEN.md.** Geeignet, wenn die Beobachtung das Verhalten des Agenten betrifft: "Ändere tsconfig.json nie ohne Bestätigung", "Zeige immer die Liste geänderter Dateien vor dem Schreiben".
• **Entscheidung in tech-stack.md.** Geeignet, wenn die Beobachtung eine langfristige technische Wahl betrifft: "Wir verwenden Vitest für alle Tests", "Kein ORM in den ersten Phasen", "Alle Tabellen erhalten created_at".
• **Vorlage in validation.md.** Geeignet, wenn die Beobachtung die Form der Prüfung betrifft: "Für Route 200 und 404 prüfen", "Für Migration Idempotenz durch erneutes Ausführen prüfen".
• Hook, Skill oder Anfrage. Geeignet, wenn die Beobachtung sich mechanisch wiederholt und sich leichter automatisieren lässt (siehe Teile 14 und 17).

Einfache Anfrage für den Kodifizierungsschritt am Ende des Neugestaltungs-Branches:

Basierend auf dem Feature Hello Hono und der durchgeführten Neugestaltung schlage vor

Liste von Änderungen in QWEN.md, tech-stack.md, validation.md-Vorlage
und dem Set von Hooks/Skills. Für jeden Punkt gib an:
1. die Beobachtung, die dazu geführt hat;
2. die vorgeschlagene Regel oder das Artefakt;
3. in welche Datei es eingetragen werden soll;
4. warum es nicht nur im Chat gehalten werden sollte.
Ändere die Dateien vorerst nicht.

Wenn die Liste länger als 5–7 Punkte ist, versuchen Sie nicht, alles auf einmal umzusetzen — wählen Sie die zwei bis drei häufigsten Beobachtungen, notieren Sie sie und lassen Sie den Rest für die nächste Neugestaltung.

Feedback-Fliehkraft: Signal → Was aktualisieren

Damit die Kodifizierung nicht zu einem großen Ritual wird, halten Sie eine kurze Zuordnung "Signal → Was aktualisieren" griffbereit. Es ist praktisch, dies als Fliehkraft zu betrachten: Jede Beobachtung aus dem letzten Feature löst eine Aktualisierung aus, die die Wahrscheinlichkeit desselben Problems im nächsten verringert.

| Test bestanden, aber das tatsächliche Verhalten war falsch | Neuer Fakt in validation.md, möglicherweise anderer Ebene (siehe Teil 9) | | Entscheidung erschien im Code, aber nicht in requirements.md | Nachträglich in requirements.md über Neugestaltungs-Branch eintragen | | Gleichartige Anfrage an den Agent wiederholt sich bereits zum dritten Mal | Anfrage in .qwen/skills/<name>/SKILL.md auslagern | | Gefährlicher Befehl wurde fast ausgeführt | Schützenden Hook hinzufügen (Teil 17) | | Geheimnis ist fast in die Spezifikation gerutscht | Regel in QWEN.md + Prüfszenario (Teil 18) |

Die Liste erhebt keinen Anspruch auf Vollständigkeit. Ihre Aufgabe ist zu zeigen, dass es für jeden bemerkten Fehler einen dauerhaften Ort zur Aufzeichnung der Reaktion gibt. Wenn sich der Ort nicht finden lässt, ist das ein Signal, dass der Projektstruktur ein Abschnitt fehlt, der angelegt werden sollte.

Commit der Neugestaltung

npm test
npm run typecheck
git add specs CHANGELOG.md package.json package-lock.json vitest.config.ts tests
git commit -m "Replan workflow after first feature"
git checkout main
git merge replanning-after-hello-hono
git branch -d replanning-after-hello-hono

Praxis

1. Erstellen Sie einen Branch für die Neugestaltung.
2. Aktualisieren Sie die Testrichtlinie.

1. Fügen Sie die Anforderung an responsives Design hinzu.
2. Erstellen Sie das Änderungsprotokoll.
3. Präzisieren Sie die Roadmap.
4. Committen und mergen Sie.

Kontrollfragen

1. Warum sollte die Neugestaltung zwischen Features stattfinden, nicht innerhalb der Implementierung?
2. Welche Änderungen gehören zu Projektregeln, welche zur Feature-Spezifikation?
3. Wie hilft das Änderungsprotokoll dem Agenten?