Claude Code Subagenten: Aufgaben delegieren, Kontext sauber halten

Ein Kontextfenster ist ein Arbeitstisch. Wer eine große Codebasis erkundet, legt Datei um Datei darauf, und irgendwann liegt der eigentliche Auftrag unter dreißig Dateiausgaben begraben. Subagenten lösen genau das: Claude gibt eine Teilaufgabe an einen zweiten Claude ab, der auf seinem eigenen Tisch arbeitet und nur das Ergebnis zurückreicht. Dieser Artikel zeigt, welche Subagenten Claude Code mitbringt, wie Sie eigene anlegen, wie sie aufgerufen werden und was sie sehen. Grundlage ist die Hersteller-Dokumentation, Stand September 2026.

Was ein Subagent ist und wann er sich lohnt

Ein Subagent ist ein eigenständiger Claude-Lauf mit eigenem Kontextfenster, eigenem Systemprompt und einer eigenen Auswahl an Werkzeugen. Die Hauptsitzung formuliert eine Aufgabe, der Subagent arbeitet sie ab und liefert einen Bericht zurück. Alles, was er dafür liest und ausprobiert, bleibt bei ihm. Das lohnt sich in drei Fällen:

• Recherche in großen Codebasen. „Finde heraus, wie unser Auth-System Token erneuert“ liest zwanzig Dateien; im Hauptkontext landet nur die Antwort.
• Wiederkehrende Rollen mit eigenen Regeln. Ein Code-Reviewer, der nur lesen darf, oder ein Test-Läufer, der nach 25 Runden aufhört.
• Parallele Arbeit. Mehrere Subagenten laufen gleichzeitig, jeder mit eigenem Kontext, auf Wunsch jeder in einem eigenen Git-Worktree.

Nicht lohnend ist ein Subagent für eine einzelne Frage, deren Antwort Sie ohnehin sehen wollen. Der Bericht ist eine Zusammenfassung; wer die Dateien selbst braucht, liest sie in der Hauptsitzung.

Die drei eingebauten Subagenten

Drei eingebaute Subagenten decken den Alltag ab; dazu kommen drei Spezialagenten für die Statuszeile, für Fragen zur Claude-Code-Dokumentation und ein Sammelfall, die Sie selten direkt ansprechen. Die drei für den Alltag:

Agent	Zweck	Werkzeuge	Besonderheit
Explore	schnelle Suche und Analyse im Code	nur lesend, Schreiben und Bearbeiten verweigert	überspringt CLAUDE.md und Git-Status, damit die Recherche schnell und günstig bleibt
Plan	Recherche im Planungsmodus	nur lesend	wie Explore, einmalig, nicht fortsetzbar
General-purpose	mehrstufige Aufgaben	alle Werkzeuge, die Subagenten offenstehen	kann per SendMessage fortgesetzt werden

Explore und Plan sind Einweg-Agenten: Sie lassen sich nicht wieder aufnehmen. Wer die eingebauten Agenten nicht will, schaltet sie mit der Umgebungsvariable CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 ab.

Eigene Subagenten anlegen

Ein eigener Subagent ist eine Markdown-Datei mit YAML-Kopf. Der Kopf beschreibt den Agenten, der Textkörper ist sein Systemprompt. Fünf Ablageorte gibt es, in dieser Reihenfolge der Priorität:

• Verwaltete Einstellungen der Organisation
• das Flag --agents beim Start, nur für diese Sitzung
• .claude/agents/ im Projekt, geteilt über Git
• ~/.claude/agents/ für alle Ihre Projekte
• das Verzeichnis agents/ eines aktivierten Plugins

Die Projekt- und Nutzerverzeichnisse werden rekursiv durchsucht; Unterordner sind also erlaubt. Ein vollständiges Beispiel:

# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Prüft Code auf Qualität, Sicherheit und Konventionen. Nach jeder größeren Änderung einsetzen.
tools: Read, Glob, Grep
model: sonnet
permissionMode: default
memory: project
---

Sie sind Code-Reviewer. Analysieren Sie die genannten Dateien und nennen Sie
je Befund: Datei und Zeile, das Problem, warum es eines ist, und einen
konkreten Vorschlag. Ändern Sie nichts.

Die Felder im Kopf

Pflicht sind nur name (Kleinbuchstaben und Bindestriche) und description. Die Beschreibung entscheidet, wann Claude den Agenten von selbst wählt; sie sollte deshalb sagen, wofür und wann. Die übrigen Felder sind optional:

Feld	Wirkung
tools	Positivliste der Werkzeuge; ohne das Feld erbt der Agent alle verfügbaren
disallowedTools	Negativliste, etwa Write, Edit für einen reinen Leser
model	sonnet, opus, haiku, fable, eine volle Modell-ID oder inherit
permissionMode	default, acceptEdits, plan und weitere
maxTurns	Obergrenze an Werkzeug-Runden, bevor der Agent aufhört
skills	Skills, die beim Start vollständig in den Kontext geladen werden
mcpServers	MCP-Server, die dem Agenten zur Verfügung stehen
memory	user, project oder local: eigenes Auto-Memory des Agenten
isolation	worktree: der Agent arbeitet in einem eigenen Git-Worktree
background	true: bleibt im Hintergrund, auch wenn Claude ihn im Vordergrund starten will
effort	Aufwandsstufe von low bis max
color	Anzeigefarbe in der Oberfläche

Sie müssen die Datei nicht von Hand schreiben. Ein Satz in der Sitzung genügt: „Lege einen persönlichen Subagenten code-improver in ~/.claude/agents/ an, der Dateien liest und Verbesserungen für Lesbarkeit und Performance vorschlägt.“ Claude schreibt die Datei, Sie prüfen den Kopf.

Subagenten aufrufen

Vier Wege führen zum Agenten, und sie unterscheiden sich darin, wer entscheidet:

• Automatisch. Claude wählt anhand der Aufgabe und der description. Je klarer die Beschreibung, desto treffsicherer die Wahl. Die Beschreibungen aller eigenen Agenten zusammen sollten unter 15.000 Token bleiben, sonst warnt Claude Code beim Start.
• Im Prompt beim Namen. „Lass den code-reviewer-Subagenten meine letzten Änderungen ansehen.“
• Per @-Erwähnung. @"code-reviewer (agent)" prüfe die Auth-Änderungen, oder getippt als @agent-code-reviewer. Agenten aus Plugins sprechen Sie mit @agent-plugin:name an.
• Als Hauptsitzung. claude --agent code-reviewer startet die Sitzung direkt als dieser Agent; dasselbe lässt sich mit "agent": "code-reviewer" in .claude/settings.json festlegen.

Ein Subagent, der ein Ergebnis geliefert hat, kann fortgesetzt werden: Claude schickt ihm über SendMessage eine weitere Nachricht, und der Agent arbeitet mit seinem bisherigen Kontext weiter. Das gilt nicht für Explore und Plan.

Was ein Subagent sieht und was nicht

Der häufigste Denkfehler beim ersten Einsatz: der Subagent weiß nicht, worüber Sie gerade gesprochen haben. Er bekommt:

• seinen eigenen Systemprompt, also den Textkörper der Agentendatei, plus Umgebungsdetails; nicht den Systemprompt von Claude Code
• die Aufgabe, die Claude ihm formuliert
• die CLAUDE.md-Dateien in voller Hierarchie (Explore und Plan ausgenommen)
• einen Schnappschuss des Git-Status vom Sitzungsstart
• die Skills aus dem Feld skills, vollständig geladen

Nicht bekommt er die Gesprächshistorie, das Auto-Memory der Hauptsitzung und frühere Skill-Aufrufe. Wer will, dass der Agent den ganzen Verlauf kennt, nutzt einen Fork: /subtask entwirf Unit-Tests für die bisherigen Parser-Änderungen erbt Systemprompt, Werkzeuge, Modell und Historie, isoliert aber seine Werkzeugaufrufe und gibt nur das Ergebnis zurück.

Einige Werkzeuge stehen Subagenten grundsätzlich nicht zur Verfügung, darunter das Stellen von Rückfragen an Sie, der Wechsel in den Planungsmodus und das Starten weiterer Agenten, sobald die Verschachtelungstiefe erreicht ist. Standardmäßig sind drei Ebenen erlaubt und 20 Agenten gleichzeitig; beide Werte lassen sich über CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH und CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS ändern.

Drei Rezepte aus der Praxis

Der Leser, der nichts anfasst

Für Durchsichten und Recherche. Die Positivliste ist hier die sicherere Wahl: was nicht draufsteht, bleibt draußen, auch jedes MCP-Werkzeug, das später dazukommt. Wer dem Agenten lesende MCP-Werkzeuge lassen will, nimmt stattdessen die Negativliste und schließt Schreibendes gezielt aus, etwa mit disallowedTools: Write, Edit, NotebookEdit, Bash, mcp__github.

---
name: leser
description: Liest Code und Dokumente und berichtet. Für Durchsichten, Recherche und Bestandsaufnahmen.
tools: Read, Grep, Glob
model: sonnet
---

Sie lesen und berichten. Jeder Befund nennt Datei und Zeile. Sie ändern nichts.

Der Test-Läufer mit Ausstieg

Für „führe die Tests aus und behebe, was rot ist“. Ohne maxTurns kann so ein Agent lange kreisen:

---
name: test-laeufer
description: Führt die Test-Suite aus und behebt fehlschlagende Tests. Nach Änderungen an Logik einsetzen.
tools: Read, Edit, Bash, Grep, Glob
maxTurns: 25
permissionMode: acceptEdits
---

Führen Sie `pnpm test` aus. Beheben Sie Fehlschläge einzeln und führen Sie
danach nur den betroffenen Test erneut aus. Melden Sie am Ende, was grün
wurde und was offen blieb.

Der Umbauer im eigenen Worktree

Für mechanische Änderungen über viele Dateien, die die Hauptsitzung nicht stören sollen. isolation: worktree gibt dem Agenten eine eigene Kopie des Repositories; Details dazu im Artikel zu Worktrees in Claude Code.

---
name: umbauer
description: Führt mechanische Umbauten über viele Dateien durch
isolation: worktree
---

Führen Sie den gewünschten Umbau in jeder betroffenen Datei durch, lassen Sie
die Tests laufen und berichten Sie das Ergebnis.

Fehlersuche

• Claude wählt den Agenten nie von selbst. Die description beschreibt, was der Agent ist, aber nicht, wann er dran ist. Ergänzen Sie den Auslöser: „Nach jeder Änderung an Migrationen einsetzen.“
• Der Agent kennt eine Vorgabe nicht. Sie stand nur im Gespräch. Was jeder Agent wissen muss, gehört in die CLAUDE.md; die bekommt jeder eigene Agent, nur Explore und Plan nicht.
• Der Agent läuft ohne Ende. maxTurns setzen und die Aufgabe kleiner schneiden.
• Zwei Agenten schreiben in dieselbe Datei. Entweder nacheinander laufen lassen oder beide mit isolation: worktree trennen.

Fazit

Subagenten sind kein Trick für Fortgeschrittene, sondern die Antwort auf ein Alltagsproblem: der Hauptkontext soll den Auftrag tragen, nicht die Recherche. Beginnen Sie mit den eingebauten Agenten, legen Sie den ersten eigenen an, sobald Sie dieselbe Rolle zum dritten Mal beschreiben, und geben Sie jedem Agenten nur die Werkzeuge, die seine Rolle braucht.

Weiterführend

• Claude Code Worktrees: parallele Sitzungen ohne Kollisionen
• CLAUDE.md erstellen und richtig aufbauen
• Claude Code Hooks: Praxisguide mit Rezepten