Was sind Claude Code Agent Teams?
Eine Claude Code Session ist gut. Fünf, die parallel an der gleichen Codebase arbeiten, sich Nachrichten schicken, Hypothesen debattieren—das ist ein Multi-Agent Swarm mit echter Koordination.
Agent Teams kamen mit Opus 4.6. Du setzt eine Umgebungsvariable (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1), sagst Claude es soll Teammates spawnen, und die organisieren sich selbst über eine geteilte Task-Liste. Kein manuelles Orchestrieren. Kein Copy-Paste zwischen Terminals.
Hier ist der komplette Setup Guide, die Use Cases die den Token-Verbrauch wert sind, und die Limits die sonst niemand erwähnt.
Wie Agent Teams funktionieren
Ein Team hat drei Teile:
- Team Lead: Deine Haupt-Session. Erstellt das Team, spawnt Teammates, weist Tasks zu, synthetisiert Ergebnisse.
- Teammates: Separate Claude Code Instanzen. Jede hat eigenes Context Window, lädt Projekt-Kontext (
CLAUDE.md, MCP Server, Skills), arbeitet unabhängig. - Shared Task List: Zentrale Arbeitsliste mit drei Status: pending, in progress, completed. Tasks können Abhängigkeiten haben—blockierte Arbeit wird automatisch freigegeben.
Der Unterschied zu Subagents: Teammates reden miteinander.
Ein Subagent berichtet nur an den Main Agent. Agent Team Members schicken sich Direktnachrichten, challengen gegenseitig die Findings, und koordinieren sich selbst. Das ist kein simples Multi-Agent Setup—das ist echte Agentic Orchestration.
Agent Teams vs Subagents vs Multi-Agent Swarms
Die Entscheidung die zählt. Falsch gewählt = verschwendete Tokens. Wenn du die Agent Swarm Trap gelesen hast, weißt du warum das richtige Koordinations-Pattern alles ist.
| Feature | Subagents | Agent Teams | Multi-Agent Swarm |
|---|---|---|---|
| Kommunikation | Berichtet nur an Caller | Teammates schreiben sich direkt | Broadcast / Shared State |
| Koordination | Main Agent managed alles | Shared Task List, Selbst-Koordination | Emergent (oft chaotisch) |
| Context | Eigenes Window, Ergebnisse zusammengefasst | Eigenes Window, vollständig unabhängig | Framework-abhängig |
| Token Cost | Niedriger | ~5x pro Teammate | Variiert stark |
| Best For | Fokussierte Tasks, nur Ergebnis zählt | Komplexe Arbeit mit Diskussion | Research, nicht Production |
Nutze Subagents wenn: Du schnelle Worker brauchst die berichten. "Recherchiere X und sag mir was du findest."
Nutze Agent Teams wenn: Worker Findings teilen, sich gegenseitig challengen und autonom koordinieren müssen. "Untersuche diesen Bug aus drei Blickwinkeln und debattiert welche Theorie stimmt."
Vergiss Swarm-Fantasien: 20 Agents ohne Koordination verketten? Lass es. Context > Complexity. Agent Teams geben dir Multi-Agent Vorteile mit echter Struktur.
Setup: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
Agent Teams sind experimentell. Ein Setting zum Aktivieren.
Option 1: settings.json (Empfohlen)
Claude Code Settings öffnen und hinzufügen:
{
"env": {
"CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
}
}
Persistiert über Sessions. Einmal setzen, vergessen.
Option 2: Environment Variable
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1
In .bashrc, .zshrc oder Shell Profile packen für permanent. Ohne dieses Flag sind Agent Team Features komplett versteckt.
Option 3: Per Session
CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 claude
Gut zum Testen ohne Commitment.
Erstes Team spawnen
Einmal aktiviert, sag Claude in natürlicher Sprache:
Ich refactore das Auth-Modul. Erstelle ein Agent Team:
- Ein Teammate für Backend JWT Logic
- Einer für Frontend Session Handling
- Einer schreibt Integration Tests
Claude spawnt das Team, erstellt eine Shared Task List, und startet die Koordination. Keine YAML Configs. Kein Boilerplate. Einfach beschreiben was du brauchst.
Display Modes: Wie du dein Team siehst
Zwei Optionen:
In-process (Default): Alle Teammates laufen in deinem Terminal. Shift+Up/Down um einen Teammate zu wählen. Enter für dessen Session. Escape zum Unterbrechen. Funktioniert überall—VS Code Terminal, iTerm, jede Shell.
Split Panes: Jeder Teammate bekommt eigenen Terminal-Pane. Alle Outputs gleichzeitig sichtbar. Braucht tmux oder iTerm2. Funktioniert nicht im VS Code Terminal.
In settings.json setzen:
{
"teammateMode": "in-process"
}
Oder per Session: claude --teammate-mode in-process.
Starte mit In-Process. Funktioniert überall. Split Panes wenn du's drauf hast.
Use Cases die den Token-Verbrauch wert sind
Nicht alles braucht ein Team. Diese Setups rechtfertigen den 5x Token-Overhead. Gleiche Philosophie wie meine Claude Code Architecture—skaliere wo es zählt.
1. Parallel Code Review (3 Reviewer, 3 Linsen)
Ein Reviewer tendiert zu einer Art von Problemen. Drei fangen was einer übersieht.
Agent Team für PR #142:
- Security Reviewer: Token Handling, Input Validation, Auth Flows.
- Performance Reviewer: N+1 Queries, Memory Leaks, unnötige Renders.
- Test Reviewer: Coverage Gaps, Edge Cases, Flaky Tests.
Wöchentliche Insights zu AI-Architektur. Kein Spam.
Der Lead synthetisiert alle Findings zu einem Review. Drei Perspektiven, ein Output. Allein dafür lohnt sich das Feature.
2. Debugging mit konkurrierenden Hypothesen
Der Killer Use Case. Einzelne Agents finden eine plausible Erklärung und hören auf. Mehrere Agents die gegeneinander argumentieren finden die richtige.
Spawne 3-5 Teammates. Jeder untersucht eine andere Hypothese. Sie schicken sich Nachrichten um Theorien zu widerlegen. Konsens entsteht durch Debatte, nicht durch Raten.
Beispiel-Prompt:
Production API gibt intermittierend 500er. Erstelle ein Debug-Team:
- Hypothese 1: Database Connection Pool Exhaustion
- Hypothese 2: Race Condition im Caching Layer
- Hypothese 3: Memory Leak im Request Handler Sie sollen Evidence teilen und argumentieren welche Theorie zu den Logs passt.
Parallele Investigation mit adversarial Debate. Bringt die stärkste Theorie ans Licht.
3. Multi-Modul Feature Work
Feature spannt Frontend, Backend und Tests. Jeder Teammate besitzt einen Layer. Keine File-Konflikte.
- Teammate 1: Backend API Endpoints & DB Schema.
- Teammate 2: Frontend Components & State Management.
- Teammate 3: E2E Tests & Integration Tests.
Koordination über die Shared Task List. Backend Teammate fertig mit API → Test Teammate startet automatisch.
Pro Tipps
Plan Approval für riskante Tasks. Teammates arbeiten im Read-Only Plan Mode bis der Lead genehmigt. Lass sie nicht auf main pushen ohne Review.
Delegate Mode nutzen. Wenn der Lead anfängt zu coden statt zu koordinieren → Shift+Tab drückt ihn in Orchestration Mode (Spawning, Messaging, Task Management). Leads sollen leaden, nicht coden.
Teammates spezifischen Kontext geben. Sie laden CLAUDE.md automatisch, erben aber nicht die History des Leads. Task-spezifische Details in den Spawn-Prompt packen—File Paths, Constraints, was "done" bedeutet.
File-Konflikte vermeiden. Zwei Teammates im selben File = Überschreibungen. Arbeit aufteilen sodass jeder Teammate andere Files besitzt. Wenn sie das gleiche File brauchen, Tasks mit Dependencies sequenzieren.
Read-Only starten. Dein erster Agent Team Run sollte ein Code Review sein, kein parallelisierter Refactor. Erst Koordinations-Patterns lernen, dann mehrere Agents gleichzeitig coden lassen.
Troubleshooting & Häufige Probleme
"Agent Teams Option erscheint nicht"
Das CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS Flag ist nicht gesetzt. Prüfe mit:
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS
Sollte 1 ausgeben. Bei settings.json sicherstellen dass es im env Block ist, nicht auf Root Level.
"Teammate scheint zu hängen"
Task Status kann laggen. Der Lead denkt vielleicht ein Task ist noch pending obwohl der Teammate schon arbeitet. 10-15 Sekunden warten. Wenn wirklich stuck, den Teammate direkt über den Lead anschreiben.
"Split Panes funktionieren nicht"
Split Pane Mode braucht tmux oder iTerm2. Funktioniert nicht in:
- VS Code Integrated Terminal
- Windows Terminal
- Ghostty
Stattdessen --teammate-mode in-process nutzen.
"Session mit Teammates kann nicht resumed werden"
Bekannte Limitation. /resume und /rewind stellen In-Process Teammates nicht wieder her. Der Lead versucht vielleicht Teammates zu erreichen die nicht mehr existieren. Neue Session starten.
"Teammates editieren das gleiche File"
Kein eingebautes File Locking. Zwei Teammates schreiben in die gleiche Datei = letzer Write gewinnt. Lösung: Tasks so strukturieren dass jeder Teammate andere Files besitzt.
Limits
Ohne Beschönigung:
- Keine Session Resumption:
/resumeund/rewindstellen Teammates nicht wieder her. Nur frische Sessions. - Token-Kosten sind real: Ein 5-Personen Team verbrennt ~5x die Tokens einer Single Session. Für Routine-Tasks nicht rentabel.
- Ein Team pro Session: Aufräumen bevor neues Team startet. Teammates können keine eigenen Teams spawnen (keine verschachtelten Multi-Agent Chains).
- Split Panes brauchen tmux/iTerm2: Nicht jedes Terminal unterstützt es.
- Task Status kann laggen: Koordination ist nicht instant. Komplexe Dependency Chains brauchen manchmal manuelles Nachhelfen.
Aufräumen
Wenn fertig: Immer über den Lead aufräumen.
Der Lead checkt auf aktive Teammates und failt wenn noch welche laufen. Erst runterfahren:
"Ask the researcher teammate to shut down."
Dann: "Clean up the team."
Wenn tmux Session hängt: tmux kill-session -t <session-name>.
Das Urteil
Agent Teams sind das interessanteste Feature im Opus 4.6 Release—und das teuerste.
Für Code Reviews, Adversarial Debugging und Multi-Modul Features: die parallele Exploration findet Dinge die ein einzelner Agent übersieht. Das Competing Hypotheses Pattern allein ist das Lernen wert.
Für sequentielle Tasks oder Same-File Edits: bleib bei Subagents oder einer einzelnen Session. Der Overhead lohnt sich nicht.
Das ist ein weiterer Schritt warum Static Middleware is Dead. Starte mit einem Read-Only Task—einem Code Review—bevor du parallelisierte Implementierung wagst.