Teil 11. Zweite Feature-Phase

Die zweite Feature-Phase prüft, ob der Prozess wiederholbar geworden ist. Das erste Feature läuft oft auf Enthusiasmus. Das zweite zeigt, ob Sie sauber beginnen, Grenzen halten, das Änderungsprotokoll aktualisieren und vor dem Umfang der Änderungen nicht ermüden können.

In AgentClinic kann die zweite Phase „Agenten und Leiden“ heißen. Sie führt SQLite ein, Tabellen für Agenten und Leiden, Anfangsdaten, Seiten /agents und /ailments, Tests und Navigation.

Checkliste für sauberen Start

Vor einem neuen Feature-Zweig:

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

In Qwen Code:

/clear

Prüfen Sie die Roadmap:

Lies @specs/roadmap.md.
Welche ist die nächste unvollendete Phase?
Dateien nicht ändern.

Wenn es unvollendete Änderungen gibt, beginnen Sie keine neue Phase. Andernfalls werden die vom Agenten generierten Änderungen schwer zu erklären sein.

Erstellung der Spezifikation für die zweite Phase

Anfrage:

Beginne die nächste Feature-Phase aus @specs/roadmap.md.
Erstelle einen Feature-Zweig und ein Spezifikationsverzeichnis mit Datum.

Vor dem Schreiben der Dateien stelle mir genau drei Gruppen von Fragen:
1. Grenzen: welche Domänenentitäten und Seiten gehören zur Phase?

2. Entscheidungen: Datenbank, Anfangsdaten, Schnittstellenkonventionen, Tests?
3. Kontext: Ton, Einschränkungen, Risiken und was außerhalb der Grenzen bleiben soll?

Verwende @specs/mission.md und @specs/tech-stack.md.
Code noch nicht implementieren.

Antworten können wie folgt aussehen:

Grenzen:
Agenten und Leiden nur lesend hinzufügen. Listen- und Agentenseiten einschließen.
Vorerst ohne Terminbuchung und ohne Formulare.

Entscheidungen:
SQLite mit handgeschriebenen Migrationen verwenden. Fiktive Anfangsdaten hinzufügen.
Hono-Routen und serverseitig gerenderte Komponenten verwenden.
Routen- und Komponententests mit Vitest hinzufügen.

Kontext:
Inhalt soll satirisch sein, Implementierung jedoch verständlich.
Schnittstelle soll responsiv sein. Ohne clientseitiges JavaScript.

Kognitive Belastung und Grenzprüfung

Die zweite Phase ist meist größer als die erste. Wenn der Agent in einem Durchgang Dutzende Dateien ändert, kann ein Mensch sie physisch nicht bewältigen – das Auge gleitet, Fehler schlüpfen durch. Um nicht in diesem Strom zu ertrinken:

• implementieren Sie Aufgabengruppen einzeln oder paarweise;
• machen Sie Zwischencommits;
• bitten Sie Qwen Code, Änderungen nach Aufgabengruppe zusammenzufassen;

• verwenden Sie /review, wenn Ihre Qwen Code-Version einen eingebauten Prüfprozess unterstützt;
• akzeptieren Sie keine Änderungen, die nicht mit der Spezifikation übereinstimmen.

Beispielanfrage für die Prüfung:

/clear
Prüfe den aktuellen Zweig gegen @specs/2026-05-02-agents-ailments/plan.md
und @specs/2026-05-02-agents-ailments/validation.md.

Fokussiere dich auf:
1. Überschreitung der Phasengrenzen;
2. Sicherheit der Datenbankmigrationen;
3. Lücken in der Testabdeckung;
4. Widersprüche mit @specs/tech-stack.md.

Dateien nicht ändern.

Beispiel für Aufgabengruppen

# Plan — Agenten und Leiden

## Gruppe 1 — Datenbankstart

1. better-sqlite3 installieren.
2. Datenbankverbindungsmodul hinzufügen.
3. Wiederholbaren Migrationsmechanismus hinzufügen.

## Gruppe 2 — Domänenschema

4. Agententabelle hinzufügen.
5. Leidentabelle hinzufügen.
6. Verknüpfungstabelle agent_ailments hinzufügen.

## Gruppe 3 — Anfangsdaten

7. Fiktive Agenten hinzufügen.
8. Fiktive Leiden hinzufügen.
9. Agenten mit Leiden verknüpfen.

## Gruppe 4 — Routen und Komponenten

10. Listen-Seite /agents hinzufügen.
11. Detailseite /agents/:id hinzufügen.
12. Seite /ailments hinzufügen.

## Gruppe 5 — Tests und Prüfung

13. Routentests hinzufügen.
14. Komponenten-Rendering-Tests hinzufügen.
15. npm test und npm run typecheck ausführen.

Stilentscheidungen müssen ebenfalls in Spezifikationen stehen

Wenn Sie entscheiden, dass die Markenfarben Orange und Schwarz sind, darf das nicht nur im Chat bleiben. Notieren Sie:

## Visuelle Richtung

- Primäre Markenfarben: Orange und Schwarz.
- Farbe als Akzent verwenden, nicht als Seitenthema.
- Seiten sollen lesbar und präsentationsfreundlich bleiben.

Anfrage für Qwen Code:

Aktualisiere die nötigen Spezifikationen: AgentClinic-Markenfarben sind Orange und Schwarz.
Aktualisiere dann CSS nur dort, wo nötig.
Stil nicht zusammenhängender Seiten nicht ändern.

Fehlerbehebungsspezifikation statt Feature-Spezifikation

Nicht jeder Zweig ist ein neues Feature. Ein Teil der Arbeit ist Fehlerbehebung: ein Benutzer hat festgestellt, dass die Agentenliste nicht in der richtigen Reihenfolge sortiert wird, oder dass die Formularvalidierung eine leere Nachricht durchlässt. Für solche Änderungen ist die requirements.md-Vorlage schlecht geeignet: die Frage „was soll erscheinen“ ist hier sekundär, die Hauptfragen sind „was ist bereits defekt“, „warum“ und „was darf sich bei der Reparatur nicht verschieben“.

In solchen Fällen ist ein separater Modus nützlich – die Fehlerbehebungsspezifikation. Die Ordnerstruktur ist dieselbe:

specs/
  2026-05-12-feedback-empty-message-bug/
    bugfix.md
    plan.md
    validation.md

Nur statt requirements.md haben Sie bugfix.md mit einem anderen Satz von Abschnitten.

# Fehlerbehebung — POST /feedback lässt leere Nachricht durch

## Aktuelles Verhalten

Beim Absenden eines Formulars mit leerem Feld `message` gibt der Server 302 zurück und speichert
eine Zeile mit leerer Nachricht in der Tabelle `feedback`. Auf der Seite /feedback wird solch ein
Eintrag als leerer Block angezeigt.

## Erwartetes Verhalten

Bei leerem `message` gibt der Server 400 zurück und die Seite `/feedback/new`
mit Feldhervorhebung und Fehlertext „Nachricht erforderlich“. Kein Eintrag in der Datenbank
wird erstellt.

## Nachweis der Ursache

In `src/routes/feedback.ts` akzeptiert die POST-Route den Body ohne Validierungsaufruf:
der Body wird direkt in den Eintrag übergeben. Das ist im Commit 3a7c1b9 der Phase
2026-05-10-feedback-form sichtbar, wo die Validierung mit der Notiz `// TODO` aufgeschoben wurde.

## Was sich nicht ändern darf

- Die GET-Route /feedback gibt weiterhin die Listen-Seite zurück.
- Bestehende Einträge in der Tabelle `feedback` werden nicht bearbeitet oder gelöscht.

- Formularfeldnamen (`name`, `message`) bleiben unverändert.
- Fehlerformat 400 stimmt mit den übrigen Projektrouten überein.

## Regressionsszenarien

- POST mit nicht leerem `message` speichert weiterhin den Eintrag und gibt 302 zurück.
- POST mit leerem `name`, aber nicht leerem `message` wird gespeichert (falls es vor dem Bug so war).
- Seite /feedback zeigt alle zuvor gespeicherten Einträge unverändert.

plan.md für Fehlerbehebungen ist meist kürzer: eine Gruppe für den Fix selbst, eine – für den Regressionstest, der genau diesen Bug fängt.

validation.md enthält zwingend einen Fakt-Repro: einen Befehl oder Szenario, der vor der Behebung fehlschlägt und nach der Behebung besteht. Das ist die Prüfung, dass genau das repariert wurde, was defekt war:

### F1 — leere Nachricht wird abgelehnt

- Befehl: `npm test -- feedback`
- Erwartung: POST /feedback mit leerer message gibt 400 zurück und erstellt keine Zeile
- Verantwortlich: automatische Prüfung
- Status: Entwurf

Der Hauptunterschied zwischen Fehlerbehebung und Feature ist der zwingende Abschnitt „Was sich nicht ändern darf“ und die zwingende Regression. Ohne sie „verbessert“ der Agent oft benachbarten Code und zerstört das, was funktionierte.

Wenn sich im Verlauf herausstellt, dass die Fehlerbehebung zu einer Überarbeitung wird – mehrere verwandte Bugs, neues Schema, Modul-Umschreibung – schließen Sie den Fehlerbehebungszweig, übertragen Sie die Ergebnisse in einen gewöhnlichen Feature-Zweig und planen Sie neu. Das ist keine Niederlage, sondern ein normales Signal, dass die Aufgabe aus dem Modus „reparieren“ in den Modus „neu machen“ gewachsen ist.

Änderungsprotokoll vor dem Zusammenführen

Aktualisiere @CHANGELOG.md nach der Arbeit in diesem Zweig.
Verwende eine Überschrift mit aktuellem Datum.
Erwähne Domänenschema, Routen, Seiten, Tests und Spezifikationsaktualisierungen.
Schreibe kurz.

Praxis

• [ ] Beginnen Sie den zweiten Feature-Zweig von sauberem main.
• [ ] Erstellen Sie die Spezifikation durch Interview.
• [ ] Implementieren Sie Gruppen in Teilen.
• [ ] Prüfen Sie die Grenzüberschreitung.
• [ ] Aktualisieren Sie das Änderungsprotokoll.
• [ ] Führen Sie erst nach Prüfung zusammen.

Kontrollfragen

1. Woher kommt die kognitive Belastung bei der Arbeit mit einem Agenten und welche SDD-Techniken senken sie?
2. Warum müssen Stilentscheidungen in Spezifikationen aufgezeichnet werden?
3. Welche Anzeichen zeigen, dass eine Phase zu groß ist?