Benutzerdefinierte Claude Code Subagenten erstellen (Konfigurationsanleitung)

Es gibt eine Obergrenze, die Sie in jeder KI-Programmiersitzung erreichen: das Kontextfenster. Wenn eine Konversation eine große Refaktorisierung, mehrere Testrunden und ein Code-Review gleichzeitig enthält, verliert der Agent schnell Fokus. Claude Code Subagents lösen dieses Problem, indem Sie Aufgaben an fokussierte Worker auslagern: jeder mit eigenem Kontextfenster, eigenen Anweisungen und eigenen Tool-Berechtigungen.

Teste Apidog noch heute

In diesem Leitfaden erstellen Sie Subagents als Konfigurationsdateien, definieren deren Frontmatter, steuern die Delegation und bauen ein praktisches Setup: ein Agent reviewt Code, während ein anderer parallel API-Tests schreibt. Wenn Sie zuerst den konzeptionellen Überblick möchten, lesen Sie was Claude Code Sub-Agents sind und warum sie wichtig sind. Hier geht es um die konkrete Implementierung und darum, wie API-Tests aus einem Test-Subagenten ein echtes Verifizierungs-Gate machen.

TL;DR

Ein Claude Code Subagent ist eine Markdown-Datei in .claude/agents/ oder ~/.claude/agents/.

Sie definieren:

• name: Bezeichner des Subagenten
• description: Delegations-Trigger für Claude
• tools: optionale Tool-Zulassungsliste
• model: optionales Modell
• Body: System-Prompt des Subagenten

Jeder Subagent läuft in einem eigenen Kontextfenster mit eigenen Tools. Claude delegiert automatisch anhand der description, oder Sie rufen den Subagenten explizit auf. Die offizielle Referenz finden Sie in den Claude Code Subagents Docs.

Subagents in 60 Sekunden

Ein Subagent ist eine separate Agenteninstanz, an die der Haupt-Claude-Code-Agent eine klar begrenzte Aufgabe übergibt.

Denken Sie an diese Rollenverteilung:

• Hauptagent: leitender Entwickler
• Subagents: spezialisierte Reviewer, Tester, Debugger oder Dokumentationsautoren

Ein Subagent arbeitet in seiner eigenen Konversation und gibt nur das Ergebnis zurück. Dadurch bleibt der Haupt-Thread sauber.

Wichtige Eigenschaften:

• Eigenes Kontextfenster: Zwischenarbeit belastet nicht den Hauptkontext.
• Eigener System-Prompt: Sie definieren präzise Verhalten, Prioritäten und Ausgabeformat.
• Eigene Tool-Berechtigungen: Ein Reviewer kann z. B. nur lesen, während ein Test-Subagent Tests schreiben und ausführen darf.

Der konzeptionelle Überblick erklärt das Warum ausführlicher. Die Idee passt zum Prinzip des Claude Code Agent Harness: strukturierte Arbeitsteilung statt eines überladenen Prompts.

Warum Subagents verwenden?

1. Kontextisolation

Lange Sessions werden schlechter, wenn das Kontextfenster voll ist. Jede gelesene Datei, jeder Testlauf und jede Fehlersuche verbraucht Token.

Mit Subagents bleibt die Zwischenarbeit isoliert. Der Hauptagent erhält nur das Ergebnis, z. B.:

Review abgeschlossen:
- 2 kritische Probleme
- 1 mittleres Problem
- keine Änderungen vorgenommen

Das reduziert Kontextverschmutzung und kann auch Token-Kosten senken. Mehr dazu: Agenten-Token-Kosten reduzieren.

2. Parallelität

Unabhängige Aufgaben müssen nicht nacheinander laufen.

Beispiel:

• Subagent A reviewt den Diff
• Subagent B schreibt API-Tests
• Subagent C prüft Dokumentation

Die Gesamtlaufzeit nähert sich der langsamsten Einzelaufgabe an, nicht der Summe aller Aufgaben. Für größere Fan-outs siehe Claude Code Dynamic Workflows.

3. Spezialisierung

Ein allgemeiner Agent ist flexibel, aber nicht optimal fokussiert.

Ein guter Subagent hat:

• eine konkrete Verantwortung
• einen engen System-Prompt
• nur die notwendigen Tools
• ein strukturiertes Ausgabeformat

Das macht ihn nützlicher als einen allgemeinen Prompt wie „Bitte prüfe den Code“.

Einen benutzerdefinierten Subagenten erstellen

Subagents sind Markdown-Dateien.

Projektbezogen:

mkdir -p .claude/agents
touch .claude/agents/code-reviewer.md

Persönlich:

mkdir -p ~/.claude/agents
touch ~/.claude/agents/code-reviewer.md

Beispiel: Code-Reviewer

---
name: code-reviewer
description: "Überprüft Codeänderungen auf Fehler, Sicherheitsprobleme und Konventionsverstöße. Nach dem Schreiben oder Bearbeiten von Code verwenden."
tools: Read, Grep, Glob
model: sonnet
---

Sie sind ein erfahrener Code-Reviewer. Wenn Ihnen ein Diff oder eine Reihe von Dateien gegeben wird:

1. Suchen Sie nach Korrektheitsfehlern, Sicherheitslücken und übersehenen Randfällen.
2. Überprüfen Sie, ob der Code den bestehenden Konventionen des Projekts entspricht.
3. Melden Sie nur hochzuverlässige Probleme, nach Schweregrad geordnet.

Ausgabeformat:

- Urteil: Pass / Fail
- Kritische Probleme
- Mittlere Probleme
- Kleine Hinweise
- Dateien und Zeilen, sofern verfügbar

Seien Sie spezifisch. Nennen Sie Datei und Zeile. Stempeln Sie nicht einfach ab.

Bedeutung der Frontmatter-Felder

Feld	Zweck
name	Name, über den Sie den Subagenten aufrufen
description	Delegations-Trigger, den Claude liest
tools	erlaubte Tools für diesen Subagenten
model	optionales Modell für diese Aufgabe

Die description ist besonders wichtig. Schreiben Sie sie nicht wie einen Titel, sondern wie eine Einsatzregel.

Schlecht:

description: Code-Reviewer

Besser:

description: Überprüft Codeänderungen auf Fehler, Sicherheitsprobleme und Konventionsverstöße. Nach dem Schreiben oder Bearbeiten von Code verwenden.

Der Body ist der System-Prompt. Behandeln Sie ihn wie ein Onboarding-Dokument für einen neuen Teamkollegen: Aufgabe, Prioritäten, Grenzen und Ausgabeformat. Wenn Ihr Projekt ein design.md oder AGENTS.md nutzt, können Subagents daraus Projektkonventionen ableiten.

Subagents aufrufen

Es gibt zwei Wege.

Automatische Delegation

Claude liest die description aller verfügbaren Subagents und entscheidet, ob eine Aufgabe passt.

Beispiel-Prompt an den Hauptagenten:

Implementiere den neuen Orders-Endpunkt und prüfe danach die Änderungen.

Wenn der code-reviewer eine passende Beschreibung hat, kann Claude den Review automatisch delegieren.

Expliziter Aufruf

Sie können einen Subagenten direkt nennen:

Verwende den Subagenten code-reviewer für die Änderungen im Modul orders.

Oder:

Nutze api-test-writer, um Tests für den neuen POST /orders Endpunkt zu schreiben.

Der Subagent arbeitet dann in seinem eigenen Kontext und gibt eine Zusammenfassung zurück. Für deterministischere Abläufe können Slash Commands oder das SDK besser passen. Die Claude Code-Übersicht beschreibt die Konfigurationsoberfläche.

Subagents vs. Agent SDK vs. dynamische Workflows

Tool	Kontrollmodell	Am besten geeignet für
Subagents	Modell entscheidet, wann delegiert wird, oder Sie benennen einen Subagenten explizit	In-Session-Spezialisierung und leichte Parallelisierung
Dynamische Workflows	Modell orchestriert große Fan-outs in einer Sitzung	Viele parallele Aufgaben, große Reviews
Agent SDK	Sie schreiben den Kontrollfluss im Code	Deterministische Schleifen, geplante oder unbeaufsichtigte Ausführungen

Subagents sind ideal, wenn Sie interaktiv in Claude Code arbeiten und ein kleines Set spezialisierter Helfer brauchen.

Wenn Sie eine programmatische Schleife benötigen, verwenden Sie das Claude Agent SDK. Wenn Sie gehostete und selbst entwickelte Agenten vergleichen möchten, lesen Sie Managed Agents vs. Agent SDK.

Praktisches Beispiel: Review und API-Tests parallel ausführen

Angenommen, Claude Code hat einen neuen Orders-Endpunkt implementiert. Jetzt wollen Sie:

1. den Code reviewen
2. API-Tests schreiben
3. die Tests ausführen
4. Pass/Fail zurückbekommen

Dafür definieren Sie zwei Subagents.

Subagent 1: Code-Reviewer

---
name: code-reviewer
description: Überprüft Codeänderungen auf Fehler, Sicherheitsprobleme und Konventionsverstöße. Nach dem Schreiben oder Bearbeiten von Code verwenden.
tools: Read, Grep, Glob
model: sonnet
---

Sie sind ein erfahrener Code-Reviewer.

Prüfen Sie:

1. Korrektheitsfehler
2. Sicherheitsprobleme
3. fehlende Randfälle
4. Abweichungen von Projektkonventionen

Geben Sie das Ergebnis in dieser Struktur zurück:

- Urteil: Pass / Fail
- Kritische Probleme
- Mittlere Probleme
- Kleine Hinweise
- Empfohlene nächste Schritte

Subagent 2: API-Testautor

---
name: api-test-writer
description: Schreibt API-Testfälle für neue oder geänderte Endpunkte. Nach der Implementierung eines Endpunkts verwenden.
tools: Read, Grep, Write, Bash
model: sonnet
---

Sie schreiben API-Tests gemäß der OpenAPI-Spezifikation des Projekts.

Vorgehen:

1. Lesen Sie die OpenAPI-Spezifikation.
2. Lesen Sie die Endpunktimplementierung.
3. Schreiben Sie Tests für:
   - erfolgreichen Request
   - Validierungsfehler
   - Authentifizierungsfehler
   - relevante Randfälle
4. Prüfen Sie Statuscodes.
5. Validieren Sie Response-Bodies gegen das Schema.
6. Führen Sie die Tests aus.
7. Melden Sie Pass/Fail mit Gründen.

Ausgabeformat:

- Urteil: Pass / Fail
- Geschriebene Tests
- Fehlgeschlagene Tests
- Relevante Logs
- Empfohlene Fixes

Beispiel-Prompt

Der neue Orders-Endpunkt ist implementiert.

Starte parallel:
1. code-reviewer für den Diff
2. api-test-writer für API-Tests gegen die OpenAPI-Spezifikation

Fasse danach beide Ergebnisse zusammen und priorisiere notwendige Fixes.

Der Hauptagent kann beide Aufgaben gleichzeitig delegieren. Der Reviewer liest den Diff, während der Testautor Spezifikation und Implementierung prüft, Tests schreibt und die Suite ausführt.

Das Ergebnis sind zwei isolierte Berichte:

code-reviewer:
- Fail
- Kritisch: fehlende Auth-Prüfung in orders.controller.ts:42

api-test-writer:
- Fail
- POST /orders akzeptiert ungültige currency-Werte
- Schema-Validierung schlägt für error response fehl

Damit wird der Test-Subagent zu einem Verifizierungs-Gate. Das entspricht dem Prinzip aus Coding Agent Loops: Nicht die Selbsteinschätzung des Agenten zählt, sondern das Ergebnis eines deterministischen Gates.

Wenn Sie Apidog verwenden, können Sie den Subagenten auf ein Apidog-Testszenario verweisen, damit Responses schema-validiert werden. Für Live-Endpunktaufrufe kann der Apidog AI Agent Debugger helfen, Requests wie ein menschlicher Tester zu inspizieren. Dasselbe Muster lässt sich zu autonomen Claude-Workflows, die ohne Sie laufen, erweitern. Sie können Apidog herunterladen, wenn Ihr Test-Gate schema-bewusst arbeiten soll.

Best Practices

Eine Verantwortung pro Subagent

Gut:

• code-reviewer
• api-test-writer
• security-auditor

Schlecht:

• do-everything-agent

Ein Subagent sollte eine klar begrenzte Aufgabe haben.

Beschreibungen als Trigger schreiben

Die description sollte Claude sagen, wann der Subagent verwendet werden soll.

Gut:

description: Reproduziert gemeldete Bugs und isoliert die Ursache. Bei Bugreports oder fehlschlagenden Tests verwenden.

Schlecht:

description: Debugger

Tools nach Least Privilege vergeben

Ein Reviewer braucht normalerweise keinen Schreibzugriff:

tools: Read, Grep, Glob

Ein Testautor braucht eventuell Schreib- und Shell-Zugriff:

tools: Read, Grep, Write, Bash

Wenn Sie tools weglassen, erbt der Subagent die Tools des Hauptagenten. Das ist bequem, aber riskanter, besonders bei unbeaufsichtigten Läufen.

Modell passend zur Aufgabe wählen

Mechanische Aufgaben können mit einem schnelleren Modell laufen. Schwierige Reviews oder Architekturentscheidungen profitieren eher von einem stärkeren Modell.

model: sonnet

Nutzen Sie das Modellfeld bewusst, um Geschwindigkeit und Kosten zu steuern.

Strukturierte Ergebnisse verlangen

Gute Subagenten geben keine Fließtext-Wand zurück, sondern ein auswertbares Ergebnis.

Beispiel:

Ausgabeformat:

- Urteil: Pass / Fail
- Blockierende Probleme
- Nicht-blockierende Probleme
- Dateien
- Empfohlene nächste Schritte

Das macht die Ausgabe für Sie und den Hauptagenten leichter nutzbar.

Hierarchie flach halten

Vermeiden Sie Subagents, die wiederum Subagents starten, die weitere Subagents starten. Das wird schwer nachvollziehbar und teuer.

Diese Muster passen zu den Prinzipien aus Agentic Workflow Tool Wiring.

Wann Sie Subagents einsetzen sollten

Nutzen Sie Subagents für Aufgaben, die:

• begrenzt sind
• unabhängig ausführbar sind
• viel Zwischenarbeit erzeugen
• ein klares Ergebnis liefern

Gute Kandidaten:

• Code-Reviews
• API-Testgenerierung
• Security-Audits
• Bug-Reproduktion
• Dokumentationsprüfung
• Migration einzelner Module

Beispiel:

Überprüfe das payments-Modul auf Authentifizierungs- und Validierungsfehler.

Das ist eine gute Subagent-Aufgabe: klar begrenzt, unabhängig und review-intensiv.

Wann Sie keine Subagents einsetzen sollten

Lassen Sie Subagents weg, wenn die Aufgabe:

• sehr klein ist
• eng mit dem aktuellen Hauptkontext gekoppelt ist
• sequenziell mit der laufenden Arbeit zusammenhängt
• mehr Erklärung als Ausführung benötigt

Beispiele:

• Variable umbenennen
• Einzeiligen Bug fixen
• kleinen Import ergänzen
• gerade diskutierte Logik direkt anpassen

Faustregel:

Delegieren Sie Arbeit, die eigenständig genug ist, um sie in einem Absatz zu beschreiben, und wertvoll genug, um parallel ausgeführt zu werden.

Wenn Sie viele parallele Aufgaben orchestrieren, helfen die Muster aus dynamischen Workflows.

Häufige Fehler

Vage Beschreibungen

Wenn description nur ein Label ist, wird automatische Delegation unzuverlässig.

Statt:

description: Tests

Besser:

description: Schreibt und führt API-Tests für neue oder geänderte Endpunkte aus. Nach Endpunktänderungen verwenden.

Zu breite Subagents

Ein Subagent sollte nicht reviewen, testen, debuggen und dokumentieren. Teilen Sie Verantwortlichkeiten auf.

Alle Tools erben lassen

Wenn tools fehlt, bekommt der Subagent alles, was der Hauptagent hat. Das ist nicht immer gewünscht.

Besser:

tools: Read, Grep, Glob

Kein Verifizierungs-Gate

Ein Review ohne Tests liefert nur Einschätzung. Ein Test-Subagent, der die Suite wirklich ausführt, liefert ein belastbareres Signal.

Subagents wie das SDK behandeln

Subagents sind modellgesteuert und in der Claude-Code-Session verankert. Für deterministische, geplante Kontrollflüsse ist das Agent SDK besser geeignet.

Anthropics Artikel Building Effective Agents beschreibt den übergeordneten Punkt: Struktur um das Modell herum ist oft wirkungsvoller als ein größerer Prompt.

Häufig gestellte Fragen

Was ist ein Claude Code Subagent?

Ein Claude Code Subagent ist eine separate Agenteninstanz, an die der Hauptagent Aufgaben delegiert. Jeder Subagent hat ein eigenes Kontextfenster, einen eigenen System-Prompt und eigene Tool-Berechtigungen.

Wie erstelle ich einen Claude Code Subagenten?

Erstellen Sie eine Markdown-Datei in .claude/agents/ oder ~/.claude/agents/. Fügen Sie YAML-Frontmatter mit name, description, optionalen tools und optionalem model hinzu. Der Markdown-Body wird zum System-Prompt.

Wie entscheidet Claude, welchen Subagenten es verwendet?

Claude liest das description-Feld jedes verfügbaren Subagenten und delegiert automatisch, wenn eine Aufgabe passt. Sie können Subagents auch explizit namentlich aufrufen.

Was ist der Unterschied zwischen Subagents und dem Claude Agent SDK?

Subagents sind interaktiv und modellgesteuert innerhalb von Claude Code. Das Agent SDK ist programmatisch: Sie schreiben den Kontrollfluss selbst, z. B. für geplante oder unbeaufsichtigte Workflows.

Können Subagents parallel laufen?

Ja. Der Hauptagent kann mehrere Subagents für unabhängige Aufgaben parallel starten, z. B. Review, Tests und Dokumentation.

Wie helfen Subagents beim API-Testen?

Sie können einen Subagenten definieren, der API-Tests schreibt, gegen die OpenAPI-Spezifikation validiert und die Suite ausführt. Mit einer Plattform wie Apidog wird dieses Gate schema-bewusst und prüft Responses gegen den Vertrag.

Fazit

Claude Code Subagents lösen ein praktisches Problem: Ein Kontextfenster kann nicht alles aufnehmen. Mit Subagents geben Sie jeder Aufgabe eigenen Kontext, eigene Anweisungen und passende Tools.

Starten Sie klein:

1. code-reviewer für Reviews
2. api-test-writer für API-Tests
3. klare description-Trigger
4. minimale Tool-Rechte
5. strukturierte Pass/Fail-Ausgaben

Für API-Endpunkte lohnt sich besonders ein echter Test-Subagent. Wenn Sie Apidog einsetzen, bekommt dieses Gate ein Schema zur Validierung. Sie können Apidog herunterladen und einen Test-Subagenten den Code prüfen lassen, bevor Sie den Diff selbst lesen.