Orchestrieren Sie Teams von Claude Code-Sitzungen

Koordinieren Sie mehrere Claude Code-Instanzen, die zusammen als Team arbeiten, mit gemeinsamen Aufgaben, Messaging zwischen Agenten und zentraler Verwaltung.

[!WARNING]

Agent-Teams sind experimentell und standardmäßig deaktiviert. Aktivieren Sie sie, indem Sie CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in Ihrer settings.json oder Umgebung setzen. Ohne diese Variable wird kein Team beim Sitzungsstart eingerichtet, keine Team-Verzeichnisse werden geschrieben, und Claude spawnt oder schlägt keine Teammates vor. Agent-Teams haben bekannte Einschränkungen bezüglich Sitzungswiederaufnahme, Aufgabenkoordination und Abschaltungsverhalten.

Agent-Teams ermöglichen es Ihnen, mehrere Claude Code-Instanzen zu koordinieren, die zusammenarbeiten. Eine Sitzung fungiert als Team-Lead und koordiniert die Arbeit, weist Aufgaben zu und synthetisiert Ergebnisse. Teammates arbeiten unabhängig, jeder in seinem eigenen Kontextfenster, und kommunizieren direkt miteinander. Sie können auch direkt mit jedem Teammate sprechen, ohne den Lead einzubeziehen.

Bevor Sie ein Team einrichten, überprüfen Sie, ob eine leichtere Option die Aufgabe erfüllt. Subagents arbeiten innerhalb einer einzelnen Sitzung, und mit sitzungsübergreifendem Messaging kann Claude Erkenntnisse zwischen den Sitzungen weitergeben, die Sie selbst ausführen.

Wann Agent-Teams verwendet werden

Agent-Teams sind am effektivsten für Aufgaben, bei denen parallele Exploration echten Wert bietet. Siehe Anwendungsbeispiele für vollständige Szenarien. Die stärksten Anwendungsfälle sind:

• Recherche und Überprüfung: mehrere Teammates können verschiedene Aspekte eines Problems gleichzeitig untersuchen und dann ihre Erkenntnisse austauschen und in Frage stellen
• Neue Module oder Features: Teammates können jeweils ein separates Stück besitzen, ohne sich gegenseitig zu behindern
• Debugging mit konkurrierenden Hypothesen: Teammates testen verschiedene Theorien parallel und konvergieren schneller zur Antwort
• Schichtenübergreifende Koordination: Änderungen, die Frontend, Backend und Tests umfassen, jeweils von einem anderen Teammate verwaltet

Agent-Teams fügen Koordinationsaufwand hinzu und verwenden deutlich mehr Tokens als eine einzelne Sitzung. Sie funktionieren am besten, wenn Teammates unabhängig arbeiten können. Für sequenzielle Aufgaben, Bearbeitungen in derselben Datei oder Arbeit mit vielen Abhängigkeiten sind eine einzelne Sitzung oder subagents effektiver.

Vergleich mit subagents

Sowohl Agent-Teams als auch subagents ermöglichen es Ihnen, Arbeit zu parallelisieren, aber sie funktionieren unterschiedlich. Für separate Sitzungen, die Nachrichten aneinander weitergeben, ohne ein Team zu bilden, siehe sitzungsübergreifendes Messaging.

Subagents berichten Ergebnisse an den Hauptagenten zurück. Bei Agent-Teams teilen sich Teammates eine Aufgabenliste, beanspruchen Arbeit und kommunizieren direkt miteinander.

Verwenden Sie subagents, wenn Sie schnelle, fokussierte Worker benötigen, die berichten. Verwenden Sie Agent-Teams, wenn Teammates Erkenntnisse austauschen, sich gegenseitig in Frage stellen und selbst koordinieren müssen.

Agent-Teams aktivieren

Agent-Teams sind standardmäßig deaktiviert. Aktivieren Sie sie, indem Sie die Umgebungsvariable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS auf 1 setzen, entweder in Ihrer Shell-Umgebung oder über settings.json:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

Das Aktivieren von Agent-Teams ändert auch die gewöhnliche Delegation. Claude kann einen Subagenten selbst benennen, und während Agent-Teams aktiviert sind, wird ein Subagent, den Claude benennt, als Teamkollege gestartet, sodass sich Teams auch dann bilden können, wenn Sie nicht um einen gebeten haben. Weitere Informationen finden Sie unter Wie Claude Agent-Teams startet; um das Verhalten auszuschalten, siehe Claude startet Teamkollegen statt Subagenten.

Das Starten von Teamkollegen erfordert auch eine interaktive Sitzung. Im nicht-interaktiven Modus mit dem Flag -p, einschließlich Agent SDK-Sitzungen, startet Claude keine Teamkollegen, und ein Subagent, den Claude benennt, wird als gewöhnlicher Subagent ausgeführt, auch wenn Agent-Teams aktiviert sind.

Ihr erstes Agent-Team starten

Nachdem Sie Agent Teams aktiviert haben, beschreiben Sie die Aufgabe und die gewünschten Teammitglieder in natürlicher Sprache. Claude erstellt sie und koordiniert die Arbeit basierend auf Ihrem Prompt.

Dieses Beispiel funktioniert gut, weil die drei Rollen unabhängig voneinander sind und das Problem erkunden können, ohne aufeinander warten zu müssen:

I'm designing a CLI tool that helps developers track TODO comments across
their codebase. Spawn three teammates to explore this from different angles:
one on UX, one on technical architecture, one playing devil's advocate.

Von dort aus füllt Claude eine gemeinsame Aufgabenliste in einer Sitzung, die über die Task-Tools verfügt, erstellt Teammitglieder für jede Perspektive, lässt sie das Problem erkunden und fasst die Ergebnisse zusammen, wenn sie fertig sind.

Claude verwendet manchmal Subagenten, anstatt ein Team zu erstellen. Subagenten erscheinen im selben Agenten-Panel wie Teammitglieder, daher bestätigt das Panel allein nicht, dass ein Team gebildet wurde. Falls Claude stattdessen Subagenten erstellt hat, fragen Sie erneut und fordern Sie ausdrücklich ein Agent-Team an.

Das Terminal des Leads listet die Teammitglieder im Agenten-Panel unterhalb des Prompt-Eingabefelds auf. Im Panel:

• Pfeiltasten nach oben und unten: ein Teammitglied auswählen
• Enter: das Transkript des ausgewählten Teammitglieds öffnen und ihm direkt eine Nachricht senden
• Escape: die Auswahl aufheben. Während Sie das Transkript eines Teammitglieds ansehen, unterbricht Escape den aktuellen Turn dieses Teammitglieds

Die Zeile eines inaktiven Teammitglieds bleibt im Panel, solange noch ein Teammitglied oder Subagent arbeitet, sodass Sie sie auswählen können, um das Transkript zu prüfen oder weitere Arbeit zu übergeben. Sobald alle Agenten im Panel inaktiv sind, werden inaktive Zeilen nach 30 Sekunden ausgeblendet und erscheinen beim nächsten Turn des Teammitglieds wieder; das Teammitglied läuft weiter und bleibt ansprechbar, während es ausgeblendet ist.

Wenn mehr als drei Teammitglieder gleichzeitig inaktiv sind, werden die Zeilen nach den ersten drei zu einer einzigen Zeile zusammengefasst, die die zusammengefassten Teammitglieder zählt, etwa 2 idle agents, wenn fünf inaktiv sind. Wählen Sie sie aus und drücken Sie Enter, um die zusammengefassten Zeilen aufzuklappen, oder drücken Sie Esc, um sie wieder zusammenzuklappen. Arbeitende Teammitglieder, fehlgeschlagene Teammitglieder und das Teammitglied, das Sie gerade ansehen, behalten immer ihre eigenen Zeilen.

Wenn Sie jedes Teammitglied in einem eigenen geteilten Bereich haben möchten, lesen Sie Anzeigemodus auswählen.

Ihr Agent-Team steuern

Teilen Sie dem Lead in natürlicher Sprache mit, was Sie möchten. Er übernimmt die Teamkoordination, die Aufgabenzuweisung und die Delegation auf Grundlage Ihrer Anweisungen.

Einen Anzeigemodus wählen

Agent-Teams unterstützen zwei Anzeigemodi:

• In-Process: Alle Teammitglieder laufen in Ihrem Hauptterminal. Verwenden Sie die Pfeiltasten nach oben und unten im Agentenbereich, um ein Teammitglied auszuwählen, drücken Sie dann Enter, um es anzuzeigen, und tippen Sie, um ihm direkt eine Nachricht zu senden. Funktioniert in jedem Terminal, keine zusätzliche Einrichtung erforderlich.
• Geteilte Bereiche: Jedes Teammitglied erhält einen eigenen Bereich. Sie sehen die Ausgabe aller gleichzeitig und können in einen Bereich klicken, um direkt zu interagieren. Erfordert tmux oder iTerm2.

[!NOTE]

tmux hat bekannte Einschränkungen auf bestimmten Betriebssystemen und funktioniert traditionell am besten unter macOS. Die Verwendung von tmux -CC in iTerm2 ist der empfohlene Einstiegspunkt in tmux.

Der Standardwert ist "in-process". Setzen Sie "auto", um geteilte Bereiche zu aktivieren, wenn Sie bereits innerhalb einer tmux-Sitzung arbeiten oder Ihr Terminal iTerm2 mit installierter it2-CLI ist; andernfalls wird auf In-Process zurückgefallen. Die Einstellung "tmux" aktiviert den Modus mit geteilten Bereichen und erkennt anhand Ihres Terminals automatisch, ob tmux oder iTerm2 verwendet werden soll.

Setzen Sie "iterm2", um explizit die nativen geteilten Bereiche von iTerm2 zu verwenden. Dieser Modus erfordert die it2-CLI und zeigt einen Fehler mit dem Installationsbefehl an, wenn it2 fehlt. Die Einrichtungsabfrage, die anbietet, it2 zu installieren oder zu tmux zu wechseln, erscheint unter "auto" oder "tmux", wenn Ihr Terminal iTerm2 ist und tmux als Fallback verfügbar ist.

Um den Standardwert zu überschreiben, setzen Sie teammateMode in ~/.claude/settings.json:

{
  "teammateMode": "auto"
}

Um den Modus für eine einzelne Sitzung festzulegen, übergeben Sie ihn als Flag:

claude --teammate-mode auto

Das Flag --teammate-mode ist experimentell und erscheint nicht in claude --help.

Der Modus mit geteilten Bereichen erfordert entweder tmux oder iTerm2 mit der it2-CLI. So installieren Sie manuell:

• tmux: Installieren Sie es über den Paketmanager Ihres Systems. Plattformspezifische Anweisungen finden Sie im tmux-Wiki.
• iTerm2: Installieren Sie die it2-CLI und aktivieren Sie dann die Python-API unter iTerm2 → Settings → General → Magic → Enable Python API.

Teammitglieder und Modelle festlegen

Claude entscheidet anhand Ihrer Aufgabe, wie viele Teammitglieder erzeugt werden, oder Sie können genau angeben, was Sie möchten:

Spawn 4 teammates to refactor these modules in parallel. Use Sonnet for
each teammate.

Claude Code wählt das Modell jedes Teammitglieds aus der ersten der folgenden Quellen, die zutrifft:

1. Das Modell, das Ihr Spawn-Prompt für dieses Teammitglied nennt.
2. Für ein Teammitglied, das aus einer Subagenten-Definition erzeugt wurde, das model der Definition, wobei inherit das Modell des Leads auswählt.
3. CLAUDE_CODE_SUBAGENT_MODEL, wenn diese Variable auf einen anderen Wert als inherit gesetzt ist.
4. Das aktuelle Modell des Leads.

Wenn ein installierter Mod in seinem agent.spawn-Hook ein Modell festlegt, verwendet Claude Code dieses Modell anstelle der ersten Quelle.

Wenn Sie CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 setzen, gelten die ersten beiden Quellen nicht. Claude Code wählt das Modell jedes Teammitglieds aus CLAUDE_CODE_SUBAGENT_MODEL, wenn diese Variable auf einen anderen Wert als inherit gesetzt ist, und andernfalls aus dem aktuellen Modell des Leads. Erfordert Claude Code v2.1.257 oder höher.

Vor v2.1.251 stand CLAUDE_CODE_SUBAGENT_MODEL an erster Stelle dieser Reihenfolge.

[!NOTE]

teammateDefaultModel wurde in v2.1.234 entfernt; Claude Code ignoriert einen verbliebenen Wert. Nennen Sie das Modell stattdessen in Ihrem Prompt.

Claude Code prüft das Modell, das es für ein Teammitglied auswählt, gegen die availableModels-Allowlist Ihrer Organisation. Wenn die Allowlist einen Wert blockiert, ersetzt Claude Code ihn durch ein anderes Modell:

• Familien-Alias wie opus: Auf der Anthropic API und der Claude Platform on AWS führt Claude Code das Teammitglied mit der neuesten Version dieser Familie aus, die die Allowlist zulässt. Bei Anbietern mit anbieterspezifischen Modell-IDs, bei denen die Ersetzung nicht greift, fällt ein blockierter Alias wie jeder andere blockierte Wert gemäß dem nächsten Punkt zurück
• Jeder andere blockierte Wert, einschließlich eines Familien-Alias bei Anbietern, bei denen die Ersetzung nicht greift, oder eines Alias, dessen Familie keine zulässige Version hat: Claude Code führt das Teammitglied stattdessen mit dem Modell des Leads aus. Wenn Sie CLAUDE_CODE_SUBAGENT_MODEL setzen, versucht Claude Code zuerst dieses Modell, nach denselben Regeln

Standardmäßig übernehmen Teammitglieder die Effort-Stufe des Leads. Im Modus mit geteilten Bereichen gilt dies ab v2.1.186; frühere Versionen haben die Effort-Stufe der Sitzung des Leads nicht an Teammitglieder in geteilten Bereichen weitergegeben.

Teammitglieder vor der Implementierung planen lassen

Bei komplexen oder riskanten Aufgaben können Sie Teammitglieder vor der Implementierung planen lassen. Ein Teammitglied, das Claude erzeugt, während sich der Lead im Plan-Modus befindet, arbeitet im nur lesenden Plan-Modus, bis sein Plan fertig ist. Versetzen Sie zuerst den Lead in den Plan-Modus und fordern Sie dann das Teammitglied an:

Spawn an architect teammate to refactor the authentication module.

Wenn dieses Teammitglied mit der Planung fertig ist, sendet es eine Anfrage zur Plangenehmigung an den Lead. Wenn Sie den Berechtigungsmodus dieses Teammitglieds seit seiner Erzeugung nicht geändert haben, genehmigt Claude Code den Plan, sobald die Anfrage eintrifft, ohne dass der Lead ihn prüft. Die Bearbeitungen und Befehle des Teammitglieds durchlaufen weiterhin die unter Berechtigungen beschriebenen Berechtigungsabfragen. Nach der Genehmigung verlässt das Teammitglied den Plan-Modus und beginnt mit der Implementierung.

Wenn Sie ein laufendes In-Process-Teammitglied in den Plan-Modus versetzen, indem Sie beim Anzeigen seiner Sitzung Shift+Tab drücken, prüft der Lead den Plan dieses Laufs, statt dass Claude Code ihn genehmigt. Sie werden nicht um Genehmigung gebeten; der Lead genehmigt den Plan oder schickt ihn zur Überarbeitung zurück.

Direkt mit Teammitgliedern sprechen

Jedes Teammitglied ist eine vollständige, unabhängige Claude Code-Sitzung. Sie können jedem Teammitglied direkt eine Nachricht senden, um zusätzliche Anweisungen zu geben, Rückfragen zu stellen oder seine Vorgehensweise umzulenken.

• In-Process-Modus: Verwenden Sie die Pfeiltasten nach oben und unten im Agentenbereich, um ein Teammitglied auszuwählen, drücken Sie dann Enter, um seine Sitzung anzuzeigen, und tippen Sie, um ihm eine Nachricht zu senden. Drücken Sie x bei einem ausgewählten Teammitglied, um es zu stoppen. Drücken Sie Ctrl+T, um die Aufgabenliste ein- oder auszublenden.
• Modus mit geteilten Bereichen: Klicken Sie in den Bereich eines Teammitglieds, um direkt mit seiner Sitzung zu interagieren. Jedes Teammitglied hat eine vollständige Ansicht seines eigenen Terminals.

Während Sie ein In-Process-Teammitglied anzeigen, gehen einfacher Text und Skills an dieses Teammitglied, und integrierte Befehle gehen an die Sitzung des Leads, mit diesen Schutzmaßnahmen:

• /compact, /clear und /rewind wirken auf die Konversation des Leads, daher bittet Claude Code Sie um Bestätigung, bevor einer dieser Befehle aus dieser Ansicht ausgeführt wird.
• /model und /fast legen das Modell und den Fast-Modus des Leads fest, nicht die des Teammitglieds, daher werden sie in dieser Ansicht nicht ausgeführt. Ein Hinweis erklärt Ihnen den Grund.

Modell und Fast-Modus eines Teammitglieds werden bei seiner Erzeugung festgelegt.

Aufgaben zuweisen und übernehmen

Die gemeinsame Aufgabenliste koordiniert die Arbeit im Team. Der Lead erstellt Aufgaben, und die Teammitglieder arbeiten sie ab. Aufgaben haben drei Zustände: ausstehend, in Bearbeitung und abgeschlossen. Eine Aufgabe kann auch von anderen Aufgaben abhängen und wird in der Aufgabenliste als blockiert angezeigt, bis diese abgeschlossen sind. Teammitglieder übernehmen eine blockierte Aufgabe nicht selbst, aber Sie oder der Lead können sie trotzdem zuweisen.

Agenten ohne die Task-Tools koordinieren sich stattdessen über Nachrichten statt über die gemeinsame Aufgabenliste.

Der Lead kann Aufgaben explizit zuweisen, oder Teammitglieder können sie selbst übernehmen:

• Zuweisung durch den Lead: Teilen Sie dem Lead mit, welche Aufgabe er welchem Teammitglied geben soll
• Selbstübernahme: Nach Abschluss einer Aufgabe übernimmt ein Teammitglied selbstständig die nächste nicht zugewiesene, nicht blockierte Aufgabe

Die Übernahme von Aufgaben verwendet Dateisperren, um Race Conditions zu verhindern, wenn mehrere Teammitglieder gleichzeitig versuchen, dieselbe Aufgabe zu übernehmen.

Teammitglieder beenden

Um die Sitzung eines Teammitglieds ordnungsgemäß zu beenden, sprechen Sie es mit seinem Namen an. Zum Beispiel bei einem Teammitglied namens researcher:

Ask the researcher teammate to shut down

Der Lead sendet eine Anfrage zum Herunterfahren. Das Teammitglied kann zustimmen und sich ordnungsgemäß beenden oder mit einer Begründung ablehnen.

Die gemeinsamen Verzeichnisse des Teams werden automatisch bereinigt, wenn die Sitzung endet, daher gibt es keinen separaten Bereinigungsschritt. Unter Architektur erfahren Sie, welche Verzeichnisse entfernt werden und welche auf dem Datenträger verbleiben.

Qualitätskontrollen mit Hooks durchsetzen

Verwenden Sie Hooks, um Regeln durchzusetzen, wenn Teammitglieder ihre Arbeit beenden oder Aufgaben erstellt oder abgeschlossen werden:

• TeammateIdle: Wird ausgeführt, wenn ein Teammitglied kurz davor ist, in den Leerlauf zu wechseln. Beenden Sie mit Code 2, um Feedback zu senden und das Teammitglied weiterarbeiten zu lassen.
• TaskCreated: Wird ausgeführt, wenn eine Aufgabe erstellt wird. Beenden Sie mit Code 2, um die Erstellung zu verhindern und Feedback zu senden.
• TaskCompleted: Wird ausgeführt, wenn eine Aufgabe als abgeschlossen markiert wird. Beenden Sie mit Code 2, um den Abschluss zu verhindern und Feedback zu senden.

Wie Agent-Teams funktionieren

Dieser Abschnitt behandelt die Architektur und Mechanik hinter Agent-Teams. Wenn Sie sie verwenden möchten, siehe Kontrolle Ihres Agent-Teams oben.

Wie Claude Agent-Teams startet

Um ein Team zu starten, fordern Sie Claude um Teammates an. Claude startet einen Teammate, wenn er das Agent-Tool mit einem name aufruft, während Agent-Teams aktiviert sind, es sei denn, der Aufruf ist ein Fork oder übergibt isolation beim Aufruf selbst. Claude Code fragt Sie nicht um Bestätigung für den Start.

Claude benennt auch gewöhnliche Subagenten von selbst, damit es sie später anschreiben kann. Diese Aufrufe folgen der gleichen Regel, sodass Teams sich auch dann bilden können, wenn Sie nicht um einen gebeten haben. Wenn Sie stattdessen Subagenten möchten, schalten Sie Agent-Teams aus.

Architektur

Ein Agent-Team besteht aus:

Die Mailbox jedes Agenten ist eine JSON-Datei unter ~/.claude/teams/{team-name}/inboxes/{agent-name}.json. Claude Code validiert jeden Eintrag, wenn es eine Mailbox-Datei liest. Einträge, die nicht dem Nachrichtenformat entsprechen, werden als Fehler gemeldet und aus der Datei entfernt; die gültigen Nachrichten werden trotzdem zugestellt.

Claude Code meldet eine Nachricht als gesendet nur, wenn der Schreibvorgang in die Mailbox-Datei des Empfängers erfolgreich ist, ob die Nachricht Klartext oder eine strukturierte Protokollnachricht wie eine Plan-Genehmigung oder Shutdown-Anfrage ist. Wenn der Schreibvorgang fehlschlägt, beispielsweise weil der Speicher voll ist oder das Mailbox-Verzeichnis nicht beschreibbar ist, erhält der sendende Agent einen Fehler und nichts wird gesendet. Siehe Fehler beim Schreiben in die Mailbox eines Teammates für die Fehlermeldungen und Wiederherstellungsschritte.

Claude Code verwaltet Aufgabenabhängigkeiten automatisch: wenn ein Teammate eine Aufgabe abschließt, von der andere Aufgaben abhängen, werden die abhängigen Aufgaben ohne Aktion von Ihnen entsperrt.

Teams und Aufgaben werden lokal unter einem sitzungsabgeleiteten Namen gespeichert. Der Name ist session- gefolgt von den ersten acht Zeichen der Sitzungs-ID:

• Team-Konfiguration: ~/.claude/teams/{team-name}/config.json. Claude Code entfernt das Team-Konfigurationsverzeichnis, wenn die Sitzung endet.
• Aufgabenliste: ~/.claude/tasks/{team-name}/. Dieses Verzeichnis bleibt nach dem Ende der Sitzung auf dem Datenträger erhalten. Um zu ändern, wie lange Claude Code es aufbewahrt, setzen Sie cleanupPeriodDays.

Claude Code generiert beide automatisch beim Sitzungsstart und aktualisiert sie, wenn Teammates beitreten, untätig werden oder gehen.

Die Team-Konfiguration enthält Laufzeitzustand wie Sitzungs-IDs und tmux-Pane-IDs, also bearbeiten Sie sie nicht von Hand oder verfassen Sie sie nicht im Voraus: Ihre Änderungen werden beim nächsten Zustandsupdate überschrieben.

Um wiederverwendbare Teammate-Rollen zu definieren, verwenden Sie stattdessen Subagent-Definitionen.

Die Team-Konfiguration enthält ein members-Array mit dem Namen und der Agent-ID jedes Mitglieds. Der Eintrag des Leads trägt immer den Agent-Typ team-lead. Der Eintrag eines Teammates trägt den Agent-Typ, den der Lead beim Erzeugen benannt hat, ob ein integrierter Typ oder eine Subagent-Definition, und lässt das Feld weg, wenn der Lead keinen benannt hat. Teammates können diese Datei lesen, um andere Teammitglieder zu entdecken.

Es gibt kein Projekt-Level-Äquivalent der Team-Konfiguration. Eine Datei wie .claude/teams/teams.json in Ihrem Projektverzeichnis wird nicht als Konfiguration erkannt; Claude behandelt sie als gewöhnliche Datei.

Verwenden Sie Subagent-Definitionen für Teammates

Beim Erzeugen eines Teammates in beiden Anzeigemodi können Sie einen Subagent-Typ aus dem Projekt-, Benutzer-, verwalteten oder Plugin-Geltungsbereich für Subagenten referenzieren. Dies ermöglicht es Ihnen, eine Rolle einmal zu definieren, wie z. B. einen Security-Reviewer oder Test-Runner, und sie sowohl als delegierter Subagent als auch als Agent-Team-Teammate wiederzuverwenden.

Um eine Subagent-Definition zu verwenden, benennen Sie sie, wenn Sie Claude auffordern, den Teammate zu erzeugen:

Spawn a teammate using the security-reviewer agent type to audit the auth module.

Claude Code liest die Subagent-Definition, die Sie benannt haben, und wendet diese Teile davon auf den Teammate an. Wenn ein Teil vom Anzeigemodus des Teammates abhängt, sagt der Eintrag dies:

• tools: Claude Code beschränkt den Teammate auf die Tools in der tools-Liste der Definition. Für einen In-Process-Teammate fügt Claude Code SendMessage zu dieser Liste hinzu, und in einer Sitzung, die die Task-Tools hat, fügt es auch TaskCreate, TaskGet, TaskList und TaskUpdate hinzu.
• model: Claude Code verwendet das model der Definition in beiden Anzeigemodi, wenn Ihr Spawn-Prompt keinen benennt. Siehe wie Claude Code das Modell eines Teammates auswählt.
• disallowedTools: Für einen In-Process-Teammate entfernt Claude Code die Tools aus disallowedTools der Definition aus den Tools des Teammates. SendMessage und die Task-Tools, die es hinzufügt, bleiben verfügbar, auch wenn die Liste sie nennt.
• effort: Für einen In-Process-Teammate wendet Claude Code den effort-Wert der Definition gemäß den Frontmatter-Regeln für den Effort an.
• autoCompactWindow: Für einen In-Process-Teammate wendet Claude Code den autoCompactWindow-Wert der Definition gemäß den Regeln dieses Felds an. Ein Split-Pane-Teammate ignoriert das Feld. Erfordert Claude Code v2.1.296 oder höher.
• Body: Für einen In-Process-Teammate hängt Claude Code den Body der Definition an seinen Standard-System-Prompt als zusätzliche Anweisungen an. Für einen Split-Pane-Teammate verwendet Claude Code den Body anstelle seines Standard-System-Prompts.
• skills: Claude Code wendet die skills der Definition nicht auf einen Teammate in beiden Anzeigemodi an. Der Teammate lädt Skills aus Ihren Projekt- und Benutzereinstellungen.
• mcpServers: Für einen Split-Pane-Teammate wendet Claude Code das mcpServers der Definition unter den Regeln für dieses Feld an, die auch eine Sitzung abdecken, die mit --agent gestartet wurde. Ein In-Process-Teammate ignoriert das Feld und lädt MCP-Server aus Ihren Projekt- und Benutzereinstellungen.

Wenn Claude einen In-Process-Teammate anschreibt, der nicht mehr läuft, bringt Claude Code ihn in der gleichen Sitzung zurück, stellt alle für ihn gespeicherten Gespräche wieder her und gibt ihm die Nachricht als seinen nächsten Prompt. Nachdem Sie eine Sitzung fortsetzen, werden Teammates auf diese Weise nicht zurückgebracht, gemäß der Fortsetzen-Einschränkung.

Für einen Teammate, den es zurückbringt, wendet Claude Code eine Definition, die aus dem .claude/agents/-Verzeichnis eines Projekts oder einem --add-dir-Verzeichnis stammt, nur erneut an, wenn Sie dem Ordner vertraut haben, in dem die Agent-Datei ist. Einem übergeordneten Ordner zu vertrauen zählt nicht. Bis dahin kommt der Teammate zurück, ohne die Tools oder Anweisungen der Definition zu haben, und behält nur die Tools, die Claude Code jedem In-Process-Teammate hinzufügt. Siehe die Agent-Definition des Teammates wurde nicht wiederhergestellt für den Benachrichtigungstext.

Berechtigungen

Teammates starten mit dem Berechtigungsmodus des Leads, außer dem dontAsk-Modus, den sie nicht erben. Wenn der Lead mit --dangerously-skip-permissions ausgeführt wird, tun dies auch alle Teammates. Nach dem Erzeugen können Sie den Berechtigungsmodus eines einzelnen Teammates ändern, aber Sie können keine Pro-Teammate-Berechtigungsmodi zum Zeitpunkt des Erzeugung setzen.

Ein In-Process-Teammate läuft unter den aktuellen Allow- und Deny-Regeln des Leads, sodass --disallowedTools, --tools und --allowedTools alle für ihn gelten. Prüfen Sie bei einem Split-Pane-Teammate jedes Flag einzeln:

• --disallowedTools und --tools: Der Teammate startet mit den Deny-Regeln und der Tool-Liste aus der Befehlszeile des Leads. Erfordert Claude Code v2.1.309 oder höher.
• --allowedTools: Claude Code übergibt dieses Flag nicht an einen Split-Pane-Teammate, daher ist eine Aktion, die Sie nur damit erlaubt haben, dort nicht vorab genehmigt. Um diese Aktionen im Voraus zu genehmigen, tragen Sie die Regeln unter permissions.allow in --settings ein, wenn Sie den Lead starten. Führen Sie beispielsweise claude --settings '{"permissions":{"allow":["Bash(npm *)"]}}' in Ihrer Shell aus. Die Regeln gelten für den Lead und jeden Split-Pane-Teammate dieser Sitzung.

Berechtigungsabfragen von Teammates erscheinen in der Lead-Sitzung, also genehmigen Sie sie dort selbst. Den Plan eines Teammates müssen Sie nicht genehmigen.

Nachrichten zwischen Agenten

Wenn ein Agent einem anderen eine Nachricht über SendMessage sendet, wird dem empfangenden Agent mitgeteilt, dass sie von einer anderen Claude-Sitzung stammt, nicht von Ihnen. Ein Teammate kann eine Berechtigungsaufforderung nicht genehmigen oder Zustimmung in Ihrem Namen erteilen, und ein Teammate, dem eine Aktion verweigert wurde, kann sie nicht an einen anderen Teammate weitergeben, um die Überprüfung zu umgehen. Die gleichen Regeln gelten für eine Nachricht, die von einer Ihrer anderen Claude Code-Sitzungen ankommt, außerhalb des Teams ganz.

Im Auto-Modus wendet der Klassifizierer zwei Überprüfungen auf Nachrichten zwischen Agenten an:

• Er behandelt einen Genehmigungsanspruch, der von einem anderen Agenten weitergeleitet wird, als nicht vertrauenswürdige Eingabe statt als Bestätigung von Ihnen.
• Er überprüft jede Nachricht, bevor Claude Code sie liefert, ob eine einfache Nachricht oder eine strukturierte Protokollnachricht wie eine Shutdown-Anfrage oder Plan-Genehmigungsantwort. Eine Nachricht, die er blockiert, erreicht den Empfänger nie.

Kontext und Kommunikation

Jeder Teammate hat sein eigenes Kontextfenster. Beim Erzeugen lädt ein Teammate denselben Projektkontext wie eine reguläre Sitzung: CLAUDE.md, MCP-Server und Skills. Wenn Sie den Lead mit --setting-sources starten, laden Teammates aus der gleichen eingeschränkten Liste von Quellen. Vor v2.1.281 luden Split-Pane-Teammates jede Einstellungsquelle.

Ein Teammate erhält auch den Spawn-Prompt vom Lead. Die Gesprächshistorie des Leads wird nicht übertragen.

Wie Teammates Informationen teilen:

• Automatische Nachrichtenlieferung: wenn Teammates Nachrichten senden, werden sie automatisch an Empfänger geliefert. Der Lead muss nicht auf Updates abfragen.
• Untätigkeitsbenachrichtigungen: wenn ein Teammate fertig ist und stoppt, benachrichtigt er automatisch den Lead und enthält seine endgültige Antwort in der Benachrichtigung. Ein Teammate, dessen Zug bei einem API-Fehler endet, benachrichtigt den Lead, dass er fehlgeschlagen ist, und enthält den Fehlertext.
• Gemeinsame Aufgabenliste: Agenten, die die Task-Tools haben, können den Aufgabenstatus sehen und verfügbare Arbeit beanspruchen.
• Teammate-Messaging: senden Sie eine Nachricht an einen bestimmten Teammate nach Name. Um alle zu erreichen, senden Sie eine Nachricht pro Empfänger.

Der Lead weist jedem Teammate einen Namen zu, wenn er ihn erzeugt, und jeder Teammate kann jeden anderen nach diesem Namen anschreiben. Um vorhersehbare Namen zu erhalten, die Sie in späteren Prompts referenzieren können, teilen Sie dem Lead mit, wie er jeden Teammate in Ihrer Spawn-Anweisung nennen soll.

Token-Nutzung

Agent-Teams verwenden deutlich mehr Tokens als eine einzelne Sitzung. Jeder Teammate hat sein eigenes Kontextfenster, und die Token-Nutzung skaliert mit der Anzahl der aktiven Teammates. Für Recherche, Überprüfung und neue Feature-Arbeit sind die zusätzlichen Tokens normalerweise lohnenswert. Für Routineaufgaben ist eine einzelne Sitzung kostengünstiger. Siehe Agent-Team-Token-Kosten für Nutzungsleitfäden.

Die Anfragen eines In-Process-Teammates fallen außerhalb des Cache-TTL-Buckets der Hauptkonversation, sodass sein Cache standardmäßig fünf Minuten hält, auch bei einem Claude-Abonnement. Um es für eine Stunde zu behalten, setzen Sie subagentPromptCacheTtl auf 1h. Die API berechnet 1-Stunden-Cache-Schreibvorgänge mit einem höheren Satz.

Anwendungsbeispiele

Diese Beispiele zeigen, wie Agent-Teams Aufgaben handhaben, bei denen parallele Exploration Wert bietet.

Führen Sie eine parallele Code-Überprüfung durch

Ein einzelner Reviewer neigt dazu, sich jeweils auf eine Art von Problem zu konzentrieren. Das Aufteilen von Überprüfungskriterien in unabhängige Domänen bedeutet, dass Sicherheit, Leistung und Testabdeckung alle gleichzeitig gründlich beachtet werden. Der Prompt weist jedem Teammate eine unterschiedliche Perspektive zu, damit sie sich nicht überlappen:

Spawn three teammates to review PR #142:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

Jeder Reviewer arbeitet vom selben PR aus, wendet aber einen anderen Filter an. Der Lead synthetisiert Erkenntnisse über alle drei nach Abschluss.

Untersuchen Sie mit konkurrierenden Hypothesen

Wenn die Grundursache unklar ist, neigt ein einzelner Agent dazu, eine plausible Erklärung zu finden und zu stoppen. Der Prompt bekämpft dies, indem er Teammates explizit gegnerisch macht: die Aufgabe jedes ist nicht nur, seine eigene Theorie zu untersuchen, sondern auch die anderen in Frage zu stellen.

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses. Have them talk to
each other to try to disprove each other's theories, like a scientific
debate. Update the findings doc with whatever consensus emerges.

Die Debattenstruktur ist der Schlüsselmechanismus hier. Sequenzielle Untersuchung leidet unter Verankerung: sobald eine Theorie untersucht wird, ist die nachfolgende Untersuchung zu ihr vorgespannt.

Mit mehreren unabhängigen Ermittlern, die aktiv versuchen, sich gegenseitig zu widerlegen, ist die Theorie, die überlebt, viel wahrscheinlicher die tatsächliche Grundursache.

Best Practices

Geben Sie Teammates genug Kontext

Teammates laden Projektkontext automatisch, einschließlich CLAUDE.md, MCP-Server und Skills, aber sie erben nicht die Gesprächshistorie des Leads. Siehe Kontext und Kommunikation für Details. Fügen Sie aufgabenspezifische Details in den Spawn-Prompt ein:

Spawn a security reviewer teammate with the prompt: "Review the authentication module
at src/auth/ for security vulnerabilities. Focus on token handling, session
management, and input validation. The app uses JWT tokens stored in
httpOnly cookies. Report any issues with severity ratings."

Wählen Sie eine angemessene Teamgröße

Es gibt keine harte Grenze für die Anzahl der Teammates, aber praktische Einschränkungen gelten:

• Token-Kosten skalieren linear: jeder Teammate hat sein eigenes Kontextfenster und verbraucht Tokens unabhängig. Siehe Agent-Team-Token-Kosten für Details.
• Koordinationsaufwand nimmt zu: mehr Teammates bedeutet mehr Kommunikation, Aufgabenkoordination und Konfliktpotenzial
• Sinkende Erträge: über einen bestimmten Punkt hinaus beschleunigen zusätzliche Teammates die Arbeit nicht proportional

Beginnen Sie mit 3-5 Teammates für die meisten Workflows. Dies balanciert parallele Arbeit mit verwaltbarer Koordination. Wenn Sie 15 unabhängige Aufgaben haben, sind 3 Teammates ein guter Ausgangspunkt.

Skalieren Sie nur auf, wenn die Arbeit wirklich davon profitiert, dass Teammates gleichzeitig arbeiten. Drei fokussierte Teammates übertreffen oft fünf verstreute.

Dimensionieren Sie Aufgaben angemessen

• Zu klein: Koordinationsaufwand übersteigt den Nutzen
• Zu groß: Teammates arbeiten zu lange ohne Check-ins, was das Risiko verschwendeter Anstrengungen erhöht
• Genau richtig: in sich geschlossene Einheiten, die ein klares Ergebnis liefern, wie eine Funktion, eine Testdatei oder eine Überprüfung

[!TIP]

Der Lead teilt Arbeit in Aufgaben auf und weist sie Teammates automatisch zu. Wenn er nicht genug Aufgaben erstellt, bitten Sie ihn, die Arbeit in kleinere Stücke aufzuteilen. Mit 5-6 Aufgaben pro Teammate bleibt jeder produktiv und der Lead kann Arbeit neu zuweisen, wenn jemand steckenbleibt.

Warten Sie, bis Teammates fertig sind

Manchmal beginnt der Lead, Aufgaben selbst zu implementieren, anstatt auf Teammates zu warten. Wenn Sie dies bemerken:

Wait for your teammates to complete their tasks before proceeding

Beginnen Sie mit Recherche und Überprüfung

Wenn Sie neu bei Agent-Teams sind, beginnen Sie mit Aufgaben, die klare Grenzen haben und nicht das Schreiben von Code erfordern: Überprüfung eines PR, Recherche einer Bibliothek oder Untersuchung eines Bugs. Diese Aufgaben zeigen den Wert paralleler Exploration ohne die Koordinationschallenges, die mit paralleler Implementierung einhergehen.

Vermeiden Sie Dateikonflikte

Zwei Teammates, die dieselbe Datei bearbeiten, führen zu Überschreibungen. Teilen Sie die Arbeit so auf, dass jeder Teammate einen anderen Satz von Dateien besitzt.

Überwachen und lenken Sie

Überprüfen Sie den Fortschritt der Teammates, leiten Sie Ansätze um, die nicht funktionieren, und synthetisieren Sie Erkenntnisse, wenn sie eintreffen. Ein Team zu lange unbeaufsichtigt laufen zu lassen, erhöht das Risiko verschwendeter Anstrengungen.

Fehlerbehebung

Teammates werden nicht angezeigt

Wenn Teammates nicht angezeigt werden, nachdem Sie Claude gebeten haben, sie zu starten:

• Im In-Process-Modus erscheinen Teammates im Agenten-Panel unterhalb des Prompt-Eingabefelds. Verwenden Sie die Pfeiltasten nach oben und unten, um einen Teammate auszuwählen, und drücken Sie dann Enter, um ihn anzuzeigen.
• Eine Teammate-Zeile, die nach einer Leerlaufphase verschwunden ist, wurde ausgeblendet, nicht gestoppt. Leerlaufzeilen werden 30 Sekunden, nachdem das gesamte Panel in den Leerlauf gewechselt ist, ausgeblendet und erscheinen beim nächsten Turn des Teammates wieder. Wenn sich mehr als drei Teammates im Leerlauf befinden, werden die überzähligen Zeilen zu einer einzigen Zeile N idle agents zusammengefasst, die Sie mit Enter aufklappen. Senden Sie dem Teammate eine Nachricht mit seinem Namen, um eine ausgeblendete Zeile zurückzuholen.
• Prüfen Sie, ob die Aufgabe, die Sie Claude gegeben haben, komplex genug war, um ein Team zu rechtfertigen. Claude entscheidet anhand der Aufgabe, ob Teammates gestartet werden.
• Wenn Sie ausdrücklich geteilte Bereiche angefordert haben, stellen Sie sicher, dass tmux installiert und in Ihrem PATH verfügbar ist:

  which tmux
  

• Prüfen Sie bei iTerm2, ob die it2 CLI installiert ist und die Python-API in den iTerm2-Einstellungen aktiviert ist.

Claude startet Teammates statt Subagenten

Solange Agent-Teams aktiviert sind, wird ein Subagent, den Claude in der Sitzung des Leads benennt, als Teammate gestartet. Claude kann Subagenten selbstständig benennen, daher kann dies auch bei einer Delegation passieren, die Sie nie als Teamarbeit formuliert haben.

Damit benannte Subagenten wieder als Subagenten gestartet werden, schalten Sie Agent-Teams aus, indem Sie CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS auf 0 setzen:

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "0"
  }
}

Sie müssen keine neue Sitzung starten: Claude Code wendet die env-Werte aus der Einstellungsdatei beim Speichern erneut auf die laufende Sitzung an und liest die Variable jedes Mal neu ein, wenn Claude einen Subagenten startet, sodass der nächste Subagent, den Claude benennt, als Subagent gestartet wird.

Das Setzen der Variable auf 0 in Ihrer Benutzer-settings.json überschreibt einen Shell-Export. Andere Einstellungsquellen können Agent-Teams dennoch aktivieren:

• Einstellungsdateien mit höherem Vorrang: Projekteinstellungen, lokale Einstellungen und eine --settings-Payload werden nach den Benutzereinstellungen angewendet, sodass ein env-Eintrag, der die Variable in einer davon auf 1 setzt, Vorrang hat. Siehe Vorrang von Einstellungen.
• Verwaltete Einstellungen: Verwaltete Einstellungen werden nach allen anderen Quellen angewendet. Wenn Ihre Organisation Agent-Teams dort aktiviert, bitten Sie Ihren Administrator, den verwalteten Wert zu ändern.

Nach der Änderung kann Claude weiterhin Subagenten benennen, und der Name funktioniert weiterhin als SendMessage-Adresse. Claude erhält das Ergebnis jedes Subagenten, sobald dieser fertig ist.

Zu viele Berechtigungsabfragen

Berechtigungsanfragen von Teammates werden an den Lead weitergeleitet, was zu Reibung führen kann. Genehmigen Sie häufige Vorgänge vorab in Ihren Berechtigungseinstellungen, bevor Sie Teammates starten, um Unterbrechungen zu reduzieren.

Agenten stoppen vorzeitig

Teammates können nach Fehlern stoppen, anstatt sich davon zu erholen. Prüfen Sie ihre Ausgabe, indem Sie im In-Process-Modus den Teammate im Agenten-Panel auswählen und Enter drücken oder im Split-Modus auf den Bereich klicken, und dann entweder:

• Geben Sie ihnen direkt zusätzliche Anweisungen
• Starten Sie einen Ersatz-Teammate, der die Arbeit fortsetzt

Eine Nachricht vom Lead oder einem anderen Teammate weckt einen In-Process-Teammate, der darauf wartet, eine fehlgeschlagene API-Anfrage erneut zu versuchen, sodass er es sofort erneut versucht, anstatt die volle Wartezeit bis zum nächsten Wiederholungsversuch abzuwarten.

Auch der Lead kann vorzeitig stoppen, wenn er entscheidet, dass das Team fertig ist, bevor tatsächlich alle Aufgaben abgeschlossen sind. Falls das passiert, weisen Sie ihn an, weiterzumachen.

Verwaiste tmux-Sitzungen

Wenn eine tmux-Sitzung nach dem Ende der Claude Code-Sitzung bestehen bleibt, wurde sie möglicherweise nicht vollständig bereinigt. Listen Sie die Sitzungen auf und beenden Sie die vom Team erstellte Sitzung:

tmux ls
tmux kill-session -t <session-name>

Einschränkungen

Agent-Teams sind experimentell. Aktuelle Einschränkungen, die Sie beachten sollten:

• Keine Sitzungswiederaufnahme mit In-Process-Teammates: /resume und /rewind stellen In-Process-Teammates nicht wieder her. Nach der Wiederaufnahme einer Sitzung kann der Lead versuchen, mit Teammates zu kommunizieren, die nicht mehr existieren. Wenn dies geschieht, teilen Sie dem Lead mit, neue Teammates zu erzeugen.
• Aufgabenstatus kann verzögert sein: Teammates markieren Aufgaben manchmal nicht als abgeschlossen, was abhängige Aufgaben blockiert. Wenn eine Aufgabe steckenbleibt, überprüfen Sie, ob die Arbeit tatsächlich erledigt ist, und aktualisieren Sie den Aufgabenstatus manuell oder teilen Sie dem Lead mit, den Teammate zu anstoßen.
• Abschaltung kann langsam sein: Teammates beenden ihre aktuelle Anfrage oder ihren Werkzeugaufruf, bevor sie herunterfahren, was Zeit in Anspruch nehmen kann.
• Ein Team pro Sitzung: eine Sitzung hat genau ein Team, das auf diese Sitzung beschränkt ist. Sie können keine zusätzlichen benannten Teams erstellen oder ein Team über Sitzungen hinweg freigeben.
• Keine verschachtelten Teams: Teammates können ihre eigenen Teammates nicht erzeugen. Nur der Lead kann das Team verwalten.
• Keine Hintergrund-Subagenten von In-Process-Teammates: die eigenen Subagenten eines In-Process-Teammates laufen im Vordergrund, da die Hintergrundarbeit eines Teammates nicht länger als der Prozess des Leads bestehen kann. Claude Code gibt einen Fehler zurück, wenn ein Teammate einen Subagenten erzeugt, dessen Definition background: true setzt. Eine run_in_background: true-Anfrage eines Teammates schlägt ebenfalls fehl, entweder mit einem Fehler oder durch stilles Ausführen im Vordergrund. Subagenten, die aus der Hauptkonversation gestartet werden, folgen dem Hintergrund-Standard.
• Lead ist fest: die Hauptsitzung ist der Lead für seine Lebensdauer. Sie können einen Teammate nicht zum Lead befördern oder die Führung übertragen.
• Berechtigungen beim Erzeugen gesetzt: Teammates starten mit dem Berechtigungsmodus, der unter Berechtigungen beschrieben ist. Sie können den Berechtigungsmodus eines einzelnen Teammates nach dem Erzeugen ändern, aber Sie können keine Pro-Teammate-Berechtigungsmodi zum Zeitpunkt des Erzeugung setzen.
• Split Panes erfordern tmux oder iTerm2: der Standard-In-Process-Modus funktioniert in jedem Terminal. Der Split-Pane-Modus wird in VS Code's integriertem Terminal, Windows Terminal oder Ghostty nicht unterstützt.

Nächste Schritte

Erkunden Sie verwandte Ansätze für parallele Arbeit und Delegation:

• Leichte Delegation: subagents erzeugen Helper-Agenten für Recherche oder Überprüfung innerhalb Ihrer Sitzung, besser für Aufgaben, die keine Inter-Agent-Koordination benötigen
• Messaging zwischen Ihren eigenen Sitzungen: Cross-Session-Messaging ermöglicht es Claude, Erkenntnisse zwischen den Sitzungen zu übergeben, die Sie selbst ausführen
• Manuelle parallele Sitzungen: Git worktrees ermöglichen es Ihnen, mehrere Claude Code-Sitzungen selbst ohne automatisierte Teamkoordination auszuführen