Benutzerdefinierte Subagenten erstellen

• 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

Integrierte Subagenten

• Um einen bestimmten integrierten Typ zu blockieren, fügen Sie ihn zu permissions.deny hinzu, wie in Spezifische Subagenten deaktivieren gezeigt.
• Um zu verhindern, dass Claude an einen Subagenten delegiert, verweigern Sie das Agent-Werkzeug selbst mit permissions.deny.
• Um nur die integrierten Explore- und Plan-Subagenten zu entfernen, setzen Sie CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude liest und erkundet Dateien direkt, anstatt an sie zu delegieren. Erfordert Claude Code v2.1.198 oder später.
• Im nicht-interaktiven Modus und dem Agent SDK setzen Sie CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1, um alle integrierten Typen zu entfernen und nur Ihre eigenen bereitzustellen.

Schnellstart: Erstellen Sie Ihren ersten Subagenten

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.

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

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

Konfigurieren Sie Subagenten

Wählen Sie den Subagenten-Umfang

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."
  }
}'

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."
  }
}
'@

• prompt: Der Systemprompt des Agenten, äquivalent zum Markdown-Body in dateibasierten Subagenten. prompt kann leer sein. Wenn Sie einen Agent mit einem leeren prompt und ohne memory-Feld als Sitzungs-Agent mit --agent auswählen, bleibt der Systemprompt der Sitzung unverändert. Ein leerer prompt erfordert Claude Code v2.1.281 oder später.
• Frontmatter-Felder: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, autoCompactWindow, skills, initialPrompt, memory, effort, background, omitClaudeMd und isolation.
• Ignorierte Felder: color und experimental werden hier nicht akzeptiert und werden ignoriert statt abgelehnt.

Schreiben Sie Subagenten-Dateien

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

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

Frontmatter-Referenz

• Um ein falsch geschriebenes Feld in einem geladenen Subagenten zu finden, führen Sie claude --debug in Ihrer Shell aus und durchsuchen Sie das Debug-Log unter ~/.claude/debug/<session-id>.txt nach does not recognize or apply. Das Debug-Log nennt bis zu fünf Felder der obersten Ebene in der Datei des Subagenten, die Claude Code nicht erkennt, zusammen mit dem wahrscheinlich gemeinten Namen, wenn ein unterstütztes Feld ähnlich ist. Erfordert Claude Code v2.1.296 oder später.
• Um herauszufinden, warum eine Subagenten-Datei nicht geladen wurde, siehe Subagenten-Dateien, die Claude Code überspringt.

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

Subagenten-Dateien, die Claude Code überspringt

• 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, : enthält oder länger als 256 Zeichen ist: Claude Code überspringt die Datei und schreibt einen Fehler in das Debug-Log.
• 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.

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

Wählen Sie ein Modell

• 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-5 oder claude-sonnet-5. Akzeptiert dieselben Werte wie das --model-Flag
• inherit: Verwenden Sie dasselbe Modell wie die Hauptkonversation

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 Modell der Hauptkonversation gehört zu dieser Familie: Der Subagent läuft auf dem genauen Modell der Hauptkonversation, einschließlich aller [1m]-Suffixe, sodass er das gleiche erweiterte Kontextfenster wie die Hauptkonversation erhält.
• Claude Code kann die Modellfamilie der Hauptkonversation nicht bestimmen, auf einem anderen Provider als der Anthropic API: Dies kann mit einem Application Inference Profile ARN auf Amazon Bedrock passieren, das Claude Code nicht zu einem Backing-Modell aufgelöst hat. Dieser Fall deckt nur den opus-Alias ab und gilt nicht, wenn Sie ANTHROPIC_DEFAULT_OPUS_MODEL setzen, da opus dann zum von Ihnen gesetzten Modell aufgelöst wird.

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

Führen Sie jeden Subagenten auf einem Modell aus

• 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, mit der Ausnahme, dass der integrierte Explore-Subagent auf dem Modell läuft, das für ihn unter Integrierte Subagenten aufgeführt ist.

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

• Ein Fork
• Ein Skill, der in einem Subagenten läuft mit model: inherit

Wählen Sie eine Effort-Stufe

Wenn ein Subagent weder ein effort-Feld noch einen Parameter hat

Kontrollieren Sie Subagenten-Fähigkeiten

Verfügbare Werkzeuge

• 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
• WaitForMcpServers
• Workflow

Beschränken Sie, welche Tools ein Subagent verwenden kann

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

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

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

MCP-Servernamen, die einen doppelten Unterstrich enthalten

• In tools: Schreiben Sie mcp__, gefolgt vom vollständigen Namen des Servers und __*, wie in mcp__reports__v2__*. Ohne das abschließende __* passt mcp__reports__v2 auf keines der Tools dieses Servers.
• In disallowedTools: Suchen Sie nach mcp__reports oder mcp__reports__*, den Einträgen, die die Tools eines Servers namens reports vorenthalten. Mit jedem der beiden Einträge verliert der Subagent auch jedes reports__v2-Tool, da diese Tool-Namen ebenfalls mit mcp__reports__ beginnen. Um nur die Tools des reports-Servers vorzuenthalten, listen Sie sie stattdessen einzeln auf, etwa mcp__reports__run_query.

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

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

tools: Agent, Read, Bash

Umfang von MCP-Servern auf einen Subagenten

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

• --strict-mcp-config und --bare
• Enterprise-verwaltete MCP-Konfiguration
• allowedMcpServers- und deniedMcpServers-Richtlinien

Erforderliches Vertrauen für Inline-MCP-Server

• 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

• 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

Berechtigungsmodi

• Wenn die Hauptkonversation in bypassPermissions, acceptEdits oder Auto-Modus ist, läuft der Subagent in diesem gleichen Modus und Claude Code ignoriert den permissionMode, den Sie setzen. Unter Auto-Modus bewertet der Klassifizierer die Werkzeugaufrufe des Subagenten mit den Block- und Zulassungsregeln der Hauptkonversation. Wenn der Subagent endet, überprüft der Klassifizierer auch seine Arbeit und seinen endgültigen Bericht, bevor der Bericht geliefert wird, wie Wie Auto-Modus Subagenten handhabt beschreibt. Wenn ein Subagent um Erlaubnis fragt, während die Hauptkonversation in bypassPermissions ist, prüfen Sie, ob sein Tool-Aufruf zu den Aktionen gehört, die kein Modus automatisch genehmigt.
• Wenn die Hauptkonversation im Modus plan ist, bleibt der Subagent im Plan-Modus, unabhängig davon, welchen permissionMode Sie setzen, es sei denn, er läuft als Teammate eines Agent-Teams gemäß den Regeln für Agent-Teams. Wenn Sie dontAsk setzen, fragt der Subagent Sie außerdem nicht nach: Eine Aktion, für die der Plan-Modus Sie um Genehmigung bitten würde, wird stattdessen abgelehnt.
• Wenn die Hauptkonversation im Modus default oder dontAsk ist, läuft der Subagent in dem Berechtigungsmodus, den Sie setzen. In diesen Fällen behält er stattdessen den Berechtigungsmodus der Hauptkonversation:
  • Sie setzen bypassPermissions. Die bypassPermissions-Ausnahme erfordert Claude Code v2.1.267 oder später.
  • Sie setzen auto, und der Auto-Modus ist für den Subagenten nicht verfügbar, etwa wenn eine Einstellungsdatei disableAutoMode setzt oder das Modell des Subagenten den Auto-Modus nicht unterstützt.

Laden Sie Skills in Subagenten vor

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

Aktivieren Sie persistenten Speicher

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

• 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

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

#!/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

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

Deaktivieren Sie spezifische Subagenten

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

claude --disallowedTools "Agent(Explore)"

Definieren Sie Hooks für Subagenten

• 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 im Subagenten-Frontmatter

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

Hooks auf Projektebene für Subagenten-Ereignisse

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

Mit Subagenten arbeiten

Automatische Delegation verstehen

Subagenten explizit aufrufen

• 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 wird als dieser Subagent über das Flag --agent oder die Einstellung agent ausgeführt

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

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

claude --agent code-reviewer

claude --agent security-reviewer

claude --agent my-plugin:security-reviewer

{
  "agent": "code-reviewer"
}

Subagenten im Vordergrund oder Hintergrund ausführen

• Vordergrund-Subagenten blockieren die Hauptkonversation bis zur Fertigstellung. Berechtigungsabfragen werden an Sie weitergeleitet, wenn sie auftauchen.
• Hintergrund-Subagenten werden gleichzeitig ausgeführt, während Sie weiterarbeiten. Wenn ein Hintergrund-Subagent einen Tool-Aufruf erreicht, der eine Berechtigung benötigt, zeigt Claude Code die Abfrage in Ihrer Hauptsitzung an und nennt den Subagenten, der fragt. Genehmigen Sie, um den Subagenten fortfahren zu lassen, oder drücken Sie Esc, um diesen einen Tool-Aufruf zu verweigern, ohne den Subagenten zu stoppen.

Welche Subagenten im Hintergrund laufen

• claude -p und das Agent SDK: Claude kann warten, nach eigenem Ermessen oder wenn Sie darum bitten.
• Interaktive Terminal-Sitzung, VS Code und Sitzungen der Desktop-App auf Ihrem Rechner: Damit Claude auf einen Subagenten warten kann, schalten Sie den Fork-Modus aus, der standardmäßig aktiviert ist.

Claude auf einen Subagenten warten lassen

1. Schalten Sie den Fork-Modus aus, indem Sie CLAUDE_CODE_FORK_SUBAGENT auf 0 setzen, zum Beispiel in settings.json:
   {
     "env": {
       "CLAUDE_CODE_FORK_SUBAGENT": "0"
     }
   }
   
2. Führen Sie claude erneut in Ihrer Shell aus oder öffnen Sie eine neue VS Code-Konversation.
3. Bitten Sie Claude zu warten, wenn Sie zuerst ein Ergebnis benötigen, zum Beispiel „run the reviewer subagent and wait for its report“.

Tools, Berechtigungen und Ergebnisse von Hintergrund-Subagenten

Beendete Subagenten im Panel und in der Aufgabenliste

• Wenn ein Subagent erfolgreich beendet wird, entfernt Claude Code seine Zeile sofort und zeigt, außer im Screen-Reader-Modus, /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 Beendigung des Subagenten, genauso wie bei einem 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 schneller zu löschen, wählen Sie sie aus und drücken x.

Subagenten-Namen

API-Fehler in Subagenten

• Vordergrund: Wenn ein Rate-Limit, eine Überlastung oder ein Serverfehler einen Subagenten unterbricht, der bereits Textausgabe produziert hat, gibt das Agent-Tool diese teilweise Ausgabe mit einer Notiz zurück, dass der Subagent unterbrochen wurde und seine Aufgabe nicht abgeschlossen hat. Ein Subagent, der nichts produziert hat oder dessen einzige Ausgabe Tool-Aufrufe waren, schlägt mit Agent terminated early due to an API error fehl, gefolgt vom Fehlerdetail.
• 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 teilweise Arbeit nicht verloren geht.

⚠ This agent switched to <model> because its earlier model could not be used.

Subagenten-Ausgabe-Scanning

• Backslash-Einfügung: Der Scan fügt einen Backslash in Text ein, der die eigene Ausgabe von Claude Code 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. Erwähnungen von Berechtigungseinstellungen erhalten die Marker-Zeile, aber der Text selbst bleibt wie geschrieben.

Häufige Muster

Isolieren Sie hochvolumige Operationen

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

Führen Sie parallele Recherchen durch

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

Verketten Sie Subagenten

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

Wählen Sie zwischen Subagenten und Hauptkonversation

• Die Aufgabe häufiges Hin und Her oder iterative Verfeinerung benötigt
• Mehrere Phasen teilen erheblichen Kontext, z. B. Planung, Implementierung und Tests
• 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

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

Lassen Sie Subagenten ihre eigenen Subagenten spawnen

• Interaktive Terminal-Sitzung: Nur die Zusammenfassung des Top-Level-Subagenten kehrt zu Ihnen zurück, da ein Subagent, der Hintergrund-Subagenten startet, auf deren Ergebnisse wartet, bevor er beendet wird.
• claude -p und das Agent SDK: Der startende Subagent wartet, solange der Fork-Modus aktiviert ist. Wenn Sie den Fork-Modus ausschalten, starten verschachtelte Subagenten stattdessen im Hintergrund. Der startende Subagent wartet nicht auf einen verschachtelten Hintergrund-Subagenten, der an Ihre Hauptkonversation meldet, wenn er den startenden Subagenten überdauert.

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

Gleichzeitige Subagenten-Grenze

• 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 beendet wurde, belegt einen frischen Slot, ohne die Grenze zu überprüfen, sodass Fortsetzungen die laufende Anzahl über sie hinaus drücken können.

Verwalten Sie den Subagenten-Kontext

Was beim Start geladen wird

• System-Prompt: der eigene Prompt des Agenten plus Umgebungsdetails, die Claude Code anfügt, nicht der System-Prompt von Claude Code. Benutzerdefinierte Subagenten definieren ihren im Markdown-Body oder im Feld prompt. Integrierte Agenten haben vordefinierte Prompts.
• Task-Nachricht: der Delegierungs-Prompt, 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, verwaltete Richtliniendateien und alle AGENTS.md-Dateien, die als Projektanweisungen geladen werden. Die integrierten Explore- und Plan-Agenten überspringen dies. Ein Subagent, dessen Definition omitClaudeMd setzt, lädt nur die verwalteten Richtliniendateien oder gar keine, wenn die Definition aus verwalteten Einstellungen kommt.
• Git-Status: Ein Snapshot, den Claude Code aus Ihrem Repository liest, wenn der Subagent startet. Für einen Subagenten in seinem eigenen Worktree dieses Repositorys zeigt der Snapshot den Branch, den Status und die letzten Commits des Worktrees. Abwesend außerhalb eines Git-Repositorys oder wenn der Snapshot ausgeschaltet ist; siehe includeGitInstructions. Explore und Plan überspringen es unabhängig davon.
• Vorgeladene Skills: Vollständiger Inhalt jedes Skills, der im Feld skills des Agenten benannt ist. Integrierte Agenten laden Skills nicht vor.
• Geschwister-Roster: Eine System-Erinnerung, die main und jeden anderen benannten Agenten in der Sitzung auflistet, jeweils ein gültiger to-Wert für SendMessage. Das Roster 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 beim Start des Subagenten aufgenommen wird, sodass später benannte Agenten nicht erscheinen.

• Ausgabestil: Ein Subagent führt seinen eigenen System-Prompt aus, sodass Ihr Ausgabestil seine Antworten nicht formt, außer in einem Fork.
• Auto-Memory: Das Auto-Memory der Hauptkonversation wird nicht geladen. Um einem Subagenten sein eigenes persistentes Gedächtnis zu geben, verwenden Sie das Feld memory.
• 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.

Subagenten fortsetzen

• Wenn ein Subagent abgeschlossen wird, 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 teilweise, und Claude kann den Subagenten fortsetzen, um seine Arbeit weiterzuführen.

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]

• 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 Aufbewahrungsfrist cleanupPeriodDays, standardmäßig 30 Tage, nach den Regeln für die automatische Bereinigung.

Einem Subagenten nach einem Neustart per Name eine Nachricht senden

Automatische Komprimierung

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

Das Fenster für die automatische Komprimierung für einen Subagenten festlegen

---
name: log-reader
description: Reads long log files and reports the errors it finds
autoCompactWindow: 200000
---

• Der Wert liegt nicht unter dem Fenster für die automatische Komprimierung, das der Subagent sonst erben würde: Um früher zu komprimieren, setzen Sie einen Wert unterhalb dieses Fensters.
• Sie führen die gesamte Sitzung mit --agent oder der Einstellung agent als diesen Subagenten aus: Das Feld hat dort keine Wirkung. Um das Fenster der Sitzung festzulegen, siehe Das Fenster für die automatische Komprimierung festlegen.

Gegabelte Konversation

/subtask draft unit tests for the parser changes so far

Beobachten und lenken Sie laufende Forks

• /compact, /clear und /rewind wirken auf die Hauptkonversation, daher bittet Claude Code Sie um Bestätigung, bevor einer dieser Befehle aus dieser Ansicht ausgeführt wird.
• /model und /fast legen das Modell und den Fast-Modus der Hauptkonversation fest, nicht die des angezeigten Agenten, daher werden sie aus dieser Ansicht nicht ausgeführt. Ein Hinweis erklärt Ihnen den Grund.

Wie sich Forks von anderen Subagenten unterscheiden

Fork-Modus deaktivieren

• Nur Forks unterbinden: Fügen Sie "Agent(fork)" zu permissions.deny in Ihren Einstellungen hinzu.
• Fork-Modus deaktivieren: Setzen Sie CLAUDE_CODE_FORK_SUBAGENT auf 0 und folgen Sie dabei den Schritten unter Claude auf einen Subagenten warten lassen.

Beispiel-Subagenten

Code-Reviewer

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

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

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

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

#!/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

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

Nächste Schritte

• Verteilen Sie Subagenten mit Plugins, um Subagenten über Teams oder Projekte hinweg zu teilen
• Führen Sie Claude Code programmgesteuert aus mit dem Agent SDK für CI/CD und Automatisierung
• Verwenden Sie MCP-Server, um Subagenten Zugriff auf externe Werkzeuge und Daten zu geben