Claude Code Subagenten: Einrichtung, Konfiguration und Einsatzszenarien

Die meisten Claude Code-Sitzungen werden aus demselben Grund langsam und unübersichtlich: Jeder explorative Grep-Durchlauf, jeder Log-Dump und jedes „Ich checke noch eine Datei“ bleibt für immer im Hauptchatverlauf stehen.

Subagenten wurden genau entwickelt, um dieses Problem zu lösen. Sie sind eines der Agenten-Primitives, die in Claude Code integriert sind, um mit lautem, parallelisierbarem Arbeiten umzugehen – eine Möglichkeit, den Chaos in ein isoliertes Fenster zu verlagern und nur die zusammenfassende Information zurückzubringen, die wichtig ist.

Ein Subagent ist kein intelligenterer Claude, und er ist auch nicht dasselbe wie eine Skill (Fertigkeit). Er ist ein separater Reasoning-Agent mit eigenem Kontextfenster, eigener Tool-Allowlist und ohne Erinnerung an Ihre aktuelle Konversation, es sei denn, Sie forkten ihn explizit. Das Verständnis dieser Unterscheidung ist der Unterschied zwischen einer Subagenten-Konfiguration, die stillschweigend Ihr Kontextbudget spart, und einer, die nur Latenz hinzufügt, ohne Nutzen zu bringen.

Subagenten vs. Skills vs. MCP

Claude Code bietet Ihnen drei Erweiterungspunkte, die unterschiedliche Probleme lösen. Sie werden ständig verwechselt, weil alle drei technisch gesehen „bei einer Aufgabe helfen“ können.

Eine nützliche Daumenregel: Ein Hook erzwingt eine harte Einschränkung deterministisch, ein Skill gibt dem Hauptagenten eine Fähigkeit inline, und ein Subagent ist für Arbeiten gedacht, die Sie delegieren und vollständig aus dem Hauptkontext heraushalten wollen. Wenn die Aufgabe eines Skills darin besteht, ein Tool zu orchestrieren, das noch nicht existiert, ist das in der Regel ein Zeichen dafür, dass Sie einen MCP-Server benötigen, keinen Subagenten. Claude Code ist nicht allein mit dieser Struktur – das Ökosystem von OpenCode hat eine vergleichbare Idee in seinen spezialisierten Agenten, die Planung, Recherche und Review auf ähnliche Weise über dedizierte Rollen aufteilen.

Was ein Subagent eigentlich ist

Drei Eigenschaften definieren einen Claude Code Subagenten, und alle drei sind für die Nutzung relevant:

• Isolierter Kontext. Ein Subagent startet mit einem frischen Fenster. Er sieht Ihre Konversationsverlauf nicht, es sei denn, Sie forkten ihn explizit, was sicherstellt, dass seine Ausgabe nicht durch das Kontext verunreinigt wird, über das Sie drei Runden zuvor gesprochen haben.
• Eine eingeschränkte Tool-Allowlist. Subagenten können nur einen Teil dessen nutzen, was die Eltern-Session bereits hat – sie können sich keine neuen Fähigkeiten verschaffen, und ein gut gestalteter Subagent sollte nur die Tools erhalten, die seine Aufgabe erfordert (z. B. read-only Tools für einen Recherche-Agenten).
• Keine Sichtbarkeit zwischen Subagenten. Subagenten können die laufenden Arbeiten der anderen nicht sehen. Wenn Aufgabe B wirklich die Ausgabe von Aufgabe A benötigt, handelt es sich um eine sequenzielle Abhängigkeit, nichts, was Sie über zwei Subagenten parallelisieren können.

Der Auslöser für die Nutzung ist nicht „diese Aufgabe ist schwer“. Es ist „diese Aufgabe ist laut“ – die Art von Arbeit, die viel Zwischenausgabe erzeugt (Dutzende von Dateilesungen, ein langes Log, ein explorativer Grep über das gesamte Repo), bei der keines dieser Zwischenmaterialien in Ihren nächsten Konversationsschritt überleben muss.

Wann Sie einen Subagenten nutzen sollten (und wann nicht)

Gute Anwendungsfälle: Codebasis-Exploration vor einer großen Änderung, automatisierte Testläufe, bei denen Sie sich nur für Pass/Fail und Fehlerzusammenfassungen interessieren, Sicherheits- oder Style-Reviews und jede mehrstufige Rechercheaufgabe, deren Rohausgabe Ihre Hauptsession sonst überschwemmen würde.

Schlechte Anwendungsfälle: Zweisekundige Nachschauen („was gibt diese Funktion zurück“), alles, was enges Hin-und-Her-Verfeinern erfordert, und abhängige Aufgaben, die Sie versucht sind zu „parallelisieren“, obwohl die zweite Aufgabe die Antwort der ersten benötigt. Die Nutzung eines Subagenten für eine triviale Suche fügt nur den Overhead des Startens eines frischen Kontextfensters hinzu, ohne echten Isolationsnutzen.

Die Rendite messen: Kontext- und Kostenrechnung

Das Argument für Subagenten bleibt abstrakt, bis man Zahlen auf eine echte Aufgabe anwendet. Nehmen wir eine gängige: Grep durch einen Service mit ~500 Dateien, um jede Stelle zu finden, an der noch ein veralteter Konfig-Schlüssel gelesen wird, und melden Sie dann die exakten Datei:Zeile-Treffer.

Das ist eine Reduktion von etwa 15-20x dessen, was Ihre Hauptsession für diesen Schritt tragen muss. Das ist der eigentliche Mechanismus hinter „Subagenten halten Sessions schneller“ – es ist keine Magie, es ist Kontext, der überhaupt nicht geladen wird.

Die Kosten compounded sich auf die gleiche Weise. Unter Verwendung der Preise aus der Claude Code Preisübersicht, kostet der Durchlauf dieser Exploration mit Opus (5 $/MTok Input, 25 $/MTok Output) etwa 0,20–0,25 $ nur für die ~40K Input-Tokens. Die Weiterleitung an Haiku (1 $/MTok Input, 5 $/MTok Output) reduziert dies auf 0,04–0,05 $ – und das Opus-Budget der Hauptsession wird durch die Explorationstokens überhaupt nicht berührt, da sie nur die ~2K-Token-Zusammenfassung sieht.

Einen benutzerdefinierten Subagenten definieren

Benutzerdefinierte Subagenten leben als Markdown-Dateien mit YAML-Frontmatter, entweder projektweit in .claude/agents/ (in das Repo committed, vom ganzen Team geteilt) oder benutzerspezifisch in ~/.claude/agents/ (persönliche Tools, die Sie zu jedem Projekt mitbringen).

---
name: code-reviewer
description: >
  Überprüft stagede Änderungen auf Bugs, Sicherheitsprobleme und Style-Verstöße
  vor dem Commit. Verwenden, wenn der Benutzer nach einer Überprüfung, Audit oder
  Prüfung der Änderungen vor dem Committen oder Erstellen eines PRs fragt.  
tools: Read, Grep, Glob
model: sonnet
skills:
  - security-checklist
---
Sie sind ein sorgfältiger Code-Reviewer. Lesen Sie den stageden Diff, markieren Sie
konkrete Probleme mit Datei:Zeile-Referenzen und enden Sie mit einer kurzen
Pass/Fail-Zusammenfassung. Modifizieren Sie keine Dateien.

Das description-Feld ist die wichtigste Zeile in der Datei. Es ist das, was die Routing-Logik der Eltern-Session liest, um zu entscheiden, ob dieser Subagent für die aktuelle Aufgabe passt. Schreiben Sie es wie eine Stellenanzeige – nennen Sie die Auslösebedingung explizit, nicht vage „hilft bei Code“. Vage Beschreibungen werden von der automatischen Dispatch-Logik übersprungen oder falsch angewendet.

Das tools-Feld ist Ihre Isolationsgrenze. Geben Sie einem Recherche-Subagenten Read, Grep und Glob und nichts anderes; ihm jedes verfügbare Tool zu geben, untergräbt den gesamten Sinn, ihn in einer eingeschränkten Sandbox laufen zu lassen. Das optionale skills-Feld lädt den vollständigen Inhalt benannter Skills in den Startkontext des Subagenten vor – nützlich, wenn ein Subagent Domänenwissen benötigt, ohne eine Runde damit zu verschwenden, es während der Aufgabe zu entdecken und zu laden.

Modell-Routing: Billige Modelle für Schmutzarbeit

Subagenten sind auch der Ort, an dem Kostenekontrolle wirklich greift. Routen Sie Dateientdeckung, Log-Scanning und andere günstig zu verifizierende Arbeiten an Haiku, und reservieren Sie Sonnet oder Opus für die reasoningsintensiven Schritte – Architekturentscheidungen, mehrdebiges Debugging, alles, wo Fehler teuer sind. Haiku ist etwa 15x günstiger pro Token als Opus, und bei der Art von lauter Exploration, für die Subagenten gebaut sind, summiert sich diese Lücke schnell über eine echte Arbeitssession.

Das Muster: Explore, Plan, Execute

Für komplexe, mehrstufige Arbeiten ist das Muster, das in der Praxis funktioniert, Explore, Plan, Execute – billige Subagenten für die Teile, die Lärm erzeugen, und die menschliche Review-Gate an der einen Stelle, an der sie tatsächlich zählt.

Das Detail, das Leute oft falsch herum verstehen, ist, wo die Review-Gate hingehört. Exploration ist günstig, lassen Sie also einen Subagenten frei lesen, ohne zuerst um Erlaubnis zu fragen. Planung ist analytisch, lassen Sie den Agenten den Ansatz eigenständig entwerfen. Aber bevor ein Agent Dateien modifiziert, wollen Sie den Plan sehen und ihn genehmigen – dafür ist der Plan-Modus von Claude Code (permissionMode: plan) da, und es ist dasselbe Prinzip, das in den breiteren Vibe Coding Best Practices bezüglich der Überprüfung jedes Diffs vor dem Deployment diskutiert wird.

Häufige Fehler

Ein paar Fehler tauchen wiederholt auf, sobald Teams anfangen, benutzerdefinierte Subagenten zu schreiben:

• Vage Beschreibungen. „Hilft bei Code“ wird nie korrekt routen. Nennen Sie die exakte Auslösebedingung.
• Zu breiter Tool-Zugriff. Einem read-only Recherche-Subagenten Schreib- und Bash-Zugriff zu geben, entfernt die Isolationsgarantie, die ihn überhaupt erst wertvoll gemacht hat.
• Parallelisieren abhängiger Aufgaben. Wenn Aufgabe B die fertige Ausgabe von Aufgabe A benötigt, führen Sie sie sequenziell aus – Subagenten können nicht mid-task koordinieren, wie ein gemeinsamer Orchestrierer es kann. Für Workflows, die wirklich Agenten benötigen, die mid-task miteinander kommunizieren, ist das eine andere Art von Problem; siehe Multi-Agent Orchestrierungsmuster wenn Sie ein Produktionssystem und nicht nur einen Single-Repo-Workflow bauen.
• Subagenten für triviale Arbeit nutzen. „JSON formatieren“ oder „diesen einen Befehl ausführen“ benötigt kein frisches Kontextfenster; machen Sie es direkt.

Ausgeführtes Beispiel: Ein Code-Review-Subagent von Anfang bis Ende

Sagen wir, Sie wollen, dass jeder nicht-triviale Commit überprüft wird, bevor er landet. Legen Sie die code-reviewer-Definition, die oben gezeigt wurde, in .claude/agents/code-reviewer.md, committen Sie sie, damit das ganze Team denselben Reviewer hat, und rufen Sie sie mit einer natürlichen Anfrage wie „reviewe meine stageden Änderungen, bevor ich committe“ auf. Claude Code passt Ihre Anfrage an die description des Subagenten an, startet ihn mit nur Read, Grep und Glob-Zugriff, und er kommt mit Datei:Zeile-referenzierten Ergebnissen und einer Pass/Fail-Zusammenfassung zurück – kein einziges Stück des Lärms, das dabei entsteht, berührt Ihre Hauptsession.

Wie das in der Haupttranskription aussieht, kommentiert:

Sie:  reviewe meine stageden Änderungen, bevor ich committe

Main: [dispatcht code-reviewer Subagenten — 6 Dateien gelesen, 1 Grep-Pass,
       nichts davon hier gezeigt]

Main: code-reviewer Ergebnisse:
      - auth/session.go:142 — Token-Refresh-Pfad behandelt abgelaufene
        Refresh-Token nicht; fällt durch zu nil-Dereferenzierung
      - auth/session.go:203 — Style: Fehler nicht mit %w gewrappt
      PASS/FAIL: FAIL (1 blockierendes Problem)

Sechs Dateilesungen und ein Grep-Pass passierten, und Ihre Hauptsession bezahlte genau für vier Zeilen davon. Diese Lücke – alles, was der Subagent tat, versus der dreizeilige Bericht, den Sie tatsächlich sehen – ist das gesamte Wertversprechen in einer Transkription.

Wenn Ihr Team auch Spec-Driven Development-Scaffolds nutzt, passt ein Review-Subagent natürlich in den Validierungsschritt; siehe GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows für einen Vergleich dieses Review-Gates über portable und IDE-integrierte SDD-Setups.

Lohnt es sich, benutzerdefinierte Subagenten einzurichten?

Nicht am ersten Tag. Der eingebaute Allzweck-Subagent deckt bereits die meisten Exploration- und Recherchedelegationen ab, ohne dass Sie eine einzige YAML-Datei schreiben müssen, und ein einzelner Explore-Plan-Execute-Durchlauf reicht für die meisten alltäglichen Arbeiten aus. Schreiben Sie eine benutzerdefinierte .claude/agents/*.md-Datei erst, nachdem Sie dieselbe Aufgabe dreimal manuell delegiert haben – einen Code-Reviewer, einen Test-Runner-Triager, einen Docs-Lookup-Agenten für eine bestimmte interne Bibliothek. Teams, die in ihrer ersten Woche fünf Subagenten schreiben, enden meist mit fünf veralteten description-Feldern, die niemand aktualisiert, wenn sich die tatsächliche Auslösebedingung verschiebt, was die automatische Routing-Logik Monate später stillschweigend bricht. Beginnen Sie mit null benutzerdefinierten Subagenten, fügen Sie sie eines nach dem anderen hinzu, und nur wenn Wiederholung – nicht theoretischer Nutzen – es verlangt.

Bekannte Einschränkungen

Ein paar Unebenheiten sind bekannt, bevor Sie um Subagenten herum bauen:

• Keine rekursive Delegation. Ein Subagent kann keine eigenen Subagenten spawnen. Wenn eine Aufgabe wirklich eine zweite Ebene der Delegation benötigt, ist das ein Zeichen dafür, dass Sie eine andere Orchestrierungsstruktur wollen – siehe Multi-Agent Orchestrierungsmuster für das, was das außerhalb einer einzelnen Claude Code-Session bedeutet.
• Kein Gedächtnis über Aufrufe hinweg. Jeder Dispatch startet bei Null, auch wenn Sie denselben Subagenten vor fünf Minuten bei einer verwandten Aufgabe aufgerufen haben. Es gibt keinen eingebauten Mechanismus für einen Subagenten, sich an seinen letzten Lauf zu erinnern.
• Isolation ist eine Tool-Allowlist, keine Sandbox. Ein Subagent mit Bash-Zugriff kann immer noch das Dateisystem und das Netzwerk wie jeder andere Tool-Call berühren. Das Einschränken von tools reduziert die Explosionsradius; es erstellt keine harte Sicherheitsgrenze.

Fehlerbehebung

Subagenten löst nie aus. Das Problem liegt fast immer in der Beschreibung. Schreiben Sie sie um die spezifische Auslösebedingung herum, anstatt eine allgemeine Fähigkeitsaussage zu treffen, und prüfen Sie doppelt, ob die Datei in .claude/agents/ (Projekt) oder ~/.claude/agents/ (persönlich) mit der richtigen Erweiterung existiert.

Subagenten verbrennt trotzdem zu viel Kontext. Prüfen Sie die tools-Allowlist – ein zu breites Toolset lädt zu breite Exploration ein. Prüfen Sie auch, ob die Aufgabe in zwei Subagenten aufgeteilt hätte werden sollen, anstatt dass einer alles macht.

Eine aufgelistete Skill lädt nicht innerhalb des Subagenten. Claude Code überspringt eine fehlende oder deaktivierte Skill, die im skills-Feld genannt wird, anstatt den Lauf zu scheitern, und protokolliert eine Zeile dazu in der Debug-Ausgabe (/debug von der Hauptsession, dann reproduzieren Sie den Dispatch) – etwas wie skill "security-checklist" nicht gefunden, überspringen. Führen Sie danach /doctor aus, um zu bestätigen, dass der Rest Ihres Setups gesund ist.

Ergebnisse fühlen sich zwischen Läufen inkonsistent an. Das ist oft ein Modell-Routing-Problem, kein Subagenten-Design-Problem – reasoningsintensive Arbeit, die einem billigen Modell zugewiesen wird, variiert mehr. Verschieben Sie es zu Sonnet oder Opus und behalten Sie Haiku für die deterministischen, wenig mehrdeutigen Schritte.

Subagenten sind ein Teil eines viel größeren Werkzeugkastens; wenn Sie Claude Code gegen den Rest des KI-Entwickler-Tools-Ökosystems vergleichen, bevor Sie sich für diesen Workflow entscheiden, ist diese Übersicht ein guter nächster Halt.

Nützliche Links

• Claude Code Installation und Konfiguration für Ollama, llama.cpp, Preise
• Claude Skills und SKILL.md für Entwickler
• GitHub Spec Kit vs Kiro vs Claude Code SDD Workflows
• Was ist Vibe Coding?
• Multi-Agent Orchestrierungsmuster: Ein praktischer Leitfaden
• Oh My Opencode Spezialisierte Agenten Tiefenblick
• KI-Entwickler-Tools: Der komplette Leitfaden