Claude Code Subagents: Der praktische Guide (2026)

Ein Subagent ist ein zweites Claude, gestartet von deiner Haupt-Claude-Code-Session, das eine Aufgabe im eigenen Kontextfenster ausführt und ein Ergebnis zurückgibt. Er teilt nicht deine Gesprächshistorie. Er sieht nicht die Dateien, die du schon gelesen hast, oder die Entscheidungen, die du schon getroffen hast. Er bekommt einen Prompt, erledigt die Arbeit und kehrt zurück.

Diese Isolation ist das ganze Feature. Die Parallelität, die Spezialisierung, die individuellen Tool-Beschränkungen, all das ist Folge einer Tatsache: Ein Subagent verbrennt sein eigenes Kontextfenster, und nur die Endantwort kommt zurück in deins.

Wir fahren beim Bau von SkillProof Dutzende Subagents am Tag, meist für Recherche-Fan-out und unabhängige Fixes über die Datendateien des Katalogs hinweg. Manches, was wir gelernt haben, ist wirklich nützlich. Manches haben wir gelernt, indem wir einem Agenten zugesehen haben, der Erfolg für Arbeit beanspruchte, die er nie geleistet hat. Beide Arten sind in diesem Guide.

Was ein Subagent eigentlich ist

In Claude Code ist die Hauptsession ein Loop: lesen, denken, handeln, beobachten, wiederholen, wobei jeder Schritt an eine wachsende Konversation angehängt wird. Ein Subagent ist eine separate Instanz desselben Loops, gestartet mitten in der Session, mit eigener Historie, die außer dem Prompt, den du ihm gibst, leer beginnt.

Wenn der Subagent fertig ist, reist nichts von seiner Zwischenarbeit zurück. Nicht die Dateien, die er gelesen hat, nicht die Befehle, die er ausgeführt hat, nicht die Sackgassen, die er erkundet hat. Nur der Text, den er zurückgibt, landet in deinem Hauptkontext. Wenn er 40 Dateien gelesen hat, um deine Frage zu beantworten, zahlt deine Hauptsession für keine dieser 40 Reads. Sie zahlt für eine Zusammenfassung.

Deshalb werden Subagents als eine Art beschrieben, Kontext zu bewahren: nicht weil die Arbeit kostenlos ist (sie kostet irgendwo dieselben Tokens), sondern weil die Kosten in einem Fenster unter Quarantäne stehen, das weggeworfen wird, statt eines, das du durch den Rest der Session schleppst.

Der Kompromiss folgt direkt daraus. Ein Subagent, der nicht weiß, was du schon versucht hast, kann deine eigenen Sackgassen wiederholen, und er kann nicht mitten in der Aufgabe eine klärende Frage stellen, wie es der Hauptloop kann, er hat entweder genug im Prompt, um weiterzumachen, oder er rät. Delegation kauft Isolation und kostet geteiltes Gedächtnis. Jeder gute Subagent-Prompt wird von jemandem geschrieben, der diesen Handel verinnerlicht hat.

Warum Kontextisolation der Punkt ist

Stell dir eine Hauptsession vor, zwei Stunden in ein Refactoring: vierzig Dateien gelesen, ein Dutzend Tool-Aufrufe, eine Design-Entscheidung zweimal überdacht. Diese Historie leistet echte Arbeit, sie ist, was den nächsten Edit kohärent macht, aber sie ist auch fünfzigtausend Tokens Ballast.

Jetzt musst du wissen, wie ein unabhängiges Subsystem Retries handhabt. Lies diese Dateien im Hauptloop, und jede einzelne wird permanentes Gepäck, das für den Rest der Session mitfährt, egal ob du sie nochmal brauchst, bis sie Teil davon ist, warum das Modell anfängt, den eigentlichen Refactor aus den Augen zu verlieren. Ein Subagent lässt dich die Frage stellen, die Antwort bekommen und vom Lesen weggehen. Die vierzig Dateien, die er gelesen hat, betreten nie dein Fenster. Du bekommst einen Absatz zurück.

Das ist der Mechanismus hinter jedem legitimen Subagent-Gewinn in diesem Guide: Recherche, parallele Fixes, laute Exploration. Alle sind eigentlich derselbe Move, die teure Leserei irgendwo Wegwerfbarem erledigen, den Hauptthread sauber halten.

Wann Subagents die Arbeit im Hauptloop schlagen

Recherche über viele Dateien. „Wie fließt Auth durch diese Codebasis" berührt Routen, Middleware, Session-Speicher und drei Config-Dateien. Das im Hauptloop zu beantworten heißt, all das landet permanent in deinem Kontext. Ein Subagent liest dieselben Dateien, gibt eine Synthese zurück, und das Rohmaterial verschwindet mit ihm.

Parallele unabhängige Aufgaben. Fünf Komponenten brauchen alle dieselbe Prop umbenannt. Keine hängt von der anderen ab. Fünf gleichzeitig laufende Subagents sind in etwa der Zeit fertig, die einer braucht, ohne geteilten Zustand, den man zwischen den Änderungen koordinieren müsste.

Laute Exploration. Nach einem Muster über ein großes Repo greppen, drei Suchstrategien probieren, bevor eine trifft, Dateien lesen, die sich als irrelevant herausstellen. Das ist genau die Arbeit, die du unter Quarantäne stellen willst. Ein Subagent kann eine Weile herumfliegen, und nur der nützliche Teil kommt zurück.

Eine spezialisierte Persona isolieren. Ein Code-Reviewer-Subagent, der immer nur reviewt, mit einem engeren Tool-Set und einem auf Skepsis abgestimmten Prompt, verhält sich konsistenter, als deinen Hauptagenten zu bitten, mitten in der Session in „sei jetzt kritisch gegenüber deiner eigenen Arbeit" umzuschalten.

Wann Subagents schlechter sind

Enge iterative Loops. Einen fehlschlagenden Test debuggen, indem man eine Zeile ändert, erneut ausführt, den neuen Fehler liest, eine weitere Zeile ändert, braucht die volle Historie dessen, was du schon versucht hast. Das jeder Iteration an einen frischen Subagent zu geben, heißt, die ganze Untersuchung jedes Mal neu zu erklären, langsamer und schlechter als im Hauptloop zu bleiben. Das ist das Terrain, das unsere Systematic-Debugging-Notizen abdecken: Debugging will Kontinuität, keine Delegation.

Aufgaben, die die volle Konversation brauchen. Wenn der Nutzer zehn Nachrichten damit verbracht hat, zu präzisieren, was „räum diese API auf" genau bedeutet, wird ein Subagent, der nur die Endanweisung sieht, sie nach seiner eigenen Vermutung von „sauber" aufräumen, nicht der, die ihr ausgehandelt habt. Alles, wo die Anforderungen in der Konversation leben statt in einem Prompt, den du wiederholen kannst, passt schlecht.

Einfache Ein-Datei-Edits. „Benenne diese Variable in dieser Datei um" an einen Subagent zu delegieren fügt einen Hin-und-her-Trip hinzu, einen frischen Kontext-Load und ein Ergebnis, das du immer noch lesen und dem du vertrauen musst, für Arbeit, die direkt fünfzehn Sekunden gedauert hätte. Einen isolierten Worker zu starten zahlt sich nur aus, wenn die Arbeit, vor der er dich schützt, wirklich groß ist.

Das Muster über alle drei hinweg: Subagents sind genau dann schlechter, wenn der Wert von geteiltem Kontext die Kosten überwiegt, ihn zu tragen. Isolation hört auf, ein Feature zu sein, in dem Moment, wo Kontinuität ist, was die Aufgabe brauchte.

Individuelle Agent-Definitionen

Claude Code lädt individuelle Subagents aus Markdown-Dateien unter .claude/agents/ (Projektebene, über git geteilt) oder ~/.claude/agents/ (persönlich, jedes Projekt). Jede Datei ist ein Agent: Frontmatter plus ein System-Prompt, dieselbe Form wie ein Skill, aber eine Persona statt eine Prozedur beschreibend.

Hier ist ein vollständiges, kommentiertes Beispiel, ein Code-Reviewer, gescopt auf reine Review-Arbeit:

---
name: code-reviewer
description: Reviews a diff or pull request for correctness bugs,
  security issues, and missed edge cases. Use after a change is
  written and before it's committed, not while still drafting.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior engineer doing a pre-commit review. You did not
write this code and you have no attachment to it.

When given a diff or a set of changed files:

1. Read every changed file in full, not just the diff hunks.
   Bugs hide in the context around a change as often as in the
   change itself.
2. Check for: unhandled errors, off-by-one boundaries, null or
   undefined paths the type system doesn't catch, and any
   secret or credential that shouldn't be committed.
3. Do not comment on style or formatting unless it hides a bug.
   A linter's job is not your job.
4. For each finding, cite the file and line, and say what
   breaks and how you'd confirm it. If you're not sure something
   is a bug, say so explicitly instead of stating it as fact.
5. If you find nothing, say that plainly. Do not invent minor
   issues to look thorough.

Never run commands that modify files. You are reviewing, not fixing.

Ein paar Dinge zählen hier. Der name ist, wie du ihn aufrufst (Use the code-reviewer agent to check this diff) oder wie Claude Code ihn automatisch bei einer passenden Aufgabe aufruft. Das description-Feld trägt dasselbe Gewicht wie bei einem Skill: spezifische Trigger-Bedingungen schlagen eine vage Zusammenfassung.

tools ist eine echte Sicherheitsgrenze, kein Vorschlag. Nur Read, Grep, Glob, Bash zu listen heißt, dieser Agent kann physisch nicht Edit oder Write aufrufen, selbst wenn sein eigenes Reasoning einen Fix für offensichtlich hielt. Das ist Absicht: ein Review-Agent, der auch den Code patchen kann, den er reviewt, ist einer, dem du nicht zutrauen kannst, nur zu reviewen. model lässt dich einen mechanischen, gut spezifizierten Agenten auf ein günstigeres Modell routen als deine Hauptsession, da die Aufgabe nicht das volle Gewicht deines Hauptmodells braucht.

Der Body ist dasselbe Handwerk wie bei einem Skill: negative Einschränkungen („kommentiere Stil nicht", „erfinde keine kleinen Probleme") leisten mehr Arbeit als positive, weil sie es sind, die einen Reviewer davon abhalten, seinen Output aufzupolstern, um gründlich zu wirken.

Parallele Muster, die tatsächlich funktionieren

Fan-out-Reads. Starte mehrere Subagents gleichzeitig, jedem eine andere Scheibe derselben Frage zugewiesen: einer liest das Auth-Modul, einer die Datenschicht, einer die Testsuite. Jeder gibt eine kurze Synthese zurück. Du bekommst drei Antworten in der Zeit, die ein sequenzieller Durchlauf brauchen würde, und die rohen Dateiinhalte berühren nie deinen Hauptkontext.

N unabhängige Fixes. Eine Charge von Komponenten braucht dieselbe mechanische Änderung, und keine importiert von der anderen. Starte einen Subagenten pro Komponente, jeden mit einem in sich geschlossenen Prompt: die genaue Änderung, die genaue Datei, die genaue Abnahmeprüfung. Das ist der sauberste Parallelfall, kein Subagent muss wissen, was ein anderer getan hat.

Beide Muster teilen eine Anforderung, die leicht zu übersehen und teuer ist, wenn man es tut: Jeder Prompt muss in sich geschlossen sein. Er hat deine Konversation nicht. Wenn die Aufgabe von einer vor drei Nachrichten getroffenen Entscheidung abhängt, muss diese Entscheidung im Prompt wiederholt werden, sonst wird der Subagent selbstbewusst das Falsche tun.

Fehlermuster, die wir tatsächlich erlebt haben

Das ist der Teil, den die meisten Guides auslassen, geschrieben von jemandem, der einen Subagenten zweimal laufen ließ und es funktionierte. Wir fahren sie täglich, und hier ist, was in der Praxis kaputtgeht.

Agenten, die „fertig" melden, ohne die Arbeit getan zu haben. Ein Subagent kommt mit einer sauberen, selbstbewussten Zusammenfassung zurück: „Drei Dateien aktualisiert, Tests bestehen, bereit zum Commit." Du prüfst, und eine Datei ist unberührt. Das ist nicht in irgendeinem absichtlichen Sinne das Modell, das unehrlich ist, es ist die Rückgabe-Zusammenfassung, die von dem abdriftet, was tatsächlich passiert ist, besonders bei längeren Aufgaben, wo die eigene Darstellung des Agenten von seiner Arbeit komprimiert wird. Der Fix ist langweilig und nicht verhandelbar: verifiziere anhand des Artefakts, nicht des Berichts. Lies den Diff selbst. Führ den Test selbst aus. Die Zusammenfassung eines Subagenten ist eine Behauptung, kein Beleg.

Agenten, die auf Phantom-Benachrichtigungen warten. Wir hatten Subagents, die mitten in der Aufgabe pausiert haben, einen Callback oder ein Signal von einem anderen Prozess erwartend, das nie kam, weil der Koordinationsmechanismus nur in der Vorstellung des Prompts existierte, nicht in irgendetwas tatsächlich Verdrahtetem. Der Fix ist, nie einen Subagent-Prompt um ein Ereignis herum zu entwerfen, das du nicht verifiziert hast. Wenn der nächste Schritt eines Subagenten vom Output eines anderen Agenten abhängt, gib ihm diesen Output direkt beim Start, bitte ihn nicht, ein Abschlusssignal zu erkennen, das du nicht gebaut hast.

Beide Fehler gehen auf dieselbe Disziplin zurück: ein Prompt, der sich nicht auf geteilten Kontext oder eine angenommene Benachrichtigung stützt, ist einer, den ein Agent tatsächlich korrekt abschließen kann, und ein Ergebnis, das du prüfst, indem du die Datei liest, nicht die Darstellung des Agenten von der Datei, ist der einzige Weg zu wissen, dass er es getan hat. Nichts davon ist ein Argument gegen Subagents. Es ist ein Argument dagegen, einer Textzusammenfassung so zu vertrauen, wie du einem Diff vertrauen würdest. Wir fahren sie ständig. Wir mergen nur nichts allein auf ihr Wort hin.

Skills funktionieren auch innerhalb von Subagents

Ein Subagent ist immer noch eine Claude-Instanz, also lädt er Skills auf dieselbe Weise wie deine Hauptsession: seine Aufgabe gegen installierte Skill-Beschreibungen abgleichend und den Inhalt beim Trigger ziehend. Ein Code-Review-Subagent mit installiertem Code Review Checklist-Skill bekommt denselben strukturierten Durchgang wie im Hauptloop, gescopt auf welchen Diff auch immer du ihm gegeben hast.

Das komponiert sauber. Der Subagent handhabt, wo die Arbeit passiert, der Skill handhabt, wie sie erledigt wird. Keiner muss vom anderen wissen; sie stapeln sich automatisch, solange beide dort installiert sind, wo der Subagent sie sehen kann, Projekt-Skills in .claude/skills/, persönliche Skills in ~/.claude/skills/. Unsere Best-Coding-Skills-Seite rankt die, die sich lohnen zu installieren, bevor du einen Review- oder Recherche-Agenten verdrahtest.

Subagents vs. Hooks vs. Skills

Drei unterschiedliche Mechanismen, drei unterschiedliche Aufgaben, und sie werden ständig verwechselt:

	Was es tut	Triggert auf	Läuft wo
Skill	Bringt Claude eine Prozedur oder einen Stil bei	Claude gleicht deine Anfrage mit einer Beschreibung ab	Im aktuellen Kontext
Hook	Führt automatisch einen festen Shell-Befehl aus	Ein Lifecycle-Ereignis (vor einem Tool-Aufruf, nach einer Antwort, Sessionstart)	Außerhalb des Modells, deterministisch
Subagent	Delegiert eine Aufgabe an eine isolierte Claude-Instanz	Ein expliziter Aufruf, von dir oder vom Hauptagenten	Ein separates Kontextfenster

Ein Skill ändert wie Claude an etwas herangeht, das es sowieso schon tun wird. Ein Hook erzwingt etwas jedes Mal, bedingungslos, ohne das Modell zu bitten, sich zu erinnern: Tests nach jedem Edit ausführen, einen Commit blockieren, falls Secrets erkannt werden. Ein Subagent ändert wo Arbeit passiert, verschiebt sie in ein wegwerfbares Fenster statt in dein Hauptfenster. Wir behandeln Hooks ausführlich, mit derselben Art von Narbengewebe wie oben, in unserem Claude-Code-Hooks-Guide.

Sie stapeln sich. Ein Team-Setup könnte einen Hook nutzen, um nach jedem Write zu linten, einen Skill, um den hauseigenen Codestil zu lehren, und einen Subagenten, um den vollen Review-Durchgang vor dem Merge zu fahren, drei Schichten, keine redundant. Wenn du noch den Rest deines Setups zusammenstellst, führt unser 2026-Setup-Guide durch, wo jedes Stück hingehört, und unser Token-Kosten-Guide deckt ab, was alle drei im Ruhezustand kosten.

FAQ

Teilen Subagents den Kontext meiner Hauptsession?

Nein, und das ist der ganze Punkt. Ein Subagent startet mit leerer Historie außer dem Prompt, den du ihm gibst. Nichts aus deiner Hauptkonversation überträgt sich automatisch, und nichts, was der Subagent liest oder tut, kommt zurück außer dem finalen Text, den er zurückgibt. Wenn er Hintergrund aus deiner Konversation braucht, packe diesen Hintergrund in den Prompt.

Können Subagents parallel laufen?

Ja. Mehrere gleichzeitig zu starten ist das Standardmuster für Fan-out-Recherche und für unabhängige, sich nicht überlappende Fixes. Jeder bekommt sein eigenes Kontextfenster, sodass sie sich nicht gegenseitig stören, aber sie können auch mitten in der Aufgabe nicht koordinieren, sofern du nicht explizit den Output eines in den Prompt eines anderen gefüttert hast.

Wie weiß ich, ob ein Subagent tatsächlich getan hat, was er behauptet hat?

Prüf das Artefakt, nicht die Zusammenfassung. Lies den Diff, führ den Test aus, öffne die Datei. Wir hatten Subagents, die sauberen Erfolg für Arbeit gemeldet haben, die teilweise rückgängig gemacht war, nicht aus Unehrlichkeit, sondern weil eine Zusammenfassung eine Rekonstruktion ist, und Rekonstruktionen abdriften. Behandle jeden Subagent-Bericht als zu verifizierende Behauptung.

Wo leben individuelle Agent-Definitionen?

.claude/agents/*.md für Projekt-Agenten, die mit dem Repo per git reisen, und ~/.claude/agents/*.md für persönliche, über jedes Projekt hinweg verfügbare. Jede Datei braucht mindestens name und description im Frontmatter; tools und model sind optional, aber es lohnt sich, sie bewusst zu setzen statt sie auf Standard zu lassen.

Sollte ich einschränken, welche Tools ein Subagent nutzen kann?

Ja, immer wenn der Agent eine enge Aufgabe hat. Ein Review-Agent, der Edit nicht aufrufen kann, kann nicht versehentlich das patchen, was er eigentlich kritisieren soll. Ein reiner Recherche-Agent, der Bash nicht aufrufen kann, kann nicht versehentlich etwas Destruktives ausführen, während er herumstöbert. Das tools-Feld im Frontmatter eines Agenten ist der Mechanismus, und es zu setzen ist billiger, als zu debuggen, was ein überstarker Agent mit seiner verbleibenden Zeit angestellt hat.