Claude Code Agents: Subagents verstehen und richtig einsetzen

Ein Subagent ist im Kern eine delegierte Funktion: Claude übergibt ihm eine Aufgabe, er arbeitet in einem separaten, unsichtbaren Fenster und liefert eine aufgeräumte Antwort zurück. Richtig eingesetzt, ist das der größte Hebel, um Claude Code über eine mehrstündige Sitzung hinweg auf Kurs zu halten. Falsch eingesetzt verbrennt das nur Tokens und erhöht ohne Nutzen die Latenz. Dieser Leitfaden zeigt beides: den genauen Ablauf, die Definitionsdatei und die ehrliche Faustregel, wann sich ein Subagent lohnt.

Die 20-Sekunden-Version

Ein Subagent erledigt eine eigenständige Nebenaufgabe in seinem eigenen, isolierten Kontext und gibt anschließend eine kurze Zusammenfassung an die Hauptkonversation zurück. Mehr steckt nicht dahinter. Das löst ein ganz bestimmtes Problem: In langen agentischen Sessions sammeln sich Suchergebnisse, Build-Logs und einmal gelesene Dateien an, bis das Modell mehr Aufmerksamkeit für diesen Ballast als für die eigentliche Aufgabe aufwendet.

Wird die geräuschvolle Arbeit an einen Subagent ausgelagert, bleibt der Ballast dort. Im Hauptverlauf kommt nur das Ergebnis an. Das passende Denkmodell lautet deshalb nicht „ein Team aus KI-Ingenieuren arbeitet gemeinsam“, sondern Kontexthygiene mit Rückgabewert. Wer das im Kopf behält, trifft auch alle weiteren Entscheidungen zu Subagents leichter.

Was Claude Code Agents als Subagents wirklich sind

Ein Subagent läuft in einem eigenen Kontextfenster, mit einem individuellen System-Prompt, festgelegtem Toolzugriff und unabhängigen Berechtigungen. Erkennt Claude eine Aufgabe, die zum beschriebenen Zuständigkeitsbereich eines Subagents passt, delegiert es: Der Subagent arbeitet selbstständig und liefert sein Ergebnis zurück. Das ist die offizielle Definition. Entscheidend sind dabei eigenes Kontextfenster und liefert sein Ergebnis zurück.

Genau an diesem Punkt liegen viele Erklärungen daneben: Ein Subagent beginnt bei null. Er sieht weder den bisherigen Gesprächsverlauf noch die Dateien, die Claude bereits gelesen hat, oder die zuvor aufgerufenen Skills. Claude formuliert eine kurze Delegationsnachricht mit einer Zusammenfassung der Aufgabe. Von da an arbeitet der Subagent nur mit seinem eigenen System-Prompt und grundlegenden Umgebungsangaben wie dem Arbeitsverzeichnis – nicht mit dem vollständigen Claude Code-System-Prompt. Nach Abschluss kommt ausschließlich seine Zusammenfassung zurück.

Diese Trennung hat zwei Seiten. Genau dieser Zielkonflikt entscheidet über den Nutzen:

• Der Gewinn: Der ausführliche Mittelteil – zwölf gelesene Dateien, ein fehlgeschlagener grep-Lauf, ein untersuchtes Log – gelangt nie in den Hauptkontext. Zurück kommt die Antwort, nicht das Durcheinander.
• Der Preis: Der Subagent muss Kontext erneut beschaffen, der bereits vorhanden war. Benötigt eine Aufgabe den Gesprächsverlauf, wird ein frisch gestarteter Subagent kaum sinnvoll weiterkommen.

Die Datei, die einen Subagent definiert

Ein benutzerdefinierter Subagent wird in einer Markdown-Datei mit YAML-Frontmatter beschrieben. Das Frontmatter enthält die Konfiguration, der Markdown-Text darunter wird zum System-Prompt des Subagents. Nur zwei Felder sind Pflicht: name und description.

---
name: code-reviewer
description: Reviews code for quality and best practices. Use immediately after writing or modifying code.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior code reviewer. When invoked, run git diff to see recent
changes, focus on modified files, and review for clarity, naming, error
handling, exposed secrets, input validation, and test coverage. Group your
feedback by priority: critical issues, warnings, then suggestions.

Damit ist der Subagent bereits vollständig und einsatzfähig. Die description ist keine Zierde: Claude liest sie, um zu entscheiden, wann delegiert werden soll. „Reviews code, use immediately after writing or modifying code“ aktiviert den Subagent im richtigen Moment. Eine vage Formulierung wie „code helper“ sorgt dagegen dafür, dass er ungenutzt bleibt. Die Beschreibung sollte wie eine Stellenausschreibung für einen Spezialisten formuliert sein.

Die Datei muss nicht von Hand geschrieben werden. Der Befehl /agents von Claude Code öffnet eine Oberfläche mit mehreren Tabs zur Verwaltung von Subagents: Unter Running erscheinen aktive und kürzlich abgeschlossene Subagents, die sich dort öffnen oder stoppen lassen. Unter Library können sie erstellt, bearbeitet und organisiert werden. Wichtig: Subagents werden beim Start einer Session geladen. Nach einer direkten Änderung der Datei auf dem Datenträger muss die Session daher neu gestartet werden. Änderungen über die /agents-Oberfläche gelten dagegen sofort.

Speicherorte für Subagents – und welche Definition Vorrang hat

Dieselbe Subagent-Datei verhält sich je nach Speicherort unterschiedlich. Der Ort bestimmt, wer sie verwenden kann und welche Definition bei Namenskonflikten gewinnt.

Tragen zwei Subagents denselben Namen, gewinnt der Speicherort mit der höheren Priorität: Verwaltete Definitionen stehen über Projektdefinitionen, Projektdefinitionen über Benutzerdefinitionen. Projektbezogene Subagents werden ausgehend vom Arbeitsverzeichnis in übergeordneten Verzeichnissen gesucht. Seit v2.1.178 gewinnt bei einem Namenskonflikt die Definition, die dem Arbeitsverzeichnis am nächsten liegt. Daneben gibt es eine reine Session-Variante: Beim Start von Claude Code lassen sich Subagents über das Flag --agents als JSON übergeben. Sie gelten dann nur für diese Session und werden nicht gespeichert – praktisch für Automatisierungsskripte und schnelle Tests.

Die praktische Regel: Ein Subagent, der festlegt, wie diese Codebasis geprüft oder getestet werden soll, gehört nach .claude/agents/ und in die Versionsverwaltung, damit das gesamte Team ihn erhält. Ein Subagent für die persönliche Arbeitsweise gehört nach ~/.claude/agents/ und steht dadurch in allen Projekten zur Verfügung.

Modell und Tools: die beiden entscheidenden Stellschrauben

Zwei Frontmatter-Felder leisten den Großteil der eigentlichen Arbeit. Ihre richtige Konfiguration macht aus Subagents mehr als eine nette Spielerei – sie macht sie wirtschaftlich.

Modell. Das Feld model akzeptiert einen Alias (sonnet, opus, haiku, fable), eine vollständige Modell-ID wie claude-opus-4-8 oder inherit. Ohne Angabe gilt standardmäßig inherit: Der Subagent verwendet also dasselbe Modell wie die Hauptkonversation. Dahinter verbirgt sich ein wichtiger Kostenhebel. Ein Subagent, der nur „die Codebasis mit grep durchsuchen und die Ergebnisse zusammenfassen“ soll, braucht kein Spitzenmodell. Mit model: haiku läuft die Routinearbeit auf einem günstigeren, schnelleren Modell, während in der Hauptsession Opus die Denkarbeit übernimmt.

Tools. Standardmäßig erbt ein Subagent alle internen Tools und MCP-Tools der Hauptkonversation. Zwei Felder grenzen das ein: tools ist eine Freigabeliste und erlaubt nur die genannten Tools; disallowedTools ist eine Ausschlussliste und erlaubt alles außer den genannten Tools. Ein Recherche-Subagent, der niemals Dateien verändern soll, erhält tools: Read, Grep, Glob, Bash und kann physisch nichts bearbeiten. Das schafft nicht nur Ordnung, sondern eine echte Sicherheitsgrenze: Ein schreibgeschützter Reviewer kann die geprüfte Datei nicht versehentlich umschreiben.

Eine weitere relevante Einstellung ist isolation: worktree. Sie startet den Subagent in einem temporären Git-Worktree, also einer isolierten Kopie des Repositorys. Nimmt er keine Änderungen vor, wird diese automatisch bereinigt. Das empfiehlt sich, wenn ein Subagent etwas Riskantes ausprobieren soll, ohne den aktuellen Arbeitsbaum zu berühren.

Wann Claude Code Agents als Subagents sinnvoll sind – und wann nicht

Genau dieser Abschnitt fehlt in den üblichen GitHub-Sammlungen voller Konfigurationsdateien, obwohl er in der Praxis Zeit und Geld spart. Ein Subagent ist nicht kostenlos. Die Frage lautet daher nie: „Könnte hier ein Subagent zum Einsatz kommen?“, sondern: „Rechtfertigt die Isolation ihren Aufwand?“

Aus der Funktionsweise ergeben sich ebenso klar die Fälle, in denen ein Subagent die falsche Wahl ist:

• Iteratives Hin und Her. Braucht eine Aufgabe häufige Nachsteuerung und fortlaufendes menschliches Urteil, gehört sie in die Hauptkonversation. Delegation unterbricht diese Schleife.
• Phasen mit gemeinsamem Kontext. Ein Ablauf aus Planung, Umsetzung und Tests, bei dem jede Phase auf der vorherigen aufbaut, gehört in einen Verlauf – nicht in drei isolierte Subagents, die jeweils ohne Vorwissen beginnen.
• Kleine, gezielte Änderungen. Einen Subagent für die Korrektur eines einzelnen Tippfehlers zu starten, kostet mehr als die Korrektur selbst.
• Zeitkritische Arbeit. Subagents beginnen bei null und brauchen Zeit, um Kontext zusammenzutragen. Wenn die Antwort sofort benötigt wird, ist die Bearbeitung im Hauptverlauf schneller.

Subagent, Skill, Fork oder Agent Team?

Claude Code bietet inzwischen vier Möglichkeiten, Arbeit zu strukturieren. Sie werden leicht verwechselt, unterscheiden sich aber vollständig durch ihren Kontext.

Besonders häufig werden Skill und Subagent verwechselt, weil beide wie „gespeichertes Fachwissen“ wirken. Ein Skill besteht aus wiederverwendbaren Anweisungen, die im Kontext der Hauptkonversation ausgeführt werden und damit alles sehen, was dort geschieht. Bei einem Subagent gilt das Gegenteil: Die Isolation ist Absicht; er sieht ausschließlich die übergebene Aufgabe. Soll Claude einen Hausstil anwenden und dabei weiter im gemeinsamen Kontext arbeiten, ist ein Skill richtig. Soll eine umfangreiche Untersuchung außerhalb des Hauptverlaufs stattfinden und nur ihr Ergebnis zurückmelden, passt ein Subagent.

Der Fork bildet die nützliche Mitte. Er erbt die gesamte bisherige Konversation – denselben System-Prompt, dieselben Tools, dasselbe Modell und den Nachrichtenverlauf. Nichts muss erneut erklärt werden. Seine Toolaufrufe bleiben dennoch außerhalb des Hauptkontexts, und nur das Endergebnis kommt zurück. Ein Fork ist die richtige Wahl, wenn ein benannter Subagent zu viel Hintergrund erst neu zusammentragen müsste. Der Fork-Modus ist an die Umgebungsvariable CLAUDE_CODE_FORK_SUBAGENT gebunden.

Leistungsstarke Funktionen – und ihre Grenzen

Zwei neuere Fähigkeiten machen Subagents deutlich leistungsfähiger. Beide haben eine klare Grenze, die berücksichtigt werden sollte.

Verschachtelung. Seit Claude Code v2.1.172 kann ein Subagent eigene Subagents starten. So kann ein Reviewer für jeden Befund einen Prüfer losschicken; sämtliche Zwischenergebnisse bleiben verborgen, nur die Zusammenfassung des obersten Subagents erreicht die Hauptkonversation. Die Grenze ist fest: Die Verschachtelung reicht fünf Ebenen tief und lässt sich nicht konfigurieren. Ein Subagent auf Ebene fünf erhält das Agent-Tool nicht mehr und kann keine weiteren Subagents starten. Diese Obergrenze hat ihren Grund. Tief verschachtelte Auffächerung kann unbeabsichtigt einen ganzen Schwarm starten und den Tokenverbrauch in die Höhe treiben. Tiefe ist deshalb als Budget zu verstehen, nicht als Ziel.

Gedächtnis. Mit memory: project – alternativ user oder local – erhält ein Subagent ein dauerhaftes Speicherverzeichnis, aus dem er über Sessions hinweg liest und in das er schreibt. Ein code-reviewer mit Projektgedächtnis baut nach und nach Wissen über Konventionen und wiederkehrende Probleme auf und wird dadurch mit jeder Nutzung präziser. project ist die empfohlene Standardeinstellung, weil sich der Speicher über die Versionsverwaltung teilen lässt. Bei aktiviertem Gedächtnis fügt Claude Code beim Start die ersten 200 Zeilen beziehungsweise 25KB aus der MEMORY.md in den System-Prompt des Subagents ein. Diese Datei sollte daher sorgfältig gepflegt werden.

Ein guter Einstieg ist ein einzelner, klar fokussierter Subagent – der schreibgeschützte code-reviewer ist das klassische Beispiel. Er gehört nach .claude/agents/, wird in die Versionsverwaltung aufgenommen und läuft nach jeder Änderung. Hat er seinen Nutzen bewiesen, kann ein Recherche-Subagent auf einem günstigeren Modell folgen. Erfolgreiche Teams betreiben hier nicht dreißig Agents. Sie betreiben drei, von denen jeder genau eine Aufgabe gut erledigt. Falls zunächst die Wahl zwischen Coding-Tools ansteht, ist das eine andere Entscheidung. Dabei helfen Codex vs Claude Code vs Cursor und der breitere Vergleich der besten KI-Coding-Agents.

Wer Claude Code in einen echten Auslieferungsprozess integrieren möchte, findet genau dazu den Großteil meiner Beiträge. Der Newsletter liefert praxiserprobte Setups statt Hype vom Tag der Ankündigung.