Claude Code Subagenten: Was sie leisten und wann man sie einsetzt

Kurze Antwort: Ein Subagent ist ein eigener Kontext, an den Claude Code Arbeit delegiert, mit eigenem System-Prompt, eigenen Werkzeugberechtigungen und wahlweise eigenem Modell. Anthropics Dokumentation nennt fünf Gründe für ihren Einsatz: Kontext schonen, indem Erkundung und Umsetzung aus dem Hauptgespräch herausgehalten werden, Einschränkungen durchsetzen, indem die verfügbaren Werkzeuge begrenzt werden, Konfigurationen projektübergreifend wiederverwenden, Verhalten über fokussierte System-Prompts spezialisieren und Kosten steuern, indem Aufgaben an schnellere, günstigere Modelle gehen. Der erste und der letzte Punkt verändern deinen Alltag am stärksten.

Das Kontextproblem, das sie lösen

Jede Nachricht in einer Claude-Code-Sitzung trägt das gesamte Gespräch mit sich. Wer bei der Suche vierzig Dateien liest, hat diese vierzig Dateien für den Rest der Sitzung im Kontext, wo sie mit der eigentlichen Arbeit um Aufmerksamkeit konkurrieren.

Daraus folgen zwei sichtbare Symptome. Lange Sitzungen werden langsamer und teurer, weil der Kostentreiber das Kontextfenster ist und nicht die Zahl der Nachrichten. Und die Qualität sinkt, weil das Signal, das du brauchst, unter Erkundungsausgaben verschüttet ist, die nur fünf Minuten lang relevant waren.

Ein Subagent löst das strukturell. Die delegierte Arbeit passiert in ihrem eigenen Kontext, und nur das Ergebnis kommt zurück. Zwölf bei einer Suche gelesene Dateien kosten dich im Hauptgespräch eine Zusammenfassung statt zwölf Dateien Rauschen.

Genau deshalb gibt es die eingebauten Erkundungsagenten, und genau die wirst du am häufigsten nutzen, oft ohne es zu bemerken.

Die eingebauten Subagenten

Anthropic dokumentiert mehrere Typen, die mit Claude Code ausgeliefert werden. Zu wissen, worauf jeder beschränkt ist, erklärt viel an sonst rätselhaftem Verhalten.

Zwei Details in dieser Tabelle verdienen einen Moment.

Der Explore-Agent ist in der Claude-API auf Opus gedeckelt, und Anthropic erklärt das damit, dass Explore nie auf einem teureren Modell laufen soll als dem, das du für die Sitzung ohnehin gewählt hast. Das ist eine bewusste Kostenbremse und bedeutet, dass das Durchsuchen deiner Codebasis nicht klammheimlich zu Frontier-Modell-Preisen abgerechnet wird.

Explore und Plan sind beide nur lesend, Write und Edit sind verweigert. Genau das macht Delegation sicher: Du kannst einen Agenten zur Untersuchung losschicken, ohne dass er dabei anfangen könnte zu bearbeiten.

Eigene Subagenten schreiben

Ein eigener Subagent ist eine Markdown-Datei mit Frontmatter. Die Struktur ist klein genug, um sie sich zu merken.

---
name: code-improver
description: Prüft Dateien und schlägt Verbesserungen für Lesbarkeit, Leistung und Best Practices vor. Nach dem Schreiben oder Ändern von Code einsetzen.
tools: Read, Grep, Glob
model: sonnet
---
Du bist Spezialist für Codeverbesserung. Erkläre zu jedem gefundenen Problem die Ursache, zeige den aktuellen Code und liefere eine verbesserte Fassung.

Vier Felder erledigen die ganze Arbeit. name ist der Aufruf. description ist das, was Claude liest, wenn es über eine Delegation entscheidet, und damit die wichtigste Zeile der Datei. tools beschränkt, was der Agent darf. model wählt die Stufe.

Die Beschreibung verdient mehr Sorgfalt, als ihr üblicherweise zuteilwird. Claude entscheidet anhand dieser Zeile, wann der Agent zuständig ist, eine vage Beschreibung erzeugt also einen Agenten, der nie zum Zug kommt oder für die falschen Dinge herangezogen wird. Nenne die Auslösebedingung ausdrücklich, wie im Beispiel oben mit “Nach dem Schreiben oder Ändern von Code einsetzen”.

Am schnellsten geht das Anlegen, indem du Claude Code darum bittest. Beschreibe, was du willst, wo es liegen soll und was erlaubt ist, und prüfe dann die erzeugte Datei, bevor du sie einsetzt.

Wo Subagenten-Definitionen liegen

Anthropic dokumentiert fünf Orte mit einer festgelegten Rangfolge, und diese zu kennen verhindert die verbreitete Verwirrung, wenn ein Agent sich anders verhält als die Datei, die du gerade anschaust.

1. Verwaltete Einstellungen, zentral organisationsweit ausgerollt. Höchste Priorität.
2. Das CLI-Flag --agents, das JSON entgegennimmt und für die aktuelle Sitzung gilt.
3. .claude/agents/, begrenzt auf das aktuelle Projekt.
4. ~/.claude/agents/, verfügbar über alle deine Projekte hinweg.
5. Das Verzeichnis agents/ eines Plugins, überall dort, wo dieses Plugin aktiviert ist. Niedrigste Priorität.

Die praktische Regel: Definitionen auf Projektebene überschreiben deine persönlichen, und was deine Organisation über verwaltete Einstellungen ausrollt, überschreibt beides.

Das Flag --agents wird zu selten genutzt und ist für einmalige Arbeiten praktisch. Du übergibst beim Start von Claude Code ein JSON-Objekt, das Agenten inline definiert, was sich anbietet, wenn du eine Spezialkonfiguration einmal brauchst, ohne eine Datei zu hinterlassen.

Was du wissen solltest, bevor du eine ganze Flotte baust

Delegation kostet einen Umweg. Ein Subagent muss gestartet, mit Kontext versorgt und sein Ergebnis zurückgegeben werden. Bei einer Aufgabe, die das Hauptgespräch in zwei Schritten erledigen würde, ist dieser Aufwand ein Verlust. Delegation zahlt sich aus, wenn die Arbeit sonst viel Material in deinen Hauptkontext kippen würde.

Der Subagent sieht dein Gespräch nicht. Er startet bei null mit dem, was du ihm mitgibst. Ein Auftrag, der geteilten Kontext voraussetzt, führt zu einem Agenten, der am falschen Problem arbeitet, und das ist der mit Abstand häufigste Fehlschlag.

Werkzeugbeschränkungen sind der Zweck, nicht die Einschränkung. Ein nur lesender Prüfer, der nichts ändern kann, ist nützlicher als ein unbeschränkter, weil du ihn laufen lassen kannst, ohne hinterher zu kontrollieren, was er angefasst hat.

Günstigere Modelle sind oft richtig. Anthropic nennt das Umleiten von Aufgaben an schnellere, günstigere Modelle wie Haiku als einen der fünf Gründe für Subagenten. Bei 1 Dollar pro Million Eingabe-Token gegenüber 5 Dollar bei Opus 5 ist eine an Haiku delegierte mechanische Aufgabe eine echte Ersparnis ohne Qualitätsverlust.

Du kannst sie abschalten. Um einen eingebauten Typ zu blockieren, trage ihn in permissions.deny ein. Um Delegation komplett zu unterbinden, verweigere das Agent-Werkzeug selbst. Um gezielt Explore und Plan zu entfernen, setze CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1, was Claude Code v2.1.198 oder neuer voraussetzt und dazu führt, dass Claude Dateien direkt liest. Im nicht interaktiven Modus und im Agent SDK entfernt CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 alle eingebauten Typen, sodass nur deine eigenen bleiben.

Ein Entscheidungsrahmen: delegieren oder nicht

Lass eine Aufgabe durch diese fünf Fragen laufen, bevor du einen Agenten dafür schreibst.

1. Erzeugt das viel Ausgabe, die ich danach nicht mehr brauche? Suchen, erkunden, viele Dateien lesen, Logs durchgehen. Wenn ja, delegieren. Das ist das stärkste Argument.
2. Sollte hier das Schreiben unterbunden sein? Review, Audit, Analyse und Untersuchung profitieren alle von einem nur lesenden Agenten, und die Beschränkung ist der eigentliche Wert.
3. Ist es mechanisch genug für ein günstigeres Modell? Formatierung, mechanische Refactorings, einfache Nachschlagearbeit. An Haiku umleiten und die Hauptsitzung auf dem Modell lassen, das du wirklich brauchst.
4. Werde ich das öfter als ein paarmal tun? Eine einmalige Sache rechtfertigt keine Definitionsdatei. Etwas Wöchentliches schon, und die Wiederverwendung summiert sich.
5. Kann ich es ohne meinen Gesprächsverlauf briefen? Wenn die Aufgabe nur mit drei Stunden aufgebautem Kontext Sinn ergibt, wird Delegation enttäuschen. Formuliere den Auftrag um oder behalte die Arbeit im Hauptstrang.

Drei oder mehr Ja bedeuten: Agenten schreiben. Weniger bedeutet: inline erledigen.

Typische Fehler

• Eine vage description schreiben, sodass Claude nie an den Agenten delegiert oder die falsche Arbeit abgibt.
• Jedem eigenen Agenten alle Werkzeuge geben und damit den wichtigsten Sicherheitsvorteil verschenken.
• Etwas Kleines delegieren, bei dem der Umweg mehr kostet als die Ersparnis bringt.
• Annehmen, der Subagent sehe das Gespräch, und ihn entsprechend briefen.
• Eine große Agentenbibliothek aufbauen, bevor überhaupt feststeht, dass auch nur einer davon genutzt wird.

Drei Agenten, die sich zuerst lohnen

Wer statt Prinzipien konkrete Startpunkte will: Diese drei rechnen sich in den meisten Codebasen und kosten jeweils ein paar Minuten.

Ein nur lesender Prüfer. Werkzeuge auf Read, Grep und Glob begrenzt, Modell auf Sonnet, mit einem System-Prompt, der Probleme im aktuellen Code samt Ersatzvorschlag melden lässt, statt Änderungen vorzunehmen. Weil er nicht bearbeiten kann, kannst du ihn auf alles loslassen, ohne danach zu prüfen, was er angefasst hat.

Ein Ermittler für fehlschlagende Tests. Gib ihm die Fähigkeit, Tests auszuführen und Dateien zu lesen, und einen Prompt, der die Grundursache finden und melden lässt, statt etwas zu reparieren. Die Trennung ist wichtig: Ein Agent, der diagnostiziert und berichtet, lässt dich entscheiden, ob sich die Korrektur lohnt, während einer, der diagnostiziert und gleich repariert, dich auf seine erste Theorie festlegt.

Ein Dokumentationsprüfer auf Haiku. Mechanische Arbeit, die abgleicht, was die Dokumentation behauptet und was der Code tut. Genau das Profil für ein günstigeres Modell: hohes Volumen, wenig Urteilsvermögen, leicht überprüfbares Ergebnis.

Zwei von dreien sind nur lesend, der dritte läuft auf dem günstigsten Modell. Dieses Verhältnis ist kein Zufall. Genutzt werden die Agenten, die entweder ohne Aufsicht sicher laufen oder günstig genug sind, um oft zu laufen.

Wo das in einen größeren Ablauf passt

Subagenten passen natürlich zum Plan-Modus. Untersuchen in einem nur lesenden Agenten, eine Zusammenfassung zurückbringen, im Hauptgespräch gegen diese Zusammenfassung planen und dann ausführen. Die Erkundung landet nie in deinem Hauptkontext, und der Plan baut auf einem sauberen Auszug statt auf vierzig Dateien Rohausgabe.

Sie verändern auch das Verhalten langer Sitzungen. Praktisch führt das Auslagern der Erkundung dazu, dass eine Sitzung sehr viel länger brauchbar bleibt, bevor Kontextdruck sie verschlechtert, und das ist bei einer großen Aufgabe mehr wert als die Token-Ersparnis.

Das Urteilsvermögen hinter der Konfiguration aufbauen

Die Mechanik auf dieser Seite ist in zwanzig Minuten gelernt. Länger dauert zu wissen, welche Arbeit sich delegieren lässt, wie man einen Agenten so briefe, dass seine Ausgabe brauchbar ist, und wann eine Beschränkung das Ergebnis verbessert statt es zu begrenzen.

Das ist dasselbe Urteilsvermögen, das für jedes agentische Werkzeug gilt: eine Aufgabe in unabhängig bearbeitbare Teile zerlegen, jedes so spezifizieren, dass die Ausgabe prüfbar ist, und den Prüfschritt entwerfen, der Fehler auffängt. Das in einer strukturierten Abfolge zu lernen statt durch Versuch und Irrtum ergibt eine Methode, die auch dann trägt, wenn sich die Werkzeuge ändern, was in diesem Feld verlässlich passiert. Wenn du einen strukturierten Einstieg suchst, sieh dir die Lektionen von Coursiv an und prüfe die aktuellen Tarifdetails auf der offiziellen Seite.

Häufig gestellte Fragen

Dein nächster Schritt

Nimm die Untersuchung, die du am häufigsten fährst, jene, bei der du am Ende ein Dutzend Dateien liest, um eine wiederkehrende Frage zu beantworten, und schreibe dafür einen nur lesenden Agenten mit tools: Read, Grep, Glob und einer Beschreibung, die den Einsatzzeitpunkt benennt. Lass ihn einmal laufen und vergleiche, wie dein Hauptgespräch danach aussieht, mit einer Sitzung, in der du dieselbe Suche inline erledigt hast. Dieser eine Vergleich begründet Delegation besser als jede Erklärung des Mechanismus.