Multi-Agent-Workflow in Claude Code: Rollen, Isolation und manuelle Prüfung
Praxisleitfaden für Multi-Agent-Workflows in Claude Code mit Rollentrennung, Git-Worktree-Isolation, Handoff-Karte und manueller Abnahme.
Inhalt
Multi-Agent-Workflow in Claude Code: Rollen, Isolation und manuelle Prüfung
Vollständig autonome „KI-Agententeams“, die Code automatisch zusammenführen, führen leicht zu subtilen Architekturfehlern, zirkulären Refactoring-Schleifen und einer schleichenden Verschlechterung der Codebasis. Zwei parallel arbeitende Agenten erzeugen keine unabhängige Wahrheit: Macht der Autor einen Denkfehler, kann ein Reviewer mit ähnlichen Prompt-Grundlagen ihn ebenfalls übersehen.
Ein belastbarer Multi-Agent-Workflow beruht daher nicht auf dem Versprechen völliger Autonomie, sondern auf sauber getrennten Rollen: einem umsetzenden Author, einem unabhängigen Reviewer und einem Menschen, der die Merge-Entscheidung trifft.
1. Klare Rollen: Author, Reviewer und verantwortliche Entwicklerperson
In einem funktionierenden Entwicklungsablauf hat jede beteiligte Rolle einen klar abgegrenzten Verantwortungsbereich:
| Rolle | Kernaufgabe | Eingabeartefakte | Ausgabeartefakte |
|---|---|---|---|
| Author Agent | Implementierung und lokale Unit-Tests | Aufgabenbeschreibung, Abnahmekriterien | Git-Branch, Diff, fokussierte Testsuite |
| Reviewer Agent | Edge Cases finden und Regressionen prüfen | Git-Diff, Handoff-Karte, Prüfkommandos | Strukturierte Review-Checkliste (Pass/Block) |
| Menschliche Entscheidungsinstanz | Architektur bewerten und final mergen | Reviewer-Zusammenfassung, CI/CD-Status | Manueller Merge in den main-Branch |
2. Kontext- und Workspace-Isolation
Lassen Sie Author und Reviewer nie im selben Arbeitsverzeichnis oder im selben Gesprächsfaden arbeiten. Trennen Sie sie auf drei Ebenen:
- Sitzungskontext: Unabhängige Gesprächsfäden reduzieren wechselseitige Halluzinationen und zirkuläre Bestätigung.
- Dateisystem-Isolation: Separate Git-Worktrees sorgen dafür, dass der Reviewer nur einen festgeschriebenen Diff und keinen schmutzigen Arbeitsstand prüft.
- Umgebungssicherheit: API-Schlüssel und Laufzeit-Credentials bleiben in Umgebungsvariablen und werden nie als Prompt-Text übergeben.
Befehle zum Vorbereiten der Worktrees
git worktree add ../agent-author -b feat/payment-retry
git worktree add ../agent-reviewer feat/payment-retry[!IMPORTANT]
API-Konfiguration: Jede Claude-Code-Sitzung verwendet eigene API-Zugangsdaten, die über Betriebssystem-Umgebungsvariablen gesetzt werden. Die aktuelle Einrichtung beschreibt die BetterToken-Dokumentation für Claude Code.
3. Der strukturierte Handoff-Vertrag
Nach Abschluss der Umsetzung erstellt der Author eine kurze Handoff-Karte. Rohe Chat-Protokolle, Geheimnisse und unbestätigte Annahmen gehören nicht hinein:
### Handoff Card
- **Task**: Add HTTP 429 retry support in payment client with exponential backoff.
- **Branch**: `feat/payment-retry`
- **Changed Files**: `src/client/http.ts`, `tests/http-retry.test.ts`
- **Verification Command**: `npm test -- tests/http-retry.test.ts` (Passed)
- **Risks & Blockers**: Exponential backoff capped at 3 attempts; socket timeout left unchanged.
- **Next Step**: Reviewer agent validates Retry-After header handling.4. Freigabeprotokoll mit menschlicher Entscheidung
Der Reviewer führt seine Prüfung isoliert aus:
- Er wechselt in den sauberen Worktree
../agent-reviewer. - Er führt das dokumentierte Prüfkommando aus.
- Er untersucht den Diff unabhängig auf Nebenwirkungen und Randfälle.
- Er erstellt eine strukturierte Zusammenfassung für die verantwortliche Entwicklerperson.
Die finale Freigabe bleibt beim Menschen:
- Die Review-Ergebnisse prüfen;
- keine Regressionen gegenüber
mainbestätigen; - den Merge manuell ausführen:
git merge feat/payment-retry.
Diese Pipeline begrenzt gegenseitige Bestätigungsfehler und hält Qualitäts- sowie Architekturverantwortung bei den Entwickelnden.
