Das Kontext-Problem, das Subagents lösen
Jede Claude-Code-Session hat ein endliches Kontextfenster. Wer eine Codebase durchsucht, zehn Dateien liest, Logs durchforstet und dann noch implementiert, füllt dieses Fenster mit Zwischenergebnissen, die für die eigentliche Entscheidung irrelevant sind — der Suchpfad zu einer Funktion ist nicht das, was am Ende zählt, nur das Ergebnis.
Subagents lösen das strukturell: Jeder Subagent läuft in seinem eigenen Kontextfenster, mit eigenem System-Prompt, eigenen Tool-Rechten und eigenem Modell. Er arbeitet unabhängig und gibt nur die Zusammenfassung an die Hauptsession zurück. Die Recherche bläht den Hauptkontext nicht auf — sie passiert daneben.
Die eingebauten Subagents
Claude Code bringt mehrere Subagents von Haus aus mit, die automatisch zum Einsatz kommen:
Explore — read-only, optimiert für Codebase-Suche. Write und Edit sind explizit verboten. Das Modell wird von der Hauptsession geerbt (bei API-Nutzung gedeckelt auf Opus, damit Explore nie teurer läuft als die Hauptsession selbst). Beim Aufruf gibt Claude eine Tiefe mit: quick, medium oder very thorough.
Plan — ebenfalls read-only, kommt im Plan-Modus zum Einsatz, um Kontext zu sammeln bevor ein Plan vorgestellt wird.
general-purpose — hat Zugriff auf das volle Subagent-Tool-Set, für komplexe Aufgaben die sowohl Recherche als auch Änderungen brauchen.
Daneben gibt es kleinere Helfer wie claude-code-guide (läuft auf Haiku, für Fragen zu Claude-Code-Features) und statusline-setup. Für die meisten Alltagsaufgaben reichen diese eingebauten Subagents völlig aus — der Bedarf für einen eigenen entsteht erst bei echter Wiederholung.
Wann sich ein eigener Subagent lohnt
Die Dokumentation formuliert die Faustregel klar: einen eigenen Subagent definierst du, wenn du wiederholt dieselbe Art Worker mit denselben Anweisungen startest. Nicht für den Einzelfall — dafür reicht ein normaler Prompt oder ein eingebauter Subagent.
Typische Kandidaten: ein Code-Reviewer mit fixem Fokus (Security, Performance, Style), ein Test-Schreiber der immer nach demselben Muster vorgeht, ein Dokumentations-Auditor der regelmäßig gegen dieselben Kriterien prüft.
Format und Ablagepfad
Ein Subagent ist eine Markdown-Datei mit YAML-Frontmatter:
---
name: code-reviewer
description: Reviewed Code auf Qualität und Best Practices. Nutzen nach jeder Code-Änderung.
tools: Read, Grep, Glob
model: sonnet
---
Du bist Code-Review-Spezialist. Erkläre für jeden Fund das Problem,
zeige den aktuellen Code und liefere eine verbesserte Version.
Ablagepfad bestimmt die Reichweite:
| Pfad | Reichweite | Priorität |
|---|---|---|
| Managed Settings | Organisationsweit | 1 (höchste) |
| --agents-CLI-Flag | Nur aktuelle Session | 2 |
| .claude/agents/ | Aktuelles Projekt | 3 |
| ~/.claude/agents/ | Alle eigenen Projekte | 4 |
| Plugin-Verzeichnis | Wo Plugin aktiv ist | 5 (niedrigste) |
Projekt-Subagents gehören ins Repo und ins Git — das Team profitiert automatisch mit. Persönliche, projektübergreifende Subagents gehören ins Home-Verzeichnis.
Stolperfalle: Ein neu angelegtes ~/.claude/agents/- oder .claude/agents/-Verzeichnis wird nur erkannt, wenn es beim Start der Session bereits existierte. Legst du das Verzeichnis mitten in einer laufenden Session an, brauchst du einen Neustart, damit der neue Subagent gefunden wird.
Die drei Hebel: Description, Tools, Modell
Description entscheidet über Auto-Delegation. Claude Code liest das description-Feld, um zu entscheiden, wann automatisch an diesen Subagent delegiert wird. Eine vage Beschreibung ("hilft bei Code") führt zu unzuverlässiger Delegation. Konkret formulieren, mit Trigger-Kontext ("Nutzen nach jeder Code-Änderung", "Für Sicherheits-Reviews vor jedem Commit").
Tools sind eine Sicherheits- und Kostengrenze, kein Implementierungsdetail. Ein Subagent der nur recherchieren soll, bekommt tools: Read, Grep, Glob — kein Write, kein Edit, oft auch kein Bash. Das verhindert nicht nur versehentliche Änderungen, es begrenzt auch den Schaden, falls ein Subagent auf manipulierten Input trifft (siehe dazu unseren MCP-Sicherheits-Artikel — dieselbe Logik von Least-Privilege gilt für Subagent-Tool-Scopes wie für MCP-Tool-Scopes).
Modell ist der Kostenhebel. Ein Subagent für einfache, klar umrissene Aufgaben (Formatierung prüfen, eine bestimmte Datei zusammenfassen) läuft auf einem günstigeren Modell wie Haiku genauso gut wie auf dem teuersten verfügbaren — und deutlich schneller. Komplexe Aufgaben mit mehrdeutiger Interpretation profitieren dagegen vom stärkeren Modell.
Ein Muster, das in der Praxis Zeit spart
Statt für jede neue Session erneut zu erklären "durchsuche zuerst die Codebase, dann implementiere" — was den Kontext mit Suchergebnissen füllt, die nach der Implementierung nicht mehr gebraucht werden — lohnt sich folgender Split:
- Recherche-lastige, wiederkehrende Aufgaben (Codebase verstehen, Muster finden, Konventionen prüfen) → eigener read-only Subagent mit engem Tool-Scope
- Implementierung basierend auf der Subagent-Zusammenfassung → Hauptsession, mit vollem Tool-Zugriff, aber ohne den Suchpfad im Kontext
Der Hauptkontext bleibt dadurch über eine lange Session hinweg deutlich schlanker — man merkt es daran, dass Claude auch nach Stunden noch präzise auf frühere Entscheidungen in derselben Session referenzieren kann, statt relevante Details in einer Flut von Zwischenergebnissen zu verlieren.
Praktische Einordnung
Subagents sind kein Ersatz für gute Prompts, sie sind eine Strukturentscheidung: Welche Arbeit soll den Hauptkontext belasten, welche nicht? Wer nur gelegentlich mit Claude Code arbeitet, braucht wahrscheinlich nie einen eigenen Subagent — die eingebauten reichen. Wer täglich in derselben Codebase arbeitet und sich dabei ertappt, immer wieder dieselbe Recherche-Anweisung zu tippen, spart mit einem eigenen, sauber gescopten Subagent echte Zeit und Kontext.
In der Zone "Coding & Projekte" im Discord landen laufend eigene Subagent- und Skill-Setups — von einzeiligen Review-Agents bis zu mehrstufigen Pipelines.
