Agent Teams Best Practices

Problem: Dein Claude Code Agent-Team startet und verbrennt sofort Tokens, ohne brauchbare Ausgabe zu produzieren. Teammitglieder überschreiben gegenseitig ihre Dateien. Der Lead krempelt die Ärmel hoch statt zu koordinieren. Aufgaben bleiben ewig "in Bearbeitung" stecken. Das ist alles behebbar, und die Muster unten wurden aus Community-Berichten und monatelanger echter Iteration seit dem Feature-Launch destilliert.

Quick Win: Schalte den Delegate-Modus ein (Shift+Tab) und gib jedem Teammitglied im Spawn-Prompt explizite Dateigrenzen. Diese zwei Anpassungen allein eliminieren die häufigsten Team-Fehler.

Hinweis: Das ist ein Schwester-Guide zum Agent Teams-Überblick. Geh zuerst dorthin, wenn du noch kein Team eingerichtet hast. Für die Knöpfe und Schalter, sieh dir Advanced Controls an.

Gib Teammitgliedern genug Kontext

Lade aufgabenspezifische Details in den Spawn-Prompt. Projektkontext (CLAUDE.md, MCP-Server, Skills) kommt automatisch, aber der Gesprächsverlauf des Leads reist nicht mit dem Teammitglied. Zeig auf spezifische Dateien, Akzeptanzkriterien und Einschränkungen. Ein präziser Spawn-Prompt schneidet das Hin-und-Her drastisch ab.

Ein schwammiger Prompt wie "überprüfe das Auth-Modul" lässt das Teammitglied durch die Codebase suchen, herausfinden, was wichtig ist, und Prioritäten raten. Diese Erkundung verbrennt Tokens und Zeit. Ein spezifischer Prompt entfernt die Ambiguität:

Die Form ist einfach: was zu tun ist, wo es zu tun ist, worauf man sich konzentrieren soll, und wie die Lieferung aussehen soll. Teammitglieder, die ihren Umfang von Anfang an kennen, sind schneller fertig und liefern bessere Arbeit. Wenn du von Subagent-Mustern kommst, die Regel ist identisch, aber der Einsatz ist höher. Jedes Teammitglied ist jetzt ein vollständiges Kontextfenster.

Bemess Aufgaben für Teammitglieder

Zu klein und der Koordinations-Overhead frisst den Gewinn. Zu groß und Teammitglieder schuften ohne Check-ins, mit dem Risiko verlorener Arbeit. Der Sweet Spot ist eine in sich geschlossene Einheit mit einem sauberen Lieferergebnis: eine Funktion, eine Test-Datei, ein Review-Dokument.

Strebe nach 5-6 Aufgaben pro Teammitglied. Das hält alle in Bewegung und ermöglicht dem Lead, Arbeit umzuverteilen, wenn jemand steckt. Wenn der Lead Arbeit nicht fein genug schneidet, sag ihm, die Teile kleiner zu machen. Ein Teammitglied mit einer riesigen Aufgabe hat keinen natürlichen Checkpoint. Ein Teammitglied mit 5-6 fokussierten Aufgaben berichtet nach jeder einzelnen, was dir Raum gibt zu steuern.

Vermeide Datei-Konflikte

Zwei Teammitglieder, die dieselbe Datei bearbeiten, bedeuten stille Überschreibungen. Das ist die wichtigste Regel für Implementierungsarbeit. Teile Aufgaben so auf, dass jedes Teammitglied einen eigenen Satz von Dateien besitzt. Schreibe Verzeichnisgrenzen explizit in den Spawn-Prompt.

Wenn sich das Repo nicht natürlich in unabhängige Verzeichnisse aufteilen lässt, erstelle die Aufteilung in deiner Zerlegung. Statt "refaktoriere die API-Schicht" für drei Teammitglieder, weise einem "refaktoriere die User-Endpoints in src/api/users/" zu und einem anderen "refaktoriere die Billing-Endpoints in src/api/billing/". Explizite Eigentümerschaft verhindert die stillen Überschreibungen, die ganze Teammitglieder-Sessions zerstören.

Für Projekte, bei denen geteilte Dateien nicht vermeidbar sind, markiere sie in deinem CLAUDE.md als "vor dem Bearbeiten koordinieren" und lass den Lead den Zugriff über die Aufgabenliste sequenzieren.

Nutze den Delegate-Modus

Schalte den Delegate-Modus ein (Shift+Tab), sobald ein Team startet. Ohne ihn schnappt der Lead manchmal Aufgaben, die für Teammitglieder gedacht sind, und verwischt, wer was besitzt. Delegate-Modus beschränkt den Lead auf Koordinations-Tools, sodass er bei Orchestrierung statt Implementierung bleibt. Für die vollständige Erklärung und Konfigurationsoptionen, sieh den Delegate-Mode-Guide.

Fang mit Recherche-Aufgaben an

Neu bei Agent Teams? Beginne mit Aufgaben, die saubere Grenzen haben und kein Code-Schreiben erfordern: PR-Reviews, Bibliotheksrecherche, Bug-Untersuchung oder Modul-Audits gegen eine spezifische Checkliste. Diese zeigen den Gewinn paralleler Erkundung ohne die Koordinations-Kopfschmerzen paralleler Implementierung.

Recherche-Aufgaben sind auch verzeihend. Wenn ein Teammitglied einen unproduktiven Pfad einschlägt, verlierst du Tokens, keinen Code. Implementierungsfehler sind schwerer rückgängig zu machen, besonders wenn mehrere Teammitglieder Änderungen aufeinander gestapelt haben.

Sobald sich Team-Dynamiken natürlich anfühlen, wechsle zu Implementierungsaufgaben. Dieselben Muster gelten, aber der Einsatz steigt und Datei-Eigentumsgrenzen sind viel wichtiger.

Überwache aktiv

Nutze Ctrl+T, um Fortschritt zu prüfen und Ansätze umzuleiten, die nicht funktionieren. Ein Team zu lange unbeaufsichtigt laufen zu lassen erhöht das Risiko verschwendeter Arbeit, besonders wenn ein Teammitglied auf eine Sackgasse fixiert ist.

Behandle Agent Teams wie einen beaufsichtigten Workflow. Du bist der Projektmanager. Der Lead koordiniert, aber du triffst die strategischen Entscheidungen: wann umzuleiten, wann einen Ersatz zu spawnen und wann ein steckengebliebenes Teammitglied abzuschalten. Denk daran wie ein verteiltes Team von Auftragnehmern zu führen. Regelmäßige Check-ins fangen Probleme, bevor sie sich häufen.

Teamgröße ist wichtig

In der Praxis sind 3-5 Teammitglieder der echte Sweet Spot. Mehr Teammitglieder bedeuten mehr Koordinations-Overhead, mehr Token-Ausgaben und mehr Chancen für Durcheinander. Der Kontext des Leads füllt sich schneller, wenn er 8 Teammitglieder statt 3 verfolgt. Kommunikationskosten skalieren mit der Teamgröße, weil jeder Broadcast im Fenster jedes Teammitglieds landet.

Wenn die Aufgabe wirklich mehr als 5 parallele Arbeiter erfordert, teile sie stattdessen in Phasen auf. Führe ein 3-Teammitglieder-Team für Phase eins aus, räume auf, dann ein weiteres 3-Teammitglieder-Team für Phase zwei. Sequentielle Phasen mit kleineren Teams produzieren sauberere Ergebnisse als ein riesiges Team, das mit allem gleichzeitig kämpft.

Planungsmodus-Verhalten

Der Planungsmodus innerhalb von Agent Teams hat zwei wichtige Verhaltensweisen, die aus der Dokumentation nicht offensichtlich sind.

Planungsmodus wird jeden Turn neu bewertet, nicht nur einmal. Wenn ein Teammitglied im Planungsmodus läuft, bleibt es für seine gesamte Lebensdauer dort. Jede Aktion, die es ausführt, wird durch die read-only Einschränkung gefiltert. Das macht den Planungsmodus großartig für Design-only Rollen und initiale Aufgabengestaltung, aber schlecht für die Ausführung.

Der Modus eines Teammitglieds ist zum Spawn-Zeitpunkt festgelegt. Einmal gestartet, kannst du ein Teammitglied nicht von Plan auf Standard umschalten. Wenn du einen Übergang von Planung zu Ausführung brauchst, spawne ein frisches Teammitglied im Standard-Modus und übergib den Plan. Versuche nicht, ein bestehendes Teammitglied aus dem Planungsmodus "herauszuschalten".

Das prägt das Team-Design. Nutze Planungsmodus-Teammitglieder für Architektur- und Review-Rollen, wo eine read-only Perspektive der ganze Punkt ist. Nutze Standard-Modus-Teammitglieder für jede Rolle, die Code schreiben oder Dateien modifizieren muss. Für einen Plan-dann-Implementier-Ablauf greife stattdessen auf die Plan-Genehmigungsfunktion zurück. Diese ermöglicht einem Standard-Modus-Teammitglied, zuerst zu planen und nach Genehmigung zu bauen.

Klare Regeln produzieren klare Berichte

Mit soliden Regeln in CLAUDE.md berichten Teammitglieder genau, was sie getan haben, ohne dass der Lead eingreift. Ein Teammitglied, das eine Aufräum-Aufgabe gegen ein gut geschriebenes CLAUDE.md abschließt, gibt etwas zurück wie: "27 console.log über 3 Dateien entfernt. Alle 12 console.error und 2 console.warn in component-page.js behalten. Null console.log in meinen zugewiesenen Dateien verblieben."

Kein Lead-Eingriff nötig. Klare Regeln rein, klare Berichte raus.

Dieses Muster entsteht natürlich, wenn dein CLAUDE.md spezifische Verifikationskriterien auflistet. Statt "Logging aufräumen" weiß das Teammitglied bereits, dass "verifiziert" bedeutet, grep nach verbliebenen Instanzen auszuführen und zu bestätigen, dass Error-Level-Logging überlebt hat. Für mehr zum Gestalten von CLAUDE.md für Teams, sieh dir CLAUDE.md mastery und den CLAUDE.md-Optimierungsabschnitt in Advanced Controls an.

Fehlerbehebung

Häufige Probleme und ihre Fixes, aus Community-Berichten und Release-Notes:

Wenn dein Problem nicht auf dieser Liste steht, prüfe, welche Claude Code-Version du ausführst. Viele frühe Schmerzpunkte wurden in den Releases v2.1.33 bis v2.1.45 behoben.

Aktuelle Einschränkungen

Agent Teams ist experimentell. Diese Einschränkungen sind wissenswert, bevor du dich zu einem teambasierten Workflow verpflichtest:

• Keine Session-Wiederaufnahme: In-Process-Teammitglieder werden bei /resume oder /rewind nicht wiederhergestellt. Nach der Wiederaufnahme kann der Lead versuchen, Nachrichten an Teammitglieder zu senden, die nicht mehr existieren. Sag ihm, Ersatz zu spawnen.
• Aufgabenstatus kann verzögert sein: Teammitglieder vergessen manchmal, Aufgaben als abgeschlossen zu markieren, was abhängige Arbeit blockiert. Prüfe manuell, wenn etwas stecken aussieht.
• Langsames Herunterfahren: Teammitglieder beenden ihren aktuellen Request oder Tool-Aufruf, bevor sie herunterfahren. Das kann Zeit brauchen, wenn ein Teammitglied mitten in einer Implementierung ist.
• Ein Team pro Session: Ein Lead verwaltet ein Team auf einmal. Räume das aktuelle Team auf, bevor du ein weiteres startest.
• Keine verschachtelten Teams: Teammitglieder können keine eigenen Teams spawnen. Nur der Lead verwaltet die Teamhierarchie.
• Fester Lead: Die Session, die das Team erstellt, bleibt für seine Lebensdauer der Lead. Du kannst kein Teammitglied befördern oder Führung übertragen.
• Berechtigungen beim Spawn festgelegt: Alle Teammitglieder starten mit den Berechtigungseinstellungen des Leads. Du kannst individuelle Modi nach dem Spawnen ändern, aber nicht zum Spawn-Zeitpunkt.
• Split-Panes erfordern tmux oder iTerm2: Split-Pane-Modus wird nicht im integrierten Terminal von VS Code, Windows Terminal oder Ghostty unterstützt.

Diese rauen Kanten offen zu kommunizieren ist wichtig. Agent Teams ist ein mächtiges Feature mit sichtbaren Nähten. Entwickler, die die Workarounds jetzt lernen, sind bereit, wenn Anthropic sie glättet.

Aktuelle Fixes

Seit dem initialen Agent Teams Launch in v2.1.32 hat Anthropic mehrere wichtige Fixes geliefert. Wenn du Agent Teams früh ausprobiert hast und Probleme hattest, prüfe, ob dein Problem behoben wurde:

v2.1.33:

• TeammateIdle und TaskCompleted Hooks für Quality Gate-Durchsetzung hinzugefügt
• Task(agent_type) Spawn-Einschränkungen hinzugefügt, um zu kontrollieren, welche Subagent-Typen gespawnt werden können
• Persistentes memory-Feld für Agents mit user-, project- und local-Scopes hinzugefügt
• tmux-Teammitglieder-Sessions korrigiert, damit sie Nachrichten korrekt senden und empfangen
• Planungsmodus-Warnungen in Team-Kontexten korrigiert

v2.1.34:

• Absturz behoben, wenn sich die Agent Teams-Einstellung zwischen Renders änderte

v2.1.41:

• Falschen Modell-Identifikator für Teammitglieder auf Bedrock/Vertex/Foundry behoben
• speed-Attribut zu OTel-Events für Fast Mode Observability hinzugefügt

v2.1.45:

• Teammitglieder-Fehler auf Bedrock/Vertex/Foundry behoben, indem API-Provider-Umgebungsvariablen an tmux-Sessions weitergegeben werden
• Skills, die von Subagents aufgerufen werden, erscheinen nach Kompaktierung nicht mehr fälschlicherweise in der Haupt-Session

Hast du Probleme? Aktualisiere Claude Code auf die neueste Version. Das Team liefert Fixes in einem schnellen Tempo und Agent Teams ist in aktiver Entwicklung.

Verwandte Guides

Dieser Guide ist das operative Playbook. Für den Rest des Bilds:

• Agent Teams-Überblick für die Feature-Grundlagen und Architektur
• Advanced Controls für Anzeigemodi, Delegate-Modus, Hooks und Token-Kostenmanagement
• Use Cases and Prompt Templates für Copy-Paste-Prompts für 10+ reale Szenarien
• End-to-End-Workflow für die vollständige 7-Schritt-Pipeline von Brain Dump bis validiertem Produktionscode
• Sub-agent best practices für den Fall, dass ein volles Team zu viel ist und fokussierte Subagents die richtige Wahl sind