Claude Code Subagents: Kontext-Isolation und wann sie lohnen

Die typische Session nach einer Stunde: Claude hat zwanzig Dateien gelesen, drei Testläufe mit langen Logs gemacht, eine Library-Doku überflogen. Der Kontext ist voll mit Material, das für den eigentlichen Change keine Rolle mehr spielt, und die Antworten werden zäher. Subagents sind Claude Codes Antwort darauf: Nebenarbeit in einen eigenen Kontext auslagern und nur das Ergebnis zurückholen. Sie sind aber kein Allheilmittel, und falsch eingesetzt kosten sie mehr, als sie bringen. Stand ist die offizielle Doku im Oktober 2026.

Was ein Subagent technisch ist

Ein Subagent läuft innerhalb deiner Session, aber in einem eigenen Kontextfenster, mit eigenem System-Prompt, eigener Tool-Auswahl und eigenen Permissions. Er sieht deinen bisherigen Verlauf nicht, auch nicht die Dateien, die Claude schon gelesen hat. Claude schreibt eine Delegations-Nachricht mit der Aufgabe, der Subagent arbeitet sie ab und liefert eine Zusammenfassung zurück.

Was ein (nicht geforkter) Subagent beim Start bekommt:

• seinen eigenen System-Prompt plus Umgebungsinfos, nicht den System-Prompt von Claude Code,
• die Task-Nachricht,
• die CLAUDE.md-Dateien des Projekts (abschaltbar mit omitClaudeMd: true),
• einen Git-Status-Snapshot,
• Skills, die im Feld skills vorgeladen sind.

Was nicht ankommt: dein Output Style, deine Auto Memory und der Gesprächsverlauf. Wichtig für die Kosten: Subagents schicken eigene Requests und zählen auf dieselben Usage-Limits wie die Hauptsession. Wenn du auf ein Modell mit kleinerem Kontextfenster delegierst, bekommt der Subagent auch nur dieses kleinere Fenster.

Eingebaut: Explore und Plan

Claude Code bringt eigene Subagents mit. Explore ist read-only (Write und Edit sind gesperrt) und für Suche und Codebase-Analyse gedacht. Plan sammelt im Plan Mode Kontext, ebenfalls read-only. Beide starten ohne CLAUDE.md und ohne Git-Status, damit die Recherche schnell und günstig bleibt.

Ein eigener Agent mit dem Namen Explore überschreibt den eingebauten. So kannst du Exploration mit model: haiku auf ein günstigeres Modell legen.

Eigene Subagents: eine Markdown-Datei

Ein Subagent ist eine Datei mit YAML-Frontmatter, der Body ist sein System-Prompt. Pflicht sind nur name und description:

<!-- .claude/agents/test-runner.md -->
---
name: test-runner
description: Führt die Test-Suite aus und fasst nur Fehlschläge zusammen. Nach Code-Änderungen nutzen.
tools: Read, Grep, Glob, Bash
model: haiku
---

Führe die Tests des Projekts aus. Gib pro fehlschlagendem Test Datei,
Testname und die relevante Fehlermeldung zurück. Keine vollständigen Logs.

Ein paar Regeln, die man kennen sollte:

• Scopes und Priorität: Managed Settings vor --agents-Flag vor .claude/agents/ vor ~/.claude/agents/ vor Plugins. Bei gleichem Namen gewinnt die höhere Ebene.
• Feldnamen sind camelCase (maxTurns, disallowedTools). Unbekannte Felder ignoriert Claude Code ohne Fehlermeldung, ein Tippfehler fällt also nicht auf.
• Die description entscheidet über die automatische Delegation und liegt dauerhaft im Kontext. Ab 15.000 Tokens Gesamtlänge eigener Beschreibungen warnt Claude Code beim Start. Details gehören in den Body, der erst beim Aufruf geladen wird.
• Änderungen an Agent-Dateien werden ohne Neustart erkannt, außer das agents-Verzeichnis existierte beim Start der Session noch nicht.

Modellwahl und Tools

Das Modell wird in dieser Reihenfolge aufgelöst: Parameter beim einzelnen Aufruf, dann model in der Frontmatter (inherit heißt Hauptmodell), dann die Umgebungsvariable CLAUDE_CODE_SUBAGENT_MODEL, zuletzt das Modell der Hauptsession. Extended Thinking erbt der Subagent von der Session, eine eigene Einstellung pro Agent gibt es nicht.

Bei den Tools gibt es zwei Filter. Einige Tools wie AskUserQuestion oder EnterPlanMode bekommt kein Subagent. Und Subagents im Hintergrund, dem Standardfall, haben nur einen reduzierten Satz eingebauter Tools. Dieselbe Definition kann im Vordergrund also andere Tools haben als im Hintergrund. Über Permission-Regeln wie Agent(Explore) im Deny lassen sich Agents ganz abschalten. Wie das zusammenspielt, steht im Artikel zu settings.json Permissions.

Hooks lassen sich direkt in der Frontmatter eines Subagents definieren und gelten nur, solange er läuft. Ein klassisches Beispiel: ein DB-Agent, dessen PreToolUse-Hook schreibende SQL-Statements blockt. Grundlagen dazu im Artikel Claude Code Hooks.

Nesting und Limits

Subagents dürfen eigene Subagents starten, standardmäßig bis zu drei Ebenen unter der Hauptsession. Einstellbar ist das über CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, der Wert 1 schaltet Nesting ab. Ein Reviewer, der nur lesen soll, bekommt Agent gar nicht erst in seine tools.

Parallel laufen standardmäßig höchstens 20 Subagents pro Session, danach scheitert das Spawnen mit Concurrent subagent limit reached. Der Wert ist über CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS änderbar. Ein Gesamtlimit über die Session gibt es nicht. Mit isolation: worktree arbeitet ein Subagent in einer eigenen Kopie des Repos, und Claude Code blockiert Befehle, die zurück in den Haupt-Checkout schreiben würden.

Wann sich ein Subagent lohnt und wann nicht

Die Doku nennt klare Kriterien, und sie decken sich mit der Praxis. Subagent, wenn die Aufgabe viel Output produziert, den du im Hauptkontext nicht brauchst (Logs, Suchergebnisse, Doku), wenn du Tools oder Rechte gezielt einschränken willst, oder wenn die Arbeit in sich geschlossen ist und eine Zusammenfassung reicht.

Hauptsession, wenn du viel hin und her iterierst, wenn Planung, Umsetzung und Tests denselben Kontext teilen, bei kleinen gezielten Änderungen und wenn Latenz zählt, weil ein frischer Subagent sich erst Kontext erarbeiten muss. Für wiederverwendbare Abläufe im Hauptkontext sind Skills das bessere Werkzeug.

Was das für deinen Workflow bedeutet

Bau Subagents für die Jobs, die deinen Kontext verschmutzen, nicht für alles:

1. Ein günstiger Test- oder Log-Agent, der nur Fehlschläge zurückgibt.
2. Ein read-only Research-Agent (oder ein überschriebener Explore) mit kleinerem Modell.
3. Kurze description-Felder, die Details in den Body.
4. Tool-Listen bewusst setzen, Agent nur dort, wo Nesting wirklich gebraucht wird.

Und prüf, ob deine Agent-Dateien überhaupt so geladen werden, wie du denkst: Ein falsch geschriebenes Frontmatter-Feld wird still ignoriert. Was alles zu einem sauberen Agenten-Setup gehört, findest du auf der Setup-Seite.

Du hast schon eigene Subagents und willst wissen, ob Zuschnitt, Tools und Modellwahl passen? Das Agent-Setup-Review prüft deine .claude/agents/ zusammen mit Settings und Hooks und liefert schriftliche Änderungsvorschläge. Setup-Review anfragen.