KI-Coding

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.

BT

BetterToken

Redaktion
3 Min. Lesezeit

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:

RolleKernaufgabeEingabeartefakteAusgabeartefakte
Author AgentImplementierung und lokale Unit-TestsAufgabenbeschreibung, AbnahmekriterienGit-Branch, Diff, fokussierte Testsuite
Reviewer AgentEdge Cases finden und Regressionen prüfenGit-Diff, Handoff-Karte, PrüfkommandosStrukturierte Review-Checkliste (Pass/Block)
Menschliche EntscheidungsinstanzArchitektur bewerten und final mergenReviewer-Zusammenfassung, CI/CD-StatusManueller 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:

  1. Sitzungskontext: Unabhängige Gesprächsfäden reduzieren wechselseitige Halluzinationen und zirkuläre Bestätigung.
  2. Dateisystem-Isolation: Separate Git-Worktrees sorgen dafür, dass der Reviewer nur einen festgeschriebenen Diff und keinen schmutzigen Arbeitsstand prüft.
  3. 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:

  1. Er wechselt in den sauberen Worktree ../agent-reviewer.
  2. Er führt das dokumentierte Prüfkommando aus.
  3. Er untersucht den Diff unabhängig auf Nebenwirkungen und Randfälle.
  4. 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 main bestä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.

Bereit, Ihren LLM-Workflow zu optimieren?

Verbinden Sie Modelle über eine API, verwalten Sie Schlüssel und behalten Sie KI-Kosten im Blick.