Specs und Todos
Zwei Wege, Arbeit festzuhalten. Ein Todo ist eine Notiz für später: eine kleine Sache, geparkt in einer Datei. Eine Spec ist ein Vertrag für jetzt: ein geschriebener Plan mit Schritten und Prüfungen, den ein Agent ausführt und ein unabhängiger Reviewer abnimmt. Die meiste Arbeit braucht keins von beiden.
Was brauche ich?
| Situation | Nutze | Beispiel |
|---|---|---|
| Kleine Änderung, in dieser Session erledigt | nichts — einfach fragen | „Tippfehler im Footer korrigieren" |
| Kleine Änderung, nicht jetzt | Todo | /todo Upload bei abgelaufenem Token wiederholen |
| Mehrere kleine, unabhängige Punkte für später | je ein Todo | drei Funde aus einem Review |
| Eine größere Übergabe an einen anderen Agenten | Spec | ein /wave-Slice, über der Größenschwelle |
| Mehr als 5 Schritte oder mehr als 6 Dateien über 2+ Subsysteme | Spec | „Dark Mode für Shop und Admin" |
| Eine Entscheidung, die du vorher treffen musst | Spec (oder Todo mit --status decision) | „Stripe oder Mollie?" |
| Du willst einen geschriebenen Plan | Spec | „Plan das durch" |
Faustregel: Ein Todo merkt sich etwas, eine Spec verpflichtet. Eine kleine Sache, die nur auf eine spätere Session wartet, ist ein Todo, keine Übergabe.
Todos
Ein Todo ist eine Markdown-Datei unter devkit/todos/<id>.md mit ID, Titel, Status, Abhängigkeiten und Notiz. Sie liegt in Git, jeder Worktree sieht dieselbe Liste.
Im Alltag
| Du tippst | Was passiert |
|---|---|
/todo <text> oder todo: <text> | Parkt den Text als neue Datei und committet nur diese. Es wird nichts umgesetzt. |
/todo oder /todo list | Listet alle Todos mit Zustand. |
/todo next | Bearbeitet das älteste bereite Todo. |
/todo next --parallel N | Bis zu N Todos ohne gemeinsame Dateien parallel per Delegate. |
/todo pick <id> | Bearbeitet genau dieses Todo. |
Der Agent bietet Todos für Nebenarbeit selbst an und parkt in langen Sessions von sich aus.
Was „ein Todo bearbeiten" heißt
Ein Lauf besitzt genau ein Todo, vom Claim bis zum Commit:
- Claim — das Todo wird für diesen Worktree gesperrt, eine parallele Session kann es nicht nehmen.
- Isolieren — ein sauberer Checkout arbeitet direkt; ein schmutziger bekommt einen eigenen
todo/<id>-Worktree. - Umsetzen — nur dieses Todo.
- Prüfen — die Projektprüfungen und die betroffenen Tests müssen grün sein.
- Commit — ein Commit mit dem Fix, der gelöschten Todo-Datei und dem Trailer
Todo: <id>.
Ein roter Check oder eine offene Frage gibt das Todo frei — mit Notiz, und nur die Dateien dieses Laufs werden zurückgesetzt.
Zustände in /todo list
| Zustand | Bedeutung |
|---|---|
open | Bereit. /todo next wählt daraus. |
claimed | Wird gerade bearbeitet. |
blocked | Wartet auf ein anderes Todo aus dependencies. |
decision | Braucht erst eine menschliche Entscheidung; kann nicht geclaimt werden. |
spec | Ist zur Spec geworden; dort geht es weiter. |
done | Erledigt. |
Mehrere Punkte auf einmal parken ergibt je eine Todo-Datei; bearbeitet wird bewusst eins pro Lauf, damit jeder Fix ein prüfbarer Commit ist.
Für die laufende Arbeit führt devkit todo plan einen Plan pro Worktree über Sessions und Runtimes; die Statuszeile zeigt ihn, plan park macht Offenes zu Todos.
Specs
Eine Spec ist ein in sich vollständiger Markdown-Vertrag: Eine frische Session oder ein anderes Modell kann sie ohne den Chat ausführen. Sie trägt Ziel, Schritte mit Verify-Befehlen, Abnahmekriterien und den Dateiumfang. /spec wählt die günstigste sichere Route:
| Route | Wann | Was du bekommst |
|---|---|---|
todo | Aufgeschoben oder mehrere unabhängige Kleinigkeiten | Todo-Dateien, keine Spec |
direct | Klein genug für jetzt | Kurzer Auftrag im Chat, keine Datei |
compact | Ein Spec-Auslöser greift — Größe, größere Übergabe, offene Entscheidung oder dein Wunsch | Kurze Spec-Datei |
full | Spec nötig, dazu hohes Risiko, irreversible Migration, Sicherheitsgrenze, öffentlicher Vertrag, 3+ Subsysteme oder neue Architektur | Volle Spec; unabhängiges Authoring-Review außer bei dokumentierter Ausnahme |
Lebenszyklus
| Phase | Was passiert |
|---|---|
/spec "<ziel>" | Schreibt und validiert den Plan und zeigt eine Zusammenfassung; korrigiere sie, wenn er dich falsch verstand. |
/spec-work NNN | Der Start ist die Freigabe — keine extra Frage. Eine frische Session ist günstiger, weil die Spec alles mitbringt. |
| Umsetzen und prüfen | Jeder Schritt und jedes Abnahmekriterium wird grün. |
| Unabhängiges Review | Ein separater Reviewer prüft den Diff gegen den Vertrag; grüne ACs allein zählen nie. |
| Completed | Die Spec ist fertig; du committest mit /commit. |
Status
| Status | Bedeutung |
|---|---|
draft | Geschrieben, startbereit. |
in-progress | /spec-work setzt um. |
paused | Bewusst angehalten; das Progress Log sagt, wo. |
in-review | Code eingefroren, Reviewer prüft. |
blocked | Eine Stop-Bedingung oder wiederholter Fehler braucht dich. |
completed | Review bestanden, Datei verlässt die aktive Liste. |
Wenn sich etwas ändert
| Situation | Tu das |
|---|---|
| Session mitten im Lauf beendet | Nochmal /spec-work NNN — setzt beim ersten offenen Schritt fort. |
| Plan passt nicht mehr zum Code oder Umfang wächst | /spec-update NNN "<änderung>" — schreibt den Vertrag neu und öffnet betroffene Schritte. |
Kleiner Fix nach completed | Einfach fragen — die Spec ist jetzt ein Protokoll. |
| Mehrere freigegebene Specs auf verschiedenen Dateien | /wave führt sie parallel in Worktrees aus. |
| Arbeit über Schwester-Repositories | /workspace schreibt eine Spec pro Repository. |
Verwandt
- Workflows — wo Specs und Todos im Alltag sitzen.
- Skill-Übersicht — Skill wählen und seine Referenz öffnen.