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

​

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.

​

Unterstützte Frontmatter-Felder

​

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-4-8 oder claude-sonnet-5. Akzeptiert dieselben Werte wie das --model-Flag
• inherit: Verwenden Sie dasselbe Modell wie die Hauptkonversation
• Omitted: Wenn nicht angegeben, wird standardmäßig inherit verwendet (verwendet dasselbe Modell wie die Hauptkonversation)

1. Die Umgebungsvariable CLAUDE_CODE_SUBAGENT_MODEL, wenn gesetzt auf einen Modell-Alias oder eine Modell-ID
2. Der model-Parameter pro Invokation
3. Das model-Frontmatter der Subagenten-Definition
4. Das Modell der Hauptkonversation

​

Kontrollieren Sie Subagenten-Fähigkeiten

​

Verfügbare Werkzeuge

• AskUserQuestion
• EnterPlanMode
• ExitPlanMode, es sei denn, der permissionMode des Subagenten ist plan
• ScheduleWakeup
• WaitForMcpServers

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

---
name: no-writes
description: Inherits every tool except file writes
disallowedTools: Write, Edit
---

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

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

​

Berechtigungsmodi

​

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.

• 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

​

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, die in der Hauptsitzung ausgeführt werden, wenn Subagenten starten oder stoppen

​

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 $TOOL_INPUT"
  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" }
        ]
      }
    ]
  }
}

​

Arbeiten Sie mit Subagenten

​

Verstehen Sie automatische Delegation

​

Rufen Sie Subagenten explizit auf

• 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

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

​

Führen Sie Subagenten im Vordergrund oder Hintergrund aus

• Vordergrund-Subagenten blockieren die Hauptkonversation bis zur Fertigstellung. Berechtigungsaufforderungen werden an Sie weitergeleitet, wenn sie auftreten.
• Hintergrund-Subagenten laufen gleichzeitig, während Sie weiterarbeiten. Ab v2.1.186 wird die Aufforderung in Ihrer Hauptsitzung angezeigt, wenn ein Hintergrund-Subagent einen Werkzeugaufruf erreicht, der Berechtigung benötigt, 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.

• Claude bitten, eine Aufgabe im Hintergrund oder im Vordergrund auszuführen
• Ctrl+B drücken, um eine laufende Aufgabe in den Hintergrund zu verschieben

​

API-Fehler in Subagenten

• Vordergrund: Wenn ein Ratenlimit, eine Überlastung oder ein Serverfehler einen Subagenten unterbricht, der bereits Ausgaben 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.

​

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 Recherche 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 Testen
• Sie eine schnelle, gezielte Änderung vornehmen
• Latenz ist wichtig. Subagenten starten von vorne und benötigen möglicherweise Zeit, um Kontext zu sammeln

• 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

​

Spawnen Sie verschachtelte Subagenten

​

Verwalten Sie den Subagenten-Kontext

​

Was wird beim Start geladen

• Systemprompt: Der eigene Prompt des Agenten plus Umgebungsdetails, die Claude Code anhängt, nicht der vollständige 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 und Memory: Jede Ebene der Memory-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.

​

Setzen Sie Subagenten fort

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: Transkripte werden basierend auf der cleanupPeriodDays-Einstellung bereinigt, die standardmäßig 30 Tage beträgt.

​

Auto-Komprimierung

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

​

Gegabelte Konversation

• Claude kann einen Fork spawnen, indem es den fork-Subagenten-Typ explizit anfordert. Spawns ohne einen Subagenten-Typ verwenden weiterhin den allgemeinen-Subagenten, und benannte Subagenten wie Explore werden weiterhin wie zuvor gespawnt.
• Jeder Subagenten-Spawn wird im Hintergrund ausgeführt, unabhängig davon, ob es sich um einen Fork oder einen benannten Subagenten handelt. Setzen Sie CLAUDE_CODE_DISABLE_BACKGROUND_TASKS auf 1, um Spawns synchron zu halten.

/fork draft unit tests for the parser changes so far

​

Beobachten und lenken Sie laufende Forks

​

Wie sich Forks von benannten Subagenten unterscheiden

​

Einschränkungen

​

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