Claude Code Agent Teams: Ein Praxis-Guide für paralleles KI-Coding

Claude Code Agent Teams steht im Mittelpunkt dieses Guides. Wir nutzen Claude Code täglich in der Produktion, seit es erschienen ist. Single-Session-Workflows, Sub-Agents für fokussierte Aufgaben, AGENTS.md-Verträge als Grundlage für alles. Als Anthropic am 5. Februar 2026 Agent Teams mit Opus 4.6 veröffentlichte, haben wir alles stehen gelassen und es an unserem echten Codebase getestet. Hier ist, was wir gelernt haben — die praktischen Dinge, die noch niemand abdeckt.

Was Agent Teams wirklich sind

Agent Teams ermöglichen es, mehrere Claude Code Sessions zu orchestrieren, die gemeinsam an einem Projekt arbeiten. Eine Session agiert als Team Lead. Sie erstellt Teammates, weist Aufgaben über eine gemeinsame Task-Liste zu und fasst Ergebnisse zusammen. Jeder Teammate erhält ein eigenes Context Window und kann andere Teammates direkt anschreiben.

Das unterscheidet sich grundlegend von Sub-Agents. Sub-Agents laufen innerhalb des Kontexts deiner Haupt-Session, erledigen fokussierte Arbeit und berichten Ergebnisse zurück. Sie können nicht miteinander kommunizieren. Agent Teams erstellt unabhängige Sessions, die über ein Mailbox-System und eine gemeinsame Task-Liste zusammenarbeiten — denke an ein Projektteam versus eine Freelancer-Warteschlange.

Agent Teams einrichten

Aktiviere das Feature mit einer einzigen Umgebungsvariable:

export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Oder speichere es dauerhaft in deinen Claude Code Einstellungen:

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

Das war's. Keine zusätzlichen Abhängigkeiten, keine externen Tools. Das Feature ist nativ in Claude Code 2.1 integriert.

Plan Mode vs Delegate Mode

Hier versagen die meisten Anleitungen. Es gibt zwei verschiedene Arten, Agent Teams zu betreiben, und die falsche Wahl verschwendet Tokens und liefert schlechtere Ergebnisse.

Plan Mode (Standard)

Der Lead-Agent plant die Arbeit UND beteiligt sich an der Ausführung. Er kann Dateien lesen, Code schreiben und Befehle ausführen — während er gleichzeitig Teammates koordiniert. Das klingt effizient, schafft aber ein Problem: Der Lead lässt sich von Implementierungsdetails ablenken, anstatt sich auf die Koordination zu konzentrieren.

Wann Plan Mode nutzen:

• Kleine Teams (2-3 Teammates), bei denen die direkten Beiträge des Leads wichtig sind
• Aufgaben, bei denen der Lead Teammate-Output in Echtzeit validieren muss
• Schnelles Prototyping, bei dem der Overhead strikter Delegation sich nicht lohnt

Delegate Mode (Shift+Tab)

Drücke Shift+Tab nach dem Start eines Teams, um den Lead auf den Koordinations-Modus zu beschränken. Der Lead kann Teammates erstellen, Nachrichten senden, die Task-Liste verwalten und Worker beenden — aber er kann keinen Code direkt bearbeiten. Teammates übernehmen die gesamte Implementierung.

Wann Delegate Mode nutzen:

• Größere Teams (4+ Teammates), bei denen sich der Lead ausschließlich auf Orchestrierung konzentrieren soll
• Komplexe schichtübergreifende Refactorings, bei denen Koordinationsqualität wichtiger ist als Lead-Beiträge
• Produktions-Workflows mit sauberer Trennung zwischen Planung und Ausführung

Bekanntes Problem (Stand Februar 2026): Delegate Mode hat einen Bug, bei dem Teammates die eingeschränkten Tool-Zugriffsrechte des Leads erben. Wenn deine Teammates plötzlich keine Dateien lesen oder Code schreiben können, liegt es daran. Der Workaround ist, in jedem Teammate-Spawning-Prompt explizit volle Berechtigungen zu gewähren. Verfolge dies unter github.com/anthropics/claude-code/issues/25037.

Der Contract-First-Ansatz

Der größte Einzelfaktor für den Erfolg von Agent Teams ist nicht das Feature selbst — es ist deine AGENTS.md-Datei. Wir betreiben Contract-First-Entwicklung seit Monaten, und Agent Teams verstärkt dessen Bedeutung um eine Größenordnung.

Warum Verträge mit Teams noch wichtiger sind

Wenn eine einzelne Claude Code Session deine AGENTS.md liest, erhältst du eine Interpretation deiner Projektregeln. Wenn vier Teammates sie unabhängig lesen, erhältst du vier Interpretationen. Ohne explizite Verträge treffen Teammates widersprüchliche Annahmen über Code-Stil, Architekturmuster, Testanforderungen und Dateiorganisation.

Unsere AGENTS.md-Struktur für Teams

# AGENTS.md

## Architektur-Regeln
- Alle API-Routen nutzen das Handler-Pattern in /src/handlers/
- Datenbankabfragen gehen durch /src/db/queries/ — niemals Inline-SQL
- Jede öffentliche Funktion hat JSDoc mit @param und @returns

## Datei-Ownership (Kritisch für Teams)
- /src/api/ → API-Teammate besitzt diesen Bereich
- /src/db/ → Datenbank-Teammate besitzt diesen Bereich
- /src/components/ → Frontend-Teammate besitzt diesen Bereich
- /src/tests/ → Test-Teammate besitzt diesen Bereich

## Code-Standards
- TypeScript strict mode, keine `any`-Typen
- Fehlerbehandlung: immer Result<T, E>-Pattern verwenden
- Imports: absolute Pfade über @/-Alias

## Team-Koordinationsregeln
- Vor der Änderung einer gemeinsamen Datei den Datei-Owner anschreiben
- Integrationspunkte dokumentiert in /docs/interfaces.md
- Alle Teammates führen `npm test` aus, bevor sie eine Aufgabe als erledigt melden

Der Abschnitt Datei-Ownership ist die zentrale Ergänzung für Teams. Ohne ihn erzeugen zwei Teammates, die dieselbe Datei bearbeiten, Merge-Konflikte, die Tokens verschwenden und inkonsistenten Code produzieren.

Wann Teams vs Sub-Agents nutzen

Nach zwei Wochen täglicher Nutzung hier unser Entscheidungs-Framework:

Die Schlüsselfrage: Müssen deine Worker miteinander reden? Wenn ja, Agent Teams. Wenn sie nur Arbeit erledigen und berichten müssen, sind Sub-Agents schneller und günstiger.

Praxisbewährte Team-Muster

Muster 1: Das Feature-Squad

Lead → Erstellt 3 Teammates:
  ├── API-Teammate: Baut REST-Endpoints
  ├── DB-Teammate: Erstellt Migrationen + Queries
  └── Test-Teammate: Schreibt Integrationstests, während API + DB arbeiten

Der Test-Teammate beobachtet Nachrichten der anderen beiden und schreibt Tests gegen die definierten Interfaces. Das produziert bessere Testabdeckung als Tests nach der Implementierung zu schreiben, weil der Test-Teammate Annahmen in Echtzeit hinterfragt.

Muster 2: Die Forschungsdebatte

Lead → Erstellt 2-3 Teammates:
  ├── Befürworter A: Argumentiert für Ansatz X mit Belegen
  ├── Befürworter B: Argumentiert für Ansatz Y mit Belegen
  └── (Optional) Kritiker: Versucht beide Ansätze zu brechen

Jeder Teammate recherchiert unabhängig, dann schreiben sie sich gegenseitig Nachrichten mit ihren Ergebnissen. Der Lead fasst die stärksten Argumente aller Seiten zusammen. Wir nutzen das für Architekturentscheidungen, bei denen es keine offensichtlich richtige Antwort gibt.

Muster 3: Der parallele Prozessor

Lead → Erstellt N Teammates:
  ├── Worker 1: Verarbeitet Dateien 1-50
  ├── Worker 2: Verarbeitet Dateien 51-100
  └── Worker N: Verarbeitet Dateien (N-1)*50+1 bis N*50

Für großflächige Operationen wie codebase-weite Refactorings oder Massenverarbeitung von Dateien. Jeder Worker besitzt einen eigenen Dateibereich. Keine Kommunikation zwischen Workern nötig — der Lead verteilt nur und sammelt ein.

Praktische Tipps aus dem täglichen Einsatz

1. Klein anfangen

Erstelle nicht gleich am ersten Tag 6 Teammates. Starte mit 2 Teammates bei einer klar definierten Aufgabe. Lerne die Koordinationsmuster, bevor du skalierst.

2. Scope explizit definieren

Vage Prompts wie „refaktoriere die Codebase" erzeugen Chaos mit Teams. Spezifische Prompts wie „Teammate A: refaktoriere /src/api/auth.ts auf das neue Middleware-Pattern. Teammate B: aktualisiere alle Tests in /src/tests/auth/ entsprechend" liefern saubere Ergebnisse.

3. Keyboard-Shortcuts nutzen

• Shift+Hoch/Runter: Teammate auswählen zum Anzeigen oder Nachricht senden
• Enter (bei ausgewähltem Teammate): Direktnachricht an diesen Teammate öffnen
• Shift+Tab: Delegate Mode ein-/ausschalten

4. Token-Verbrauch überwachen

Agent Teams verbrauchen deutlich mehr Tokens als Einzelsitzungen. Jeder Teammate ist eine separate Claude-Instanz mit eigenem Context Window. Eine Session mit 4 Teammates verbraucht leicht 4-5x so viele Tokens wie eine Solo-Session. Plane dein Budget entsprechend.

5. Immer aufräumen

Rufe TeamDelete auf, wenn die Arbeit abgeschlossen ist. Verwaiste Teammate-Sessions laufen weiter und verbrennen Tokens. Der Lead sollte alle Teammates explizit beenden, bevor er sich verabschiedet.

Die YouTube-Explosion

Drei große YouTube-Videos erschienen innerhalb von 24 Stunden zu Agent Teams — von WorldofAI, Cole Medin und AI Labs. Das signalisiert massives Entwicklerinteresse, bedeutet aber auch, dass die Suchnachfrage gleich explodieren wird. Die meisten dieser Inhalte decken die grundlegende Einrichtung ab. Dieser Guide konzentriert sich auf die Muster und Stolperfallen, die nach dem anfänglichen „Wow"-Moment auftauchen.

Was als Nächstes kommt

Agent Teams ist noch experimentell. Basierend auf den GitHub-Issues und Anthropics Entwicklungstempo erwarten wir:

• Delegate Mode Fix: Der Tool-Vererbungsbug wird wahrscheinlich bald behoben
• Persistente Teams: Aktuell existieren Teams nur innerhalb einer Session. Persistente Teams über Sessions hinweg wären transformativ
• Bessere Token-Effizienz: Der aktuelle Overhead ist hoch. Anthropic arbeitet wahrscheinlich an Context-Sharing-Optimierungen
• SDK-Integration: Das Claude Agent SDK unterstützt bereits Team-Operationen programmatisch. Erwarte tiefere Integration mit CI/CD-Pipelines

Häufig gestellte Fragen (FAQ)

Wie aktiviere ich Agent Teams in Claude Code?

Setze die Umgebungsvariable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 oder füge sie in deiner Claude Code settings.json unter dem env-Schlüssel hinzu. Das Feature erfordert Claude Code 2.1 oder höher und funktioniert mit Opus 4.6.

Was ist der Unterschied zwischen Sub-Agents und Agent Teams?

Sub-Agents laufen innerhalb deiner Haupt-Session, erledigen fokussierte Arbeit und berichten Ergebnisse zurück — sie können nicht miteinander kommunizieren. Agent Teams erstellt unabhängige Sessions mit eigenen Context Windows, die sich direkt über ein Mailbox-System anschreiben und über eine gemeinsame Task-Liste koordinieren können.

Wie viele Teammates sollte ich erstellen?

Starte mit 2-3 für deine ersten Projekte. Jeder Teammate ist eine separate Claude-Instanz, die eigene Tokens verbraucht. Ein Team mit 4 Teammates verbraucht etwa 4-5x so viele Tokens wie eine einzelne Session. Skaliere erst hoch, wenn du bestätigt hast, dass der Koordinations-Overhead sich für deine spezifische Aufgabe lohnt.

Funktioniert AGENTS.md mit Agent Teams?

AGENTS.md ist mit Agent Teams noch kritischer als bei Solo-Sessions. Jeder Teammate liest sie unabhängig, daher muss sie explizit über Datei-Ownership, Code-Standards und Koordinationsregeln sein. Füge einen „Datei-Ownership"-Abschnitt hinzu, der Verzeichnisse auf spezifische Teammate-Rollen abbildet, um Merge-Konflikte zu vermeiden.

Ist Delegate Mode oder Plan Mode besser?

Es hängt von Teamgröße und Aufgabenkomplexität ab. Plan Mode funktioniert gut für kleine Teams (2-3), bei denen die direkten Beiträge des Leads Mehrwert schaffen. Delegate Mode (Shift+Tab) ist besser für größere Teams (4+), bei denen sich der Lead auf Koordination konzentrieren sollte. Beachte, dass Delegate Mode derzeit einen bekannten Bug mit der Vererbung von Tool-Zugriffen hat — prüfe den Issue Tracker für Updates.