docs: add batch orchestrator section to README
Document run-batch usage, checkpoint modes, parallelization, safety rules, and example workflow for human readers. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
beo3000
parent
befa2c16e0
commit
37a61f97a9
94
README.md
94
README.md
|
|
@ -40,6 +40,83 @@ Decisions are tracked in `docs/B_planning/decisions-log.md` across all phases.
|
|||
**Switch phases:** `/project:phase-transition`
|
||||
- Only when all Definition-of-Done items in the current phase are checked off.
|
||||
|
||||
## Batch-Modus: Mehrere Tasks automatisiert abarbeiten
|
||||
|
||||
Wenn die nächsten Schritte bereits geplant sind (z.B. Discovery-Waves, User Stories schreiben, Module analysieren), erspart der Batch-Modus den manuellen Session-Zyklus:
|
||||
|
||||
```
|
||||
Vorher: session-start → Aufgabe → session-end → clear → commit → repeat (pro Task)
|
||||
Nachher: /project:run-batch → N Tasks laufen durch → Review → fertig
|
||||
```
|
||||
|
||||
### So funktioniert's
|
||||
|
||||
**Starten:** `/project:run-batch` oder natürlichsprachlich ("Arbeite die nächsten 3 Tasks ab").
|
||||
|
||||
Claude liest die `task.md` der aktiven Phase, zeigt die offenen Tasks, und fragt nach:
|
||||
- **Welche Tasks?** — alle, bestimmte Nummern, oder eine Gruppe
|
||||
- **Checkpoint-Modus?** — wann soll für Review pausiert werden
|
||||
|
||||
### Checkpoint-Modi
|
||||
|
||||
| Modus | Verhalten | Wann verwenden |
|
||||
|-------|-----------|----------------|
|
||||
| `after-each` (Standard) | Pause nach jeder Gruppe, Zusammenfassung zeigen | Neue/unsichere Tasks |
|
||||
| `after-batch:N` | N Gruppen durchlaufen, dann pausieren | "Mach 3, dann schau ich" |
|
||||
| `at-end` | Alles durchlaufen, am Ende Review | Gut verstandene Tasks |
|
||||
|
||||
### Parallelisierung
|
||||
|
||||
Tasks sind in `task.md` unter `###`-Überschriften gruppiert:
|
||||
- Tasks **unter dem gleichen Heading** laufen **parallel** (z.B. 3 Module gleichzeitig)
|
||||
- **Zwischen Gruppen** wird **sequenziell** gearbeitet (Wave 2 wartet auf Wave 1)
|
||||
|
||||
### Was passiert im Hintergrund
|
||||
|
||||
1. Pro Task wird ein **Subagent** mit frischem Context gestartet
|
||||
2. Jeder Subagent schreibt sein Ergebnis in eine **eigene Output-Datei**
|
||||
3. Die Output-Dateien sind sofort in VS Code sichtbar — du kannst sie während des Laufs beobachten
|
||||
4. Am **Checkpoint** zeigt Claude eine Tabelle mit Status und Zusammenfassung pro Task
|
||||
5. Du entscheidest: `weiter`, `stopp`, oder `zeig mir [datei]`
|
||||
6. Am Ende: Claude aktualisiert task.md, status.md und decisions-log.md und schlägt einen Commit vor
|
||||
|
||||
### Sicherheitsregeln
|
||||
|
||||
- **Phasengrenze ist ein harter Stopp** — der Batch läuft nie automatisch in die nächste Phase
|
||||
- **Fehlgeschlagene Tasks** bleiben offen (`[ ]`) und werden beim Checkpoint gemeldet
|
||||
- **Ohne bestätigte Parameter** startet kein Batch — Claude fragt immer nach
|
||||
|
||||
### Beispiel
|
||||
|
||||
```
|
||||
Du: /project:run-batch
|
||||
|
||||
Claude: Ich sehe 5 offene Tasks in Phase 1 — Discovery:
|
||||
1. [ ] structure-map.md (Wave 1)
|
||||
2. [ ] entry-points.md (Wave 2)
|
||||
3. [ ] Module: auth (Wave 3)
|
||||
4. [ ] Module: invoicing (Wave 3)
|
||||
5. [ ] Module: reporting (Wave 3)
|
||||
|
||||
Welche Tasks? (alle / Nummern / Gruppe)
|
||||
Checkpoint-Modus? (after-each / after-batch:N / at-end)
|
||||
|
||||
Du: alle, after-each
|
||||
|
||||
Claude: [dispatcht Wave 1 → Checkpoint → Wave 2 → Checkpoint → Wave 3 parallel → Checkpoint]
|
||||
Claude: Batch abgeschlossen. 5/5 erfolgreich. Soll ich committen?
|
||||
```
|
||||
|
||||
### Permissions
|
||||
|
||||
Damit der Batch nicht an Berechtigungsdialogen hängen bleibt, müssen die nötigen
|
||||
Tools in `.claude/settings.json` freigeschaltet sein. Das Projekt enthält bereits
|
||||
eine passende Konfiguration. Falls nicht vorhanden:
|
||||
|
||||
```json
|
||||
{ "permissions": { "allow": ["Read", "Write", "Edit", "Glob", "Grep", "Agent"] } }
|
||||
```
|
||||
|
||||
## User Stories
|
||||
|
||||
User stories are created during Phase 2 (Planning) and bridge the gap between
|
||||
|
|
@ -83,7 +160,10 @@ docs/
|
|||
C_integration/ — Phase 3 working directory
|
||||
templates/ — Document templates (read-only reference)
|
||||
rules/ — Constraints Claude follows automatically
|
||||
batch-orchestration.md — Rules for batch/subagent execution
|
||||
.claude/commands/ — Slash commands for session workflow
|
||||
run-batch.md — Batch orchestrator command
|
||||
.claude/settings.json — Project-level tool permissions
|
||||
```
|
||||
|
||||
|
||||
|
|
@ -102,4 +182,16 @@ Das Session-Protokoll ist kein Extra-Overhead für spezielle Anlässe — es ist
|
|||
|
||||
Die task.md muss auch nicht in Session 1 perfekt sein. Du kannst mit 2-3 DoD-Punkten starten und sie in späteren Sessions erweitern, wenn du den Legacy-Code besser verstehst.
|
||||
|
||||
Kurz: Jede Interaktion = eine Session. Das Protokoll ist der Herzschlag des Frameworks, nicht ein Sonderereignis.
|
||||
Kurz: Jede Interaktion = eine Session. Das Protokoll ist der Herzschlag des Frameworks, nicht ein Sonderereignis.
|
||||
|
||||
## Wann Session-Workflow, wann Batch?
|
||||
|
||||
| Situation | Empfehlung |
|
||||
|-----------|------------|
|
||||
| Erkundend, unklar was als nächstes kommt | `/project:session-start` → manuell arbeiten |
|
||||
| Nächste Schritte klar, Tasks in task.md definiert | `/project:run-batch` |
|
||||
| Ein einzelner, klar definierter Task | Manuell oder Batch mit einem Item |
|
||||
| Viele unabhängige Module analysieren | Batch mit Parallelisierung |
|
||||
|
||||
Der Batch-Modus ergänzt den Session-Workflow — er ersetzt ihn nicht grundsätzlich.
|
||||
Für explorative Arbeit bleibt der manuelle Zyklus der richtige Ansatz.
|
||||
Loading…
Reference in New Issue