SpyBara
Go Premium

sub-agents.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 338 additions and 109 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Fri 18 23:58 Tue 22 23:59 Fri 25 23:58

Benutzerdefinierte Subagenten erstellen

Erstellen und verwenden Sie spezialisierte KI-Subagenten in Claude Code für aufgabenspezifische Workflows und verbesserte Kontextverwaltung.

Subagenten sind spezialisierte KI-Assistenten, die bestimmte Arten von Aufgaben bearbeiten. Verwenden Sie einen, wenn eine Nebenaufgabe Ihre Hauptkonversation mit Suchergebnissen, Protokollen oder Dateiinhalten überfluten würde, auf die Sie nicht mehr verweisen werden: Der Subagent führt diese Arbeit in seinem eigenen Kontext durch und gibt nur die Zusammenfassung zurück. Definieren Sie einen benutzerdefinierten Subagenten, wenn Sie wiederholt denselben Typ von Worker mit denselben Anweisungen spawnen.

Jeder Subagent läuft in seinem eigenen Kontextfenster mit einem benutzerdefinierten Systemprompt, spezifischem Werkzeugzugriff und unabhängigen Berechtigungen. Wenn Claude auf eine Aufgabe trifft, die der Beschreibung eines Subagenten entspricht, delegiert es an diesen Subagenten, der unabhängig arbeitet und Ergebnisse zurückgibt. Um die Kontexteinsparungen in der Praxis zu sehen, zeigt die Kontextfenster-Visualisierung eine Sitzung, in der ein Subagent Recherchen in seinem eigenen separaten Fenster durchführt.

Subagenten helfen Ihnen:

  • Kontext bewahren, indem Sie Exploration und Implementierung aus Ihrer Hauptkonversation heraushalten
  • Einschränkungen durchsetzen, indem Sie begrenzen, welche Werkzeuge ein Subagent verwenden kann
  • Konfigurationen wiederverwenden über Projekte hinweg mit Subagenten auf Benutzerebene
  • Verhalten spezialisieren mit fokussierten Systemprompts für spezifische Domänen
  • Kosten kontrollieren, indem Sie Aufgaben an schnellere, günstigere Modelle wie Haiku weiterleiten

Claude verwendet die Beschreibung jedes Subagenten, um zu entscheiden, wann Aufgaben delegiert werden. Wenn Sie einen Subagenten erstellen, schreiben Sie eine klare Beschreibung, damit Claude weiß, wann er ihn verwenden soll.

Diese Beschreibungen beanspruchen Kontext, daher halten Sie sie kurz. Wenn die kombinierten Beschreibungen Ihrer Subagenten, mit Ausnahme der integrierten, 15.000 Token überschreiten, zeigt Claude Code eine Warnung beim Start mit der Gesamtanzahl der Token. Kürzen Sie die description-Felder Ihrer Subagenten und verschieben Sie Details in den Systemprompt jedes Subagenten, der nur geladen wird, wenn dieser Subagent ausgeführt wird.

Integrierte Subagenten

Claude Code enthält integrierte Subagenten, die Claude automatisch bei Bedarf verwendet. Jeder erbt die Berechtigungen der übergeordneten Konversation; die meisten werden mit einem eingeschränkten Werkzeugsatz ausgeführt.

Explore und Plan überspringen Ihre CLAUDE.md-Dateien und den Git-Status der übergeordneten Sitzung, um die Recherche schnell und kostengünstig zu halten. Alle anderen integrierten und benutzerdefinierten Subagenten laden beide. Für die vollständige Aufschlüsselung dessen, was einen Subagenten erreicht, siehe was beim Start geladen wird.

Ein schneller, schreibgeschützter Agent, der für die Suche und Analyse von Codebases optimiert ist.

  • Modell: Erbt von der Hauptkonversation, begrenzt auf Opus in der Claude API, sodass Explore niemals auf einem teureren Modell ausgeführt wird als dem, das Sie bereits für die Sitzung gewählt haben, es sei denn, Sie setzen CLAUDE_CODE_SUBAGENT_MODEL und erzwingen es auf jeden Subagenten
  • Werkzeuge: Schreibgeschützte Werkzeuge; Write und Edit sind nicht zulässig
  • Zweck: Dateiermittlung, Codesuche, Codebase-Exploration

Ab v2.1.198 erbt Explore das Modell der Hauptkonversation, anstatt immer auf Haiku ausgeführt zu werden. In der Claude API ist das geerbte Modell auf Opus begrenzt: Eine Hauptkonversation auf einer höheren Stufe führt Explore auf Opus aus, und eine Hauptkonversation auf Sonnet oder Haiku führt Explore auf demselben Modell aus. Bei jedem anderen Anbieter, wie z. B. Amazon Bedrock, Google Cloud's Agent Platform, Microsoft Foundry oder Claude Platform on AWS, erbt Explore das Modell der Hauptkonversation direkt.

Ein Benutzer- oder Projekt-Subagent mit dem Namen Explore überschreibt den integrierten und behält sein eigenes model-Feld, daher definieren Sie einen mit model: haiku, um die Exploration auf einem kostengünstigeren Modell zu halten.

Claude delegiert an Explore, wenn es eine Codebase durchsuchen oder verstehen muss, ohne Änderungen vorzunehmen. Dies hält Explorationsergebnisse aus Ihrem Hauptkonversationskontext heraus.

Beim Aufrufen von Explore gibt Claude ein Gründlichkeitsniveau an: quick für gezielte Lookups, medium für ausgewogene Exploration oder very thorough für umfassende Analyse.

Integrierte Subagenten sind in interaktiven Sitzungen standardmäßig registriert. Um sie einzuschränken:

Ein Agent-Werkzeugaufruf, der subagent_type auslässt, schlägt mit subagent_type is required fehl, wenn die Sitzung keinen general-purpose-Subagenten hat, auf den zurückgegriffen werden kann.

Über diese integrierten Subagenten hinaus können Sie Ihre eigenen mit benutzerdefinierten Prompts, Werkzeugbeschränkungen, Berechtigungsmodi, Hooks und Skills erstellen. Die folgenden Abschnitte zeigen, wie Sie anfangen und Subagenten anpassen.

Schnellstart: Erstellen Sie Ihren ersten Subagenten

Subagenten sind Markdown-Dateien mit YAML-Frontmatter. Um einen zu erstellen, bitten Sie Claude, ihn für Sie zu schreiben, oder schreiben Sie die Datei selbst.

Ab v2.1.198 öffnet der /agents-Befehl nicht mehr den interaktiven Erstellungs-Assistenten; das Ausführen gibt eine Erinnerung aus, Claude zu fragen oder .claude/agents/ direkt zu bearbeiten. Subagenten-Dateien, Frontmatter-Felder und die Speicherorte .claude/agents/ und ~/.claude/agents/ bleiben unverändert; nur der Terminal-Assistent wird entfernt.

Diese Anleitung erstellt einen Subagenten auf Benutzerebene, der Code überprüft und Verbesserungen vorschlägt.

1

Bitten Sie Claude, den Subagenten zu erstellen

Beschreiben Sie in Claude Code den Subagenten, den Sie möchten, und wo Sie ihn speichern möchten:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude schreibt die Datei mit einem name, einer description, einer tools-Liste, einem model und einem Systemprompt.

2

Überprüfen Sie die Datei

Öffnen Sie ~/.claude/agents/code-improver.md und bestätigen Sie, dass das Frontmatter dem entspricht, was Sie angefordert haben. Das Ergebnis sieht so aus:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Da sich die Datei in ~/.claude/agents/ befindet, ist der Subagent in jedem Projekt auf Ihrem Computer verfügbar. Um ihn stattdessen auf ein Projekt zu beschränken, verschieben Sie ihn in das .claude/agents/-Verzeichnis dieses Projekts. Wählen Sie den Subagenten-Umfang vergleicht die beiden.

3

Probieren Sie es aus

Bitten Sie Claude, an den neuen Subagenten zu delegieren:

Use the code-improver agent to suggest improvements in this project

Claude delegiert an Ihren neuen Subagenten, der die Codebase durchsucht und Verbesserungsvorschläge zurückgibt. Im Transkript wird die Delegierung als eine Werkzeugaufrufs-Zeile angezeigt, die den Namen des Subagenten gefolgt von einer kurzen Aufgabenbeschreibung zeigt, wie z. B. code-improver(Suggest code improvements).

Wenn Claude den neuen Subagenten nicht finden kann, starten Sie Claude Code neu und versuchen Sie es erneut. Dies geschieht nur, wenn ~/.claude/agents/ vor dem Sitzungsstart nicht vorhanden war, da eine laufende Sitzung ein neu erstelltes agents-Verzeichnis nicht erkennt.

Sie haben jetzt einen Subagenten, den Sie in jedem Projekt auf Ihrem Computer verwenden können, um Codebases zu analysieren und Verbesserungen vorzuschlagen.

Sie können Subagenten-Dateien auch manuell schreiben, sie über CLI-Flags definieren oder sie über Plugins verteilen. Die folgenden Abschnitte behandeln alle Konfigurationsoptionen.

Konfigurieren Sie Subagenten

Der Dateispeicherort eines Subagenten bestimmt, wer darauf zugreifen kann, und sein Frontmatter bestimmt, was er tun kann. Dieser Abschnitt behandelt, wo Subagenten-Dateien gespeichert werden und welche Felder sie unterstützen.

Wählen Sie den Subagenten-Umfang

Speichern Sie Subagenten-Dateien an verschiedenen Orten je nach Umfang. Wenn mehrere Subagenten denselben Namen haben, verwendet Claude Code den aus dem höherrangigen Ort.

Ort Umfang Priorität Wie zu erstellen
Verwaltete Einstellungen Organisationsweit 1 (höchste) Bereitgestellt über verwaltete Einstellungen
--agents CLI-Flag Aktuelle Sitzung 2 JSON beim Starten von Claude Code übergeben
.claude/agents/ Aktuelles Projekt 3 Claude fragen oder die Datei manuell erstellen
~/.claude/agents/ Alle Ihre Projekte 4 Claude fragen oder die Datei manuell erstellen
Plugin-Verzeichnis agents/ Wo Plugin aktiviert ist 5 (niedrigste) Installiert mit Plugins

Projekt-Subagenten (.claude/agents/) sind ideal für Subagenten, die spezifisch für eine Codebase sind. Checken Sie sie in die Versionskontrolle ein, damit Ihr Team sie gemeinsam verwenden und verbessern kann.

Projekt-Subagenten werden durch Aufwärts-Traversierung vom aktuellen Arbeitsverzeichnis entdeckt, sodass jedes .claude/agents/-Verzeichnis zwischen dort und dem Repository-Root gescannt wird. Ab v2.1.178 verwendet Claude Code, wenn mehr als eines dieser verschachtelten Verzeichnisse denselben name definiert, die Definition, die dem Arbeitsverzeichnis am nächsten liegt.

Wenn Sie ein Verzeichnis mit --add-dir oder /add-dir hinzufügen, lädt Claude Code auch seinen .claude/agents/-Ordner zusammen mit Ihren Projekt-Subagenten. Siehe Zusätzliche Verzeichnisse für welche anderen Konfigurationstypen aus --add-dir geladen werden. Um Subagenten über Projekte hinweg zu teilen, ohne --add-dir zu verwenden, nutzen Sie ~/.claude/agents/ oder ein Plugin.

Benutzer-Subagenten (~/.claude/agents/) sind persönliche Subagenten, die in allen Ihren Projekten verfügbar sind.

Claude Code scannt .claude/agents/ und ~/.claude/agents/ rekursiv, sodass Sie Definitionen in Unterordnern wie agents/review/ oder agents/research/ organisieren können. Der Unterverzeichnis-Pfad beeinflusst nicht, wie ein Subagent identifiziert oder aufgerufen wird, da die Identität nur vom name-Frontmatter-Feld stammt.

Halten Sie name-Werte über den gesamten Baum eindeutig: Wenn zwei Dateien unter demselben .claude/agents/-Verzeichnis, einschließlich seiner Unterordner, denselben Namen deklarieren, lädt Claude Code nur eine von ihnen, ausgewählt nach Dateisystem-Lesereihenfolge statt nach dokumentierter Priorität. Über verschachtelte Projekt-Verzeichnisse hinweg gewinnt die Definition, die dem Arbeitsverzeichnis am nächsten liegt, wie oben beschrieben. Die /doctor-Setup-Überprüfung meldet Dateien im selben Verzeichnis, die einen Namen teilen, und schlägt vor, alle außer einer umzubenennen oder zu entfernen. Vor v2.1.205 öffnete /doctor einen Diagnose-Bildschirm, der Duplikate auflistete und zeigte, welche Definition aktiv war.

Plugin-agents/-Verzeichnisse werden ebenfalls rekursiv gescannt. Im Gegensatz zu Projekt- und Benutzer-Umfängen wird ein Unterordner in einem Plugin-agents/-Verzeichnis Teil des scoped identifier: Eine Datei unter agents/review/security.md im Plugin my-plugin registriert sich als my-plugin:review:security.

CLI-definierte Subagenten werden als JSON beim Starten von Claude Code übergeben. Sie existieren nur für diese Sitzung und werden nicht auf der Festplatte gespeichert, was sie für schnelle Tests oder Automatisierungsskripte nützlich macht. Sie können mehrere Subagenten in einem einzigen --agents-Aufruf definieren:

claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
},
"debugger": {
"description": "Debugging specialist for errors and test failures.",
"prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
}
}'

Das --agents-Flag akzeptiert JSON mit einem prompt-Feld plus diese Frontmatter-Felder: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background und isolation. Verwenden Sie prompt für den Systemprompt, äquivalent zum Markdown-Body in dateibasierten Subagenten. Jeder Top-Level-Schlüssel im JSON ist der Name des Agenten. Starten Sie einen Namen nicht mit -.

Für das, was Claude Code mit einem Wert tut, den es nicht laden kann, und die Flags und Umgebungsvariable, die diese Überprüfung überspringen, siehe Invalid --agents configuration.

Verwaltete Subagenten werden von Organisationsadministratoren bereitgestellt. Platzieren Sie Markdown-Dateien in .claude/agents/ im Verzeichnis der verwalteten Einstellungen, wobei Sie das gleiche Frontmatter-Format wie bei Projekt- und Benutzer-Subagenten verwenden. Verwaltete Definitionen haben Vorrang vor Projekt- und Benutzer-Subagenten mit demselben Namen.

Plugin-Subagenten stammen von Plugins, die Sie installiert haben. Sie werden automatisch zusammen mit Ihren benutzerdefinierten Subagenten geladen und erscheinen in der @-Erwähnung-Typeahead unter ihrem scoped name. Siehe die Plugin-Komponenten-Referenz für Details zum Erstellen von Plugin-Subagenten.

Subagenten-Definitionen aus einem dieser Umfänge sind auch für Agent-Teams verfügbar: Beim Spawnen eines Teammates können Sie auf einen Subagenten-Typ verweisen, und Claude Code wendet Teile dieser Definition auf den Teammate an. Siehe Agent-Teams für welche Teile in jedem Anzeigemodus gelten.

Schreiben Sie Subagenten-Dateien

Subagenten-Dateien verwenden YAML-Frontmatter für die Konfiguration, gefolgt vom Systemprompt in Markdown:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Das Frontmatter definiert die Metadaten und Konfiguration des Subagenten. Der Body wird zum Systemprompt, der das Verhalten des Subagenten leitet. Subagenten erhalten nur diesen Systemprompt plus grundlegende Umgebungsdetails wie Arbeitsverzeichnis, nicht den Claude Code-Systemprompt.

Im nicht-interaktiven Modus hängt das Flag --append-subagent-system-prompt den von Ihnen bereitgestellten Text an das Ende des Systemprompts jedes Subagenten an, einschließlich verschachtelter Subagenten, außer einem forked Subagenten, der den Prompt der Konversation selbst wiederverwendet. Erfordert Claude Code v2.1.205 oder später. Wenn Ihr Text zu lang ist, um ihn in der Befehlszeile zu übergeben, speichern Sie ihn in einer Datei und übergeben Sie den Pfad mit --append-subagent-system-prompt-file stattdessen. Das Datei-Flag erfordert Claude Code v2.1.261 oder später.

Ein Subagent startet im aktuellen Arbeitsverzeichnis der Hauptkonversation. Innerhalb eines Subagenten bleiben cd-Befehle nicht zwischen Bash- oder PowerShell-Werkzeugaufrufen bestehen und beeinflussen nicht das Arbeitsverzeichnis der Hauptkonversation. Um dem Subagenten stattdessen eine isolierte Kopie des Repositorys zu geben, setzen Sie isolation: worktree.

Ein Subagent mit isolation: worktree führt seine Bash- und PowerShell-Befehle in seinem Worktree aus. Ein Befehl, dessen Arbeitsverzeichnis sich stattdessen zu Ihrem Haupt-Checkout auflöst, beispielsweise weil das Worktree-Verzeichnis entfernt wurde, während der Subagent lief, schlägt mit einem Fehler fehl. Vor v2.1.203 konnte ein solcher Befehl im Haupt-Checkout ausgeführt werden.

Diese Arbeitsverzeichnis-Überprüfung deckt das gesamte Repository ab, das das Verzeichnis enthält, von dem aus Sie Claude Code gestartet haben. Wenn Ihre Sitzung in einem verknüpften Worktree läuft, deckt die Überprüfung auch den Haupt-Checkout ab, von dem dieser Worktree verknüpft ist. Vor v2.1.210 deckte die Überprüfung nur das Start-Verzeichnis selbst ab. Ein Befehl, dessen Arbeitsverzeichnis sich anderswo im selben Repository auflöste, wie das Repository-Root, wenn Sie Claude Code von einem Monorepo-Unterverzeichnis aus gestartet haben, wurde dort ausgeführt, anstatt zu fehlschlagen.

Für Bash-Befehle überprüft Claude Code auch den Befehl selbst auf zwei Arten:

  • Es blockiert einen Befehl, der Git in den Haupt-Checkout umleitet.
  • Es weigert sich, einen Befehl auszuführen, wenn es nicht vom Befehlstext überprüfen kann, dass jedes Git, das der Befehl ausführt, im Worktree bleibt, beispielsweise wenn der Befehlsname zur Laufzeit berechnet wird.

Die Umleitungsvektoren und die Formregeln sind unter Wie Claude Code Isolation erzwingt aufgelistet. PowerShell-Befehle erhalten nur die Arbeitsverzeichnis-Überprüfung.

Monitor-Befehle durchlaufen die gleichen Arbeitsverzeichnis- und Befehlsinhalts-Überprüfungen wie Bash-Befehle.

Wenn die Hauptkonversation selbst isoliert in einem Worktree läuft, wendet Claude Code die gleichen Überprüfungen auf die Sitzung und jeden Subagenten an, den es spawnt, einschließlich Subagenten ohne isolation: worktree; siehe Wie Claude Code Isolation erzwingt.

Unterstützte Frontmatter-Felder

Die folgenden Felder können im YAML-Frontmatter verwendet werden. Nur name und description sind erforderlich.

Feld Erforderlich Beschreibung
name Ja Eindeutige Kennung mit Kleinbuchstaben und Bindestrichen. Hooks erhalten diesen Wert als agent_type. Der Dateiname muss nicht übereinstimmen. Namen können kein : enthalten, das für Plugin-Umfang-Identifier wie my-plugin:reviewer reserviert ist. Claude Code lädt eine Datei, deren Name eins enthält, nicht und protokolliert einen Fehler im Debug-Protokoll. Vor v2.1.218 wurden solche Namen akzeptiert
description Ja Wann Claude an diesen Subagenten delegieren sollte
tools Nein Werkzeuge, die der Subagent verwenden kann. Erbt jedes Werkzeug, das für Subagenten verfügbar ist, wenn weggelassen. Wenn kein Eintrag in der Liste sich zu einem Werkzeug auflöst, schlägt der Subagent normalerweise fehl zu starten mit einem Fehler, der die Einträge benennt. Um Skills in den Kontext zu laden, verwenden Sie das skills-Feld statt Skill hier aufzulisten
disallowedTools Nein Werkzeuge zum Verweigern, entfernt aus geerbter oder angegebener Liste
model Nein Modell zu verwenden: sonnet, opus, haiku, fable, eine vollständige Modell-ID wie claude-opus-5 oder inherit. Wenn Sie es weglassen, wählt Claude Code das Modell in der Subagenten-Modell-Reihenfolge
permissionMode Nein Berechtigungsmodus: default, acceptEdits, auto, dontAsk, bypassPermissions, plan oder manual als Alias für default. Der manual-Alias erfordert Claude Code v2.1.200 oder später. Ignoriert für Plugin-Subagenten
maxTurns Nein Maximale Anzahl von Agenten-Turns, bevor der Subagent stoppt. Wenn der Subagent die Grenze erreicht, gibt Claude Code seine Ausgabe als teilweise markiert zurück, und Claude kann ihn fortsetzen, um fortzufahren. Die teilweise Markierung erfordert Claude Code v2.1.246 oder später
skills Nein Skills zum Vorausladen in den Kontext des Subagenten beim Start. Der vollständige Skill-Inhalt wird eingespritzt, nicht nur die Beschreibung. Subagenten können weiterhin unlisted Projekt-, Benutzer- und Plugin-Skills durch das Skill-Werkzeug aufrufen
mcpServers Nein MCP-Server verfügbar für diesen Subagenten. Jeder Eintrag ist entweder ein Servername, der auf einen bereits konfigurierten Server verweist (z. B. "slack") oder eine Inline-Definition mit dem Servernamen als Schlüssel und einer vollständigen MCP-Server-Konfiguration als Wert. Ignoriert für Plugin-Subagenten
hooks Nein Lifecycle-Hooks mit Umfang auf diesen Subagenten. Ignoriert für Plugin-Subagenten
memory Nein Persistenter Speicherumfang: user, project oder local. Ermöglicht sitzungsübergreifendes Lernen
background Nein Auf true setzen, um diesen Subagenten im Hintergrund zu halten, auch wenn Claude ihn im Vordergrund ausführen möchte. Wo Fork-Modus aktiviert ist, führt Claude Code die Subagenten, die Claude spawnt, bereits im Hintergrund aus
effort Nein Aufwandsstufe, wenn dieser Subagent aktiv ist. Überschreibt die Aufwandsstufe der Sitzung. Standard: erbt von Sitzung. Optionen: low, medium, high, xhigh, max; verfügbare Stufen hängen vom Modell ab
isolation Nein Auf worktree setzen, um den Subagenten in einem temporären Git-Worktree auszuführen, was ihm eine isolierte Kopie des Repositorys gibt, die standardmäßig von Ihrem Standard-Branch verzweigt ist, anstatt vom HEAD der übergeordneten Sitzung. Der Worktree wird automatisch bereinigt, wenn der Subagent keine Änderungen vornimmt
color Nein Anzeigefarbe für den Subagenten in der Aufgabenliste und dem Transkript. Akzeptiert red, blue, green, yellow, purple, orange, pink oder cyan
initialPrompt Nein Auto-eingereicht als der erste Benutzer-Turn, wenn dieser Agent als Hauptsitzungs-Agent läuft (über --agent oder die agent-Einstellung). Befehle und Skills werden verarbeitet. Vorangestellt zu jedem vom Benutzer bereitgestellten Prompt
experimental Nein Zuordnung experimenteller Optionen. Setzen Sie seinen cacheTtl-Schlüssel auf 5m oder 1h, um die Prompt-Cache-Lebensdauer für die Anfragen dieses Subagenten zu wählen, an der Stelle des Frontmatters in der Cache-Lebensdauer-Priorität. Claude Code ignoriert jeden anderen Wert, ignoriert 1h, während Ihr Claude-Abonnement Nutzungsguthaben verwendet, und liest das Feld nur aus Subagenten-Dateien. Erfordert Claude Code v2.1.248 oder später

Schreiben Sie cacheTtl in die experimental-Zuordnung, nicht auf die oberste Ebene des Frontmatters.

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

Subagenten-Dateien, die Claude Code überspringt

Claude Code überspringt eine Datei in einem Projekt-, Benutzer- oder verwalteten agents-Verzeichnis oder in einem unter einem Verzeichnis, das Sie mit --add-dir hinzufügen, ohne es in der Sitzung zu melden, wenn das Frontmatter eines dieser Probleme hat:

  • Kein name: Claude Code behandelt die Datei als Dokumentation, die neben Ihren Agenten aufbewahrt wird.
  • Ein öffnendes ---, das nicht die erste Zeile der Datei ist: Claude Code liest die Datei als ohne Frontmatter und behandelt sie als Dokumentation.
  • Ein name, der mit - beginnt oder : enthält: Claude Code überspringt die Datei und schreibt einen Fehler in das Debug-Protokoll. Siehe die name-Zeile in der Tabelle oben.
  • Ein name, aber keine description: Claude Code überspringt die Datei und schreibt den Grund in das Debug-Protokoll.
  • YAML, das nicht analysiert wird: Claude Code liest keine Felder aus der Datei, überspringt sie und schreibt den Parse-Fehler in das Debug-Protokoll.

Um das Debug-Protokoll zu sehen, führen Sie Claude Code mit --debug aus.

Ein Plugin-Subagent, dessen Frontmatter kein name hat oder nicht analysiert wird, wird immer noch unter seinem Dateinamen geladen.

Überprüfen Sie ein `agents`-Verzeichnis vor einer Sitzung

Um Dateien in einem agents-Verzeichnis zu finden, deren Frontmatter nicht analysiert wird, führen Sie claude plugin validate gegen das Verzeichnis aus, beispielsweise .claude/agents oder ~/.claude/agents. Claude Code überprüft nur das Verzeichnis, das Sie benennen, und kennzeichnet keine Datei, deren Frontmatter analysiert wird, aber kein name hat. Erfordert Claude Code v2.1.233 oder später.

Wählen Sie ein Modell

Das model-Feld steuert, welches Modell der Subagent verwendet:

  • Modell-Alias: Verwenden Sie einen der verfügbaren Aliase: sonnet, opus, haiku oder fable
  • Vollständige Modell-ID: Verwenden Sie eine vollständige Modell-ID wie claude-opus-5 oder claude-sonnet-5. Akzeptiert dieselben Werte wie das --model-Flag
  • inherit: Verwenden Sie dasselbe Modell wie die Hauptkonversation

Wenn Claude einen Subagenten aufruft, kann es auch einen model-Parameter für diese spezifische Invokation übergeben. Claude Code löst das Modell des Subagenten in dieser Reihenfolge auf:

  1. Der Per-Invokation-model-Parameter
  2. Das model-Frontmatter des Subagenten, wobei inherit das Modell der Hauptkonversation auswählt
  3. Die CLAUDE_CODE_SUBAGENT_MODEL-Umgebungsvariable, wenn Sie sie auf einen Modell-Alias oder eine Modell-ID setzen
  4. Das Modell der Hauptkonversation

Das Setzen von CLAUDE_CODE_SUBAGENT_MODEL allein ändert nicht das Modell, auf dem die integrierten Explore- und Plan-Subagenten laufen. Um es zu ändern, siehe Führen Sie jeden Subagenten auf einem Modell aus.

Vor v2.1.251 kam CLAUDE_CODE_SUBAGENT_MODEL zuerst in dieser Reihenfolge und überschrieb sowohl den Per-Invokation-Parameter als auch das Frontmatter, einschließlich model: inherit.

Das Setzen der Variablen auf inherit ist dasselbe wie das Nichtsetzen. Vor v2.1.196 erzwang dieser Wert Subagenten auf das Modell der Hauptkonversation und ignorierte die anderen Quellen.

Claude Code überprüft die Per-Invokation-Parameter, Frontmatter und Umgebungsvariablenwerte gegen die availableModels-Allowlist Ihrer Organisation. Für einen blockierten Wert ersetzt es ein anderes Modell:

  • Wenn der blockierte Wert ein Familien-Alias wie opus ist, führt Claude Code den Subagenten auf der neuesten Version dieser Familie aus, die die Allowlist zulässt, und folgt den gleichen Substitutionsregeln und Provider-Umfang wie /model. Vor v2.1.222 führte Claude Code den Subagenten auf dem geerbten Modell für einen blockierten Familien-Alias aus.
  • Für jeden anderen blockierten Wert, auf Providern, wo diese Substitution nicht funktioniert, oder wenn die Allowlist keine Version der Familie zulässt, führt Claude Code den Subagenten stattdessen auf dem geerbten Modell aus. Wenn Sie CLAUDE_CODE_SUBAGENT_MODEL setzen, versucht Claude Code zuerst dieses Modell unter den gleichen Regeln.

In interaktiven Sitzungen zeigt Claude Code eine Warnung an, die das angeforderte Modell und das Modell benennt, auf dem der Subagent läuft, für beide Substitutionen.

Um zu überprüfen, auf welchem Modell ein Subagent läuft, führen Sie /tasks aus. Claude Code benennt das Modell in der Zeile des Subagenten und fügt die Aufwandsstufe hinzu, wenn die Definition des Subagenten oder der Skill, von dem er geforkt wurde, effort setzt. Erfordert Claude Code v2.1.242 oder später.

Ein Per-Invokation-model-Parameter gilt auch, wenn der Subagent fortgesetzt oder eine Folgenachricht gesendet wird, sodass der Subagent auf diesem Modell bleibt. Vor v2.1.211 ließ das Fortsetzen den Per-Invokation-Wert fallen und der Subagent kehrte zu seinem model-Feld oder, ohne einen, zum Modell der Hauptkonversation zurück.

Ab v2.1.198 erben Subagenten auch die Extended Thinking-Konfiguration der Hauptkonversation: Wenn Thinking in Ihrer Sitzung aktiviert ist, ist es für den Subagenten aktiviert, und wenn es deaktiviert ist, bleibt es deaktiviert. Es gibt keine Pro-Subagenten-Thinking-Einstellung. Vor v2.1.198 liefen Subagenten mit deaktiviertem Extended Thinking, unabhängig von der Einstellung der Hauptkonversation.

Führen Sie jeden Subagenten auf einem Modell aus

CLAUDE_CODE_SUBAGENT_MODEL ist ein Standard, daher hat die Definition eines Subagenten oder ein Modell, das Claude übergibt, immer noch Vorrang vor ihm. Um ein Modell auf jeden Subagenten, Teammate und Workflow-Agent anzuwenden, setzen Sie auch CLAUDE_CODE_SUBAGENT_MODEL_FORCE auf 1. Erfordert Claude Code v2.1.257 oder später.

  • Wenn Sie beide Variablen setzen, laufen Subagenten auf dem Modell in CLAUDE_CODE_SUBAGENT_MODEL.
  • Wenn Sie nur CLAUDE_CODE_SUBAGENT_MODEL_FORCE setzen, laufen Subagenten auf dem Modell der Hauptkonversation.

Um beispielsweise jeden Subagenten auf Haiku auszuführen, setzen Sie beide Variablen im env-Block einer Einstellungsdatei:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Um zu überprüfen, dass die Einstellung wirksam wurde, führen Sie /tasks aus, während ein Subagent läuft. Die Zeile des Subagenten zeigt das Modell, auf dem er läuft.

Während CLAUDE_CODE_SUBAGENT_MODEL_FORCE aktiviert ist, ignoriert Claude Code das model-Feld jeder Subagenten-Definition, einschließlich der integrierten Explore- und Plan-Subagenten, und Claude kann kein Modell übergeben, wenn es einen Subagenten startet. Zwei Arten von Subagenten laufen immer noch auf dem Modell der Hauptkonversation:

Wenn Sie nur CLAUDE_CODE_SUBAGENT_MODEL_FORCE setzen, behält der integrierte Explore-Subagent seine Modell-Obergrenze.

Kontrollieren Sie Subagenten-Fähigkeiten

Sie können kontrollieren, was Subagenten durch Werkzeugzugriff, Berechtigungsmodi und bedingte Regeln tun können.

Verfügbare Werkzeuge

Subagenten erben die integrierten Werkzeuge und MCP-Werkzeuge, die in der Hauptkonversation verfügbar sind, eingeengt durch zwei Filter: Der erste entfernt eine kurze Liste von Werkzeugen aus jedem Subagenten, und der zweite reduziert den integrierten Werkzeugsatz für Subagenten, die im Hintergrund laufen, was der Standard ist. Forks überspringen beide Filter und erhalten den genauen Werkzeugpool der Hauptkonversation. Der erste Filter entfernt diese Werkzeuge, auch wenn sie im tools-Feld aufgelistet sind:

  • Agent, wenn der Subagent die Tiefengrenze erreicht hat; in einem Fork bleibt das Werkzeug aufgelistet, gibt aber stattdessen einen Fehler zurück
  • AskUserQuestion
  • EndConversation, das nur die Hauptkonversation beenden kann; siehe EndConversation-Werkzeugverhalten
  • EnterPlanMode
  • ExitPlanMode, es sei denn, der permissionMode des Subagenten ist plan
  • ScheduleWakeup
  • TaskOutput
  • WaitForMcpServers
  • Workflow

Der zweite Filter gilt für Subagenten, die im Hintergrund laufen. Abgesehen von Agent und ExitPlanMode, die den Bedingungen des ersten Filters folgen, wo immer der Subagent läuft, behält ein Hintergrund-Subagent jedes MCP-Werkzeug, aber nur diese integrierten Werkzeuge: Read, Grep, Glob, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage und Artifact. Claude Code entfernt jedes andere integrierte Werkzeug aus einem Hintergrund-Subagenten, ob geerbt oder im tools-Feld aufgelistet, sodass die gleiche Definition zu verschiedenen Werkzeugen im Vordergrund und im Hintergrund führen kann. Die Entfernung meldet keinen Fehler, es sei denn, sie hinterlässt die tools-Liste aufgelöst zu nichts. ListAgents folgt diesen Filtern wie jedes integrierte Werkzeug: Ein Vordergrund-Subagent erbt es in Sitzungen, wo sitzungsübergreifendes Messaging aktiviert ist, und ein Hintergrund-Subagent behält es nicht.

Teammates in Agent-Teams behalten zusätzlich die Task-Werkzeuge und Cron-Werkzeuge: TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete und CronList.

In einer Sitzung ohne die Task-Werkzeuge stellt Claude Code die Task-Werkzeuge auch nicht für Subagenten bereit, auch wenn der Subagent ein anderes Modell ausführt. Ein In-Process-Teammate folgt Ihrer Sitzung auf die gleiche Weise, während ein Teammate in seinem eigenen Split-Pane als separater Claude Code-Prozess läuft, sodass sein eigenes Modell entscheidet.

Um Werkzeuge einzuschränken, verwenden Sie das tools-Feld als Allowlist oder das disallowedTools-Feld als Denylist. Dieses Beispiel verwendet tools, um ausschließlich Read, Grep, Glob und Bash zuzulassen. Der Subagent kann keine Dateien bearbeiten, keine Dateien schreiben oder MCP-Werkzeuge verwenden:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

Dieses Beispiel verwendet disallowedTools, um alle verfügbaren Werkzeuge außer Write und Edit zu erben. Der Subagent behält Bash, MCP-Werkzeuge und den Rest seines Pools:

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

Wenn beide gesetzt sind, wird disallowedTools zuerst angewendet, dann wird tools gegen den verbleibenden Pool aufgelöst. Ein Werkzeug, das in beiden aufgelistet ist, wird entfernt.

Wenn nichts in der tools-Liste sich zu einem Werkzeug auflöst, beispielsweise weil jeder Eintrag falsch geschrieben ist oder ein Werkzeug benennt, das nicht für Subagenten verfügbar ist, weigert sich Claude Code normalerweise, den Subagenten zu starten, und das Agent-Werkzeug gibt einen Fehler zurück, der die ungelösten Einträge benennt; siehe Agent würde mit null Werkzeugen gespawnt für die Nachricht und wie man jeden Eintrag behebt. Vor v2.1.208 startete dieser Subagent mit keinen Werkzeugen und konnte ein leeres oder verwirrendes Ergebnis zurückgeben.

Beide Felder akzeptieren MCP-Server-Level-Muster zusätzlich zu exakten Werkzeugnamen: mcp__<server> oder mcp__<server>__* gewährt oder entfernt jedes Werkzeug vom benannten Server. In disallowedTools entfernt mcp__* auch jedes MCP-Werkzeug von jedem Server. Dieses Beispiel entfernt jedes Werkzeug vom github MCP-Server, während Werkzeuge von anderen Servern und die integrierten Werkzeuge in seinem Pool beibehalten werden:

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

Beschränken Sie, welche Subagenten gespawnt werden können

Wenn ein Agent als Hauptthread mit claude --agent läuft, kann er Subagenten mit dem Agent-Werkzeug spawnen. Um zu beschränken, welche Subagenten-Typen er spawnen kann, verwenden Sie die Agent(agent_type)-Syntax im tools-Feld.

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

Dies ist eine Allowlist: Nur die worker- und researcher-Subagenten können gespawnt werden. Wenn der Agent versucht, einen anderen Typ zu spawnen, schlägt die Anfrage fehl und der Agent sieht nur die zulässigen Typen in seinem Prompt. Um bestimmte Agenten zu blockieren und alle anderen zuzulassen, verwenden Sie stattdessen permissions.deny.

Um das Spawnen eines beliebigen Subagenten ohne Einschränkungen zu ermöglichen, verwenden Sie Agent ohne Klammern:

tools: Agent, Read, Bash

Wenn Agent vollständig aus der tools-Liste weggelassen wird, kann der Agent keine Subagenten spawnen.

Die Agent(agent_type)-Allowlist-Syntax gilt nur für einen Agent, der als Hauptthread mit claude --agent läuft. In einer Subagenten-Definition ermöglicht das Auflisten von Agent in tools diesem Subagenten, Subagenten zu spawnen, während die Tiefengrenze es zulässt, aber jede Typenliste in den Klammern wird ignoriert.

Umfang von MCP-Servern auf einen Subagenten

Verwenden Sie das mcpServers-Feld, um einem Subagenten Zugriff auf MCP-Server zu geben, die in der Hauptkonversation nicht verfügbar sind. Inline-Server, die hier definiert sind, werden verbunden, wenn der Subagent startet, unter Beachtung der Vertrauensregel für den Ordner der Agent-Datei, und getrennt, wenn er endet. String-Verweise teilen die Verbindung der übergeordneten Sitzung.

Jeder Eintrag in der Liste ist entweder eine Inline-Server-Definition oder ein String, der auf einen bereits konfigurierten MCP-Server in Ihrer Sitzung verweist:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

Inline-Definitionen verwenden das gleiche Schema wie .mcp.json-Server-Einträge, mit dem Servernamen als Schlüssel, und unterstützen die Typen stdio, http, sse und ws.

Um einen MCP-Server vollständig aus der Hauptkonversation herauszuhalten und zu vermeiden, dass seine Werkzeugbeschreibungen dort Kontext verbrauchen, definieren Sie ihn inline hier statt in .mcp.json. Der Subagent erhält die Werkzeuge; die übergeordnete Konversation nicht.

Claude Code lädt einen Inline-Server aus einer Agent-Datei in Ihrem Projekt-.claude/agents/-Verzeichnis oder in einem --add-dir-Verzeichnis-.claude/agents/ nur, nachdem Sie dem Ordner vertrauen, aus dem die Agent-Datei stammt. Vor v2.1.238 lud Claude Code diese Server ohne Vertrauensprüfung.

  • Vertrauen, das nicht zählt: Vertrauen eines übergeordneten Ordners und das automatische Vertrauen, das eine -p- oder SDK-Sitzung für Hooks in Einstellungsdateien erhält
  • Bis dahin: Claude Code überspringt jeden Inline-Server in dieser Agent-Datei und schreibt den genauen projects["<path>"].hasTrustDialogAccepted-Schlüssel für ~/.claude.json in das Debug-Protokoll
  • --add-dir-Verzeichnisse: Ein Verzeichnis außerhalb des Repositorys Ihres vertrauenswürdigen Arbeitsbereichs benötigt seinen eigenen Vertrauenseintrag, da seine .claude/agents/-Dateien das Vertrauen Ihres Arbeitsbereichs nicht erben

Claude Code lädt zwei Arten von Servern ohne Vertrauensprüfung für den Ordner, aus dem die Agent-Datei stammt:

  • Ein Name, der auf einen bereits konfigurierten Server verweist
  • Ein Inline-Server in einer Agent-Datei aus ~/.claude/agents/, in einer, die Sie mit --agents oder der SDK-Option agents übergeben, oder in einer, die verwaltete Einstellungen liefern

Ab v2.1.153 gelten die MCP-Einschränkungen, die für die Hauptsitzung gelten, auch für Server, die im Subagenten-Frontmatter deklariert sind:

Wenn einer dieser Punkte einen Server blockiert, überspringt Claude Code ihn und zeigt eine Warnung mit den Namen der blockierten Server an.

Verwaltete Einstellungseinschränkungen gelten für jeden Subagenten, unabhängig davon, wie er definiert ist. --strict-mcp-config filtert keine Server, die Sie inline über --agents oder die SDK-Option agents übergeben, da diese explizite Eingaben des Aufrufers sind.

Berechtigungsmodi

Setzen Sie permissionMode, um den Berechtigungsmodus zu wählen, in dem ein Subagent läuft. Verwenden Sie die Konfigurationswerte der Modi, daher ist der Manuelle Modus default. Wenn Sie ihn nicht setzen, erbt der Subagent den Modus der Hauptkonversation, der als Auto-Modus auf Pro-, Max- und Team-Plänen beginnt, es sei denn, Ihre Einstellungen oder Ihre Organisation ändern ihn. Das Setzen überschreibt diesen Modus, außer in den unten beschriebenen Fällen.

Modus Verhalten
default Manueller Modus: fordert Berechtigung an
acceptEdits Auto-Akzeptanz von Dateibearbeitungen und häufigen Dateisystem-Befehlen für Pfade im Arbeitsverzeichnis oder additionalDirectories
auto Auto-Modus: ein Hintergrund-Klassifizierer überprüft Befehle und Schreibvorgänge in geschützten Verzeichnissen
dontAsk Auto-Ablehnung von Berechtigungsaufforderungen. Explizit zulässige Werkzeuge funktionieren weiterhin; AskUserQuestion, MCP-Werkzeuge, die mit requiresUserInteraction gekennzeichnet sind, und Connector-Werkzeuge die Ihre Organisation auf ask gesetzt hat in Sitzungen, wo diese Einstellung Claude Code erreicht, werden verweigert, auch wenn Sie sie zugelassen haben
bypassPermissions Alle Berechtigungsprüfungen überspringen
plan Plan-Modus (schreibgeschützte Exploration)

Wenn das übergeordnete Element bypassPermissions oder acceptEdits verwendet, hat dies Vorrang und kann nicht überschrieben werden. Wenn das übergeordnete Element den Auto-Modus verwendet, erbt der Subagent den Auto-Modus und jedes permissionMode in seinem Frontmatter wird ignoriert: der Klassifizierer bewertet die Werkzeugaufrufe des Subagenten mit den gleichen Block- und Zulassungsregeln wie die übergeordnete Sitzung.

Wenn der Bypass-Modus durch permissions.disableBypassPermissionsMode deaktiviert ist, ignoriert Claude Code permissionMode: bypassPermissions im Frontmatter und der Subagent läuft mit dem Modus der übergeordneten Sitzung. Vor v2.1.223 wendete Claude Code den Frontmatter-Modus auch mit deaktiviertem Bypass an.

Laden Sie Skills in Subagenten vor

Verwenden Sie das skills-Feld, um Skill-Inhalte beim Start in den Kontext eines Subagenten einzuspeisen. Dies gibt dem Subagenten Domänenwissen, ohne dass er Skills während der Ausführung entdecken und laden muss.

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

Der vollständige Inhalt jedes aufgelisteten Skills wird in den Kontext des Subagenten eingespritzt. Dieses Feld steuert, welche Skills vorausgeladen werden, nicht welche Skills der Subagent zugreifen kann: ohne es kann der Subagent weiterhin Projekt-, Benutzer- und Plugin-Skills durch das Skill-Werkzeug während der Ausführung entdecken und aufrufen. Um einen Subagenten daran zu hindern, Skills überhaupt aufzurufen, lassen Sie Skill aus der tools-Liste weg oder fügen Sie es zu disallowedTools hinzu.

Sie können keine Skills vorausladen, die disable-model-invocation: true setzen, da das Vorausladen aus dem gleichen Satz von Skills stammt, die Claude aufrufen kann. Dies schließt den gebündelten /verify-Skill ein: Nur Sie können ihn ausführen, daher kann er auch nicht vorausgeladen werden.

Wenn ein aufgelisteter Skill fehlt oder deaktiviert ist, beispielsweise durch die Richtlinie Ihrer Organisation, überspringt Claude Code ihn und protokolliert eine Warnung im Debug-Protokoll.

Aktivieren Sie persistenten Speicher

Das memory-Feld gibt dem Subagenten ein persistentes Verzeichnis, das über Konversationen hinweg bestehen bleibt. Der Subagent verwendet dieses Verzeichnis, um im Laufe der Zeit Wissen aufzubauen, wie z. B. Codebase-Muster, Debugging-Erkenntnisse und architektonische Entscheidungen.

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

Wählen Sie einen Umfang basierend darauf, wie breit der Speicher angewendet werden sollte:

Umfang Ort Verwenden Sie, wenn
user ~/.claude/agent-memory/<name-of-agent>/ der Subagent Erkenntnisse über alle Projekte hinweg merken sollte
project .claude/agent-memory/<name-of-agent>/ das Wissen des Subagenten projektspezifisch ist und über Versionskontrolle teilbar ist
local .claude/agent-memory-local/<name-of-agent>/ das Wissen des Subagenten projektspezifisch ist, aber nicht in die Versionskontrolle eingecheckt werden sollte

Subagenten-Speicher ist Teil des Auto-Speichers: Wenn Sie Auto-Speicher mit der autoMemoryEnabled-Einstellung oder CLAUDE_CODE_DISABLE_AUTO_MEMORY ausschalten, hat das memory-Feld keine Auswirkung und der Subagent startet ohne die Speicheranweisungen oder den Speicher-Werkzeugzugriff, der unten beschrieben ist.

Wenn der Speicher aktiviert ist:

  • Der Systemprompt des Subagenten enthält Anweisungen zum Lesen und Schreiben in das Speicherverzeichnis.
  • Der Systemprompt des Subagenten enthält auch die ersten 200 Zeilen oder 25 KB von MEMORY.md im Speicherverzeichnis, je nachdem, was zuerst kommt, mit Anweisungen zur Verwaltung von MEMORY.md, wenn es diese Grenze überschreitet.
  • Read-, Write- und Edit-Werkzeuge werden automatisch aktiviert, damit der Subagent seine Speicherdateien verwalten kann.
Tipps zum persistenten Speicher

  • project ist der empfohlene Standard-Umfang. Es macht Subagenten-Wissen über Versionskontrolle teilbar.

  • Bitten Sie den Subagenten, seinen Speicher vor dem Start zu konsultieren: "Review this PR, and check your memory for patterns you've seen before."

  • Bitten Sie den Subagenten, seinen Speicher nach Abschluss einer Aufgabe zu aktualisieren: "Now that you're done, save what you learned to your memory." Im Laufe der Zeit baut dies eine Wissensdatenbank auf, die den Subagenten effektiver macht.

  • Fügen Sie Speicheranweisungen direkt in die Markdown-Datei des Subagenten ein, damit er proaktiv seine eigene Wissensdatenbank verwaltet:

    Update your agent memory as you discover codepaths, patterns, library
locations, and key architectural decisions. This builds up institutional
knowledge across conversations. Write concise notes about what you found
and where.

Bedingte Regeln mit Hooks

Für dynamischere Kontrolle über die Werkzeugnutzung verwenden Sie PreToolUse-Hooks, um Operationen vor ihrer Ausführung zu validieren. Dies ist nützlich, wenn Sie einige Operationen eines Werkzeugs zulassen möchten, während Sie andere blockieren.

Dieses Beispiel erstellt einen Subagenten, der nur schreibgeschützte Datenbankabfragen zulässt. Der PreToolUse-Hook führt das in command angegebene Skript vor jeder Bash-Befehlsausführung aus:

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Claude Code übergibt Hook-Eingabe als JSON über stdin an Hook-Befehle. Das Validierungsskript liest dieses JSON, extrahiert den Bash-Befehl und beendet mit Code 2, um Schreibvorgänge zu blockieren:

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

Auf macOS und Linux machen Sie das Skript ausführbar, oder der Hook schlägt fehl, anstatt etwas zu blockieren:

chmod +x ./scripts/validate-readonly-query.sh

Um die Regel zu testen, bitten Sie den Subagenten, eine UPDATE-Anweisung auszuführen: Das Skript beendet sich mit Code 2, Claude Code blockiert den Befehl, und der Subagent sieht die Nachricht Blocked: Only SELECT queries are allowed.

Siehe Hook-Eingabe für das vollständige Eingabeschema und Exit-Codes für die Auswirkungen von Exit-Codes auf das Verhalten. Unter Windows schreiben Sie Hook-Skripte in PowerShell und fügen Sie shell: powershell zum Hook-Eintrag hinzu, wie in Ausführen von Hooks in PowerShell gezeigt.

Deaktivieren Sie spezifische Subagenten

Sie können verhindern, dass Claude bestimmte Subagenten verwendet, indem Sie sie zum deny-Array in Ihren Einstellungen hinzufügen. Verwenden Sie das Format Agent(subagent-name), wobei subagent-name dem name-Feld des Subagenten entspricht.

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

Dies funktioniert für integrierte und benutzerdefinierte Subagenten. Sie können auch das --disallowedTools-CLI-Flag verwenden:

claude --disallowedTools "Agent(Explore)"

Siehe Berechtigungsdokumentation für weitere Details zu Berechtigungsregeln.

Definieren Sie Hooks für Subagenten

Subagenten können Hooks definieren, die während des Lebenszyklus des Subagenten ausgeführt werden. Es gibt zwei Möglichkeiten, Hooks zu konfigurieren:

  • Im Frontmatter des Subagenten: Definieren Sie Hooks, die nur ausgeführt werden, während dieser Subagent aktiv ist
  • In settings.json: Definieren Sie Hooks auf Sitzungsebene, die auch in Subagenten ausgelöst werden. Tool-Ereignisse wie PreToolUse und PostToolUse werden für die Werkzeugaufrufe des Subagenten auf die gleiche Weise ausgelöst wie in der Hauptkonversation, und SubagentStart und SubagentStop werden ausgelöst, wenn ein Subagent startet oder endet

Hooks aus Einstellungsdateien, verwalteten Richtlinieneinstellungen und Plugins gelten alle in Subagenten, daher wird ein PreToolUse-Hook in settings.json auch vor jedem Werkzeug ausgeführt, das ein Subagent verwendet.

Hooks im Subagenten-Frontmatter

Definieren Sie Hooks direkt in der Markdown-Datei des Subagenten. Diese Hooks werden nur ausgeführt, während dieser spezifische Subagent aktiv ist, und werden bereinigt, wenn er endet.

Um Frontmatter-Hooks eines Subagenten auf Projektebene auszuführen, akzeptieren Sie den Arbeitsbereichs-Vertrauensdialog für den Ordner, der die Agent-Datei enthält. Hooks von Benutzer-Subagenten in ~/.claude/agents/ und von Definitionen, die Sie mit --agents übergeben, werden ohne diesen Schritt ausgeführt. Wenn Sie einen Ordner mit --add-dir von außerhalb des Repositorys Ihres vertrauenswürdigen Arbeitsbereichs hinzugefügt haben, vertrauen Sie diesem Ordner separat: Seine .claude/agents/-Hooks erben das Vertrauen Ihres Arbeitsbereichs nicht.

Bis Sie dem Ordner vertrauen, wird der Subagent immer noch ausgeführt, aber Claude Code überspringt seine Frontmatter-Hooks und protokolliert einen Fehler im Debug-Protokoll, der erklärt, wie man dem Ordner vertraut. Dies ist eine strengere Regel als die für Hooks in Einstellungsdateien: Das Vertrauen eines übergeordneten Ordners ist nicht ausreichend, und eine -p-Sitzung zählt nicht als vertrauenswürdig. Was vor dem Vertrauen eines Ordners ausgeführt wird vergleicht die beiden. Vor v2.1.218 konnten Frontmatter-Hooks aus Ordnern ausgeführt werden, denen Sie nicht vertraut haben, auch in nicht-interaktiven Sitzungen.

Alle Hook-Ereignisse werden unterstützt. Die häufigsten Ereignisse für Subagenten sind:

Ereignis Matcher-Eingabe Wann es ausgelöst wird
PreToolUse Werkzeugname Bevor der Subagent ein Werkzeug verwendet
PostToolUse Werkzeugname Nachdem der Subagent ein Werkzeug verwendet hat
Stop (keine) Wenn der Subagent endet (wird zur Laufzeit in SubagentStop konvertiert)

Dieses Beispiel validiert Bash-Befehle mit dem PreToolUse-Hook und führt einen Linter nach Dateibearbeitungen mit PostToolUse aus:

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

Wenn der Agent als Subagent aufgerufen wird, werden Stop-Hooks im Frontmatter automatisch in SubagentStop-Ereignisse konvertiert.

Hooks auf Projektebene für Subagenten-Ereignisse

Konfigurieren Sie Hooks in settings.json, die auf Subagenten-Lebenszyklus-Ereignisse in der Hauptsitzung reagieren.

Ereignis Matcher-Eingabe Wann es ausgelöst wird
SubagentStart Agent-Typname Wenn ein Subagent mit der Ausführung beginnt
SubagentStop Agent-Typname Wenn ein Subagent abgeschlossen ist

Beide Ereignisse unterstützen Matcher, um bestimmte Agent-Typen nach Name zu adressieren. Der Matcher-Wert ist der name des Frontmatters des Agenten für Projekt- und Benutzer-Subagenten oder der Plugin-Umfang-Identifier wie my-plugin:db-agent für Plugin-Subagenten. Ein Umfang-Name enthält einen Doppelpunkt, daher wird er als unverankerte reguläre Ausdrücke ausgewertet; verankern Sie ihn mit ^ und $, wie in ^my-plugin:db-agent$, um nur diesen Agent zu treffen.

Dieses Beispiel führt ein Setup-Skript nur aus, wenn der db-agent-Subagent startet, und ein Cleanup-Skript, wenn ein beliebiger Subagent stoppt:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

Ein Matcher mit Bindestrichen wie db-agent passt genau auf Claude Code v2.1.195 oder später. In früheren Versionen wird er als unverankerte reguläre Ausdrücke ausgewertet und wird auch für jeden Agent-Typ ausgelöst, der ihn enthält, wie prod-db-agent; verankern Sie ihn als ^db-agent$ in diesen Versionen.

Siehe Hooks für das vollständige Hook-Konfigurationsformat.

Arbeiten Sie mit Subagenten

Verstehen Sie automatische Delegation

Claude delegiert automatisch Aufgaben basierend auf der Aufgabenbeschreibung in Ihrer Anfrage, dem description-Feld in Subagenten-Konfigurationen und dem aktuellen Kontext. Um proaktive Delegation zu fördern, fügen Sie Phrasen wie "use proactively" in das description-Feld Ihres Subagenten ein.

Halten Sie Beschreibungen kurz: Claude Code zeigt eine Startwarnmeldung an, wenn die kombinierten Beschreibungen Ihrer Subagenten das Limit von 15.000 Token überschreiten, und lädt dennoch jeden Subagenten.

Rufen Sie Subagenten explizit auf

Wenn automatische Delegation nicht ausreicht, können Sie einen Subagenten selbst anfordern. Drei Muster eskalieren von einem einmaligen Vorschlag zu einem sitzungsweiten Standard:

  • Natürliche Sprache: Nennen Sie den Subagenten in Ihrem Prompt; Claude entscheidet, ob delegiert werden soll
  • @-Erwähnung: Garantiert, dass der Subagent für eine Aufgabe ausgeführt wird
  • Sitzungsweit: Die gesamte Sitzung verwendet den Systemprompt, die Werkzeugbeschränkungen und das Modell dieses Subagenten über das --agent-Flag oder die agent-Einstellung

Für natürliche Sprache gibt es keine spezielle Syntax. Nennen Sie den Subagenten und Claude delegiert normalerweise:

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@-Erwähnen Sie den Subagenten. Geben Sie @ ein und wählen Sie den Subagenten aus der Typeahead-Liste, genauso wie Sie Dateien @-erwähnen. Dies stellt sicher, dass dieser spezifische Subagent ausgeführt wird, anstatt die Wahl Claude zu überlassen:

@"code-reviewer (agent)" look at the auth changes

Ihre vollständige Nachricht geht immer noch an Claude, das den Task-Prompt des Subagenten basierend auf Ihrer Anfrage schreibt. Die @-Erwähnung steuert, welcher Subagent Claude aufruft, nicht welchen Prompt er erhält.

Subagenten, die von einem aktivierten Plugin bereitgestellt werden, erscheinen in der Typeahead-Liste unter ihrem scoped Namen, z. B. my-plugin:code-reviewer oder my-plugin:review:security, wenn das Plugin Agenten in Unterordnern organisiert. Benannte Hintergrund-Subagenten, die derzeit in der Sitzung ausgeführt werden, erscheinen auch in der Typeahead-Liste und zeigen ihren Status neben dem Namen an.

Sie können die Erwähnung auch manuell eingeben, ohne den Picker zu verwenden: @agent-<name> für lokale Subagenten, oder @agent- gefolgt vom scoped Namen für Plugin-Subagenten, z. B. @agent-my-plugin:code-reviewer. Während Sie diese Form eingeben, zeigt die Typeahead-Liste Dateien statt Agenten an. Die Agent-Erwähnung wird trotzdem aufgelöst, wenn Sie absenden.

Führen Sie die gesamte Sitzung als Subagent aus. Übergeben Sie --agent <name>, um eine Sitzung zu starten, in der der Hauptthread selbst den Systemprompt, die Werkzeugbeschränkungen und das Modell dieses Subagenten annimmt:

claude --agent code-reviewer

Der Systemprompt des Subagenten ersetzt den Standard-Claude Code-Systemprompt vollständig, genauso wie --system-prompt es tut. CLAUDE.md-Dateien und Projekt-Memory werden weiterhin durch den normalen Nachrichtenfluss geladen. Der Agent-Name erscheint als @<name> in der Startup-Kopfzeile, damit Sie bestätigen können, dass er aktiv ist.

Dies funktioniert mit integrierten und benutzerdefinierten Subagenten, und die Wahl bleibt bestehen, wenn Sie die Sitzung fortsetzen: Claude Code stellt den Systemprompt, die Werkzeugbeschränkungen und das Modell des Agenten zusammen mit der Konversation wieder her. Wenn der Agent nicht mehr vorhanden ist, wenn Sie fortsetzen, wird die Sitzung mit den Standard-Tools und dem Standard-Systemprompt fortgesetzt und zeigt eine Warnung mit dem Namen des Agenten.

Für einen von einem Plugin bereitgestellten Subagenten können Sie einfach den Agent-Namen übergeben und Claude Code findet ihn:

claude --agent security-reviewer

Wenn mehrere Plugins Agenten mit demselben Namen bereitstellen, übergeben Sie den scoped Namen zur Disambiguierung:

claude --agent my-plugin:security-reviewer

Wenn das Plugin den Agenten in einem Unterordner seines agents/-Verzeichnisses platziert, fügen Sie den Unterordner in den scoped Namen ein, z. B. claude --agent my-plugin:review:security.

Um es zum Standard für jede Sitzung in einem Projekt zu machen, setzen Sie agent in .claude/settings.json:

{
  "agent": "code-reviewer"
}

Das CLI-Flag überschreibt die Einstellung, wenn beide vorhanden sind.

Führen Sie Subagenten im Vordergrund oder Hintergrund aus

Subagenten können im Vordergrund oder im Hintergrund ausgeführt werden:

  • Vordergrund-Subagenten blockieren die Hauptkonversation bis zur Fertigstellung. Berechtigungsaufforderungen werden an Sie weitergeleitet, wenn sie auftreten.
  • Hintergrund-Subagenten laufen gleichzeitig, während Sie weiterarbeiten. Wenn ein Hintergrund-Subagent einen Werkzeugaufruf erreicht, der Berechtigung benötigt, wird die Aufforderung in Ihrer Hauptsitzung angezeigt und nennt den Subagenten, der fragt. Genehmigen Sie, um den Subagenten fortzusetzen, oder drücken Sie Esc, um diesen einen Werkzeugaufruf zu verweigern, ohne den Subagenten zu stoppen. Vor v2.1.186 lehnten Hintergrund-Subagenten automatisch jeden Werkzeugaufruf ab, der eine Aufforderung ausgelöst hätte.

Für jeden Subagenten, den Claude mit dem Agent-Werkzeug spawnt, wählt Claude Code Vordergrund oder Hintergrund aus dem ersten dieser Fälle, der zutrifft:

  • Wenn ein In-Process-Agent-Team-Teamkollege den Subagenten spawnt, führt Claude Code ihn im Vordergrund aus. Claude Code weigert sich mit einem Fehler, einen Subagenten eines Teamkollegen zu spawnen, dessen Definition background: true setzt. Wenn Fork-Modus aus ist und Sie Hintergrund-Aufgaben nicht ausgeschaltet haben, weigert sich Claude Code auch mit einem Fehler, wenn ein Teamkollege run_in_background: true setzt.
  • Wenn Sie CLAUDE_CODE_DISABLE_BACKGROUND_TASKS auf 1 setzen, führt Claude Code den Subagenten im Vordergrund aus, in jeder Art von Sitzung und unabhängig davon, ob Fork-Modus an ist.
  • Wenn Fork-Modus an ist, wie es standardmäßig in einer interaktiven Sitzung der Fall ist, führt Claude Code den Subagenten im Hintergrund aus, sowohl Fork- als auch Nicht-Fork-Subagenten, und Claude kann nicht den Vordergrund anfordern.
  • Wenn Fork-Modus aus ist, führt Claude den Subagenten standardmäßig im Hintergrund aus und im Vordergrund, wenn er das Ergebnis benötigt, bevor er fortfährt. Fork-Modus ist aus im nicht-interaktiven Modus mit -p und im Agent SDK, es sei denn, Sie schalten ihn ein. Um einen bestimmten Subagenten im Hintergrund zu halten, auch wenn Claude das Ergebnis benötigt, setzen Sie sein Frontmatter-Feld background auf true.

Für eine Skill mit context: fork folgt Claude Code stattdessen den Regeln in Führen Sie Skills in einem Subagenten aus, unabhängig davon, ob Fork-Modus an ist.

Hintergrund-Subagenten laufen mit einem kleineren integrierten Werkzeugsatz als Vordergrund-Subagenten, außer für Konversations-Forks, und sie zeigen jede Berechtigungsaufforderung in Ihrer Hauptsitzung an. Wenn Sie eine dieser Aufforderungen mit einer Wahl beantworten, die über diesen einen Werkzeugaufruf hinausgeht, z. B. eine Genehmigung, die für den Rest der Sitzung gilt, wendet Claude Code Ihre Antwort auf die gesamte Sitzung an, einschließlich Ihrer Hauptkonversation.

Ein Hintergrund-Subagent kann einen Hintergrund-Bash- oder PowerShell-Befehl über das Ende seiner Runde hinaus laufen lassen. Wenn dieser Befehl endet, sendet Claude Code dem Subagenten eine Benachrichtigung.

Die Ergebnisse eines Hintergrund-Subagenten erreichen Claude als Abschlussbenachrichtigung in einer späteren Runde. Claude wartet auf diese Benachrichtigung, bevor er die Ergebnisse des Subagenten meldet, und wenn Sie zuerst nach Fortschritt fragen, meldet er, dass der Subagent noch läuft. Vor v2.1.211 meldete Claude manchmal Ergebnisse für einen Hintergrund-Subagenten, der noch nicht fertig war.

Sie können auch selbst steuern:

  • Wenn Fork-Modus aus ist, bitten Sie Claude, eine Aufgabe im Hintergrund oder im Vordergrund auszuführen
  • Drücken Sie Ctrl+B, um eine laufende Aufgabe in den Hintergrund zu verschieben

Claude Code löscht eine Zeile eines Hintergrund-Subagenten aus dem Subagenten-Panel unter der Eingabeaufforderung auf eine von zwei Arten, je nachdem, wie der Subagent endete:

  • Wenn ein Subagent erfolgreich fertig wird, entfernt Claude Code seine Zeile sofort und zeigt außer im Bildschirmlesemodus /tasks to see subagents in der Fußzeile für 30 Sekunden an. Während dieser 30 Sekunden führen Sie /tasks aus und drücken Enter auf dem Subagenten, um sein Transkript zu öffnen. Vor v2.1.232 behielt Claude Code die Zeile 30 Sekunden nach Fertigstellung des Subagenten, genauso wie einen fehlgeschlagenen, und zeigte keinen Fußzeilentipp.
  • Wenn ein Subagent fehlschlägt oder Sie ihn stoppen, behält Claude Code seine Zeile für 30 Sekunden. Um die Zeile früher zu löschen, wählen Sie sie aus und drücken x.

Ein Hintergrund-Subagent, der abgeschlossen ist, bleibt in /tasks aufgelistet, als erledigt markiert und unter laufenden Arbeiten sortiert, für dasselbe Fenster wie der Fußzeilentipp oben. Seine Detailansicht bleibt offen, wenn der Subagent fertig ist. Subagenten, die fehlschlagen oder die Sie stoppen, verlassen die Liste. Vor v2.1.208 verließ ein abgeschlossener Subagent die Liste in dem Moment, in dem er fertig war, und seine Detailansicht schloss sich.

Subagenten-Namen

Claude kann einem Subagenten einen Namen geben, indem er einen name-Parameter beim Agent-Werkzeugaufruf übergibt, und kann dies von sich aus tun, ohne Sie zuerst zu fragen. Der Name macht den Subagenten adressierbar: Claude kann ihn nach Fertigstellung nach Name ansprechen oder fortsetzen.

In einer interaktiven Sitzung mit aktivierten Agent-Teams wird ein Subagent, den Claude aus der Hauptkonversation mit einem name spawnt, stattdessen als Teamkollege gestartet, es sei denn, der Aufruf ist ein Fork oder übergibt isolation beim Aufruf selbst. Ein isolation-Wert im Frontmatter des Subagenten verhindert es nicht, und der Teamkollege läuft dann im Arbeitsverzeichnis der Hauptsitzung. Siehe Wie Claude Agent-Teams startet.

API-Fehler in Subagenten

Wenn etwas einen Subagenten-Response mid-stream unterbricht, und die Teilantwort Text enthält, aber keine Werkzeugaufrufe, fordert Claude Code den Subagenten auf, fortzufahren, anstatt die Ausführung zu beenden. Dies geschieht auch in interaktiven Sitzungen. Die Ausführung endet beim Fehler nur, wenn diese Fortsetzungen aufgebraucht sind.

Ab v2.1.199 meldet ein Subagent, dessen Ausführung mit einem API-Fehler endet, z. B. ein Nutzungslimit oder ein wiederholter Serverfehler, diesen Fehler an Claude zurück, anstatt den Fehlertext so zurückzugeben, als wären es die Erkenntnisse des Subagenten. Was Claude erhält, hängt davon ab, wo der Subagent ausgeführt wurde:

  • Vordergrund: Wenn ein Ratenlimit, eine Überlastung oder ein Serverfehler einen Subagenten unterbricht, der bereits Textausgabe erzeugt hat, gibt das Agent-Werkzeug diese Teilausgabe mit einem Hinweis zurück, dass der Subagent unterbrochen wurde und seine Aufgabe nicht abgeschlossen hat. Ein Subagent, der nichts erzeugt hat, oder dessen einzige Ausgabe Werkzeugaufrufe waren, schlägt mit Agent terminated early due to an API error fehl, gefolgt von der Fehlerdetail. In v2.1.199 gab ein Ratenlimit, eine Überlastung oder ein Serverfehler, der die Form nur mit Werkzeugaufrufen unterbrach, ein leeres Teilergebnis zurück, das nur den Unterbrechungshinweis enthielt.
  • Hintergrund: Der Subagent wird als fehlgeschlagen markiert, und die Nachricht, die Claude erhält, wenn er endet, nennt den API-Fehler und enthält die letzte Ausgabe des Subagenten, sodass Teilarbeit nicht verloren geht.

Wenn Sie eine Fallback-Modellkette konfigurieren und ein Subagent auf einen Fehler trifft, den die Kette abdeckt, z. B. dass sein Modell nicht verfügbar ist, wechselt Claude Code den Subagenten zum ersten Modell in der Kette, das die Anfrage akzeptiert. Der Subagent arbeitet weiter, anstatt beim Fehler zu enden.

Sobald der zugrunde liegende API-Fehler behoben ist, bitten Sie Claude, die Aufgabe zu wiederholen oder setzen Sie den Subagenten fort.

Subagenten-Ausgabe-Scanning

Claude Code scannt den abschließenden Bericht jedes Subagenten, bevor Claude ihn liest. Ein Subagent kann Dateien, Webseiten oder Befehlsausgaben gelesen haben, die Sie nie überprüft haben, und Text aus diesen Quellen kann Anweisungen enthalten, die auf die Hauptkonversation abzielen. Der Scan entfernt oder umformuliert niemals etwas; er nimmt zwei Arten von Änderungen vor, die Sie in einem Bericht bemerken können:

  • Backslash-Einfügung: Der Scan fügt einen Backslash in Text ein, der Claude Code's eigene Ausgabe imitiert, z. B. ein <system-reminder>-Tag oder eine Zeile, die mit Human: oder Assistant: beginnt, damit die Imitation als gewöhnlicher Text gelesen wird, anstatt als Teil der Konversation verwechselt zu werden.
  • Marker-Zeile: Der Scan stellt eine Zeile voran, die mit [harness: subagent output matched instruction-shaped pattern(s): beginnt, wenn der Bericht ein Tag wie <system-reminder> imitiert oder Berechtigungseinstellungen wie bypassPermissions oder --dangerously-skip-permissions erwähnt. Berechtigungseinstellungs-Erwähnungen erhalten die Marker-Zeile, aber der Text selbst bleibt wie geschrieben.

Der Scan beurteilt nicht, ob Inhalte bösartig sind, und er ändert nicht, was eine Anweisung in einem Bericht tun kann: Ein Werkzeugaufruf, zu dem der Bericht Claude führt, durchläuft immer noch die Berechtigungsprüfungen und Sandboxing der Sitzung. Es ist kein Ersatz für Einschränkung, was ein Subagent erreichen kann.

Häufige Muster

Isolieren Sie hochvolumige Operationen

Eine der effektivsten Verwendungen für Subagenten ist die Isolierung von Operationen, die große Mengen an Ausgaben erzeugen. Das Ausführen von Tests, das Abrufen von Dokumentation oder die Verarbeitung von Protokolldateien kann erheblichen Kontext verbrauchen. Durch die Delegierung an einen Subagenten bleibt die ausführliche Ausgabe im Kontext des Subagenten, während nur die relevante Zusammenfassung zu Ihrer Hauptkonversation zurückkehrt.

Use a subagent to run the test suite and report only the failing tests with their error messages

Führen Sie parallele Recherche durch

Für unabhängige Untersuchungen spawnen Sie mehrere Subagenten, um gleichzeitig zu arbeiten:

Research the authentication, database, and API modules in parallel using separate subagents

Jeder Subagent erkundet seinen Bereich unabhängig, dann synthetisiert Claude die Erkenntnisse. Dies funktioniert am besten, wenn die Recherchepfade nicht voneinander abhängen.

Für Aufgaben, die anhaltende Parallelität benötigen oder Ihr Kontextfenster nicht passen, führen Sie sie in separaten Sitzungen aus und lassen Sie Claude Erkenntnisse zwischen ihnen weitergeben.

Verketten Sie Subagenten

Für mehrstufige Workflows bitten Sie Claude, Subagenten nacheinander zu verwenden. Jeder Subagent vervollständigt seine Aufgabe und gibt Ergebnisse an Claude zurück, das dann relevanten Kontext an den nächsten Subagenten übergibt.

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

Wählen Sie zwischen Subagenten und Hauptkonversation

Verwenden Sie die Hauptkonversation, wenn:

  • Die Aufgabe häufiges Hin und Her oder iterative Verfeinerung benötigt
  • Mehrere Phasen teilen erheblichen Kontext, z. B. Planung, Implementierung und Testen
  • Sie eine schnelle, gezielte Änderung vornehmen
  • Latenz ist wichtig. Ein Subagent, der kein Fork ist, startet von vorne und benötigt möglicherweise Zeit, um Kontext zu sammeln

Verwenden Sie Subagenten, wenn:

  • Die Aufgabe ausführliche Ausgaben erzeugt, die Sie nicht in Ihrem Hauptkontext benötigen
  • Sie spezifische Werkzeugbeschränkungen oder Berechtigungen durchsetzen möchten
  • Die Arbeit in sich geschlossen ist und eine Zusammenfassung zurückgeben kann

Erwägen Sie stattdessen Skills, wenn Sie wiederverwendbare Prompts oder Workflows möchten, die im Kontext der Hauptkonversation ausgeführt werden, anstatt in isoliertem Subagenten-Kontext.

Für eine Frage zu etwas, das bereits in Ihrer Konversation ist, verwenden Sie stattdessen /btw. Es sieht Ihren vollständigen Kontext, hat aber keinen Werkzeugzugriff, und die Antwort wird nicht zur Historie hinzugefügt.

Lassen Sie Subagenten ihre eigenen Subagenten spawnen

Standardmäßig kann ein Subagent seine eigenen Subagenten spawnen, bis zu drei Ebenen unter der Hauptkonversation. Bei der Tiefengrenze entzieht Claude Code das Agent-Werkzeug jedem Subagenten außer einem Fork, sodass ein Subagent bei der Grenze seine delegierte Arbeit selbst erledigt und eine Zusammenfassung zurückgibt. Ein Fork bei der Grenze behält Agent in seiner geerbten Werkzeugliste, aber das Werkzeug gibt stattdessen einen Fehler zurück.

Verschachtelte Subagenten eignen sich für eine delegierte Aufgabe, die sich selbst in parallele Unteraufgaben aufteilt, z. B. ein Reviewer-Subagent, der einen Verifier pro Befund versendet, sodass die Zwischenausgabe niemals Ihre Hauptkonversation erreicht. Nur die Zusammenfassung des Top-Level-Subagenten kehrt zu Ihnen zurück.

Um die Grenze zu ändern, setzen Sie CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH auf die Anzahl der Subagenten-Ebenen, die Sie unter Ihrer Hauptkonversation möchten. Zum Beispiel begrenzt dieser Eintrag in settings.json die Verschachtelung auf zwei Ebenen:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

Mit diesem Wert können Ihre Subagenten an eine zweite Ebene ihrer eigenen delegieren, und diese zweite Ebene kann nicht weiter delegieren. Setzen Sie 1, um Verschachtelung auszuschalten.

Ein verschachtelter Subagent wird genauso konfiguriert wie ein Top-Level-Subagent und wird aus denselben Scopes aufgelöst. Um zu verhindern, dass ein Subagent spawnt, während Verschachtelung an ist, z. B. ein Reviewer, der schreibgeschützt bleiben sollte, lassen Sie Agent aus seiner tools-Liste weg oder fügen Sie es zu disallowedTools hinzu.

Claude Code zeigt verschachtelte Subagenten als Baum im Subagenten-Panel unter der Eingabeaufforderung an und markiert jede Zeile, die noch Nachkommen hat, mit einer (+N)-Anzahl von ihnen. Öffnen Sie eine Zeile, um die Geschwister und direkten Kinder dieses Subagenten mit einem Pfad zurück zu main zu sehen.

Gleichzeitige Subagenten-Grenze

Zwei Grenzen steuern die Subagenten-Nutzung, jede mit ihrer eigenen Variablen: Diese stoppt Claude daran, mehr Subagenten zu spawnen, während zu viele laufen, und die Tiefengrenze begrenzt, wie tief Subagenten verschachtelt sind. Es gibt keine Grenze für die Gesamtzahl der Subagenten, die Claude über eine Sitzung spawnen kann.

Standardmäßig schlägt das Spawnen eines anderen mit dem Agent-Werkzeug fehl mit Concurrent subagent limit reached, wenn 20 Subagenten in einer Sitzung laufen, und der Fehler teilt Claude mit, nicht zu wiederholen. Das Spawnen gelingt wieder, wenn die laufende Anzahl unter die Grenze fällt. Um die Grenze zu ändern, setzen Sie CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS auf eine beliebige positive ganze Zahl. Sitzungen mit aktiviertem ultracode sind ausgenommen: Die Grenze wird dort nicht durchgesetzt. Erfordert Claude Code v2.1.217 oder später.

Die Grenze blockiert nur Subagenten, die Claude mit dem Agent-Werkzeug spawnt, aber andere Ausführungen belegen dieselben Slots:

  • Ein In-Session-Fork, den Sie mit /subtask starten, belegt einen Slot, während er läuft, und wird niemals durch die Grenze blockiert.
  • Fortsetzen eines Subagenten, der bereits fertig ist, belegt einen frischen Slot, ohne die Grenze zu prüfen, sodass Fortsetzungen die laufende Anzahl über die Grenze hinaus drücken können.

Agenten, die andere Funktionen ausführen, z. B. Workflow-Agenten und Agent-Team-Teamkollegen, folgen stattdessen ihren eigenen Grenzen.

Verwalten Sie den Subagenten-Kontext

Was wird beim Start geladen

Jeder Subagent startet mit einem frischen, isolierten Kontextfenster. Er sieht nicht Ihre Konversationshistorie, die Skills, die Sie bereits aufgerufen haben, oder die Dateien, die Claude bereits gelesen hat. Claude verfasst eine Delegierungsnachricht, die die Aufgabe zusammenfasst, und der Subagent arbeitet von dort aus. Die Ausnahme ist ein Fork, der die übergeordnete Konversation erbt, anstatt von vorne zu beginnen.

Der anfängliche Kontext eines Nicht-Fork-Subagenten enthält:

  • Systemprompt: Der eigene Prompt des Agenten plus Umgebungsdetails, die Claude Code anhängt, nicht der Claude Code-Systemprompt. Benutzerdefinierte Subagenten definieren ihren in der Markdown-Datei oder im prompt-Feld. Integrierte Agenten haben vordefinierte Prompts.
  • Task-Nachricht: Der Delegierungsprompt, den Claude schreibt, wenn er die Arbeit übergibt.
  • CLAUDE.md-Dateien: Jede Ebene der CLAUDE.md-Hierarchie, die die Hauptkonversation lädt, einschließlich ~/.claude/CLAUDE.md, Projektregeln, CLAUDE.local.md und verwaltete Richtliniendateien. Die integrierten Explore- und Plan-Agenten überspringen dies.
  • Git-Status: Ein Snapshot, der zu Beginn der übergeordneten Sitzung erstellt wurde. Fehlt, wenn das Arbeitsverzeichnis kein Git-Repository ist oder wenn includeGitInstructions false ist. Explore und Plan überspringen es unabhängig davon.
  • Vorgeladene Skills: Vollständiger Inhalt aller Skills, die im skills-Feld des Agenten benannt sind. Integrierte Agenten laden Skills nicht vor.
  • Geschwister-Verzeichnis: Eine Systemerinnerung, die main und jeden anderen benannten Agenten in der Sitzung auflistet, jeweils ein gültiger to-Wert für SendMessage. Erfordert Claude Code v2.1.206 oder später. Das Verzeichnis erscheint nur, wenn die Tools des Subagenten SendMessage enthalten und mindestens ein anderer Agent einen Namen hat, ob Claude ihn beim Spawnen benannt hat oder er als Agent-Team-Teamkollege läuft. Es ist ein Snapshot, der erstellt wird, wenn der Subagent startet, daher erscheinen später benannte Agenten nicht.

Explore und Plan sind die einzigen Subagenten, die CLAUDE.md und Git-Status auslassen. Es gibt kein Frontmatter-Feld oder eine Pro-Agent-Einstellung, um zu ändern, welche Agenten sie überspringen.

Die Hauptkonversation liest Explore- und Plan-Ergebnisse mit vollständigem CLAUDE.md-Kontext, daher müssen die meisten Regeln den Subagenten selbst nicht erreichen. Wenn eine Regel dies muss, z. B. "ignore the vendor/ directory", wiederholen Sie sie in dem Prompt, den Sie Claude geben, wenn Sie delegieren.

Einige Hauptkonversations-Status erreichen niemals einen Nicht-Fork-Subagenten:

  • Ausgabestil: Ein Subagent führt seinen eigenen Systemprompt aus, daher formt Ihr Ausgabestil seine Antworten nicht, außer in einem Fork.
  • Auto-Memory: Das Auto-Memory der Hauptkonversation wird nicht geladen. Um einem Subagenten sein eigenes persistentes Memory zu geben, verwenden Sie das memory-Feld.
  • Kontextfenstergröße: Das Kontextfenster eines Subagenten wird durch sein eigenes Modell dimensioniert, nicht das des übergeordneten. Die Delegierung an ein Modell mit einem kleineren Fenster gibt diesem Subagenten das kleinere Fenster.

Setzen Sie Subagenten fort

Jede Subagenten-Invokation erstellt eine neue Instanz, anstatt eine frühere fortzusetzen. Um die Arbeit eines vorhandenen Subagenten fortzusetzen, anstatt von vorne zu beginnen, bitten Sie Claude, ihn fortzusetzen.

Fortgesetzte Subagenten behalten ihre vollständige Konversationshistorie, einschließlich aller vorherigen Werkzeugaufrufe, Ergebnisse und Überlegungen. Der Subagent setzt genau dort an, wo er gestoppt hat, anstatt von vorne zu beginnen.

  • Wenn ein Subagent abgeschlossen ist, erhält Claude seine Agent-ID.
  • Die integrierten Explore- und Plan-Agenten sind einmalig und geben keine Agent-ID zurück, sodass Claude sie nicht fortsetzen kann. Verwenden Sie general-purpose oder einen benutzerdefinierten Subagenten, wenn Sie die Arbeit fortsetzen müssen.
  • Wenn ein Subagent bei seiner maxTurns-Grenze stoppt, markiert Claude Code die zurückgegebene Ausgabe als Teilausgabe. Für Subagenten, die eine Agent-ID zurückgeben, vermerkt Claude Code auch im Ergebnis, dass Claude den Subagenten ansprechen kann, um von dort weiterzumachen, wo er gestoppt hat.

Claude verwendet das SendMessage-Werkzeug mit der Agent-ID oder dem Namen des Agenten als to-Feld, um ihn fortzusetzen. SendMessage erfordert nicht, dass Agent-Teams aktiviert sind; nur strukturierte Team-Protokoll-Nachrichten wie shutdown_request und plan_approval_response erfordern dies. Über Subagenten und Teamkollegen hinaus können Claude in Sitzungen, in denen Cross-Session-Messaging aktiviert ist, mit demselben Werkzeug Ihre anderen Claude Code-Sitzungen auf dieser Maschine oder darüber hinaus ansprechen.

Um einen Subagenten fortzusetzen, bitten Sie Claude, die vorherige Arbeit fortzusetzen:

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

Ein abgeschlossener Subagent, der eine SendMessage erhält, wird automatisch im Hintergrund fortgesetzt, ohne dass eine neue Agent-Invokation erforderlich ist. Das Gleiche gilt für einen Subagenten, den Claude mit dem TaskStop-Werkzeug gestoppt hat.

Ein Subagent, den Sie selbst gestoppt haben, mit x in /tasks oder einer SDK-stop_task-Anfrage, wird nicht automatisch fortgesetzt. Wenn Claude ihm eine Nachricht sendet, wird die Nachricht abgelehnt und Claude wird mitgeteilt, dass der Agent abgebrochen wurde.

Während diese Zeile des Subagenten noch im Subagenten-Panel ist, geben Sie in sein Transkript ein, um ihn selbst fortzusetzen. Danach kann eine Nachricht von Claude ihn wieder automatisch fortsetzen. Erfordert Claude Code v2.1.191 oder später.

Das Fortsetzen startet einen neuen Lauf des Agenten unter derselben ID, sodass ein Subagent, der bereits fehlgeschlagen oder abgeschlossen war, in der Aufgabenliste und in den Task-Events des Agent SDK wieder als laufend angezeigt wird. Vor v2.1.205 zeigte er seinen früheren fehlgeschlagenen oder abgeschlossenen Status, während der fortgesetzte Lauf funktionierte.

Ab v2.1.199 überprüft SendMessage, dass ein Name immer noch auf denselben Agenten verweist, den er früher in der Konversation erreicht hat. Wenn ein neuerer Agent den Namen übernommen hat, z. B. ein neu gestarteter Hintergrund-Agent, der ihn wiederverwendet hat, weigert sich Claude Code, die Nachricht zu senden, anstatt sie an den falschen Agenten zu liefern, und der Fehler meldet, welchen Agenten der Name jetzt erreicht, damit Claude neu ausrichten kann. Um den früheren Agenten zu erreichen, während er noch läuft, adressiert Claude ihn nach der Agent-ID, die er beim Spawnen dieses Agenten erhalten hat. Die Überprüfung ist auf die aktuelle Konversation beschränkt und wird bei /clear zurückgesetzt.

Ab v2.1.198 behandelt ein Subagent Nachrichten vom Agenten, der ihn gestartet hat, als normale Aufgabenrichtung, einschließlich Kurskorrektionen während der Aufgabe, und handelt danach innerhalb seiner eigenen Berechtigungseinstellungen. Zwei Limits gelten immer noch unabhängig davon, wer die Nachricht gesendet hat: Keine Nachricht von einem Agenten zählt als Ihre Genehmigung für eine ausstehende Berechtigungsaufforderung, und keine Agent-Nachricht kann die Berechtigungseinstellungen, CLAUDE.md oder Konfiguration eines Subagenten ändern. Nur das Berechtigungssystem oder Ihre eigenen Nachrichten können Genehmigung gewähren.

Sie können auch Claude nach der Agent-ID fragen, wenn Sie sie explizit referenzieren möchten, oder IDs in den Transkriptdateien unter ~/.claude/projects/{project}/{sessionId}/subagents/ finden. Jedes Transkript wird als agent-{agentId}.jsonl gespeichert.

Subagenten-Transkripte bleiben unabhängig von der Hauptkonversation bestehen:

  • Hauptkonversations-Komprimierung: Wenn die Hauptkonversation komprimiert wird, sind Subagenten-Transkripte nicht betroffen. Sie werden in separaten Dateien gespeichert.
  • Sitzungs-Persistenz: Subagenten-Transkripte bleiben innerhalb ihrer Sitzung bestehen. Sie können einen Subagenten fortsetzen, nachdem Sie Claude Code neu gestartet haben, indem Sie dieselbe Sitzung fortsetzen.
  • Automatische Bereinigung: Claude Code löscht Subagenten-Transkripte nach der cleanupPeriodDays-Aufbewahrungsfrist, standardmäßig 30 Tage, nach den Aufbewahrungssweep-Regeln.

Auto-Komprimierung

Subagenten unterstützen automatische Komprimierung mit derselben Logik wie die Hauptkonversation. Die Komprimierung wird unter denselben Bedingungen ausgelöst, und CLAUDE_AUTOCOMPACT_PCT_OVERRIDE gilt auch für Subagenten. Siehe Umgebungsvariablen für den Zeitpunkt, zu dem die Überschreibung wirksam wird.

Komprimierungsereignisse werden in Subagenten-Transkriptdateien protokolliert:

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

Der preTokens-Wert zeigt, wie viele Token vor der Komprimierung verwendet wurden.

Gegabelte Konversation

Ein Fork ist ein Subagent, der die gesamte bisherige Konversation erbt, anstatt von vorne zu beginnen. Dies lässt die Eingabe-Isolierung fallen, die Subagenten ansonsten bieten: Ein Fork sieht denselben Systemprompt, dieselben Werkzeuge, dasselbe Modell und die Nachrichtenhistorie wie die Hauptsitzung, sodass Sie ihm eine Nebenaufgabe übergeben können, ohne die Situation erneut zu erklären. Die eigenen Werkzeugaufrufe des Forks bleiben weiterhin aus Ihrer Konversation heraus und nur sein endgültiges Ergebnis kommt zurück, sodass Ihr Hauptkontextfenster sauber bleibt. Verwenden Sie einen Fork, wenn ein anderer Subagent zu viel Hintergrund benötigen würde, um nützlich zu sein, oder wenn Sie mehrere Ansätze parallel vom gleichen Ausgangspunkt aus versuchen möchten.

Claude startet einen Fork, indem er den fork-Subagenten-Typ durch das Agent-Werkzeug anfordert. Sie steuern, ob dies möglich ist, mit dem Fork-Modus, der in interaktiven Sitzungen standardmäßig aktiviert ist.

Sie können einen Fork selbst mit /subtask gefolgt von einer Aufgabe starten, unabhängig davon, ob der Fork-Modus aktiviert ist oder nicht. In v2.1.161 bis v2.1.211 ist der Befehl /fork. Claude Code benennt den Fork aus den ersten Worten der Aufgabe. Das folgende Beispiel gabelt die Konversation, um Testfälle zu entwerfen, während Sie mit der Implementierung in der Hauptsitzung fortfahren:

/subtask draft unit tests for the parser changes so far

Der Fork erscheint in einem Panel unter Ihrer Eingabeaufforderung und läuft im Hintergrund, während Sie weiterarbeiten. Wenn er fertig ist, kommt sein Ergebnis als Nachricht in Ihrer Hauptkonversation an. Der nächste Abschnitt behandelt die Panel-Steuerelemente zum Beobachten und Lenken von Forks während ihrer Ausführung.

Beobachten und lenken Sie laufende Forks

Laufende Forks erscheinen in einem Panel unter der Eingabeaufforderung, mit einer Zeile für die Hauptsitzung und einer für jeden Fork.

Wenn ein Fork erfolgreich abgeschlossen ist, entfernt Claude Code seine Zeile. Claude Code behält die Zeile eines Forks, der fehlgeschlagen ist oder den Sie gestoppt haben, für 30 Sekunden bei, das gleiche wie für jeden anderen Hintergrund-Subagenten. Vor v2.1.232 behielt Claude Code die Zeile eines abgeschlossenen Forks ebenfalls für 30 Sekunden bei.

Verwenden Sie diese Tasten, um mit dem Panel zu interagieren:

Taste Aktion
↑ / ↓ Zwischen Zeilen wechseln
Enter Öffnen Sie das Transkript des ausgewählten Forks und senden Sie ihm Folgefragen
x Stoppen Sie den ausgewählten Fork, wenn er läuft, oder schließen Sie seine Zeile, wenn er nicht mehr läuft. In der Hauptsitzungs-Zeile oder in der Zeile des Forks, dessen Transkript Sie mit Enter geöffnet haben, gibt x stattdessen in die Eingabeaufforderung ein
Esc Fokus zurück zur Eingabeaufforderung

Mit einem geöffneten Transkript eines Forks oder Subagenten gehen Folgefragen und Skills an diesen Agenten, aber integrierte Befehle werden weiterhin in Ihrer Hauptkonversation ausgeführt. Ab v2.1.199 zeigt die Eingabe von /model oder /fast in dieser Ansicht einen Hinweis an, dass dies das Modell oder den Schnellmodus der Hauptkonversation ändert, nicht des angezeigten Agenten, anstatt es stillschweigend auszuführen.

Wie sich Forks von anderen Subagenten unterscheiden

Ein Fork erbt alles, was die Hauptsitzung zum Zeitpunkt des Spawnens hat. Jeder andere Subagent startet von seiner Definition aus.

Fork Nicht-Fork-Subagent
Kontext Vollständige Konversationshistorie Frischer Kontext mit dem Prompt, den Sie übergeben
Systemprompt und Werkzeuge Gleich wie Hauptsitzung Aus der Definitionsdatei des Subagenten, gefiltert für Hintergrund-Läufe
Modell Gleich wie Hauptsitzung Aus dem model-Feld des Subagenten
Berechtigungen Aufforderungen erscheinen in Ihrem Terminal Aufforderungen erscheinen in Ihrer Hauptsitzung bei Ausführung im Hintergrund
Prompt-Cache Mit Hauptsitzung geteilt Separater Cache

Da der Systemprompt und die Werkzeugdefinitionen eines Forks identisch mit dem übergeordneten Element sind, wird seine erste Anfrage den Prompt-Cache des übergeordneten Elements wiederverwenden. Dies macht das Forking billiger als das Spawnen eines frischen Subagenten für Aufgaben, die denselben Kontext benötigen.

Wenn Claude einen Fork durch das Agent-Werkzeug spawnt, kann es isolation: "worktree" übergeben, sodass die Dateibearbeitungen des Forks in einen separaten Git-Worktree geschrieben werden, anstatt in Ihren Checkout. Ein Fork kann keine weiteren Forks spawnen.

Fork-Modus aktivieren oder deaktivieren

Claude Code aktiviert den Fork-Modus standardmäßig in interaktiven Sitzungen und lässt ihn standardmäßig im nicht-interaktiven Modus mit -p und im Agent SDK deaktiviert. Der interaktive Standard erfordert Claude Code v2.1.232 oder später. In früheren Versionen setzen Sie CLAUDE_CODE_FORK_SUBAGENT auf 1, um den Fork-Modus zu aktivieren.

Sie können erkennen, dass der Fork-Modus aktiviert ist, an der Art und Weise, wie Claude Code das Agent-Werkzeug handhabt:

  • Claude kann einen Fork spawnen, indem er den fork-Subagenten-Typ anfordert. Wenn Claude keinen Typ anfordert, erhält es den allgemeinen-Subagenten, falls die Sitzung diesen Typ noch hat. Subagenten, die aus einer Definition gespawnt werden, wie Explore, funktionieren wie gewohnt.
  • Claude Code führt die Subagenten, die Claude spawnt, im Hintergrund aus, Forks und Nicht-Fork-Subagenten gleichermaßen, abgesehen von den Fällen, die im Vordergrund bleiben. Claude Code entfernt auch den run_in_background-Parameter des Agent-Werkzeugs, sodass Claude nicht den Vordergrund anfordern kann.

Setzen Sie die Umgebungsvariable CLAUDE_CODE_FORK_SUBAGENT, um die Standardwerte zu überschreiben:

  • 1 aktiviert den Fork-Modus auch im nicht-interaktiven Modus und im Agent SDK
  • 0 deaktiviert den Fork-Modus in jeder Art von Sitzung

Um den Fork-Modus aktiviert zu halten, aber Claude daran zu hindern, Forks zu spawnen, verweigern Sie den fork-Subagenten-Typ mit einer Agent(fork)-Regel. Claude Code führt die Subagenten, die Claude spawnt, weiterhin im Hintergrund aus, abgesehen von den gleichen Fällen, die im Vordergrund bleiben.

Beispiel-Subagenten

Diese Beispiele demonstrieren effektive Muster für die Erstellung von Subagenten. Verwenden Sie sie als Ausgangspunkte oder generieren Sie eine angepasste Version mit Claude.

Code-Reviewer

Ein schreibgeschützter Subagent, der Code überprüft, ohne ihn zu ändern. Dieses Beispiel zeigt, wie man einen fokussierten Subagenten mit begrenztem Werkzeugzugriff entwirft, der Edit und Write ausschließt, und einen detaillierten Prompt, der genau angibt, worauf zu achten ist und wie die Ausgabe formatiert wird.

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

Debugger

Ein Subagent, der sowohl Probleme analysieren als auch beheben kann. Im Gegensatz zum Code-Reviewer enthält dieser Edit, da das Beheben von Bugs die Änderung von Code erfordert. Der Prompt bietet einen klaren Workflow von der Diagnose zur Verifizierung.

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

Data Scientist

Ein domänenspezifischer Subagent für Datenanalyse-Arbeiten. Dieses Beispiel zeigt, wie man Subagenten für spezialisierte Workflows außerhalb typischer Coding-Aufgaben erstellt. Es setzt explizit model: sonnet für fähigere Analysen.

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

Datenbankabfrage-Validator

Ein Subagent, der Bash-Zugriff zulässt, aber Befehle validiert, um nur schreibgeschützte SQL-Abfragen zu ermöglichen. Dieses Beispiel zeigt, wie man PreToolUse-Hooks für bedingte Validierung verwendet, wenn Sie feinere Kontrolle benötigen, als das tools-Feld bietet.

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

Claude Code übergibt Hook-Eingabe als JSON über stdin an Hook-Befehle. Das Validierungsskript liest dieses JSON, extrahiert den auszuführenden Befehl und prüft ihn gegen eine Liste von SQL-Schreibvorgängen. Wenn ein Schreibvorgang erkannt wird, beendet das Skript mit Code 2, um die Ausführung zu blockieren, und gibt eine Fehlermeldung an Claude über stderr zurück.

Erstellen Sie das Validierungsskript überall in Ihrem Projekt. Der Pfad muss dem command-Feld in Ihrer Hook-Konfiguration entsprechen:

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

Machen Sie das Skript unter macOS und Linux ausführbar:

chmod +x ./scripts/validate-readonly-query.sh

Unter Windows schreiben Sie das Validierungsskript in PowerShell und fügen shell: powershell zum Hook-Eintrag hinzu. Siehe Hooks in PowerShell ausführen.

Der Hook empfängt JSON über stdin mit dem Bash-Befehl in tool_input.command. Exit-Code 2 blockiert die Operation und leitet die Fehlermeldung an Claude weiter. Siehe Hooks für Details zu Exit-Codes und Hook-Eingabe für das vollständige Eingabeschema.

Das System-Prompt teilt dem Subagenten mit, Schreibanfragen abzulehnen, daher ist der Hook ein Sicherheitsmechanismus: Wenn der Subagent trotzdem einen Schreibvorgang versucht, blockiert Claude Code den Befehl und der Subagent sieht die Meldung Blocked: Write operations not allowed. Use SELECT queries only..

Nächste Schritte

Jetzt, da Sie Subagenten verstehen, erkunden Sie diese verwandten Funktionen: