Ein Subagent ist ein zweiter Claude mit eigenem Auftrag: eigenes Kontextfenster, eigener Werkzeugsatz, eigener System-Prompt. Der Gewinn liegt in der Abgrenzung. Eine lange Recherche füllt nicht mehr das Fenster des Hauptgesprächs, mehrere Agenten können nebeneinander laufen, und was du einmal als Auftrag formuliert hast, lässt sich wiederverwenden. Dieses Modul geht der Reihe nach durch: anlegen, konfigurieren, aufrufen und im Blick behalten.
Einen Subagenten anlegen
Ein Subagent ist eine Markdown-Datei mit YAML-Frontmatter. Vier Orte kommen in Frage, und bei gleichem Namen gewinnt der höhere: verwaltete Einstellungen der Organisation, dann das --agents-Flag für genau diese Sitzung, dann .claude/agents/ im Projekt (geht in die Versionsverwaltung), dann ~/.claude/agents/ für dich persönlich, zuletzt das agents/-Verzeichnis eines Plugins. Beide Verzeichnisse werden rekursiv gelesen, du kannst also nach agents/review/ und agents/research/ sortieren — die Namen müssen im ganzen Baum eindeutig sein, sonst entscheidet die Lesereihenfolge des Dateisystems. Die eingebauten Agenten stehen immer bereit und nehmen an dieser Rangfolge nicht teil. Wer lieber klickt: /agents öffnet ein Menü zum Anlegen und Bearbeiten.
Das Frontmatter sagt, wer der Agent ist; der Text darunter ist sein System-Prompt. Schreib ihn wie eine Einweisung an eine Fachkraft — was zu prüfen ist, in welcher Reihenfolge, und in welcher Form das Ergebnis zurückkommen soll:
---
name: security-reviewer
description: Security-focused code reviewer. Use proactively after writing authentication, authorization, or data handling code.
tools: Read, Grep, Glob
---
You are a senior security engineer specializing in application security.
Review priorities:
1. Authentication and authorization flaws
2. Injection vulnerabilities (SQL, XSS, command)
3. Data exposure and sensitive information handling
4. Cryptographic weaknesses
5. Insecure direct object references
For each finding, provide: severity (Critical/High/Medium/Low), location (file:line), description, and a concrete fix with code example.
When invoked: run `git diff HEAD` first to focus on changed code. Das Feld tools grenzt ein, was der Agent anfassen darf. Ein Sicherheits-Review braucht Read, Grep und Glob und sonst nichts — ohne Schreibrecht kann er auch nichts kaputtmachen. Ein Implementierungs-Agent braucht den vollen Satz. Lässt du tools weg, erbt der Agent alles, was die Sitzung hat.
Was im Frontmatter steht
Das Frontmatter kann mehr als Tools. model wählt das Modell — haiku für kurze, mechanische Arbeit, sonnet für den Normalfall, opus für schweres Nachdenken, oder inherit, um das der Sitzung zu übernehmen. effort setzt die Denktiefe für diesen Agenten und überschreibt die der Sitzung; die Doku nennt dafür low, medium, high, xhigh und max, und welche Stufen wirklich zur Verfügung stehen, hängt am Modell. maxTurns deckelt die Zahl der Züge, permissionMode die Nachfragen. Dazu kommen disallowedTools, skills zum Vorladen bestimmter Skills, mcpServers für Server, die nur dieser Agent sieht, und initialPrompt, das den ersten Zug automatisch abschickt.
Mit memory behält ein Agent etwas über die Sitzung hinaus. Aus der MEMORY.md in seinem Speicherverzeichnis wandern die ersten 200 Zeilen oder 25 KB in seinen System-Prompt — je nachdem, was zuerst erreicht ist; wird es mehr, fordert die Anweisung ihn zum Aufräumen auf. Geschrieben wird die Datei von ihm selbst, während er arbeitet:
---
name: researcher
memory: user
description: Long-running research assistant with persistent notes
---
You are a research assistant. Check your MEMORY.md at session start to recall previous findings. Update it with new discoveries. Mit isolation: worktree bekommt der Agent einen eigenen Git-Worktree samt Branch und fasst deinen Arbeitsbaum nicht an. Am Ende meldet er Pfad und Branch zurück, du siehst dir das an und mergst oder verwirfst. Hat er nichts geändert, wird der Worktree von selbst wieder entfernt; solange er läuft, ist er gesperrt, damit ein gleichzeitiger Aufräumlauf ihn nicht wegräumt. Abgezweigt wird vom Standard-Branch des Repositories (origin/HEAD) — es sei denn, worktree.baseRef steht in den Einstellungen auf head, dann startet der Agent von deinem lokalen Stand und nimmt ungepushte Arbeit mit.
Mit background: true läuft ein Agent grundsätzlich im Hintergrund und gibt das Hauptgespräch sofort wieder frei. Einen bereits laufenden Agenten schiebst du mit Ctrl+B nach hinten.
Zwei Flags erweitern, worauf eine Sitzung überhaupt zugreift. --add-dir nimmt weitere Verzeichnisse dazu — praktisch, wenn dein Code auf eine gemeinsame Bibliothek oder ein Nachbarpaket im Monorepo zeigt; ein .claude/skills/ und ein .claude/agents/ in einem so hinzugefügten Verzeichnis werden gleich mitgelesen. Dauerhaft wird das über permissions.additionalDirectories in den Einstellungen. --mcp-config lädt MCP-Server aus einer oder mehreren JSON-Dateien nur für diese Sitzung, zusätzlich zu deinen sonstigen Quellen; --strict-mcp-config blendet die anderen Quellen aus:
claude --add-dir ~/projects/shared-types --add-dir ~/projects/design-tokens
claude --mcp-config ./ci-servers.jsonAufrufen, verketten, beobachten
Aufgerufen wird ein Agent auf zwei Wegen. Passt deine Aufgabe zum description-Feld, wählt Claude ihn von selbst; Formulierungen wie „use proactively" machen das wahrscheinlicher, sicher ist es nicht. Wenn es genau dieser eine sein muss, nennst du ihn: @"agent-name (agent)" umgeht das automatische Zuordnen.
Der Aufruf in normaler Sprache tut es genauso, solange der Name fällt:
Use the security-reviewer agent to audit the new auth module.
Have the test-engineer agent write integration tests for the payment service.
Ask the debugger agent to investigate the memory leak in src/workers/queue.ts. Agenten lassen sich hintereinanderschalten: was der eine liefert, geht in den nächsten. Was dabei läuft, zeigt claude agents im Terminal — eine Übersicht aller Sitzungen mit Zustand (working, waiting, completed, failed, idle, stopped) und letzter Aktivität. Mit --cwd siehst du nur die Sitzungen unterhalb eines Verzeichnisses, was beim Jonglieren mehrerer Repositories hilft, und CLAUDE_CODE_DISABLE_AGENT_VIEW schaltet die Ansicht ab. Eine ganze Sitzung unter einem bestimmten Agenten startest du mit claude --agent; womit ein Koordinator seinerseits Agenten starten darf, regelt eine Agent(...)-Allowlist:
# Only show agent sessions started under ~/work/api
claude agents --cwd ~/work/api Wer die Übersicht weiterverarbeiten will — eine eigene Statusleiste, ein Sitzungs-Wähler, ein Startskript —, hängt --json an und bekommt dieselben Daten als Array. Jeder Eintrag trägt pid, cwd, kind und startedAt, dazu sessionId, name und status, sobald gesetzt. Steht status auf waiting, sagt waitingFor, worauf gewartet wird — eine Berechtigungsfrage ist etwas anderes als eine fehlende Eingabe, und ein Skript kann beides verschieden behandeln:
# Wake up every session that's blocked on a permission prompt
claude agents --json \
| jq -r '.[] | select(.status == "waiting" and .waitingFor == "permission prompt") | .sessionId' \
| xargs -I {} claude respawn {}First use the code-analyzer agent to find performance bottlenecks, then use the optimizer agent to fix them. Vier Agenten sind schon da. general-purpose nimmt breite, mehrstufige Aufträge. Explore liest die Codebasis schnell und schreibgeschützt und erbt dafür das Modell der Hauptsitzung, auf der Claude-API gedeckelt bei Opus — teurer als deine eigene Wahl wird es also nie. Plan recherchiert erst und legt dann einen Plan vor, und claude-code-guide beantwortet Fragen zu Claude Code selbst. Ein Detail lohnt sich zu merken: Explore und Plan überspringen deine CLAUDE.md-Dateien und den Git-Status, damit Recherche billig bleibt — jeder andere Agent lädt beides.
Ein geforkter Subagent fängt nicht bei null an, sondern übernimmt den vollständigen Gesprächsverlauf der Hauptsitzung. Eingeschaltet wird das über CLAUDE_CODE_FORK_SUBAGENT; danach startet /fork einen solchen Agenten, statt nur ein Alias für /branch zu sein, und Agenten starten grundsätzlich im Hintergrund. Das gilt in interaktiven Sitzungen genauso wie im nicht-interaktiven Modus und im Agent SDK:
CLAUDE_CODE_FORK_SUBAGENT=1 claude Einen Schritt weiter gehen Agent-Teams: mehrere Claude-Instanzen arbeiten nebeneinander an einer gemeinsamen Aufgabenliste und schreiben sich über eine Mailbox. Gedacht ist das für große Vorhaben, bei denen unabhängige Teile parallel laufen können. Eingeschaltet wird die Funktion ausschließlich über die Umgebungsvariable CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS — in der Shell oder im env-Feld der Einstellungen. Ein gestoppter Teamkollege muss nicht erst fortgesetzt werden: SendMessage weckt ihn mit der Nachricht. Seit v2.1.178 gibt es kein TeamCreate und kein TeamDelete mehr — jede Sitzung hat mit gesetztem Schalter bereits ein Team, Teamkollegen startest du direkt über den name-Parameter des Agent-Tools, und aufgeräumt wird beim Sitzungsende von selbst.