So nutzen Sie Subagents in Claude Code

Lange Suchen und ausufernde Testausgaben füllen Ihr Gespräch in Claude Code schnell. Subagents erledigen diese Arbeit in einem eigenen Kontext und liefern eine Zusammenfassung zurück. Diese Anleitung erklärt, was sie sind, wie Sie eigene erstellen und wann sie sich lohnen.

Aktualisiert am 30. Oktober 2026

Kurz gesagt: Ein Subagent ist ein spezialisierter Helfer, an den Claude Code eine Aufgabe übergibt. Er arbeitet in einem eigenen Kontextfenster mit eigenen Anweisungen und Werkzeugzugriff und liefert nur ein Ergebnis zurück. Zum Anlegen speichern Sie eine Markdown-Datei mit name und description im Frontmatter in .claude/agents/ (ein Projekt) oder ~/.claude/agents/ (alle Projekte) und bitten Claude dann, ihn per Name zu nutzen, oder wählen ihn mit @ aus.

Die Details stammen aus der Claude-Code-Dokumentation von Anthropic, Stand Oktober 2026. Claude Code ändert sich oft; führen Sie claude update aus, wenn etwas hier Beschriebenes fehlt.

Was Subagents sind

Trifft Claude auf eine Aufgabe, die zur Beschreibung eines Subagents passt, kann es sie delegieren. Der Subagent beginnt neu: Er sieht Ihr Gespräch nicht, nur die Anweisungen, die Claude weitergibt. Er erledigt seine Arbeit, etwa Dutzende Dateien lesen oder eine Testsuite ausführen, und schickt eine Zusammenfassung zurück. Ihr Hauptgespräch bleibt kurz.

Claude Code bringt eingebaute Subagents mit, darunter:

Explore: schnelle Suche und Analyse einer Codebasis, nur lesend.
Plan: Recherche nur lesend, während Sie im Plan Mode sind.
General-purpose: mehrstufige Aufgaben, bei denen sowohl erkundet als auch geändert werden muss.

Diese müssen Sie nicht einrichten; Claude nutzt sie, wenn sie passen.

Einen eigenen Subagent erstellen

Legen Sie den Geltungsbereich fest. Für einen Subagent, den das ganze Team in einem Repository nutzen kann, erstellen Sie im Projekt den Ordner .claude/agents/. Für einen, der Sie durch alle Projekte begleitet, verwenden Sie ~/.claude/agents/.
Erstellen Sie in diesem Ordner eine Markdown-Datei, zum Beispiel code-reviewer.md.
Beginnen Sie die Datei mit Frontmatter zwischen zwei Zeilen ---. Die erste Zeile der Datei muss --- sein.
Fügen Sie die zwei Pflichtfelder hinzu: name (eine eindeutige Kennung, zum Beispiel code-reviewer, ohne Doppelpunkt) und description (wann Claude ihn nutzen soll, zum Beispiel Reviews code for quality and best practices. Use after code changes.).
Optional ergänzen Sie tools, um einzuschränken, was er nutzen darf, etwa Read, Glob, Grep für einen rein lesenden Reviewer, und model (ein Modell-Alias wie sonnet oder haiku, eine vollständige Modell-ID oder inherit).
Schreiben Sie unter das schließende --- die Anweisungen des Subagents in einfacher Sprache: seine Rolle, was er prüfen und was er zurückgeben soll.
Speichern Sie die Datei. Claude Code übernimmt Änderungen in einem bestehenden agents-Ordner innerhalb von Sekunden; haben Sie den Ordner während der Sitzung angelegt, starten Sie Claude Code neu.

Sie können Claude auch einfach in einer Sitzung bitten, einen Subagent für Sie zu erstellen. In aktuellen Versionen verweist der Befehl /agents genau darauf oder auf das direkte Bearbeiten der Ordner.

Einen Subagent nutzen

Claude entscheiden lassen: Claude vergleicht Ihre Anfrage mit der description jedes Subagents. Formulierungen wie „use proactively“ in der Beschreibung ermutigen es zum Delegieren.
Per Name bitten: zum Beispiel Use the code-reviewer subagent to check my recent changes (Prüfe meine letzten Änderungen mit dem Subagent code-reviewer).
Erwähnen: Tippen Sie @ und wählen Sie den Subagent. So ist garantiert, dass dieser Subagent die Aufgabe übernimmt.
Für eine ganze Sitzung: Führen Sie claude --agent code-reviewer aus.

Wann Subagents helfen und wann nicht

Die Empfehlungen von Anthropic lassen sich so zusammenfassen:

Nutzen Sie einen Subagent, wenn	Bleiben Sie im Hauptgespräch, wenn
die Aufgabe viel Ausgabe erzeugt, die Sie nicht behalten müssen, etwa Logs oder Suchergebnisse	Sie häufig hin und her sprechen müssen
Sie einschränken möchten, welche Werkzeuge genutzt werden dürfen	mehrere Schritte viel Kontext teilen
die Arbeit in sich abgeschlossen ist und in einer Zusammenfassung enden kann	es eine schnelle, gezielte Änderung ist
unabhängige Recherchen parallel laufen sollen

Gut zu wissen

Haben zwei Subagents denselben Namen, gewinnt der Ort mit höherer Priorität: verwaltete Einstellungen, dann das Flag --agents, dann der Projektordner, dann Ihr Benutzerordner, dann Plugins.
Ein Subagent sieht weder Ihren Chatverlauf noch Dateien, die Claude bereits gelesen hat; er ist also auf die Anweisungen angewiesen, die Claude ihm gibt.
Standardmäßig können bis zu 20 Subagents gleichzeitig laufen.
Feldnamen sind in camelCase (zum Beispiel disallowedTools, maxTurns), und unbekannte Felder werden stillschweigend ignoriert; prüfen Sie also die Schreibweise.
Projekt-Subagent-Dateien lassen sich committen, sodass das ganze Team dieselben Helfer bekommt.

Wenn es nicht funktioniert

Claude findet den neuen Subagent nicht: Gab es den agents-Ordner beim Start der Sitzung noch nicht, starten Sie Claude Code neu.
Die Datei wird stillschweigend übergangen: Häufige Ursachen sind ein fehlendes name oder description, ungültiges YAML oder --- nicht in der ersten Zeile. Führen Sie claude --debug aus und lesen Sie das Debug-Log, oder führen Sie claude plugin validate .claude/agents aus, um Dateien zu finden, deren Frontmatter sich nicht parsen lässt.
Claude meldet einen Fehler zu nicht auflösbaren Werkzeugen: Passt keiner der Einträge in tools zu einem echten Werkzeug, startet Claude Code den Subagent in der Regel nicht. Korrigieren Sie die Schreibweise der Werkzeugnamen.
Falsches Modell: Führen Sie /tasks aus, um zu sehen, welches Modell jeder Subagent tatsächlich nutzt.

Die Ergebnisse behalten, nicht nur die Zusammenfassung

Der Bericht eines Subagents landet in Ihrer Sitzung und ist aus dem Blick, sobald die Sitzung geschlossen wird. Mit dem Workbranch-Plugin für Claude Code legt „save this to Workbranch“ (speichere das in Workbranch) die Aufgaben, Entscheidungen und offenen Fragen der Sitzung in einem Projekt ab, und die nächste Sitzung in diesem Ordner beginnt mit dem, was noch offen ist. Mehr dazu unter Workbranch für Claude. Ist einer Sitzung der Platz ausgegangen, erklärt die Anleitung Claude-Code-Sitzung fortsetzen, wie Sie wieder einsteigen.

Quellen

Use Claude Code with your Pro or Max plan (Claude Help Center, geprüft am 30. Oktober 2026)
Create custom subagents (Claude Code docs, geprüft am 30. Oktober 2026)

Häufige Fragen

Verbrauchen Subagents zusätzliches Nutzungskontingent?

Anfragen von Subagents zählen zu denselben Nutzungslimits wie Ihr Hauptgespräch. Wenn Sie einfache Arbeit über das Feld model an ein günstigeres Modell wie Haiku leiten, können Sie die Kosten niedrig halten.

Kann ein Subagent eigene Subagents starten?

Ja, standardmäßig bis zu drei Ebenen unterhalb des Hauptgesprächs. Um das bei einem bestimmten Subagent zu verhindern, lassen Sie Agent aus seiner tools-Liste weg.

Kann ich eine ganze Sitzung als Subagent laufen lassen?

Ja. Starten Sie Claude Code mit claude --agent gefolgt vom Namen des Subagents, dann nutzt die Sitzung dessen Prompt, Werkzeuge und Modell.