Sub-Agents in Claude Code richtig einsetzen
Claude Code verfügt über ein Agent Tool, das eigenständige Sub-Agents innerhalb einer Konversation starten kann. Jeder Sub-Agent hat seinen eigenen Kontext, erledigt seine Aufgabe und liefert das Ergebnis an den Haupt-Agent zurück.
Klingt mächtig — in der Praxis braucht man es aber meistens nicht. Dieser Artikel klärt: Wann Sub-Agents wirklich etwas bringen und wann sie nur im Weg stehen.
Man kann das Agent Tool nicht direkt aus CLAUDE.md oder einem Slash Command aufrufen — es ist ein internes Werkzeug, das Claude Code eigenständig einsetzt. Über Prompts lässt sich die Entscheidung aber beeinflussen.
Der Ablauf eines Sub-Agents:
Wichtige Eigenschaften:
- Isolierter Kontext: Der Sub-Agent sieht den Verlauf der Hauptkonversation nicht — nur den Prompt, mit dem er gestartet wurde
- Ergebnis-Komprimierung: Egal wie viele Dateien gelesen oder Befehle ausgeführt wurden — zurück kommt nur eine Zusammenfassung
- Parallelisierbar: Mehrere Sub-Agents können gleichzeitig gestartet werden
Der klassische Anwendungsfall. Man lässt Claude Code ein Problem untersuchen, das mehrere Richtungen gleichzeitig erfordert.
Beispiel: "Wie ist die Authentifizierung in diesem Projekt umgesetzt?"
Ohne Sub-Agents arbeitet Claude Code sequenziell: Auth-Controller lesen → Middleware lesen → Routes lesen → Model lesen → Config lesen … Schritt für Schritt, langsam.
Mit Sub-Agents:
3 Sub-Agents parallel starten:
- Agent 1: Authentifizierungslogik in Controllern und Middleware untersuchen
- Agent 2: User- und Session-Design auf Model-Ebene analysieren
- Agent 3: Konfigurationsdateien und Umgebungsvariablen auf Auth-Einstellungen prüfen
Drei Richtungen gleichzeitig, Ergebnisse zusammenführen. In CLAUDE.md kann man das so steuern:
## Recherche-Aufgaben
Bei modulübergreifenden Untersuchungen bevorzugt mehrere Sub-Agents
parallel starten und die Ergebnisse am Ende zusammenführen.
Das Kontextfenster von Claude Code ist begrenzt. Wenn eine Teilaufgabe viele Dateien lesen muss, aber am Ende nur ein Fazit liefert, hält ein Sub-Agent den ganzen "Verarbeitungsballast" vom Hauptkontext fern.
Typische Beispiele:
Das gemeinsame Merkmal: Viel Input, wenig Output. Der Sub-Agent verarbeitet die Masse intern und liefert nur das Wesentliche zurück.
Manche Aufgaben könnten schiefgehen. Mit dem Parameter isolation: "worktree" arbeitet der Sub-Agent in einem separaten Git-Worktree. Wenn etwas kaputtgeht, bleibt das aktuelle Arbeitsverzeichnis unberührt.
## Hochrisiko-Refactoring
Für umfangreiche Refactorings Sub-Agents mit Worktree-Isolation verwenden.
Ergebnisse erst nach Überprüfung mergen.
Passende Szenarien:
- Experimentelles Refactoring: Unsicher, ob ein Ansatz funktioniert — der Sub-Agent probiert es zuerst
- Paralleler Lösungsvergleich: Zwei Implementierungen gleichzeitig umsetzen und vergleichen
- Code-Generierung: Große Mengen Boilerplate erzeugen, nach Review integrieren
"Benenne diese Funktion von camelCase in snake_case um" — das macht man direkt. Der Overhead eines Sub-Agents (Kontext aufbauen, auf Rückgabe warten, Ergebnis parsen) ist langsamer als die direkte Ausführung.
Faustregel: Wenn ein Grep + ein Edit reichen, keinen Agent abspalten.
"Erst Config lesen → dann Code anpassen → dann Tests aktualisieren"
Bei solchen Ketten hängt jeder Schritt vom vorherigen ab. Mit Sub-Agents müsste man Zwischenergebnisse per Prompt hin- und herschicken — umständlich und fehleranfällig. Sequenziell abarbeiten ist hier besser.
Ein Sub-Agent liefert zusammenfassenden Text zurück, keine strukturierten Daten. Wenn eine exakte Änderung nötig ist (z. B. bestimmten Code in Zeile 47 einfügen), ist der Haupt-Agent zuverlässiger.
Sub-Agents eignen sich für "recherchieren und Fazit liefern", nicht für "chirurgisch präzise Änderungen ausführen".
Wenn die Konversation gerade erst begonnen hat und das Kontextfenster noch leer ist, braucht man keinen Sub-Agent zum "Kontextschutz". Erst wenn die Konversation länger wird und der Haupt-Agent beginnt, den Verlauf zu komprimieren, lohnt es sich, schwere Aufgaben an Sub-Agents zu delegieren.
Ein reales Szenario: In einem Rails-Projekt alle Controller mit before_action untersuchen und die Authentifizierungs- und Autorisierungsmuster analysieren.
Ohne Sub-Agent:
Claude Code liest die Controller-Dateien nacheinander, jede belegt Hauptkontext. Bei 20 Controllern kann allein der Dateiinhalt massiv Tokens verbrauchen. Wenn dann die Analyse kommt, sind die anfangs gelesenen Details möglicherweise schon komprimiert und verloren.
Mit Sub-Agent:
Sub-Agent starten: "Lies alle Controller in app/controllers/,
finde alle before_action-Callbacks, analysiere die Authentifizierungs-
und Autorisierungsmuster und liefere eine kategorisierte Zusammenfassung."
Der Sub-Agent liest alle Dateien in seinem eigenen Kontext und liefert eine saubere Zusammenfassung. Der Hauptkontext wird kaum belastet — das Fazit ist da, und es kann weitergehen.
Man kann Claude Code nicht zwingen, Sub-Agents zu verwenden oder nicht. Aber über CLAUDE.md lassen sich Präferenzen setzen:
## Agent-Nutzungspräferenzen
### Aufgaben, die sich für Sub-Agents eignen
- Modulübergreifende Recherche (3+ Verzeichnisse)
- Großflächige Code-Suche und Statistiken
- Experimentelles Refactoring (mit Worktree-Isolation)
### Aufgaben, die NICHT aufgeteilt werden sollten
- Einzeldatei-Änderungen
- Sequenzielle Operationen mit Abhängigkeiten
- Bugfixes, bei denen die betroffene Stelle bereits bekannt ist
Ist der "Prozess" dieser Aufgabe deutlich umfangreicher als das "Ergebnis"?
Wenn ja — Sub-Agent einsetzen, den Prozess verdauen lassen, nur das Ergebnis zurückbekommen.
Wenn nein — direkt erledigen, keine Zwischenschicht.
Mehr Sub-Agents sind nicht automatisch besser. Sie sind ein Werkzeug zur Kontextverwaltung, kein Concurrency-Framework. Richtig eingesetzt, helfen sie Claude Code in großen Projekten den Überblick zu behalten. Falsch eingesetzt, verschwenden sie nur Startzeit.