Subagents

Subagents lassen Claude Arbeit an spezialisierte KI-Assistenten delegieren, jeder mit eigenem Kontextfenster, eigenen Tools und eigenem System-Prompt. Sie verhindern Kontextverschmutzung bei langen Aufgaben, ermöglichen parallele Ausführung und lassen dich Fachwissen in wiederverwendbare Agenten kodieren. Dieses Modul behandelt das Erstellen, Konfigurieren und effektive Nutzen von Subagents.

Subagents erstellen

Subagents sind Markdown-Dateien mit YAML-Frontmatter. Du kannst sie mit dem --agents CLI-Flag für eine Sitzung definieren, sie in .claude/agents/ für Projekt-Scope (in Git committet) ablegen oder ~/.claude/agents/ für persönlichen Scope (alle Projekte). Plugins können ebenfalls Agenten bündeln. Die Priorität ist managed > CLI-Flag > Projekt > Benutzer > Plugin. Eingebaute Subagents sind immer verfügbar und nicht Teil des Namens-Override-Prioritätssystems. Der /agents Befehl bietet ein interaktives Menü, um sie zu erstellen, zu bearbeiten und zu verwalten.

Das Frontmatter definiert die Identität des Agenten. Der Markdown-Body ist sein System-Prompt — schreib ihn, als würdest du einen Spezialisten briefen:

---
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 tools Feld schränkt ein, welche Tools der Agent verwenden kann. Ein Security-Reviewer braucht nur Read, Grep, und Glob — keinen Schreibzugriff. Ein Implementierungs-Agent braucht den vollen Satz. Das Einschränken von Tools macht den Agenten sicherer und sein Verhalten vorhersehbarer. Wenn du tools weglässt, erbt der Agent alle verfügbaren Tools.

Konfigurationsoptionen

Über den grundlegenden Tool-Zugriff hinaus unterstützt das Frontmatter mehrere mächtige Optionen. model legt fest, welches Modell der Agent verwendet — haiku für schnelle, leichtgewichtige Aufgaben, sonnet für ausgewogene Arbeit oder opus für komplexes Reasoning. Du kannst auch inherit verwenden, um das Modell des übergeordneten Agenten zu erben. effort steuert die Reasoning-Tiefe bei unterstützten Modellen, mit Werten low, medium, high, xhigh, max, und auto. maxTurns begrenzt, wie lange der Agent laufen kann. permissionMode legt die Berechtigungsstufe fest. Weitere nützliche Felder sind disallowedTools, skills um ausgewählte Skills vorzuladen, mcpServers für agent-spezifischen MCP-Zugriff und initialPrompt um den ersten Turn automatisch abzusenden.

memory gibt dem Agenten persistenten Speicher über Sitzungen hinweg. Die ersten 200 Zeilen einer MEMORY.md Datei im Memory-Verzeichnis des Agenten werden automatisch in seinen System-Prompt geladen — Claude schreibt in diese Datei, während es Dinge lernt:

---
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.

isolation: worktree gibt dem Agenten seinen eigenen Git-Worktree und Branch, um Änderungen vorzunehmen, ohne deinen Haupt-Working-Tree anzufassen. Wenn der Agent fertig ist, gibt er den Worktree-Pfad und Branch-Namen zurück, damit du prüfen und mergen kannst. Wenn er keine Änderungen gemacht hat, wird der Worktree automatisch aufgeräumt. Während der Agent läuft, sperrt Claude den Worktree, damit ein gleichzeitiger Aufräumdurchlauf ihn nicht entfernen kann, und gibt die Sperre frei, sobald der Agent fertig ist. Der Worktree zweigt vom Standard-Branch deines Repositories ab (origin/HEAD) es sei denn, du setzt worktree.baseRef zu head in den Einstellungen, was isolierte Agenten von deinem lokalen HEAD starten lässt und ungepushte Arbeit mitnimmt.

background: true lässt den Agenten immer als Hintergrundaufgabe laufen und gibt das Hauptgespräch frei. Drücke Ctrl+B um einen gerade laufenden Agenten in den Hintergrund zu verschieben.

Zwei CLI-Flags erweitern, worauf eine Sitzung zugreifen kann. --add-dir <path> gewährt Read/Edit-Zugriff auf zusätzliche Verzeichnisse über das primäre Arbeitsverzeichnis hinaus — nützlich, wenn dein Code auf gemeinsame Bibliotheken oder Monorepo-Pakete in Nachbarordnern verweist. Skills in .claude/skills/ innerhalb hinzugefügter Verzeichnisse werden automatisch geladen. Behalte diese über Sitzungen hinweg bei mit permissions.additionalDirectories in den Einstellungen. --mcp-config <path> lädt MCP-Server-Definitionen aus einer oder mehreren JSON-Dateien nur für die aktuelle Sitzung, zusammengeführt mit deinen Benutzer-/Projekt-MCP-Quellen. Füge --strict-mcp-config hinzu, um Benutzer-/Projektquellen zu ignorieren und nur die bereitgestellten Dateien zu verwenden:

claude --add-dir ~/projects/shared-types --add-dir ~/projects/design-tokens
claude --mcp-config ./ci-servers.json

Subagents nutzen und verketten

Claude ruft Agenten automatisch auf, wenn die Aufgabenbeschreibung zum description Feld des Agenten passt. Formulierungen wie „use proactively“ können die Delegation fördern, aber der explizite Aufruf ist der verlässliche Weg, wenn du einen bestimmten Agenten brauchst. Nutze @"agent-name (agent)" -Syntax, um sicherzustellen, dass ein bestimmter Agent verwendet wird, und das automatische Matching zu umgehen.

Der explizite Aufruf über natürliche Sprache funktioniert ebenfalls:

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 können in Sequenz verkettet werden, wobei die Ausgabe eines Agenten in den nächsten einfließt. Führe claude agents vom Terminal aus, um die Agent-Ansicht — eine Übersicht aller Claude-Code-Sitzungen mit ihrem Zustand (working, waiting, completed, failed, idle, stopped) und der letzten Aktivität. Das ist nützlich, um mehrere parallel laufende Agenten zu überwachen. Übergib --cwd <path> um die Übersicht auf Sitzungen zu filtern, die unter diesem Verzeichnis gestartet wurden — praktisch, wenn du mehrere Repositories jonglierst und eine Ansicht willst, die auf das gerade bearbeitete beschränkt ist. Setze CLAUDE_CODE_DISABLE_AGENT_VIEW=1 um sie zu deaktivieren. Du kannst auch eine vollständige Sitzung mit einem bestimmten Agenten ausführen über claude --agent <name>, und einschränken, welche Agenten ein Koordinator starten darf, mit Agent(...) -Tool-Allowlists.

# Only show agent sessions started under ~/work/api
claude agents --cwd ~/work/api

Für Skripte, die die Übersicht konsumieren müssen — Boot-Skripte im tmux-resurrect-Stil, eigene Statusleisten, Session-Picker — übergib --json zu claude agents um dieselben Daten als maschinenlesbares Array statt der interaktiven Ansicht zu erhalten. Jeder Eintrag enthält pid, cwd, kind, und startedAt, plus sessionId, name, und status wenn gesetzt. Wenn status gleich waiting, waitingFor sagt genau, worauf die Sitzung wartet, etwa permission prompt oder input needed, sodass ein Skript diese beiden Fälle unterschiedlichen Aktionen zuordnen kann:

# 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.

Claude Code bringt mehrere eingebaute Agenten mit, die du nicht erstellen musst: general-purpose übernimmt breite mehrstufige Aufgaben, Explore erbt das Modell der Hauptsitzung (begrenzt auf opus) für schnelle schreibgeschützte Codebase-Analyse, Plan recherchiert die Codebase, bevor es Implementierungspläne präsentiert, und claude-code-guide beantwortet Fragen zu Claude-Code-Funktionen. Beachte, dass Explore und Plan deine CLAUDE.md-Dateien und den Git-Status überspringen, um die Recherche schnell und günstig zu halten — jeder andere eingebaute und benutzerdefinierte Subagent lädt beide. Agenten können auch fortsetzbar sein, sodass Claude ein früheres Agentengespräch anhand der ID fortsetzen kann, wenn sich der Workflow über mehrere Turns erstreckt.

Setze CLAUDE_CODE_FORK_SUBAGENT=1 um geforkte Subagents zu aktivieren. Ein geforkter Subagent erbt den vollständigen Gesprächskontext von der Hauptsitzung, statt neu zu beginnen. Wenn aktiviert, /fork startet einen geforkten Subagent, statt als Alias für /branchzu fungieren, und alle Subagent-Starts laufen im Hintergrund. Es funktioniert in interaktiven Sitzungen, im nicht-interaktiven Modus, im Agent SDK und bei externen Builds:

CLAUDE_CODE_FORK_SUBAGENT=1 claude

Die experimentelle Agent-Teams-Funktion (erfordert CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 oder das --agent-teams CLI-Flag) koordiniert mehrere parallel arbeitende Claude-Instanzen über eine gemeinsame Aufgabenliste und Mailbox. Dies ist für große Projekte mit vielen Dateien gedacht, bei denen unabhängige Agenten gleichzeitig an verschiedenen Teilen arbeiten können, ohne sich gegenseitig in die Quere zu kommen. SendMessage setzt gestoppte Agenten automatisch fort, wenn ihnen eine Nachricht gesendet wird, sodass du einen Agenten nicht mehr explizit fortsetzen musst, bevor du mit ihm kommunizierst. Ab v2.1.178 wurden die TeamCreate und TeamDelete -Tools entfernt: Mit gesetztem Flag hat jede Sitzung bereits ein implizites Team, sodass du Teamkollegen direkt über den name -Parameter des Agent-Tools startest — kein Einrichtungsschritt — und das Aufräumen geschieht automatisch, wenn die Sitzung endet.