Agent Teams – Orchestrierung von Claude-Code-Sitzungsteams

• Eine experimentelle Funktion, mit der mehrere Claude Code-Instanzen als ein Team organisiert werden, um Arbeit parallel zu verteilen und zu koordinieren; eine Lead-Sitzung erstellt Teammitglieder, weist Aufgaben zu und fasst Ergebnisse zusammen
• Anders als bei bestehenden Subagents ist direkter Nachrichtenaustausch zwischen Teammitgliedern möglich; auch Nutzer können ohne Umweg über den Lead direkt mit einzelnen Teammitgliedern kommunizieren
• Besonders effektiv für Code-Reviews, parallele Untersuchung von Debugging-Hypothesen und schichtübergreifende Aufgaben in Frontend, Backend und Tests; für sequentielle Arbeit oder Änderungen an derselben Datei ist eine einzelne Sitzung besser geeignet
• Da jedes Teammitglied ein eigenes Kontextfenster hat, steigt der Token-Verbrauch deutlich an; die Kosten können proportional zur Anzahl der Teammitglieder wachsen
• Unterstützt einen Split-Screen-Modus über tmux oder iTerm2 und hilft durch parallele Analyse und automatisierte Zusammenarbeit, Produktivität und Qualität bei komplexen Entwicklungsaufgaben zu steigern

---

Überblick über Agent Teams

• Mehrere Claude-Code-Sitzungen werden als ein Team koordiniert, um Arbeit parallel auszuführen
  • Der Team-Lead verteilt Aufgaben und führt die Ergebnisse zusammen
  • Jedes Teammitglied läuft separat in einem eigenen Kontextfenster
• Anders als bei Subagent ist direktes Messaging zwischen Teammitgliedern möglich
• Die Funktion ist experimentell und standardmäßig deaktiviert; aktiviert wird sie über die Umgebungsvariable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

Wann sich Agent Teams eignen

• Research und Reviews: Mehrere Teammitglieder untersuchen gleichzeitig verschiedene Aspekte eines Problems, teilen anschließend ihre Ergebnisse und überprüfen sie gegenseitig
• Entwicklung neuer Module oder Funktionen: Jedes Teammitglied übernimmt eine separate Datei bzw. ein separates Modul, sodass parallel ohne Konflikte gearbeitet werden kann
• Debugging mit konkurrierenden Hypothesen: Unterschiedliche Hypothesen werden gleichzeitig getestet, um die Ursache schneller zu finden
• Schichtübergreifende Koordination: Teammitglieder werden nach Layern wie Frontend, Backend und Tests aufgeteilt, um Änderungen gleichzeitig umzusetzen
• Für sequentielle Aufgaben, das Bearbeiten derselben Datei oder stark abhängige Arbeiten sind eine einzelne Sitzung oder Subagents effizienter

Subagent vs. Agent Team

• Subagent: Hat ein eigenes Kontextfenster, gibt Ergebnisse aber nur an den Aufrufer zurück; der Hauptagent verwaltet die gesamte Arbeit; die Token-Kosten sind relativ niedrig
• Agent Team: Vollständig unabhängige Kontextfenster; direkter Nachrichtenaustausch zwischen Teammitgliedern möglich; selbstständige Koordination über eine gemeinsame Aufgabenliste; da jedes Teammitglied eine eigene Claude-Instanz ist, sind die Token-Kosten höher
• Für fokussierte Aufgaben, bei denen nur das Ergebnis benötigt wird, eignen sich Subagents; für komplexe Arbeiten mit Diskussion und Zusammenarbeit zwischen Teammitgliedern sind Agent Teams besser geeignet

Das erste Agent Team starten

• Standardmäßig ist die Funktion deaktiviert; sie wird aktiviert, indem die Umgebungsvariable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS auf 1 gesetzt oder in settings.json eingetragen wird
• Nach der Aktivierung beschreibt man in natürlicher Sprache Teamstruktur und Aufgabe, woraufhin Claude das Team erstellt, Teammitglieder startet und die Arbeit koordiniert

  • I'm designing a CLI tool that helps developers track TODO comments across their codebase. Create an agent team to explore this from different angles: one teammate on UX, one on technical architecture, one playing devil's advocate.

  • Es soll ein CLI-Tool zum Verfolgen von TODO-Kommentaren entworfen werden; drei Teammitglieder untersuchen unabhängig UX, technische Architektur und Gegenpositionen, danach werden die Ergebnisse zusammengeführt
  • So versucht Claude, eine gemeinsame Aufgabenliste zu erstellen, die Teammitglieder jeweils zu starten, die einzelnen Fragestellungen zu untersuchen, die Ergebnisse zu bündeln und das Team nach Abschluss der Arbeit aufzuräumen
• Im Lead-Terminal werden die vollständige Teamliste und der Aufgabenstatus angezeigt; mit Shift+Up/Down lassen sich Teammitglieder auswählen und direkt per Nachricht ansprechen

Steuerung von Agent Teams

• Auswahl des Anzeigemodus

  • In-process-Modus: Alle Teammitglieder laufen innerhalb des Hauptterminals; mit Shift+Up/Down können Teammitglieder ausgewählt und Nachrichten gesendet werden; keine zusätzliche Konfiguration nötig
  • Split-panes-Modus: Jedes Teammitglied wird in einem separaten Pane angezeigt; Ausgaben lassen sich gleichzeitig beobachten; erfordert tmux oder iTerm2
  • Der Standardwert "auto" verwendet Split-Panes, wenn innerhalb einer tmux-Sitzung ausgeführt wird, andernfalls In-process
  • Die Einstellung "tmux" aktiviert den Split-Pane-Modus und erkennt tmux sowie iTerm2 automatisch
  • Überschreiben lässt sich dies über teammateMode in settings.json oder mit dem Flag claude --teammate-mode in-process für eine einzelne Sitzung

• Teammitglieder und Modelle festlegen

  • Claude bestimmt die Anzahl der Teammitglieder je nach Aufgabe automatisch; mit Anweisungen wie "Create a team with 4 teammates" lassen sich genaue Anzahl und Modell (z. B. Sonnet) auch direkt vorgeben

• Genehmigung von Plänen verlangen

  • Bei komplexen oder riskanten Aufgaben kann für Teammitglieder ein schreibgeschützter Planungsmodus aktiviert werden, der die Umsetzung blockiert, bis der Lead zustimmt
  • Sobald ein Teammitglied seinen Plan fertiggestellt hat, sendet es eine Genehmigungsanfrage an den Lead; nach Freigabe beginnt die Umsetzung, bei Ablehnung wird mit eingearbeitetem Feedback neu eingereicht
  • Die Kriterien des Leads lassen sich über Bedingungen im Prompt beeinflussen, etwa: "Approve only plans that include test coverage"

• Delegate-Modus

  • Der Lead wird darauf beschränkt, statt selbst zu implementieren nur Koordinationswerkzeuge zu verwenden, also Teammitglieder zu starten, Nachrichten zu senden, zu beenden und Aufgaben zu verwalten
  • Nach dem Start des Teams wird mit Shift+Tab in den Delegate-Modus gewechselt

• Direkte Gespräche mit Teammitgliedern

  • Jedes Teammitglied ist eine vollständig unabhängige Claude-Code-Sitzung, daher können zusätzliche Anweisungen, Rückfragen oder geänderte Vorgehensweisen direkt übermittelt werden
  • Im In-process-Modus erfolgt die Auswahl per Shift+Up/Down, dann Nachricht senden; Enter öffnet die Sitzung, Escape bricht den aktuellen Zug ab, Ctrl+T blendet die Aufgabenliste ein oder aus
  • Im Split-Pane-Modus kann direkt durch Anklicken des jeweiligen Pane interagiert werden

• Aufgaben zuweisen und claimen

  • Über die gemeinsame Aufgabenliste wird die Teamarbeit koordiniert; Aufgaben haben die drei Status pending, in progress und completed
  • Abhängigkeiten zwischen Aufgaben können festgelegt werden; Aufgaben mit ungelösten Abhängigkeiten können nicht geclaimt werden
  • Der Lead weist Aufgaben explizit zu, oder Teammitglieder claimen automatisch nach Abschluss ihrer aktuellen Aufgabe die nächste unzugewiesene und nicht blockierte Aufgabe
  • Um zu verhindern, dass mehrere Teammitglieder gleichzeitig dieselbe Aufgabe claimen, wird Dateisperrung verwendet

• Teammitglieder beenden und Team aufräumen

  • Wenn der Lead das Beenden eines bestimmten Teammitglieds anfordert, kann dieses zustimmen oder ablehnen und den Grund erläutern
  • Beim Aufräumen entfernt der Lead die gemeinsam genutzten Teamressourcen; sind noch aktive Teammitglieder vorhanden, schlägt das Aufräumen fehl, daher müssen diese zuerst beendet werden

Interne Funktionsweise von Agent Teams

• Wege zum Teamstart

  • Nutzer fordert ein Team an: Eine für parallele Bearbeitung geeignete Aufgabe wird beschrieben und ausdrücklich die Erstellung eines Agent Teams verlangt
  • Claude schlägt ein Team vor: Wenn Claude erkennt, dass sich eine Aufgabe für parallele Verarbeitung eignet, schlägt es die Team-Erstellung vor und fährt erst nach Bestätigung durch den Nutzer fort
  • In beiden Fällen wird ohne Zustimmung des Nutzers kein Team erstellt

• Architekturkomponenten

  • Team lead: Die Hauptsitzung von Claude Code, zuständig für Team-Erstellung, Start der Teammitglieder und Koordination der Arbeit
  • Teammates: Separate Claude-Code-Instanzen, die jeweils ihre zugewiesenen Aufgaben bearbeiten
  • Task list: Eine gemeinsame Liste von Arbeitspunkten, die von Teammitgliedern geclaimt und abgeschlossen wird
  • Mailbox: Ein Nachrichtensystem für die Kommunikation zwischen Agenten
  • Aufgabenabhängigkeiten werden automatisch verwaltet; wenn ein Teammitglied eine Aufgabe abschließt, werden blockierte Aufgaben ohne manuelles Eingreifen freigegeben
  • Die Teamkonfiguration wird lokal unter ~/.claude/teams/{team-name}/config.json gespeichert, die Aufgabenliste unter ~/.claude/tasks/{team-name}/
  • Die Konfiguration enthält ein members-Array, in dem Name, Agent-ID und Agent-Typ jedes Teammitglieds festgehalten werden

• Berechtigungen

  • Teammitglieder starten mit den Berechtigungseinstellungen des Leads; wenn der Lead mit --dangerously-skip-permissions ausgeführt wird, gilt dies ebenso für alle Teammitglieder
  • Nach dem Start kann der Modus einzelner Teammitglieder geändert werden, aber beim Spawn können keine individuellen Berechtigungseinstellungen pro Teammitglied festgelegt werden

• Kontext und Kommunikation

  • Jedes Teammitglied besitzt ein eigenes Kontextfenster und lädt beim Start denselben Projektkontext wie eine normale Sitzung, einschließlich CLAUDE.md, MCP-Servern und Skills
  • Der Gesprächsverlauf des Leads wird nicht an Teammitglieder weitergegeben; nur der Spawn-Prompt wird übermittelt
  • Automatische Nachrichtenweiterleitung: Von Teammitgliedern gesendete Nachrichten werden automatisch an den Empfänger zugestellt; der Lead muss nicht pollen
  • Leerlaufbenachrichtigungen: Wenn ein Teammitglied seine Arbeit beendet und anhält, wird der Lead automatisch informiert
  • Gemeinsame Aufgabenliste: Alle Agenten können den Aufgabenstatus sehen und verfügbare Arbeiten claimen
  • Es gibt die Nachrichtentypen message (an ein bestimmtes Teammitglied) und broadcast (an das gesamte Team; sollte sparsam verwendet werden, da die Kosten mit der Teamgröße steigen)

• Token-Verbrauch

  • Agent Teams verursachen im Vergleich zu einer einzelnen Sitzung einen deutlich höheren Token-Verbrauch, der mit der Zahl aktiver Teammitglieder wächst
  • Bei Research, Reviews und neuer Funktionsentwicklung sind die zusätzlichen Token-Kosten meist gerechtfertigt; für Routineaufgaben ist eine einzelne Sitzung kosteneffizienter

Einsatzfälle

• Paralleles Code-Review

  • Ein einzelner Reviewer konzentriert sich meist nur auf eine Art von Problemen gleichzeitig; deshalb werden Review-Kriterien in unabhängige Domänen wie Sicherheit, Performance und Testabdeckung aufgeteilt
  • Jeder Reviewer wendet auf denselben PR einen anderen Filter an, und der Lead fasst die Gesamtergebnisse nach Abschluss zusammen

• Untersuchung mit konkurrierenden Hypothesen

  • Ein einzelner Agent neigt dazu, die Suche zu beenden, sobald eine Erklärung gefunden ist; deshalb werden Teammitglieder ausdrücklich in einer antagonistischen Struktur organisiert
  • Jedes Teammitglied untersucht seine eigene Hypothese und versucht gleichzeitig, die Theorie der anderen zu widerlegen – ähnlich einer wissenschaftlichen Debatte
  • So wird Anchoring Bias vermieden, der bei sequentiellen Untersuchungen entsteht, und die überlebende Theorie hat eine höhere Wahrscheinlichkeit, tatsächlich die Grundursache zu sein

Best Practices

• Teammitgliedern ausreichend Kontext geben: Der Projektkontext wird zwar automatisch geladen, aber der Gesprächsverlauf des Leads wird nicht übermittelt; deshalb sollten im Spawn-Prompt aufgabenrelevante Details enthalten sein
• Aufgabengröße passend zuschneiden: Ist eine Aufgabe zu klein, übersteigt der Koordinationsaufwand den Nutzen; ist sie zu groß, wird lange ohne Zwischenstand gearbeitet und das Risiko verschwendeter Arbeit steigt; geeignet sind abgeschlossene Einheiten mit klaren Ergebnissen wie Funktionen, Testdateien oder Reviews
• Wenn der Lead selbst mit der Implementierung beginnt, statt auf Teammitglieder zu warten, gib die Anweisung: "Wait for your teammates to complete their tasks before proceeding"
• Beim ersten Einsatz sollte man mit klar abgegrenzten Research- und Review-Aufgaben ohne Code-Schreiben beginnen, etwa PR-Reviews, Bibliotheksrecherche oder Bug-Untersuchungen
• Dateikonflikte vermeiden: Wenn zwei Teammitglieder dieselbe Datei bearbeiten, kann es zu Überschreibungen kommen; deshalb sollten die Aufgaben so aufgeteilt werden, dass jede Person an einem anderen Dateisatz arbeitet
• Den Fortschritt der Teammitglieder regelmäßig prüfen, ineffektive Ansätze umlenken und Ergebnisse fortlaufend zusammenführen

Troubleshooting

• Wenn Teammitglieder nicht erscheinen: Im In-process-Modus mit Shift+Down durch aktive Teammitglieder wechseln, prüfen, ob die Aufgabe komplex genug für eine Teamstruktur ist; bei angeforderten Split-Panes sicherstellen, dass tmux im PATH installiert ist; bei iTerm2 prüfen, ob die it2-CLI installiert und die Python-API aktiviert ist
• Zu viele Berechtigungs-Prompts: Berechtigungsanfragen von Teammitgliedern werden an den Lead hochgereicht; deshalb vor dem Spawn in den Berechtigungseinstellungen häufige Aktionen vorab genehmigen
• Teammitglied stoppt nach einem Fehler: Ausgabe des betreffenden Teammitglieds prüfen, direkt zusätzliche Anweisungen geben oder ein Ersatz-Teammitglied starten und die Arbeit fortsetzen
• Lead beendet vor Abschluss der Arbeit: Den Lead anweisen weiterzumachen oder vor dem Wechsel in den Delegate-Modus festlegen, dass auf die Fertigstellung der Teammitglieder gewartet werden soll
• Verwaiste tmux-Sitzungen: Wenn nach dem Teamende noch tmux-Sitzungen vorhanden sind, mit tmux ls prüfen und mit tmux kill-session -t <session-name> entfernen

Einschränkungen

• In-process-Teammitglieder lassen sich nicht wiederherstellen: /resume und /rewind stellen In-process-Teammitglieder nicht wieder her; nach der Wiederherstellung kann der Lead Nachrichten an nicht mehr existierende Teammitglieder senden, daher müssen neue Teammitglieder gestartet werden
• Verzögerter Aufgabenstatus: Wenn ein Teammitglied eine Aufgabe nicht als abgeschlossen markiert, kann eine abhängige Aufgabe blockiert bleiben; der Status muss dann manuell aktualisiert oder der Lead gebeten werden, das Teammitglied zu erinnern
• Verzögertes Beenden: Teammitglieder werden erst beendet, nachdem ihre aktuelle Anfrage oder ihr Tool-Aufruf abgeschlossen ist
• Nur ein Team pro Sitzung möglich: Um ein neues Team zu starten, muss zuerst das aktuelle Team aufgeräumt werden
• Keine verschachtelten Teams: Teammitglieder können keine eigenen Teams oder weitere Teammitglieder starten; nur der Lead kann das Team verwalten
• Fester Lead: Die Sitzung, die das Team erstellt hat, bleibt dauerhaft dessen Lead; Teammitglieder können nicht zum Lead befördert werden, und eine Übertragung der Führung ist nicht möglich
• Einheitliche Berechtigungen beim Spawn: Alle Teammitglieder starten im Berechtigungsmodus des Leads; beim Spawn können keine individuellen Berechtigungen pro Teammitglied gesetzt werden
• Split-Panes erfordern tmux oder iTerm2: Das integrierte Terminal von VS Code, Windows Terminal und Ghostty unterstützen den Split-Pane-Modus nicht