Du hast die Screenshots gesehen. Fuenf, zehn, fuenfzehn Claude Code Agenten laufen in tmux, jeder arbeitet an einem anderen Teil derselben Codebase. Sieht produktiv aus. Sieht spannend aus. Und wenn du versucht hast, das nachzubauen, weisst du: Es sieht deutlich einfacher aus als es ist.
Einen Claude Code Agenten laufen zu lassen ist unkompliziert. Du gibst ihm eine Aufgabe, er schreibt Code, du reviewst. Zwei sind machbar, bringen aber ein neues Problem: Sie koennten sich gegenseitig in die Quere kommen. Ab fuenf brauchst du ein System. Zehn ohne System ist Chaos mit Monatsrechnung.
In diesem Guide geht es um genau dieses System. Nicht die Theorie von Multi-Agent-Architekturen. Der tatsaechliche, praktische Workflow fuer das Ausfuehren mehrerer Claude Code Agenten auf einer echten Codebase, ohne dass alles auseinanderfaellt.
Warum ein Agent nicht reicht
Ein einzelner Claude Code Agent kann erstaunlich viel erledigen. Aber er arbeitet sequenziell. Waehrend er ein Backend-Endpoint implementiert, liegt dein Frontend brach. Waehrend er Tests schreibt, bleibt die Dokumentation liegen. Waehrend er einen Build-Fehler debuggt, warten drei neue Features in der Queue.
Die Rechnung aendert sich, wenn man realisiert, dass der Grossteil von Software-Arbeit parallelisierbar ist. Eine Frontend-Komponente und ein Backend-API-Endpoint teilen sich keine Dateien. Eine Test-Suite und ein Doku-Update beruehren verschiedene Verzeichnisse. Ein Architektur-Review und ein Bugfix operieren auf voellig unterschiedlichen Zeitskalen.
Der Flaschenhals bei Single-Agent-Entwicklung ist nicht die Geschwindigkeit des Agenten. Es ist die Pipeline-Tiefe. Ein Agent bedeutet eine Sache gleichzeitig in Arbeit. Mehrere Agenten bedeuten mehrere Dinge gleichzeitig in Arbeit, und das veraendert, was ein einzelner Entwickler an einem Tag shippen kann.
Strategien zur Arbeitsaufteilung
Bevor du ein zweites tmux-Pane oeffnest, musst du entscheiden, wie du die Arbeit aufteilst. Drei Muster haben sich in der Praxis bewaehrt.
Aufteilung nach Komponente
Der einfachste Ansatz. Agent A gehoert components/, Agent B gehoert server/, Agent C gehoert lib/. Jeder Agent arbeitet in seinem Territorium und fasst Dateien ausserhalb davon nie an.
Das funktioniert gut, wenn deine Codebase klare architektonische Grenzen hat. Eine Next.js-App mit getrennten Frontend-Komponenten, Backend-Actions und Shared Libraries laesst sich natuerlich entlang dieser Linien aufteilen.
Die Einschraenkung: querschnittliche Arbeit. Ein Feature, das Aenderungen an UI, API und Datenschicht erfordert, passt nicht sauber in das Territorium eines einzelnen Agenten. Man loest das, indem man das Feature in komponentenbezogene Teilaufgaben zerlegt und diese sequenziert.
Aufteilung nach Rolle
Statt nach Code-Location zu teilen, teilt man nach Funktion. Ein Agent schreibt Code. Ein anderer schreibt Tests. Ein dritter kuemmert sich um Dokumentation. Ein vierter macht Code Review.
Das spiegelt wider, wie menschliche Teams arbeiten, und produziert hoehere Qualitaet, weil der Test-Agent nicht weiss (oder sich nicht darum schert), wie einfach der Code zu schreiben war. Er testet gegen die Spec, nicht gegen die Annahmen des Autors.
Der Tradeoff ist mehr Koordinationsaufwand. Der Test-Agent braucht den Implementierungs-Agenten als Vorlauf. Der Doku-Agent braucht beide. Man managt eine Pipeline, nicht nur parallele Worker.
Aufteilung nach Lifecycle-Phase
Eine ausgefeiltere Version der Rollenaufteilung. Ein Agent brainstormt und plant. Ein anderer implementiert. Ein dritter verifiziert. Die Arbeit fliesst durch Phasen, und jeder Agent ist auf seine Phase spezialisiert.
Das ist das Muster, das wir bei Beadbox nutzen. Unser Architekt-Agent entwirft, unsere Engineering-Agenten implementieren, unsere QA-Agenten verifizieren unabhaengig. Dieselbe Aufgabe fliesst durch mehrere Spezialisten, und jeder einzelne fuegt eine Qualitaetsschicht hinzu, die Generalisten-Agenten verpassen. Ueber das vollstaendige Setup habe ich in Ich shippe Software mit 13 KI-Agenten geschrieben.
Die richtige Strategie haengt von deinem Projekt ab. Kleine Projekte mit klaren Dateigrenzen fahren gut mit Komponentenaufteilung. Groessere Projekte, bei denen Qualitaet zaehlt, profitieren von Rollen- oder Lifecycle-Aufteilung. Die meisten Teams landen bei einer Mischform.
Das CLAUDE.md Identity Pattern
Hier trifft Theorie auf Implementierung. Jeder Claude Code Agent bekommt seine eigene CLAUDE.md-Datei, und diese Datei ist das wichtigste Element des gesamten Multi-Agent-Systems.
Eine CLAUDE.md definiert vier Dinge:
- Was der Agent ist. Seine Rolle, Spezialisierung und Domaene.
- Was er besitzt. Die Dateien, Verzeichnisse oder Zustaendigkeiten, die er kontrolliert.
- Was er nicht anfassen darf. Die expliziten Grenzen, die Konflikte verhindern.
- Wie er kommuniziert. Die Protokolle fuer Arbeitsmeldungen und Koordination mit anderen Agenten.
Hier ein echtes Beispiel. Zwei Claude Code Agenten mit komplementaeren Scopes:
# CLAUDE.md for Agent: frontend-eng
## Identity
Frontend engineer. You implement UI components, pages, and client-side
logic. You own everything under components/, app/, and hooks/.
## File Ownership
- components/** (you own these)
- app/** (you own these)
- hooks/** (you own these)
- lib/utils.ts (shared, read-only for you)
- server/** (DO NOT MODIFY — owned by backend-eng)
## Communication
When you need a backend change, create a task describing what API
you need. Do not implement it yourself.
When done with a task, comment: "DONE: <summary>. Commit: <hash>"
# CLAUDE.md for Agent: backend-eng
## Identity
Backend engineer. You implement server actions, API routes, and
data layer logic. You own everything under server/, actions/, and lib/.
## File Ownership
- server/** (you own these)
- actions/** (you own these)
- lib/** (you own these, except utils.ts is shared)
- components/** (DO NOT MODIFY — owned by frontend-eng)
- app/** (DO NOT MODIFY — owned by frontend-eng)
## Communication
When you change a data type in lib/types.ts, notify frontend-eng
by commenting on the relevant task.
When done with a task, comment: "DONE: <summary>. Commit: <hash>"
Beachte die expliziten "DO NOT MODIFY"-Zeilen. Ohne diese driften Agenten ab. Sie sehen eine Gelegenheit zu "helfen", indem sie einen Tippfehler in einer Datei korrigieren, die ihnen nicht gehoert, und ploetzlich hast du Merge-Konflikte. Oder schlimmer: Sie refactorn stillschweigend Code, auf den ein anderer Agent angewiesen war.
Die Identity-Sektion ist keine Dekoration. Claude Code liest CLAUDE.md zu Beginn jeder Session und nutzt sie, um sein Verhalten einzugrenzen. Ein Agent, dem gesagt wird, er sei ein "Frontend-Ingenieur", wird sich natuerlich gegen Backend-Aenderungen wehren. Ein Agent, dem gesagt wird, er besitze bestimmte Verzeichnisse, wird fragen, bevor er Dateien ausserhalb dieser Verzeichnisse aendert.
Merge-Konflikte vermeiden
File-Level Ownership, wie in den CLAUDE.md-Beispielen oben gezeigt, ist die erste Verteidigungslinie. Aber nicht die einzige.
Committe und pushe haeufig. Ein Agent, der 45 Minuten ohne Commit arbeitet, baut eine Merge-Konflikt-Zeitbombe. Weise Agenten (in ihrer CLAUDE.md) an, nach jeder abgeschlossenen logischen Einheit zu committen.
Pulle vor neuer Arbeit. Jeder Agent sollte git pull --rebase ausfuehren, bevor er eine neue Aufgabe beginnt. Das laesst sich trivial durchsetzen, indem man es zum Startup-Protokoll des Agenten in CLAUDE.md hinzufuegt.
Verwende Feature Flags fuer querschnittliche Arbeit. Wenn zwei Agenten dieselbe Datei aendern muessen, ist der sicherere Ansatz oft, einen Agenten das Interface oder Flag erstellen zu lassen, committen und pushen, dann den zweiten Agenten pullen und darauf aufbauen zu lassen. Sequenziell schlaegt parallel, wenn die Alternative ein Merge-Albtraum ist.
Separate Branches fuer riskante Arbeit. Wenn ein Agent etwas Experimentelles macht, gib ihm seinen eigenen Branch. Besonders nuetzlich fuer Architektur-Spikes oder Refactoring-Arbeit, die moeglicherweise nicht landen wird.
In der Praxis eliminiert die Kombination aus File-Ownership-Regeln und haeufifen Commits 90% der Merge-Konflikte. Die verbleibenden 10% passieren in geteilten Dateien wie types.ts oder package.json, und sie sind meistens trivial zu loesen.
Agent-zu-Agent-Kommunikation
Claude Code Agenten koennen nicht direkt miteinander sprechen. Kein Shared Memory, kein Message Bus, kein Echtzeit-Kanal zwischen ihnen. Das ist tatsaechlich eine gute Sache. Direkte Kommunikation zwischen Agenten erzeugt Kopplung, Race Conditions und Debug-Albtraeume.
Stattdessen passiert Kommunikation ueber Artefakte. Drei Muster funktionieren:
Task-Kommentare
Das zuverlaessigste Muster. Agent A beendet Arbeit und kommentiert auf einem geteilten Task: "DONE: /api/users Endpoint implementiert. Gibt JSON zurueck. Schema ist in lib/types.ts." Agent B liest den Task-Kommentar und weiss genau, was verfuegbar ist.
Status-Updates
Jeder Task hat einen Status: open, in_progress, done, blocked. Wenn Agent A einen Vorbedingungen-Task als done markiert, weiss Agent B (oder du, oder ein Koordinator), dass die abhaengige Arbeit starten kann.
Dateiaenderungen
Die einfachste Form. Agent A schreibt ein TypeScript-Interface nach lib/types.ts und committet. Agent B pullt und sieht die neuen Typen. Keine explizite Kommunikation noetig, weil der Code selbst die Nachricht ist.
Was NICHT funktioniert: den Versuch, ein Echtzeit-Message-Passing-System zwischen Agenten zu bauen. Wenn Agent A auf Agent Bs Output warten muss, modelliere das als Abhaengigkeit zwischen Tasks, nicht als synchronen Aufruf.
Die Dispatch-Schleife
Jemand muss den Laden schmeissen. In einem Multi-Agent Claude Code Setup gibt es zwei Optionen: Du machst es manuell, oder du bestimmst einen Koordinator-Agenten.
Manuelles Dispatching
Du pflegst eine Task-Liste. Du weist Agenten Tasks zu. Du pruefst den Fortschritt. Du raiumst Blocker aus dem Weg. Das funktioniert bis etwa fuenf Agenten, bevor der Koordinationsaufwand die Produktivitaetsgewinne auffrisst.
Ein typischer manueller Dispatch-Zyklus sieht so aus:
- Morgens: Pruefen, was in Arbeit, was blockiert, was bereit ist
- Zuweisen: Jedem Agenten seine naechste Aufgabe mit Kontext schicken
- Monitoren: Alle 10-15 Minuten Agent-Output auf Anzeichen von Steckenbleiben pruefen
- Entblocken: Wenn ein Agent auf ein Problem stoesst, eingreifen oder umverteilen
- Abschluss: Am Ende des Tages pruefen, was shipped wurde, und morgen planen
In tmux sieht das aus wie Durchschalten zwischen Panes, aktuellen Output lesen und entscheiden, was jeder Agent als Naechstes braucht. Tools wie gp (den aktuellen Output eines Agenten einsehen, ohne ihn zu unterbrechen) helfen, aber du bleibst der Flaschenhals.
Koordinator-Agent
Widme einen Claude Code Agenten dem Dispatchen von Arbeit an die anderen. Dieser Agent schreibt keinen Code. Er liest das Task-Backlog, weist verfuegbaren Agenten Arbeit zu, prueft den Fortschritt und uebernimmt die Dispatch-Schleife programmatisch.
Das ist das Muster, das wir verwenden. Unser "super"-Agent laeuft in einer Patrol-Loop: alle paar Minuten schaut er bei jedem aktiven Agenten vorbei, prueft Task-Status, identifiziert Blocker und dispatcht neue Arbeit, wenn ein Agent idle wird. Der Mensch (ich) trifft die Prioritaetsentscheidungen und loest mehrdeutige Situationen. Super erledigt die Logistik.
Ein Koordinator-Agent braucht seine eigene CLAUDE.md:
# CLAUDE.md for Agent: super
## Identity
Dispatch coordinator. You assign work to agents, monitor progress,
and ensure the pipeline keeps moving. You do NOT write code.
## Responsibilities
- Maintain awareness of all active tasks and their statuses
- Assign ready tasks to idle agents
- Monitor agent progress every 5-10 minutes
- Escalate blockers to the human when agents can't self-resolve
- Verify agents follow the protocol: plan before code, test before done
## Communication
- To assign work: message the agent with task ID and priority
- To check progress: peek at agent's recent output
- To escalate: message the human with context and options
Das Koordinator-Muster skaliert deutlich besser als manuelles Dispatching. Bei 10+ Agenten ist manuelle Koordination ein Vollzeitjob. Ein Koordinator-Agent erledigt die Routine-Logistik und eskaliert nur die Entscheidungen, die menschliches Urteilsvermoegen erfordern.
Tmux-Layout fuer Multi-Agent-Arbeit
Das physische Layout ist wichtiger, als man denkt. Hier eine tmux-Konfiguration, die fuer das Ausfuehren mehrerer Claude Code Agenten funktioniert:
# Create a new tmux session
tmux new-session -s agents -n super
# Split into panes for each agent
tmux split-window -h -t agents:super
tmux split-window -v -t agents:super.1
# Or create named windows (easier to manage at scale)
tmux new-window -t agents -n eng1
tmux new-window -t agents -n eng2
tmux new-window -t agents -n qa1
tmux new-window -t agents -n frontend
tmux new-window -t agents -n backend
Benannte Windows schlagen Split-Panes, sobald du vier Agenten ueberschreitest. Fuenf Panes auf einem Bildschirm kann man nicht lesen, aber man kann schnell zwischen benannten Windows wechseln. Die Namenskonvention ist ebenfalls wichtig. eng1, eng2, qa1 sind sofort erfassbar. agent-1, agent-2, agent-3 sagen dir nichts.
Starte jeden Agenten in seinem eigenen Arbeitsverzeichnis mit eigener CLAUDE.md:
# In the eng1 window
cd ~/project
claude --claude-md ./agents/eng1/CLAUDE.md
# In the qa1 window
cd ~/project
claude --claude-md ./agents/qa1/CLAUDE.md
Ein praktischer Tipp: Behalte ein "Dashboard"-Window, das einfach nur eine Shell ist. Nutze es fuer git log --oneline -10, Task-Status pruefen oder Agenten beobachten, ohne ihre Arbeit zu unterbrechen. Das wird deine Kommandozentrale.
Wenn etwas schiefgeht
Multi-Agent-Workflows scheitern auf vorhersehbare Weise. Die Fehlermodi zu kennen erspart dir, sie auf die harte Tour zu lernen.
Zwei Agenten editieren dieselbe Datei. Meistens weil die File Ownership in CLAUDE.md nicht spezifisch genug war. lib/utils.ts ist ein klassischer Konfliktmagnet. Loesung: Entweder geteilte Utility-Dateien einem spezifischen Agenten zuweisen, oder sie fuer alle read-only machen und Aenderungen ueber einen einzigen Owner routen.
Ein Agent wird still. Er hat ein Rate Limit, eine Fehlerschleife oder steckt in einer tiefen Reasoning-Kette fest. Pruefe den Output. Wenn er immer wieder denselben fehlschlagenden Befehl versucht, beende die Session und starte mit klareren Anweisungen neu. Periodische Health-Checks (alle 10-15 Minuten) fangen das auf, bevor du eine Stunde verlierst.
Context Windows fuellen sich. Langlebige Agenten akkumulieren Context und performen schlechter. Die CLAUDE.md jedes Agenten sollte ein Protokoll dafuer enthalten: "Wenn du laenger als 90 Minuten arbeitest, sichere deinen State und fordere eine neue Session an." In der Praxis heisst das: Der Agent committet seine Arbeit, notiert, wo er aufgehoert hat, und eine neue Claude Code Session uebernimmt ab diesem Commit.
Arbeit weicht von der Spec ab. Agent baut etwas, das technisch funktioniert, aber nicht dem entspricht, was verlangt war. Die Loesung ist das Plan-vor-Code-Muster: Bevor er Code schreibt, kommentiert der Agent seinen Implementierungsplan. Du reviewst den Plan in 60 Sekunden und faengst Missverstaendnisse ab, bevor sie zu 500-Zeilen-Diffs werden.
Die Pipeline steht still. Agent B wartet auf Agent A, aber Agent A wartet auf eine Entscheidung von dir. Derweil hat Agent C seine Arbeit vor 30 Minuten beendet und sitzt idle. Das ist ein Koordinationsfehler, kein technischer. Der Koordinator-Agent (oder du) muss die Pipeline am Laufen halten, indem er Blocker monitort und idle Agenten neue Arbeit zuweist.
Wie wir das mit Beads geloest haben
Alles oben funktioniert mit Klebezetteln und guten Vorsaetzen. Aber ab ungefaehr fuenf Agenten bekommt der informelle Ansatz Risse. Du vergisst, woran Agent C gearbeitet hat. Du verlierst den Ueberblick, welche Tasks blockiert sind. Du weisst nicht mehr, ob das API-Endpoint, das Agent B braucht, fertig oder nur angefangen wurde.
Das ist das Problem, das beads loest. Beads ist ein Open-Source, Local-first Issue Tracker. Jeder Task ist ein "Bead" mit einer eindeutigen ID, einem Status, einer Beschreibung, Akzeptanzkriterien, Abhaengigkeiten und einem Kommentar-Thread. Alles zugaenglich ueber ein CLI namens bd, was bedeutet, dass deine Claude Code Agenten lesen und schreiben koennen, ohne das Terminal zu verlassen.
So sieht die Dispatch-Schleife mit beads aus:
# See what's ready for work
bd list --status open
# Assign a task to an agent
bd update bb-a1b2 --claim --actor eng1
# Agent reads its assignment
bd show bb-a1b2
# Agent comments its plan before coding
bd comments add bb-a1b2 --author eng1 "PLAN:
1. Add endpoint at /api/users
2. Define UserResponse type in lib/types.ts
3. Write integration test
Files: server/api/users.ts (new), lib/types.ts (modify)
Test: curl localhost:3000/api/users returns 200 with JSON array"
# Agent finishes and comments what it did
bd comments add bb-a1b2 --author eng1 "DONE: /api/users endpoint live.
Returns paginated JSON. Added UserResponse type.
Verification:
1. curl http://localhost:3000/api/users → 200, JSON array
2. curl http://localhost:3000/api/users?page=2 → 200, second page
3. pnpm test → all passing
Commit: 8f3c2a1"
# Agent marks the task done
bd update bb-a1b2 --status closed
Jeder Agent folgt diesem Protokoll: claimen, planen, implementieren, DONE kommentieren, Status updaten. Der Kommentar-Thread jedes Beads wird zu einem vollstaendigen Audit-Trail dessen, was passiert ist, warum und wie man es verifizieren kann.
Abhaengigkeiten verhindern konfligierende Arbeit:
# Create a task that depends on another
bd create --title "Build user list component" \
--deps bb-a1b2 \
--description "Frontend component that calls /api/users. Blocked until API is live."
Der abhaengige Task bleibt blockiert, bis bb-a1b2 erledigt ist. Kein Agent nimmt ihn vorzeitig auf. Niemand verschwendet Zeit damit, ein Frontend fuer eine API zu bauen, die noch nicht existiert.
Der bd list-Befehl gibt dir einen Snapshot der gesamten Pipeline:
bd list --status in_progress
# Shows what every agent is actively working on
bd blocked
# Zeigt Tasks, die auf unerledigte Abhaengigkeiten warten
bd list --status open --priority p1
# Shows the highest-priority work that's ready to start
Das ersetzt das mentale Modell, das du im Kopf hattest. Der Status jedes Tasks, die aktuelle Arbeit jedes Agenten, jede Abhaengigkeitskette, alles abfragbar von der Kommandozeile.
Sichtbarkeit skalieren
Das CLI funktioniert. Aber ab einer gewissen Groesse gibt es eine Grenze dessen, was man durch bd list im Terminal aufnehmen kann. Wenn du acht Agenten hast, die an drei Epics mit siebzehn offenen Tasks und einem Dutzend Abhaengigkeiten arbeiten, musst du die Form der Arbeit sehen, nicht nur eine Liste davon.
Das ist die Luecke, fuer die wir Beadbox gebaut haben. Beadbox ist ein Echtzeit-Dashboard, das auf beads aufsetzt und dir zeigt:
- Epic Trees mit Fortschrittsbalken, damit du siehst, wie jedes Feature ueber alle Teilaufgaben voranschreitet
- Abhaengigkeitsgraphen, die blockierte Arbeit sichtbar machen, bevor sie die Pipeline zum Stillstand bringt
- Agenten-Aktivitaet, die zeigt, welcher Agent woran arbeitet, mit Plan- und Done-Kommentaren im Kontext
- Echtzeit-Updates, weil das Dashboard deine beads-Datenbank ueberwacht und sich aktualisiert, sobald Agenten Task-Status aendern
Beadbox ersetzt nicht das CLI. Deine Agenten lesen und schreiben weiterhin ueber bd in beads. Beadbox gibt dir das grosse Bild, damit du die Urteilsentscheidungen treffen kannst: Welches Epic faellt zurueck, welcher Agent braucht Hilfe, wo bildet sich der Flaschenhals.
Es ist kostenlos waehrend der Beta. Wenn du Workflows wie diesen aufbaust, gib Beadbox einen Stern auf GitHub.
Erste Schritte
Du brauchst keine dreizehn Agenten, um davon zu profitieren. Hier das Minimum Viable Setup:
- Zwei Claude Code Agenten in separaten tmux-Windows, jeweils mit eigener CLAUDE.md, die File-Ownership-Grenzen definiert.
- Eine Task-Liste (selbst eine Textdatei reicht in dieser Groessenordnung), damit beide Agenten wissen, woran sie arbeiten und was als Naechstes kommt.
- Ein Commit-Protokoll: Beide Agenten committen haeufig und pullen vor Beginn neuer Arbeit.
Sobald sich das natuerlich anfuehlt, fuege einen dritten Agenten fuer Tests oder Dokumentation hinzu. Dann erwaege einen Koordinator-Agenten. Dann fuehre beads fuer strukturiertes Task-Tracking ein. Skaliere das System, wenn der Koordinationsschmerz zunimmt, nicht davor.
Das Schwierige ist nicht das Tooling. Es ist der Perspektivwechsel: von "Ich nutze einen KI-Assistenten" zu "Ich fuehre ein Team." Die CLAUDE.md-Dateien, die Dispatch-Protokolle, die Ownership-Grenzen: Das sind Management-Praktiken, keine Konfigurationsdateien. Du baust eine Organisation auf, auch wenn die Teammitglieder auf API-Aufrufen laufen.
Starte mit zwei Agenten und klaren Grenzen. Alles andere folgt daraus.
