Prozess des Features
Hauptprinzip: Je weniger Entscheidungen der Agent selbst trifft, desto stabiler ist das Ergebnis. Jede Phase endet mit einem Artefakt in docs/features/<slug>/ und einer Überprüfung („Gate"). Wo gekennzeichnet, erfolgt der Übergang nur nach Bestätigung durch den Menschen.
Wie man den Code selbst schreibt – fsd-frontend; Prüfung auf Müll – anti-slop-review; Einstieg und Sitzung – frontend-auth-session.
1. Phasen
| # | Phase | Artefakt | Genehmigt durch | Gate |
|---|---|---|---|---|
| 0 | Vorbereitung | Branch | — | Arbeitsbaum sauber; nach Installation von Abhängigkeiten und Migrationen – /clear |
| 1 | PRD | prd.md | Mensch | Nicht-Ziele gefüllt; Kriterien überprüfbar; keine technischen Lösungen |
| 2 | Spezifikation | spec.md, bis 150 Zeilen | Mensch | Deckt alle PRD-Kriterien ab und nichts darüber hinaus |
| 3 | Aufgaben | tasks.md | Mensch | Eine Aufgabe – ein Commit; erste – Tracer Bullet |
| 4 | Recherche | Log in tasks.md | — | Nur Lesen; gefunden, was wiederverwendet werden kann |
| 5 | Tracer Bullet | Commit | — | Ein Szenario durchläuft vollständig und ist im Browser sichtbar |
| 6 | Build | Commit pro Aufgabe | — | Test zuerst für Logik; pnpm check grün |
| 7 | Review | Bericht reviewer | Mensch (nach Befunden) | Bestätigte Befunde korrigiert |
| 8 | Browser | e2e für kritischen Pfad | — | PRD-Szenarien bestehen ohne Konsolenfehler |
Eine kleine Aufgabe (ein Commit, kein neues Verhalten für den Benutzer) überspringt die Phasen 1–3, aber die Nicht-Ziele werden dennoch in der Aufgabenbeschreibung festgehalten. Ein Überspringen einer Phase wird explizit genannt und nicht stillschweigend durchgeführt.
2. PRD
Vorlage – docs/features/_template/prd.md.
- Der Agent erstellt einen Entwurf aus der Anfrage und fragt nur das, ohne das nicht fortgefahren werden kann. Der Rest sind Annahmen in „Offenen Fragen", die der Mensch bei der Genehmigung bestätigt.
- Nicht-Ziele sind verpflichtend. Liste das auf, was der Agent „nebenbei" machen möchte: Responsivität für neue Größen, Animationen, i18n, Caching, Admin-Panel, Refactoring von benachbartem Code. Ohne diese Liste wächst das Feature ausufernd.
- Bereitschaftskriterien sind überprüfbar: „Gegeben / Wenn / Dann", nicht „bequem" und „schnell".
- Keine Bibliotheken, Dateien und Schemata: Es geht um „Was und warum", nicht „Wie".
3. Spezifikation
Vorlage – docs/features/_template/spec.md.
- Bis zu 150 Zeilen. Vom Agenten geschrieben, vom Menschen genehmigt. Eine lange generierte Spezifikation ist schlechter als keine: Sie verstopft den Kontext und verwischt Entscheidungen.
- Vor dem Schreiben – eine kurze Nur-Lesen-Übersicht der betroffenen Schichten: Was gibt es bereits, was kann wiederverwendet werden.
- Enthält: Wo der Code lebt (Schichten, Slices), Datenverträge (zod-Schemata, DTO-Mapping), API (Eingabe, Ausgabe, Fehler →
kind), UI-Zustände, Grenzfälle, Abnahmeszenarien mit Testebene. - Die Spezifikation lebt mit dem Code. Ändert sich das Verhalten, wird
spec.mdim selben Commit korrigiert. Code, der von der Spezifikation abweicht, ist ein Defekt von einem der beiden.
4. Aufgaben
Vorlage – docs/features/_template/tasks.md.
- Eine Aufgabe – ein Commit, nach dem das Projekt gebaut wird und Prüfungen bestehen. Wenn der Agent in eine Sackgasse gerät, ist ein Zurücksetzen auf den vorherigen Commit günstiger als eine Diskussion mit dem Modell.
- Eine Aufgabe passt in eine Sitzung; jede hat ein „Fertig, wenn".
- Die erste Aufgabe ist der Tracer Bullet, danach Zustände, Grenzfälle, Feinschliff.
5. Recherche (nur Lesen)
Vor jeder Aufgabe, ohne Dateiänderungen:
AGENTS.mdder betroffenen Ordner;- vorhandener Code, der Ähnliches löst (
rgnach Namen und Verträgen); - Verträge und Typen, auf die die Aufgabe sich stützt.
Wenn das Gefundene später benötigt wird – 2–3 Zeilen im Log von tasks.md.
6. Tracer Bullet
Ein Szenario durchgängig: Route → Seite → Feature oder Entität → request() → Route Handler oder Backend → Ergebnis auf dem Bildschirm.
- Dies ist Produktionscode, kein Prototyp: richtige Schichten, echte Verträge aus der Spezifikation.
- Bewusst ohne: detaillierte Validierung, Polieren von Lade- und Fehlerzuständen, Stile, Grenzfälle.
- Backend nicht bereit – Handler mit MSW oder Route Handler, der Daten gemäß Vertrag aus der Spezifikation liefert; dies wird in
tasks.mdvermerkt. - Überprüfung – im Browser: Szenario durchläuft, und in der Konsole gibt es keine Fehler.
7. Build
- Logik – Test zuerst: reine Funktionen, Stores, Antwort-Mapping, Hooks mit Verzweigungen. Der Test sollte aus erwartetem Grund fehlschlagen, dann kommt der Code. Ein nach dem Code geschriebener Test neigt dazu, das zu prüfen, was der Code tut, nicht das, was gefordert ist.
- Layout und Stile – ohne Test im Voraus: Diese prüft der Browser (Phase 8), der kritische Pfad wird durch e2e abgedeckt.
- Nach einer Aufgabe:
pnpm check, Commit (lint-staged prüft geänderte Dateien). - Stopp: Drei fehlgeschlagene Versuche, denselben Fehler zu beheben – Stopp. Beschreibe dem Menschen, was versucht wurde und welche Hypothese besteht. Passe Tests nicht an den Code an, deaktiviere keine Linter-Regeln, schwäche keine Typen ab.
- Alles, was außerhalb der Aufgabe liegt, kommt ins Log „später", nicht in diesen Commit.
8. Review
- Sub-Agent
reviewer(.claude/agents/reviewer.md) mit sauberem Kontext: Übergib den Pfad zuprd.mdundspec.mdsowie den Commit-Bereich; den Diff liest er selbst. Der Autor des Codes sieht seine eigenen Fehler schlechter: In seinem Kontext befinden sich Argumente, warum die Lösung richtig ist. - Bestätigte Befunde werden korrigiert, strittige entscheidet der Mensch.
- Sicherheit prüft auch der Mensch: Login, Sitzungen, Redirects, Cookies, Benutzereingaben in HTML. Grüne Prüfungen garantieren dies nicht: In der Praxis hat ein offener Redirect Tests bestanden und eine unlesbare Fehlerseite den Linter.
9. Browser
- Next.js: Skill
next-dev-loopmitagent-browser, falls installiert; sonst Playwright oder Chrome DevTools MCP. - Durchlaufe die PRD-Szenarien, einschließlich negativer: leere Daten, Netzwerkfehler, erneutes Absenden. Überwache Konsole und Anfragestatus.
- Für UI – helles und dunkles Thema, Telefonbreite.
- Kritischer Pfad – e2e-Test in
e2e/. - Fertig, wenn jedes PRD-Kriterium geprüft ist; in der Abschlussnachricht – Liste der Kriterien und wie jedes geprüft wurde.
10. Kontext
- Der Arbeitsstand lebt in
docs/features/<slug>/, nicht im Chat: Beginne eine neue Sitzung mit dem Lesen vonprd.md,spec.md,tasks.md. - Nach lauten Schritten (Installation, Migrationen, lange Logs) –
/clear. - Parallele Experimente – in
git worktree, nicht im Arbeitsbranch.
11. Was nicht zu tun
- Endlose Rückfragen: Frage nur, was blockiert, der Rest sind Annahmen im PRD.
- Orchestratoren aus vielen Agenten: Ein Ausführender und ein Reviewer reichen aus.
- Spezifikationen und Dokumentation, die niemand genehmigt hat und liest.
- Stillschweigendes Überspringen von Phasen und „nebenbei gefixt".