Claude Code Subagents: erstellen und richtig einsetzen

Claude Code Subagents sind Helfer, denen die Haupt-Session von Claude Code eine einzelne Aufgabe übergibt. Jeder läuft in einem eigenen Kontextfenster, mit eigenem System-Prompt, eigener Tool-Liste und eigenem Modell, und nur seine Endantwort kehrt in die Hauptkonversation zurück. Du definierst einen Subagent als Markdown-Datei in .claude/agents/, und Claude nutzt ihn automatisch, wenn die Aufgabe zu seiner Beschreibung passt, oder wenn du ihn beim Namen verlangst.

Dieser Beitrag behandelt, wie Subagents funktionieren, das Dateiformat, die Felder tools und model, wie du sie aufrufst und die Grenze zwischen einem Subagent und einem getrennten Agenten, der neben dem ersten läuft. Die Fakten stammen aus den offiziellen Subagent-Docs. Die Kurzfassung in einem Absatz findest du im Glossar-Eintrag zu Subagents.

Wie Subagents funktionieren

Entscheidet Claude zu delegieren, ruft es das Agent-Tool auf (vor Version 2.1.63 hieß es Task) und gibt einen kurzen Auftrag mit. Der Subagent startet mit frischem Kontext. Er bekommt seinen eigenen System-Prompt, die Delegationsnachricht, deine CLAUDE.md, den Git-Status und alle Skills, die du für ihn vorgeladen hast. Den Verlauf der Hauptkonversation sieht er nicht.

Dann arbeitet er die Aufgabe mit seinen erlaubten Tools ab und liefert ein Ergebnis. Alles, was er unterwegs gelesen hat, etwa Dutzende Dateien, lange grep-Ausgaben oder Testprotokolle, bleibt in seinem eigenen Kontext. Das ist der Hauptgrund für Subagents: Die Hauptkonversation bekommt eine Zusammenfassung, nicht das Rauschen.

Ein paar Grenzen, die du kennen solltest:

• Subagents können eigene Subagents starten, standardmäßig bis zu drei Ebenen tief.
• Standardmäßig können bis zu 20 gleichzeitig laufen.
• Ihre Anfragen zählen auf dieselben Nutzungslimits wie die Hauptsession.
• Ein Subagent kann im Vordergrund laufen, wobei der Hauptagent wartet, oder im Hintergrund, während der Hauptagent weitermacht.

Eingebaute Subagents

Claude Code liefert ein paar Subagents mit, die du nutzen kannst, ohne etwas zu schreiben:

Explore begegnet dir am häufigsten. Muss Claude finden, wo etwas definiert ist oder wie ein Feature über Dateien hinweg funktioniert, gibt es das oft an Explore ab, damit die Dateiinhalte nicht in deinem Hauptkontext landen.

Wo Subagent-Dateien liegen

Subagents sind Markdown-Dateien mit YAML-Frontmatter. Claude Code lädt sie von mehreren Orten, und haben zwei denselben Namen, gewinnt der weiter oben in dieser Liste:

Projekt-Subagents in .claude/agents/ solltest du einchecken, damit das ganze Team denselben Reviewer oder Test-Runner nutzt.

Das Dateiformat eines Subagents

Nur name und description sind Pflicht. Der Text nach dem Frontmatter ist der System-Prompt des Subagents.

---
name: code-reviewer
description: Reviews code changes for bugs, security issues and readability. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a senior code reviewer. When called:

1. Run git diff to see the recent changes.
2. Read the changed files and the code around them.
3. Report problems by priority: bugs, security, then readability.
4. For each problem, give the file, the line and a concrete fix.

Do not edit files. Report only.

Die description ist wichtiger, als sie aussieht. Sie liest Claude, wenn es entscheidet, ob es delegiert, also sag, was der Subagent tut und wann er zu nutzen ist. Formulierungen wie „use after writing code“ helfen Claude, ihn von selbst aufzugreifen.

Das Feld tools

tools ist eine Allowlist. Mit tools: Read, Grep, Glob, Bash kann der Reviewer oben lesen und Befehle ausführen, aber keine Dateien bearbeiten. Lässt du tools weg, erbt der Subagent jedes Tool der Hauptsession, einschließlich MCP-Tools. Es gibt auch disallowedTools, wenn es einfacher ist zu sagen, was entfernt wird, als was bleibt.

Halte die Liste so kurz, wie die Aufgabe es erlaubt. Ein Reviewer braucht kein Edit. Ein Recherche-Agent braucht kein Bash. Weniger Tools bedeuten weniger Überraschungen und eine klarere Aufgabe.

Das Feld model

model akzeptiert einen Alias (sonnet, opus, haiku), eine vollständige Modell-ID oder inherit, um das Modell der Hauptsession zu nutzen. Wird der Subagent aufgerufen, wählt Claude Code das Modell in dieser Reihenfolge: ein mit dem Aufruf übergebenes Modell, dann das Feld model der Datei, dann die Umgebungsvariable CLAUDE_CODE_SUBAGENT_MODEL, dann das Modell der Hauptsession.

Hier können Subagents echtes Geld sparen. Breite Dateisuchen und das Lesen von Logs brauchen selten das stärkste Modell. Lege sie auf Haiku und lass die Hauptsession für die Entscheidungen auf dem größeren Modell. Der Beitrag zum Claude Code Token-Verbrauch zeigt weitere Wege, Kosten zu senken.

Weitere nützliche Felder

So rufst du einen Subagent auf

Es gibt drei Wege:

1. Claude entscheiden lassen. Passt die Anfrage zur Beschreibung eines Subagents, delegiert Claude von selbst.
2. Beim Namen verlangen. „Use the code-reviewer subagent to check my last commit.“ Du kannst ihn auch aus dem Menü mit @ erwähnen.
3. Eine ganze Session als ihn laufen lassen. claude --agent code-reviewer startet eine Session, die Prompt, Tools und Modell dieses Subagents nutzt.

Für eine einmalige Session kannst du Subagents als JSON übergeben, ohne Dateien anzulegen:

claude --agents '{
  "code-reviewer": {
    "description": "Reviews code changes. Use after edits.",
    "prompt": "You are a senior code reviewer. Report bugs and fixes, do not edit.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

Damit Claude einen bestimmten Subagent nicht nutzt, nimm ihn in die Deny-Liste deiner Berechtigungen auf, zum Beispiel Agent(Explore).

Subagents oder getrennte parallele Agenten

Subagents und parallele Agenten teilen beide Arbeit auf, lösen aber unterschiedliche Probleme.

Nutze einen Subagent, wenn der Hauptagent eine Antwort braucht, um weiterzumachen: „finde alle Aufrufer dieser Funktion“, „prüfe diesen Diff“, „fasse diese Logs zusammen“. Die Arbeit ist kurz, ihr Ergebnis zählt, und du musst nicht zusehen.

Nutze getrennte Agenten, wenn jedes Stück echte Arbeit für sich ist: ein Feature, eine Migration, eine Testsuite. Du willst sehen, was jeder tut, seine Fragen beantworten und seine Änderungen als Branch prüfen. Dieses Setup beschreiben parallele Coding-Agenten und mehrere Claude Code Agenten ausführen, mit jedem Agenten in einem eigenen Git-Worktree.

Beides lässt sich gut mischen. Ein getrennter Agent kann für seine eigenen Suchen und Reviews trotzdem Subagents nutzen. Ein guter Standard: getrennte Agenten für Arbeit, die du einer Person zuweisen würdest, und Subagents für die Botengänge, die diese Agenten erledigen. Für größere Teams behandelt der Beitrag zum KI-Agenten-Team Rollen und Übergaben, und der Eintrag zur Multi-Agent-Orchestrierung die allgemeine Idee.

Claude Code hat außerdem eine eigene Funktion namens Agent Teams, in der mehrere Claude-Sessions zusammenarbeiten. Das ist nicht dasselbe wie Subagents und liegt außerhalb dieses Beitrags.

Tipps für Subagents, die funktionieren

• Eine Aufgabe pro Subagent. „Reviewer“ und „Test-Runner“ funktionieren besser als „Helfer“.
• Schreibe die Beschreibung für Claude. Sag, wann er zu nutzen ist, nicht nur, was er ist.
• Begrenze die Tools. Schreibgeschützte Subagents für Recherche und Review, Bearbeitungs-Tools nur dort, wo nötig.
• Wähle das Modell bewusst. Haiku für Suche und Zusammenfassungen, ein stärkeres Modell für Design und knifflige Fixes.
• Bitte um einen kurzen Bericht. Das Ergebnis landet im Hauptkontext, also sag dem Subagent, er soll Erkenntnisse liefern, keine Dateiinhalte.
• Checke deine Projekt-Subagents ein. .claude/agents/ in Git heißt, alle bekommen dieselben Helfer.

So zeigt AgentVera Subagents

AgentVera ist eine Desktop-App, die viele Coding-Agenten, Claude Code, Codex und andere, nebeneinander ausführt. Sie geht auf zwei Arten mit Subagents um.

Du kannst sie sehen. Im Bereich eines Claude Code Agenten öffnet der Button „Subagents“ eine Live-Ansicht der Subagents, die dieser Agent gestartet hat, und was sie gerade tun. Jeder zeigt seinen Status (Running, Done, Error, Stopped), ob er „in background“ läuft, die „Assigned task“, die er bekam, und seinen „Report“. Arbeiten gerade welche, erscheint eine Zeile „{count} subagents running — show“, damit du sie nicht übersiehst. Die Projekttour und Code-Karte hat außerdem eine Subagent-Zeitleiste mit Typ, Status, Tool-Anzahl und Dauer. Beide lesen lokale Transkripte und sind vorerst für Claude Code Agenten.

Ein günstigeres Explore. Unter Settings → „Token saving“ gibt die Option „Explorer subagent“ Claude Agenten einen schreibgeschützten Explorer für breite Suchen. Das Durchsuchen von Dateien läuft auf einem günstigeren Modell, standardmäßig Haiku, und nur das Ergebnis kehrt in die Hauptkonversation zurück. Hast du schon eine eigene Explore-Subagent-Datei, lässt AgentVera deine unangetastet. Die Option steht im selben Abschnitt wie die Smart Tools.

Getrennte Agenten, wenn die Arbeit größer ist. Die Team-Ansicht zeigt bis zu 24 Agenten gleichzeitig. Parallel team (Pläne Pro und Team) teilt ein Ziel in Teile auf, führt jeden in einem eigenen Worktree aus und führt sie in einem PR zusammen. Mit Agent-Messaging stellen sich Agenten gegenseitig Fragen, auch über CLIs hinweg, und die Agent-Koordination warnt, wenn zwei Agenten dieselbe Datei anfassen. Das ist die Seite der getrennten Agenten aus der Tabelle oben, wobei Subagents in jedem Claude Agenten weiter verfügbar sind.

Fazit

Subagents sind das richtige Werkzeug, wenn der Hauptagent eine Antwort braucht und du der Arbeit nicht zusehen musst: Suche, Review, Recherche. Schreibe eine Markdown-Datei mit klarer Beschreibung, kurzer Tool-Liste und bewusst gewähltem Modell. Ist die Arbeit groß genug für einen eigenen Branch und deine Aufmerksamkeit, nimm stattdessen einen getrennten Agenten.

Mehr dazu:

• Subagent (Glossar)
• Parallele Coding-Agenten
• Projekttour und Code-Karte
• Parallel team
• Claude Code Agent

Um AgentVera auszuprobieren, beginne auf der Startseite.