Benutzerdefinierte Subagenten in Claude Code sind spezialisierte KI-Assistenten, die aufgerufen werden können, um bestimmte Arten von Aufgaben zu bewältigen. Sie ermöglichen eine effizientere Problemlösung durch die Bereitstellung aufgabenspezifischer Konfigurationen mit angepassten Systemprompts, Tools und einem separaten Kontextfenster.

Was sind Subagenten?

Subagenten sind vorkonfigurierte KI-Persönlichkeiten, an die Claude Code Aufgaben delegieren kann. Jeder Subagent:
  • Hat einen spezifischen Zweck und Fachbereich
  • Verwendet sein eigenes Kontextfenster, getrennt von der Hauptunterhaltung
  • Kann mit spezifischen Tools konfiguriert werden, die er verwenden darf
  • Enthält einen benutzerdefinierten Systemprompt, der sein Verhalten steuert
Wenn Claude Code auf eine Aufgabe stößt, die der Expertise eines Subagenten entspricht, kann es diese Aufgabe an den spezialisierten Subagenten delegieren, der unabhängig arbeitet und Ergebnisse zurückgibt.

Hauptvorteile

Kontexterhaltung

Jeder Subagent arbeitet in seinem eigenen Kontext, verhindert die Verschmutzung der Hauptunterhaltung und hält sie auf übergeordnete Ziele fokussiert.

Spezialisierte Expertise

Subagenten können mit detaillierten Anweisungen für spezifische Bereiche feinabgestimmt werden, was zu höheren Erfolgsraten bei bestimmten Aufgaben führt.

Wiederverwendbarkeit

Einmal erstellt, können Subagenten in verschiedenen Projekten verwendet und mit Ihrem Team für konsistente Workflows geteilt werden.

Flexible Berechtigungen

Jeder Subagent kann unterschiedliche Tool-Zugriffsebenen haben, wodurch Sie mächtige Tools auf bestimmte Subagenten-Typen beschränken können.

Schnellstart

Um Ihren ersten Subagenten zu erstellen:
1

Öffnen Sie die Subagenten-Schnittstelle

Führen Sie den folgenden Befehl aus:
/agents
2

Wählen Sie 'Create New Agent'

Wählen Sie, ob Sie einen Projekt- oder Benutzer-Subagenten erstellen möchten
3

Definieren Sie den Subagenten

  • Empfohlen: Generieren Sie zuerst mit Claude, dann passen Sie ihn an, um ihn zu Ihrem zu machen
  • Beschreiben Sie Ihren Subagenten detailliert und wann er verwendet werden sollte
  • Wählen Sie die Tools aus, zu denen Sie Zugriff gewähren möchten (oder lassen Sie es leer, um alle Tools zu erben)
  • Die Schnittstelle zeigt alle verfügbaren Tools an, was die Auswahl erleichtert
  • Wenn Sie mit Claude generieren, können Sie auch den Systemprompt in Ihrem eigenen Editor bearbeiten, indem Sie e drücken
4

Speichern und verwenden

Ihr Subagent ist jetzt verfügbar! Claude wird ihn automatisch verwenden, wenn es angemessen ist, oder Sie können ihn explizit aufrufen:
> Verwende den code-reviewer Subagenten, um meine letzten Änderungen zu überprüfen

Subagenten-Konfiguration

Dateispeicherorte

Subagenten werden als Markdown-Dateien mit YAML-Frontmatter an zwei möglichen Orten gespeichert:
TypOrtGeltungsbereichPriorität
Projekt-Subagenten.claude/agents/Verfügbar im aktuellen ProjektHöchste
Benutzer-Subagenten~/.claude/agents/Verfügbar in allen ProjektenNiedriger
Wenn Subagenten-Namen in Konflikt stehen, haben Projekt-Subagenten Vorrang vor Benutzer-Subagenten.

Plugin-Agenten

Plugins können benutzerdefinierte Subagenten bereitstellen, die sich nahtlos in Claude Code integrieren. Plugin-Agenten funktionieren identisch zu benutzerdefinierten Agenten und erscheinen in der /agents-Schnittstelle. Plugin-Agenten-Speicherorte: Plugins enthalten Agenten in ihrem agents/-Verzeichnis (oder benutzerdefinierten Pfaden, die im Plugin-Manifest angegeben sind). Verwendung von Plugin-Agenten:
  • Plugin-Agenten erscheinen in /agents neben Ihren benutzerdefinierten Agenten
  • Können explizit aufgerufen werden: “Verwende den code-reviewer Agenten aus dem security-plugin”
  • Können automatisch von Claude aufgerufen werden, wenn angemessen
  • Können über die /agents-Schnittstelle verwaltet (angezeigt, inspiziert) werden
Siehe die Plugin-Komponenten-Referenz für Details zur Erstellung von Plugin-Agenten.

CLI-basierte Konfiguration

Sie können Subagenten auch dynamisch mit dem --agents CLI-Flag definieren, das ein JSON-Objekt akzeptiert:
claude --agents '{
  "code-reviewer": {
    "description": "Experte Code-Reviewer. Verwende proaktiv nach Code-Änderungen.",
    "prompt": "Du bist ein Senior Code-Reviewer. Fokussiere dich auf Code-Qualität, Sicherheit und bewährte Praktiken.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'
Priorität: CLI-definierte Subagenten haben niedrigere Priorität als Projekt-Subagenten, aber höhere Priorität als Benutzer-Subagenten. Anwendungsfall: Dieser Ansatz ist nützlich für:
  • Schnelles Testen von Subagenten-Konfigurationen
  • Sitzungsspezifische Subagenten, die nicht gespeichert werden müssen
  • Automatisierungsskripte, die benutzerdefinierte Subagenten benötigen
  • Teilen von Subagenten-Definitionen in Dokumentation oder Skripten
Für detaillierte Informationen über das JSON-Format und alle verfügbaren Optionen siehe die CLI-Referenzdokumentation.

Dateiformat

Jeder Subagent wird in einer Markdown-Datei mit dieser Struktur definiert:
---
name: ihr-sub-agent-name
description: Beschreibung, wann dieser Subagent aufgerufen werden sollte
tools: tool1, tool2, tool3  # Optional - erbt alle Tools, wenn weggelassen
model: sonnet  # Optional - spezifiziere Modell-Alias oder 'inherit'
---

Der Systemprompt Ihres Subagenten steht hier. Dies können mehrere Absätze sein
und sollte die Rolle, Fähigkeiten und den Ansatz des Subagenten zur
Problemlösung klar definieren.

Fügen Sie spezifische Anweisungen, bewährte Praktiken und alle Einschränkungen hinzu,
die der Subagent befolgen sollte.

Konfigurationsfelder

FeldErforderlichBeschreibung
nameJaEindeutige Kennung mit Kleinbuchstaben und Bindestrichen
descriptionJaNatürlichsprachige Beschreibung des Zwecks des Subagenten
toolsNeinKommagetrennte Liste spezifischer Tools. Wenn weggelassen, erbt alle Tools vom Hauptthread
modelNeinModell für diesen Subagenten. Kann ein Modell-Alias (sonnet, opus, haiku) oder 'inherit' sein, um das Modell der Hauptunterhaltung zu verwenden. Wenn weggelassen, standardmäßig das konfigurierte Subagenten-Modell

Modellauswahl

Das model-Feld ermöglicht es Ihnen zu kontrollieren, welches KI-Modell der Subagent verwendet:
  • Modell-Alias: Verwenden Sie einen der verfügbaren Aliase: sonnet, opus oder haiku
  • 'inherit': Verwenden Sie dasselbe Modell wie die Hauptunterhaltung (nützlich für Konsistenz)
  • Weggelassen: Wenn nicht angegeben, verwendet das Standardmodell, das für Subagenten konfiguriert ist (sonnet)
Die Verwendung von 'inherit' ist besonders nützlich, wenn Sie möchten, dass sich Ihre Subagenten an die Modellwahl der Hauptunterhaltung anpassen und so konsistente Fähigkeiten und Antwortstile während Ihrer gesamten Sitzung gewährleisten.

Verfügbare Tools

Subagenten können Zugriff auf alle internen Tools von Claude Code erhalten. Siehe die Tools-Dokumentation für eine vollständige Liste verfügbarer Tools.
Empfohlen: Verwenden Sie den /agents-Befehl, um Tool-Zugriff zu ändern - er bietet eine interaktive Schnittstelle, die alle verfügbaren Tools auflistet, einschließlich aller verbundenen MCP-Server-Tools, was die Auswahl der benötigten Tools erleichtert.
Sie haben zwei Optionen für die Konfiguration von Tools:
  • Lassen Sie das tools-Feld weg, um alle Tools vom Hauptthread zu erben (Standard), einschließlich MCP-Tools
  • Spezifizieren Sie einzelne Tools als kommagetrennte Liste für granularere Kontrolle (kann manuell oder über /agents bearbeitet werden)
MCP-Tools: Subagenten können auf MCP-Tools von konfigurierten MCP-Servern zugreifen. Wenn das tools-Feld weggelassen wird, erben Subagenten alle MCP-Tools, die dem Hauptthread zur Verfügung stehen.

Verwalten von Subagenten

Verwendung des /agents-Befehls (Empfohlen)

Der /agents-Befehl bietet eine umfassende Schnittstelle für die Subagenten-Verwaltung:
/agents
Dies öffnet ein interaktives Menü, in dem Sie können:
  • Alle verfügbaren Subagenten anzeigen (eingebaute, Benutzer- und Projekt-Subagenten)
  • Neue Subagenten mit geführter Einrichtung erstellen
  • Bestehende benutzerdefinierte Subagenten bearbeiten, einschließlich ihres Tool-Zugriffs
  • Benutzerdefinierte Subagenten löschen
  • Sehen, welche Subagenten aktiv sind, wenn Duplikate existieren
  • Tool-Berechtigungen einfach verwalten mit einer vollständigen Liste verfügbarer Tools

Direkte Dateiverwaltung

Sie können Subagenten auch verwalten, indem Sie direkt mit ihren Dateien arbeiten:
# Erstelle einen Projekt-Subagenten
mkdir -p .claude/agents
echo '---
name: test-runner
description: Verwende proaktiv, um Tests auszuführen und Fehler zu beheben
---

Du bist ein Test-Automatisierungsexperte. Wenn du Code-Änderungen siehst, führe proaktiv die entsprechenden Tests aus. Wenn Tests fehlschlagen, analysiere die Fehler und behebe sie, während du die ursprüngliche Testabsicht bewahrst.' > .claude/agents/test-runner.md

# Erstelle einen Benutzer-Subagenten
mkdir -p ~/.claude/agents
# ... erstelle Subagenten-Datei

Effektive Verwendung von Subagenten

Automatische Delegation

Claude Code delegiert proaktiv Aufgaben basierend auf:
  • Der Aufgabenbeschreibung in Ihrer Anfrage
  • Dem description-Feld in Subagenten-Konfigurationen
  • Aktuellem Kontext und verfügbaren Tools
Um proaktivere Subagenten-Verwendung zu fördern, fügen Sie Phrasen wie “verwende PROAKTIV” oder “MUSS VERWENDET WERDEN” in Ihr description-Feld ein.

Explizite Aufrufe

Fordern Sie einen spezifischen Subagenten an, indem Sie ihn in Ihrem Befehl erwähnen:
> Verwende den test-runner Subagenten, um fehlschlagende Tests zu beheben
> Lass den code-reviewer Subagenten meine letzten Änderungen betrachten
> Bitte den debugger Subagenten, diesen Fehler zu untersuchen

Beispiel-Subagenten

Code-Reviewer

---
name: code-reviewer
description: Experte Code-Review-Spezialist. Überprüft proaktiv Code auf Qualität, Sicherheit und Wartbarkeit. Verwende sofort nach dem Schreiben oder Ändern von Code.
tools: Read, Grep, Glob, Bash
model: inherit
---

Du bist ein Senior Code-Reviewer, der hohe Standards für Code-Qualität und Sicherheit gewährleistet.

Wenn aufgerufen:
1. Führe git diff aus, um kürzliche Änderungen zu sehen
2. Fokussiere dich auf geänderte Dateien
3. Beginne sofort mit der Überprüfung

Review-Checkliste:
- Code ist einfach und lesbar
- Funktionen und Variablen sind gut benannt
- Kein duplizierter Code
- Ordnungsgemäße Fehlerbehandlung
- Keine exponierten Geheimnisse oder API-Schlüssel
- Eingabevalidierung implementiert
- Gute Testabdeckung
- Leistungsüberlegungen berücksichtigt

Gib Feedback organisiert nach Priorität:
- Kritische Probleme (muss behoben werden)
- Warnungen (sollte behoben werden)
- Vorschläge (erwäge Verbesserung)

Füge spezifische Beispiele hinzu, wie Probleme behoben werden können.

Debugger

---
name: debugger
description: Debugging-Spezialist für Fehler, Testfehler und unerwartetes Verhalten. Verwende proaktiv bei Problemen.
tools: Read, Edit, Bash, Grep, Glob
---

Du bist ein Experte-Debugger, spezialisiert auf Ursachenanalyse.

Wenn aufgerufen:
1. Erfasse Fehlermeldung und Stack-Trace
2. Identifiziere Reproduktionsschritte
3. Isoliere den Fehlerort
4. Implementiere minimale Lösung
5. Verifiziere, dass die Lösung funktioniert

Debugging-Prozess:
- Analysiere Fehlermeldungen und Logs
- Überprüfe kürzliche Code-Änderungen
- Bilde und teste Hypothesen
- Füge strategisches Debug-Logging hinzu
- Inspiziere Variablenzustände

Für jedes Problem, gib an:
- Ursachenerklärung
- Beweise, die die Diagnose stützen
- Spezifische Code-Lösung
- Testansatz
- Präventionsempfehlungen

Fokussiere dich darauf, das zugrundeliegende Problem zu beheben, nicht nur Symptome.

Datenwissenschaftler

---
name: data-scientist
description: Datenanalyse-Experte für SQL-Abfragen, BigQuery-Operationen und Dateneinblicke. Verwende proaktiv für Datenanalyse-Aufgaben und Abfragen.
tools: Bash, Read, Write
model: sonnet
---

Du bist ein Datenwissenschaftler, spezialisiert auf SQL- und BigQuery-Analyse.

Wenn aufgerufen:
1. Verstehe die Datenanalyse-Anforderung
2. Schreibe effiziente SQL-Abfragen
3. Verwende BigQuery-Kommandozeilen-Tools (bq) wenn angemessen
4. Analysiere und fasse Ergebnisse zusammen
5. Präsentiere Erkenntnisse klar

Wichtige Praktiken:
- Schreibe optimierte SQL-Abfragen mit ordnungsgemäßen Filtern
- Verwende angemessene Aggregationen und Joins
- Füge Kommentare hinzu, die komplexe Logik erklären
- Formatiere Ergebnisse für Lesbarkeit
- Gib datengestützte Empfehlungen

Für jede Analyse:
- Erkläre den Abfrageansatz
- Dokumentiere alle Annahmen
- Hebe wichtige Erkenntnisse hervor
- Schlage nächste Schritte basierend auf Daten vor

Stelle immer sicher, dass Abfragen effizient und kosteneffektiv sind.

Bewährte Praktiken

  • Beginnen Sie mit Claude-generierten Agenten: Wir empfehlen dringend, Ihren ersten Subagenten mit Claude zu generieren und dann darauf zu iterieren, um ihn persönlich zu Ihrem zu machen. Dieser Ansatz gibt Ihnen die besten Ergebnisse - eine solide Grundlage, die Sie an Ihre spezifischen Bedürfnisse anpassen können.
  • Entwerfen Sie fokussierte Subagenten: Erstellen Sie Subagenten mit einzelnen, klaren Verantwortlichkeiten, anstatt zu versuchen, einen Subagenten alles machen zu lassen. Dies verbessert die Leistung und macht Subagenten vorhersagbarer.
  • Schreiben Sie detaillierte Prompts: Fügen Sie spezifische Anweisungen, Beispiele und Einschränkungen in Ihre Systemprompts ein. Je mehr Anleitung Sie geben, desto besser wird der Subagent funktionieren.
  • Beschränken Sie Tool-Zugriff: Gewähren Sie nur Tools, die für den Zweck des Subagenten notwendig sind. Dies verbessert die Sicherheit und hilft dem Subagenten, sich auf relevante Aktionen zu konzentrieren.
  • Versionskontrolle: Checken Sie Projekt-Subagenten in die Versionskontrolle ein, damit Ihr Team davon profitieren und sie gemeinsam verbessern kann.

Erweiterte Verwendung

Verkettung von Subagenten

Für komplexe Workflows können Sie mehrere Subagenten verketten:
> Verwende zuerst den code-analyzer Subagenten, um Leistungsprobleme zu finden, dann verwende den optimizer Subagenten, um sie zu beheben

Dynamische Subagenten-Auswahl

Claude Code wählt intelligent Subagenten basierend auf dem Kontext aus. Machen Sie Ihre description-Felder spezifisch und handlungsorientiert für beste Ergebnisse.

Leistungsüberlegungen

  • Kontext-Effizienz: Agenten helfen dabei, den Hauptkontext zu bewahren und ermöglichen längere Gesamtsitzungen
  • Latenz: Subagenten beginnen jedes Mal mit einem sauberen Zustand, wenn sie aufgerufen werden, und können Latenz hinzufügen, da sie Kontext sammeln, den sie benötigen, um ihre Arbeit effektiv zu erledigen.

Verwandte Dokumentation

  • Plugins - Erweitern Sie Claude Code mit benutzerdefinierten Agenten durch Plugins
  • Slash-Befehle - Lernen Sie andere eingebaute Befehle kennen
  • Einstellungen - Konfigurieren Sie das Verhalten von Claude Code
  • Hooks - Automatisieren Sie Workflows mit Event-Handlern