Benutzerdefinierte Claude Code Subagenten erstellen (Konfigurationsanleitung)

Es gibt eine Obergrenze, die Sie bei jeder einzelnen KI-Programmiersitzung erreichen: das Kontextfenster. Wenn Sie eine Konversation mit einer ausgedehnten Refaktorisierung, drei Runden Testergebnissen und einem Code-Review überladen, verliert der Agent den Faden. Claude Code Subagents sind die Lösung. Anstatt dass ein Agent alles in einem Kontext jongliert, starten Sie fokussierte Worker, jeder mit seinem eigenen Kontextfenster, seinen eigenen Anweisungen und seinen eigenen Tool-Berechtigungen. Sie erledigen eine Aufgabe, liefern ein Ergebnis zurück und halten den Haupt-Thread sauber.

Dies ist die praktische Bauanleitung. Wie man einen benutzerdefinierten Subagenten als Konfigurationsdatei erstellt, was jedes Frontmatter-Feld bewirkt, wie Claude entscheidet, an ihn zu delegieren, und wie man ein praktisches Setup verdrahtet, bei dem ein Agent Code überprüft, während ein anderer parallel Tests schreibt. Wenn Sie zuerst den konzeptionellen Überblick wünschen, deckt unser Beitrag über was Claude Code Sub-Agents sind und warum sie wichtig sind die Grundlagen ab. Hier konzentrieren wir uns auf deren Erstellung und auf den API-Testaspekt, der einen Test-Subagenten in einen vertrauenswürdigen Verifizierungsschritt verwandelt.

TL;DR

Sie erstellen einen Claude Code Subagenten, indem Sie eine Markdown-Datei in .claude/agents/ mit YAML-Frontmatter schreiben: einen name, eine description, die Claude mitteilt, wann delegiert werden soll, eine optionale tools-Zulassungsliste und ein optionales model. Der Hauptteil der Datei wird zum System-Prompt des Subagenten. Jeder Subagent läuft in seinem eigenen Kontextfenster mit seinen eigenen Tools, sodass Sie Kontextisolation, Parallelität und Spezialisierung erhalten. Claude delegiert automatisch basierend auf der Beschreibung, oder Sie rufen einen Subagenten namentlich auf. Die offizielle Referenz sind die Claude Code Subagents Docs.

Subagents in 60 Sekunden

Ein Subagent ist eine separate Agenteninstanz, der der Haupt-Claude-Code-Agent eine Aufgabe übergibt. Der Hauptagent ist der leitende Ingenieur; Subagents sind Spezialisten, die er hinzuzieht. Der Spezialist arbeitet in seiner eigenen Konversation, mit seinem eigenen Kontextfenster und System-Prompt, und gibt dann nur das Ergebnis zurück. Drei Eigenschaften machen sie es wert, konfiguriert zu werden:

• Sein eigenes Kontextfenster. Ein Subagent beginnt frisch nur mit der ihm zugewiesenen Aufgabe, sodass der Haupt-Thread niemals mit seiner Zwischenarbeit gefüllt wird.
• Ein benutzerdefinierter System-Prompt. Sie gestalten, wie er sich verhält: ein Prüfer, der nach Sicherheitslücken sucht, ein Testautor, der Ihre Konventionen befolgt.
• Konfigurierbare Tools. Sie gewähren jedem Subagenten nur die Tools, die er benötigt, sodass ein Prüfer nicht schreiben kann und ein Test-Runner gerade genug Shell-Zugriff erhält.

Das ist die konzeptionelle Grundlage; der konzeptionelle Überblick geht tiefer auf das Warum ein. Der Rest dieses Leitfadens befasst sich mit deren Erstellung, was dem gleichen Prinzip hinter dem Claude Code Agent Harness entspricht, angewendet auf der Ebene einzelner Aufgaben.

Warum Subagents verwenden

Drei Gründe, und sie verstärken sich gegenseitig.

Kontextisolation. Eine lange Sitzung verschlechtert sich, wenn das Kontextfenster voll wird. Jede gelesene Datei, jeder Testlauf, jede Abschweifung verbraucht Budget und verwässert den Fokus. Das Delegieren einer umfangreichen Aufgabe an einen Subagenten hält die gesamte Arbeit im Kontext des Subagenten, nicht im Hauptkontext. Der Hauptagent erhält eine saubere Zusammenfassung zurück, anstatt 50.000 Token Zwischenlärm. Diese Isolation ist auch ein Kostenhebel, da Sie keinen überladenen Kontext bei jeder Runde mitschleppen. Unsere Hinweise zur Reduzierung der Agenten-Token-Kosten gehen auf die Wirtschaftlichkeit ein.

Parallelität. Unabhängige Aufgaben müssen nicht nacheinander ausgeführt werden. Ein Hauptagent kann mehrere Subagenten gleichzeitig entsenden: dieses Modul überprüfen, während jenes getestet und ein drittes dokumentiert wird. Die tatsächliche Laufzeit sinkt auf die langsamste Einzelaufgabe statt auf die Summe. Claude Codes dynamische Workflows treiben dies an seine Grenze, indem sie Hunderte paralleler Subagenten aus einer einzigen Sitzung fächern.

Spezialisierung. Ein allgemeiner Agent ist bei allem gut und bei nichts großartig. Ein Subagent mit einem prägnanten System-Prompt und den richtigen Tools ist bei einer Sache großartig. Ein Prüfer, der angewiesen wird, antagonistisch zu sein, findet mehr Fehler als ein Generalist, der den Diff überfliegt. Ein Testautor, der Ihren Assertionsstil kennt, erstellt Tests, die Sie tatsächlich behalten werden. Sie bauen ein kleines Team von Spezialisten anstelle eines überladenen Generalisten auf.

Wie man einen benutzerdefinierten Subagenten erstellt

Subagents sind einfache Markdown-Dateien. Projektbezogene Dateien legen Sie in .claude/agents/ ab und persönliche in ~/.claude/agents/. Jede Datei hat YAML-Frontmatter und einen Textkörper, der zum System-Prompt des Subagenten wird.

Hier ist ein 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.

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

Die Frontmatter-Felder:

• name — der Bezeichner, den Sie zum Aufrufen verwenden.
• description — dies ist der wichtige Punkt. Claude liest ihn, um zu entscheiden, wann automatisch delegiert werden soll. Schreiben Sie ihn als einen klaren Auslöser ("Nach dem Schreiben von Code verwenden"), nicht als vage Bezeichnung.
• tools — die Zulassungsliste. Lassen Sie sie weg, um die Tools des Hauptagenten zu erben, oder listen Sie spezifische auf, um sie einzuschränken. Ein Prüfer, der keinen Code schreiben kann, kann ihn nicht versehentlich ändern.
• model — optional ein Modell festlegen. Verwenden Sie ein günstigeres, schnelleres Modell für mechanische Subagenten und ein stärkeres für schwierige Schlussfolgerungen.

Der Körper ist der System-Prompt. Hier liegt die Spezialisierung, also schreiben Sie ihn, als würden Sie einen neuen Mitarbeiter einweisen: was zu tun ist, was priorisiert werden soll, was vermieden werden soll. Die Kombination mit einem Projekt-design.md oder AGENTS.md gibt dem Subagenten Ihre Konventionen, ohne sie in jeder Datei zu wiederholen.

Wie man Subagents aufruft

Es gibt zwei Möglichkeiten, wie ein Subagent ausgeführt wird.

Automatische Delegation. Claude liest das description-Feld jedes verfügbaren Subagenten und delegiert selbstständig, wenn eine Aufgabe passt. Wenn Sie das Bearbeiten einer Datei beendet haben, kann der Hauptagent den Diff an Ihren code-reviewer übergeben, ohne dass es gesagt werden muss, da die Beschreibung „nach dem Schreiben von Code verwenden“ besagt. Gute Beschreibungen führen zu guter Delegation.

Expliziter Aufruf. Sie können ihn auch direkt benennen: „Verwenden Sie den Subagenten code-reviewer für die Änderungen im Modul orders.“ So erzwingen Sie einen bestimmten Spezialisten, wenn Sie die Delegation nicht dem Zufall überlassen wollen.

In jedem Fall läuft der Subagent in seinem eigenen Kontext, erledigt die Arbeit und gibt ein Ergebnis an den Haupt-Thread zurück. Sie sehen den Übergang geschehen, und Sie können konfigurieren, wie viele Details angezeigt werden. Für die Verkettung von Subagenten zu deterministischen, wiederholbaren Sequenzen bieten Schrägstrich-Befehle und das SDK mehr Kontrolle als ad-hoc-Prompts; die Claude Code-Übersicht behandelt die Konfigurationsoberfläche.

Subagents vs. das Agent SDK vs. dynamische Workflows

Diese überschneiden sich, hier erfahren Sie, wann was passt.

Subagents sind die interaktive, konversationelle Option: Sie arbeiten in Claude Code und möchten einen oder zwei Spezialisten. Wenn Sie eine programmatische Schleife benötigen, die nach einem Zeitplan ohne menschliche Anwesenheit läuft, greifen Sie zum Claude Agent SDK und schreiben die Orchestrierung selbst. Wenn Sie eine gehostete Option gegen eine selbst entwickelte abwägen, erklärt unser Vergleich Managed Agents vs. Agent SDK die Kompromisse. Die drei sind weniger Konkurrenten als vielmehr Sprossen auf einer Leiter von interaktiv bis vollautomatisch.

Ein praktisches Beispiel: Paralleles Review und Testschreiben

Fügen Sie es zusammen. Nehmen wir an, Sie haben gerade den Hauptagenten einen neuen Orders-Endpunkt implementieren lassen. Sie möchten, dass er überprüft und getestet wird, und es gibt keinen Grund, warum dies nacheinander geschehen sollte.

Definieren Sie zwei Subagenten. Den oben genannten code-reviewer, plus einen 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.

1. Lesen Sie die Spezifikation und die Endpunktimplementierung.
2. Schreiben Sie Tests, die Erfolg, Validierungsfehler und Authentifizierung abdecken.
3. Bestätigen Sie Statuscodes und validieren Sie Antwortkörper anhand des Schemas.
4. Führen Sie die Suite aus und melden Sie Pass/Fail mit Gründen.

Nun entsendet der Hauptagent beide gleichzeitig: Der Prüfer liest den Diff, während der Testautor die Spezifikation liest und die Abdeckung schreibt. Zwei Spezialisten, zwei isolierte Kontexte, parallel laufend. Der Haupt-Thread bleibt sauber und erhält zwei Zusammenfassungen zurück: einen Prüfbericht und ein Testergebnis.

Dieses Testergebnis ist der Teil, der es vertrauenswürdig macht. Ein Subagent, der Ihre API-Suite ausführt, ist ein Verifizierungs-Gate, die deterministische Prüfung, die aussagt, ob der Endpunkt tatsächlich funktioniert, anstatt ob er fertig aussieht. Dies ist die Kernidee aus den Coding Agent Loops: Die eigene Zuversicht des Agenten zählt nicht, das Urteil des Gates zählt. Verbinden Sie den Test-Subagenten mit einer echten API-Testplattform, und das Feedback wird schärfer. Teams, die Apidog verwenden, weisen den Subagenten auf ein Apidog-Testszenario, sodass jede Antwort schemavalidiert wird, und leiten die Live-Endpunktaufrufe des Agenten über den Apidog AI Agent Debugger, sodass er Anfragen wie ein menschlicher Tester inspiziert. Nehmen Sie dasselbe Setup, wickeln Sie es in eine Schleife, und Sie haben den unbeaufsichtigten Workflow, den wir in autonomen Claude-Workflows, die ohne Sie laufen, erstellt haben. Laden Sie Apidog herunter, wenn Sie möchten, dass das Test-Gate von Haus aus schemabewusst ist.

Best Practices

Einige Gewohnheiten sorgen dafür, dass Subagents nützlich statt chaotisch bleiben.

• Eine Verantwortung pro Subagent. Ein Reviewer überprüft. Ein Tester testet. Bauen Sie keinen Alles-Könner-Subagenten; das ist nur der Hauptagent mit zusätzlichen Schritten.
• Schreiben Sie Beschreibungen für die Delegation. Das description-Feld entscheidet, wie Claude Ihren Subagenten aufruft. Machen Sie es zu einem klaren Auslöser, nicht zu einem Titel. "Nach dem Bearbeiten von Code zur Fehlersuche verwenden" ist besser als "Code-Reviewer".
• Gewähren Sie das Prinzip der geringsten Rechte. Listen Sie nur die Tools auf, die jeder Subagent benötigt. Ein Reviewer ohne Schreibzugriff kann nicht ändern, was er überprüft. Dies ist besonders wichtig bei unbeaufsichtigten Läufen.
• Pinpointen Sie das richtige Modell für die Aufgabe. Mechanische Subagenten können mit einem schnelleren, günstigeren Modell ausgeführt werden. Sparen Sie das stärkste Modell für Subagenten, die schwierige Schlussfolgerungen ziehen. Dies kontrolliert sowohl Geschwindigkeit als auch Kosten.
• Geben Sie strukturierte Ergebnisse zurück. Bitten Sie Subagenten, in einer konsistenten Form zu berichten (ein Urteil, eine Liste von Problemen, ein Pass/Fail). Strukturierte Ausgaben sind für den Hauptagenten und für Sie leichter zu bearbeiten.
• Vermeiden Sie zu tiefe Verschachtelungen. Subagenten, die Subagenten aufrufen, die wiederum Subagenten aufrufen, werden schwer nachvollziehbar und teuer. Halten Sie die Hierarchie flach.

Diese spiegeln die Verdrahtungsmuster wider, die wir in Agentic Workflow Tool Wiring behandelt haben, und sie gelten, egal ob Sie zwei Subagents oder zwanzig haben.

Wann man Subagents einsetzen sollte (und wann nicht)

Subagents sind ein Werkzeug, keine Standardeinstellung. Zu wissen, wann man sie weglassen sollte, hält Ihr Setup schnell und kostengünstig.

Greifen Sie zu einem Subagenten, wenn eine Aufgabe begrenzt, unabhängig und laut ist. Ein Code-Review ist begrenzt (es hat ein klares Ende), unabhängig (es benötigt keinen laufenden Zustand des Haupt-Threads) und laut (es erzeugt viel Zwischenablesung, die Sie nicht den Hauptkontext verstopfen wollen). Dasselbe gilt für das Schreiben einer Testsuite, das Reproduzieren eines Fehlers oder das Auditieren eines Moduls auf Sicherheitsprobleme. Dies sind perfekte Delegationen: isolieren Sie die Arbeit, erhalten Sie ein Urteil zurück.

Lassen Sie den Subagenten weg, wenn die Aufgabe klein, eng gekoppelt oder sequenziell mit der Hauptarbeit ist. Das Umbenennen einer Variablen, das Beheben eines Ein-Zeilen-Fehlers oder alles, bei dem der Hauptagent den benötigten Kontext bereits im Blick hat, profitiert nicht von einer Übergabe. Das Starten eines Subagenten würde dort nur Latenz und einen Kontext-Roundtrip ohne Gewinn hinzufügen. Wenn der Hauptagent die Hälfte der Konversation erklären müsste, um den Subagenten zu instruieren, behalten Sie es im Haupt-Thread.

Die Faustregel: Delegieren Sie Arbeit, die selbstständig genug ist, um sie in einem Absatz zu beschreiben, und wertvoll genug, um parallel ausgeführt zu werden. Ein neuer Endpunkt zum Überprüfen und Testen passt. Eine Tippfehlerkorrektur nicht. Wenn Sie auf viele gleichzeitige Subagenten skalieren, übernehmen die Orchestrierungsmuster in dynamischen Workflows die Führung, aber dasselbe Urteil gilt: Parallelisieren Sie das Unabhängige, halten Sie die gekoppelte Arbeit zusammen.

Häufige Fehler

• Vage Beschreibungen. Wenn die description ein Label ist, wird die automatische Delegation nicht wie erwartet ausgelöst. Schreiben Sie sie als einen Nutzungsauslöser.
• Ein überladener Subagent. Jede Aufgabe in einen einzigen Subagenten zu pressen, tötet den Vorteil der Spezialisierung. Teilen Sie nach Verantwortlichkeiten auf.
• Standardmäßige Vererbung aller Tools. Wenn tools nicht festgelegt ist, erhält ein Subagent alles, was der Hauptagent hat. Gut für vertrauenswürdige Arbeit, riskant für alles Automatisierte. Erlauben Sie bewusst nur das Nötigste.
• Kein Verifizierungs-Subagent. Ein Review-und-Build-Setup ohne Test-Gate liefert Code, der richtig aussieht und an den Rändern bricht. Fügen Sie immer einen Subagenten hinzu, der die Tests tatsächlich ausführt.
• Subagenten wie das SDK behandeln. Subagenten werden modellgesteuert und In-Session ausgelöst. Wenn Sie einen deterministischen, geplanten Kontrollfluss benötigen, ist das die Aufgabe des Agent SDK, nicht ein Haufen Subagenten.

Wenn Sie dies richtig machen, verwandeln eine Handvoll gut definierter Subagenten Claude Code von einem einzelnen vielbeschäftigten Assistenten in ein kleines, fokussiertes Team. Anthropic's Building Effective Agents untermauert den umfassenderen Fall: Struktur um das Modell herum schlägt einen größeren Prompt.

Häufig gestellte Fragen

Was ist ein Claude Code Subagent? Es ist eine separate Agenteninstanz, an die der Haupt-Claude-Code-Agent Aufgaben delegiert. Jeder Subagent hat sein eigenes Kontextfenster, einen benutzerdefinierten System-Prompt und eine konfigurierbare Reihe von Tools. Er erledigt eine fokussierte Aufgabe und gibt das Ergebnis zurück, wodurch die Hauptkonversation sauber bleibt und Sie Spezialisten parallel ausführen können.

Wie erstelle ich einen Claude Code Subagenten? Erstellen Sie eine Markdown-Datei in .claude/agents/ (Projekt) oder ~/.claude/agents/ (persönlich). Fügen Sie YAML-Frontmatter mit name, description, optionalen tools und optionalem model hinzu, und schreiben Sie dann den System-Prompt in den Hauptteil. Die Beschreibung teilt Claude mit, wann automatisch an ihn delegiert werden soll.

Wie entscheidet Claude, welchen Subagenten er verwenden soll? Es liest das description-Feld jedes verfügbaren Subagenten und delegiert automatisch, wenn eine Aufgabe passt. Sie können auch einen explizit namentlich aufrufen, z.B. „Verwende den Code-Reviewer-Subagenten.“ Klare, trigger-ähnliche Beschreibungen machen die automatische Delegation zuverlässig.

Was ist der Unterschied zwischen Subagents und dem Claude Agent SDK? Subagents sind In-Session und werden vom Modell gesteuert: Sie arbeiten in Claude Code, und es zieht Spezialisten hinzu. Das Agent SDK ist programmatisch, wo Sie den Kontrollfluss im Code für deterministische oder unbeaufsichtigte Ausführungen schreiben. Verwenden Sie Subagents für interaktive Spezialisierung, das SDK für geplante Schleifen.

Können Subagents parallel laufen? Ja. Der Hauptagent kann mehrere Subagents gleichzeitig für unabhängige Aufgaben entsenden, sodass Überprüfung, Tests und Dokumentation gleichzeitig statt nacheinander erfolgen. Für eine große Verteilung erweitern die dynamischen Workflows von Claude Code dies auf viele parallele Subagents in einer Sitzung.

Wie helfen Subagents beim API-Testen? Definieren Sie einen Subagenten, der Ihre API-Tests gegen die OpenAPI-Spezifikation schreibt und ausführt. Er wird zu einem Verifizierungs-Gate, das prüft, ob ein Endpunkt tatsächlich funktioniert, nicht nur ob er fertig aussieht. Wenn Sie ihn auf eine Plattform wie Apidog verweisen, wird das Feedback schemabewusst, sodass jede Antwort gegen den Vertrag validiert wird.

Das Fazit

Claude Code Subagents lösen das Problem, dass ein Kontextfenster nicht alles aufnehmen kann. Indem Sie jeder Aufgabe ihren eigenen Kontext, Anweisungen und Tools geben, tauschen Sie einen einzigen überladenen Agenten gegen ein kleines Team von Spezialisten, die parallel arbeiten und saubere Ergebnisse liefern. Das Setup ist nur eine Markdown-Datei, und der Gewinn ist Fokus, Geschwindigkeit und die Fähigkeit, das richtige Modell für die richtige Aufgabe einzusetzen.

Beginnen Sie mit zwei: einem Reviewer und einem Tester. Schreiben Sie präzise Beschreibungen, damit Claude eigenständig delegiert, gewähren Sie jedem nur die Tools, die er benötigt, und machen Sie den Tester zu einem echten Verifizierungs-Gate, indem Sie ihn auf Ihre API-Suite verweisen. Für alles, was Endpunkte betrifft, bietet Apidog diesem Gate ein Schema zur Überprüfung; laden Sie es herunter und lassen Sie einen Test-Subagenten Ihren Code prüfen, bevor Sie den Diff überhaupt lesen.