Claude Code Subagents: Spezialisten für komplexe Coding-Aufgaben erstellen

Ein neues Feature klingt zunächst überschaubar: eine zusätzliche API, ein Formular und ein paar Tests. Doch schon steckt Claude mitten in Datenbankmodellen, Zugriffsrechten und Fehlermeldungen. Die Unterhaltung wächst, während die eigentliche Aufgabe immer weiter in den Hintergrund rückt.

Claude Code Subagents helfen dabei, solche Aufgaben aufzuteilen. Ein Spezialist untersucht den Code, ein anderer entwickelt Testfälle, ein dritter verfolgt eine konkrete Fehlerursache. Entscheidend ist, dass jeder einen klaren Auftrag erhält und ein überprüfbares Ergebnis zurückliefert.

In dieser Anleitung erstellst du drei eigene Agent-Vorlagen. Du lernst außerdem, wie du ihre Aufgaben begrenzt und wann zusätzliche Agenten mehr Aufwand als Nutzen verursachen.

Was sind Claude Code Subagents?

Subagents sind spezialisierte KI-Assistenten, an die Claude Code Teilaufgaben delegieren kann. Sie bearbeiten diese in einem eigenen Kontextfenster und geben Ergebnisse an die Hauptunterhaltung zurück. Das hilft beispielsweise, umfangreiche Recherchen auszulagern, ohne sämtliche gelesenen Dateien in die laufende Diskussion einzubringen. Anthropic beschreibt diesen Einsatz ausdrücklich für Recherche, unabhängige Teilaufgaben und zusätzliche Reviews. ^[1]

Stell dir eine Werkstatt vor: Du besprichst den Auftrag mit einer verantwortlichen Person. Für Elektrik, Mechanik und Prüfung zieht sie passende Fachkräfte hinzu. Damit die Zusammenarbeit funktioniert, brauchen alle einen konkreten Arbeitsauftrag.

Bei KI gilt allerdings: Eine Rolle wie „Security-Experte" ist keine Qualifikation und kein Qualitätsnachweis. Ob der Agent hilfreich war, erkennst du an seinen Belegen, nachvollziehbaren Schlussfolgerungen und überprüften Ergebnissen.

Wann lohnt sich ein eigener Spezialagent?

Eine sinnvolle Faustregel für den Einstieg: Definiere einen Agenten für eine Aufgabe, die in deinem Projekt wiederholt vorkommt und ein klar beschreibbares Ergebnis hat.

Für einen Tippfehler brauchst du diese Aufteilung normalerweise nicht. Auch eng miteinander verflochtene Änderungen können in einer einzigen Unterhaltung leichter zu bearbeiten sein. Zusätzliche Agenten benötigen eigenen Kontext und verursachen weitere Verarbeitung; mehr Parallelität bedeutet daher nicht automatisch weniger Kosten. ^[1]

Subagent, Skill, MCP und CLAUDE.md: Was gehört wohin?

Diese Bausteine ergänzen sich, übernehmen aber unterschiedliche Aufgaben. Die offizielle Funktionsübersicht trennt Projektkontext, wiederverwendbare Arbeitsabläufe, externe Anbindungen und ausgelagerte Agentenarbeit. ^[2]

Wie CLAUDE.md und AGENTS.md zusammenspielen, wenn mehrere Coding-Agenten dasselbe Repository nutzen, erklärt der Artikel AGENTS.md vs. CLAUDE.md: Welche Datei braucht dein KI-Coding-Projekt? (Zum Artikel). Eine breitere Einordnung von Skills, Plugins, Apps und MCP liefert KI-Skills, Plugins, Apps und MCP: Was ist eigentlich der Unterschied? (Zum Artikel).

Für die folgenden Beispiele brauchst du keine zusätzliche MCP-Verbindung. Ein vorhandenes Projekt und eine eingerichtete Claude-Code-Umgebung genügen.

Eigenen Claude Code Subagent erstellen

1. Agent-Datei im passenden Ordner anlegen

Projektbezogene Agenten liegen unter .claude/agents/, persönliche Agenten für mehrere Projekte unter ~/.claude/agents/. Ihre Markdown-Dateien beginnen mit YAML-Metadaten; danach folgen die Arbeitsanweisungen. Pflichtfelder sind name und description. ^[3]

Die erste Vorlage speicherst du im Projekt als .claude/agents/code-reviewer.md:

---
name: code-reviewer
description: Prüft benannte Quelldateien auf konkrete Funktionsfehler und fehlende Zugriffskontrollen. Für Reviews nach Codeänderungen verwenden.
tools: Read, Grep, Glob
model: sonnet
---

Du prüfst den im Auftrag benannten Code. Antworte auf Deutsch.

Arbeitsweise:
1. Lies die genannten Dateien und die unmittelbar relevanten Aufrufer.
2. Prüfe Fehlerpfade, Eingabevalidierung und Zugriffskontrollen.
3. Bewerte ein Problem anhand eines konkreten Auslösers.
4. Trenne belegte Fehler, begründete Vermutungen und offene Fragen.

Grenzen:
- Verändere keine Dateien.
- Behaupte nicht, Tests oder Shell-Befehle ausgeführt zu haben.
- Erfinde keine Fundstellen und keine ausgeführten Angriffe.
- Prüfe keine zusätzlichen Module ohne erkennbaren Zusammenhang.

Ausgabe je Befund:
- Priorität: hoch, mittel oder niedrig
- Datei und Zeile, soweit eindeutig ermittelbar
- Auslöser und Auswirkung
- Beleg aus dem Code
- Kleinster sinnvoller Korrekturvorschlag

Wenn kein belastbarer Befund vorliegt, sage das ausdrücklich.
Nenne abschließend die Grenzen der Prüfung.

Das ist eine eigene Beispielvorlage, kein Ergebnis eines durchgeführten Projektreviews. Passe den Prüffokus an deine Anwendung an.

2. Beschreibung und Werkzeuge bewusst wählen

description beschreibt den Einsatzfall. tools begrenzt die verfügbaren Werkzeuge; ohne diese Angabe werden die verfügbaren Subagent-Werkzeuge geerbt. model: sonnet wählt den Modellalias Sonnet. ^[3]

Eine Beschreibung wie „Experte für alles" hilft bei der Aufgabenverteilung kaum. „Prüft Flask-Endpunkte auf fehlende Mandantenprüfung" beschreibt dagegen eine konkrete Verantwortung.

Für den Reviewer reichen die angegebenen Lese- und Suchwerkzeuge. Er soll Fundstellen erklären. Ein beliebiger Shell-Zugriff ist dafür im gewählten Ablauf nicht erforderlich.

3. Agenten gezielt aufrufen

Verwende in Claude Code beispielsweise diesen Auftrag und ersetze die Dateipfade durch vorhandene Dateien:

Nutze den Subagenten code-reviewer für backend/routes/orders.py
und backend/services/orders.py.

Prüfe, ob Benutzer ausschließlich Bestellungen ihres eigenen
Mandanten lesen und ändern können. Berücksichtige direkte
Aufrufer und vorhandene Tests, soweit sie dafür relevant sind.

Liefere konkrete Befunde mit Belegen. Ändere keine Dateien.

Die explizite Delegation per natürlicher Sprache wird unterstützt. Wurde das Agent-Verzeichnis erst während der laufenden Sitzung neu angelegt und der Agent nicht erkannt, starte Claude Code erneut. ^[3]

Versionshinweis: Laut aktueller Dokumentation entfällt der interaktive /agents-Erstellungsassistent ab Version 2.1.198. Die Agent-Dateien bleiben bestehen. Ältere Tutorials können deshalb eine andere Bedienung zeigen. ^[3]

Zweite Vorlage: ein Testplaner für übersehene Randfälle

Ein Testplaner ist besonders hilfreich, wenn „Tests schreiben" bisher bedeutet, nur den erfolgreichen Standardfall abzudecken.

Bei einer Bestellfunktion entstehen relevante Fragen bereits vor dem ersten Test: Was passiert bei einer unbekannten Bestellung? Darf ein fremder Mandant sie sehen? Was geschieht, wenn eine Anfrage doppelt ankommt?

Speichere diese Vorlage als .claude/agents/test-planner.md:

---
name: test-planner
description: Entwickelt aus Anforderungen und vorhandenem Code einen priorisierten Testplan. Vor Implementierungen oder zur Suche nach Testlücken verwenden.
tools: Read, Grep, Glob
model: sonnet
---

Du planst Tests für die im Auftrag genannte Funktion.
Antworte auf Deutsch.

Lies Anforderungen, Implementierung und relevante vorhandene Tests.
Wenn sich Anforderungen und Code widersprechen, markiere den Konflikt.

Berücksichtige, soweit für die Aufgabe relevant:
- Standardfall und leere Eingaben
- Ungültige Datentypen und Grenzwerte
- Fehlende Anmeldung und fremde Mandanten
- Wiederholte Anfragen und Fehler abhängiger Dienste

Liefere eine Tabelle mit:
Priorität | Testfall | Vorbereitung | Eingabe | Erwartetes Ergebnis

Kennzeichne unbekannte Sollwerte als offene Anforderung.
Erfinde weder Produktregeln noch vorhandene Testabdeckung.
Schreibe keine Dateien und führe keine Tests aus.
Empfiehl zum Schluss die drei wichtigsten zuerst umzusetzenden Tests.

Passender Auftrag:

Nutze test-planner für die Bestell-API in backend/routes/orders.py.
Die fachlichen Anforderungen stehen in docs/order-api.md.
Berücksichtige die Tests unter tests/orders/.

Erstelle höchstens zehn priorisierte Testfälle. Markiere, welche
Anforderungen nicht eindeutig genug für einen Test sind.

Die Begrenzung auf zehn Fälle zwingt zur Auswahl. Für den Einstieg ist ein kurzer Plan mit wichtigen Fehlerfällen meist besser zu beurteilen als eine lange Liste ähnlicher Varianten.

Dritte Vorlage: ein Debugger mit Schreibrechten

Ein Debugger soll in diesem Beispiel einen Fehler reproduzieren und beheben dürfen. Damit bekommt er eine andere Verantwortung als die beiden lesenden Agenten.

Speichere die Vorlage als .claude/agents/focused-debugger.md:

---
name: focused-debugger
description: Reproduziert einen konkret beschriebenen Fehler in einer lokalen Entwicklungsumgebung und erstellt einen kleinen, überprüfbaren Fix.
tools: Read, Grep, Glob, Bash, Edit, Write
model: sonnet
permissionMode: default
---

Du bearbeitest genau den beschriebenen Fehler. Antworte auf Deutsch.

Ablauf:
1. Lies Reproduktionsschritte, relevante Dateien und Testanweisungen.
2. Prüfe vor Befehlen, welche Umgebung und Daten sie betreffen.
3. Reproduziere den Fehler möglichst mit einem gezielten lokalen Test.
4. Belege die Ursache und ändere nur den erforderlichen Code.
5. Prüfe den Fix und direkt betroffene Nachbarfunktionen.

Grenzen:
- Keine Produktionszugriffe, Deployments, Pushes oder Datenmigrationen.
- Keine Installation neuer Abhängigkeiten ohne Rücksprache.
- Keine fremden Änderungen zurücksetzen.
- Keine Tests abschwächen, um ein grünes Ergebnis zu erzeugen.
- Keine Zugangsdaten ausgeben.
- Bei unklarer Testumgebung vor der Ausführung nachfragen.

Abschlussbericht:
- Ursache und Beleg
- Geänderte Dateien und Begründung
- Tatsächlich ausgeführte Befehle mit Ergebnis
- Nicht ausgeführte Prüfungen mit Grund
- Verbleibende Unsicherheiten

Beachte die Grenze dieser Vorlage: Die Arbeitsanweisungen beschreiben gewünschtes Verhalten. Technisch durchgesetzte Zugriffsrechte entstehen durch Berechtigungsregeln und die Umgebung. Claude Code unterscheidet ausdrücklich zwischen Prompt-Anweisungen und durchgesetzten Permissions. Über /permissions kannst du die Regeln prüfen. ^[4]

Bash ermöglicht Programmausführung und damit potenziell auch Dateiänderungen oder Netzwerkzugriffe. Auch ein Testskript kann Daten löschen oder externe Dienste aufrufen. Verwende daher eine überprüfte lokale Testumgebung und passende Regeln. permissionMode: default ersetzt diese Prüfung nicht; vorhandene Freigaben bleiben relevant. ^[4] Wie du Zugangsdaten und API-Keys zusätzlich absicherst, zeigt Secrets und API-Keys bei KI-Agenten schützen: .env, Vault und Berechtigungen richtig einsetzen (Zum Artikel).

Die Beispiele wurden anhand der Dokumentation erstellt, aber hier nicht in einer Claude-Code-Installation ausgeführt.

So setzt du die drei Spezialisten gemeinsam ein

Nehmen wir einen beispielhaften Fehler: Beim Ändern einer Bestellung wird deren Existenz geprüft, die Zuordnung zum angemeldeten Mandanten ist jedoch unklar.

Ein sinnvoller Auftrag an Claude Code könnte so aussehen:

Untersuche die Mandantenprüfung beim Ändern von Bestellungen.

Phase 1:
Lass code-reviewer die Zugriffskontrolle prüfen und test-planner
aus Anforderungen und vorhandenen Tests die relevanten Fälle ableiten.
Die beiden lesenden Aufgaben dürfen parallel laufen.
Übergebe beiden die relevanten Dateipfade und Anforderungen.

Phase 2:
Fasse die Ergebnisse zusammen. Wenn ein konkreter Fehler belegt ist,
übergib focused-debugger den Befund und die passenden Testfälle.
Er soll den Fehler in der lokalen Testumgebung reproduzieren und beheben.

Phase 3:
Lass code-reviewer die geänderten Dateien erneut prüfen.
Berichte, welche Tests tatsächlich gelaufen sind und was offenbleibt.

Hier können die ersten beiden Untersuchungen unabhängig voneinander beginnen. Der Debugger benötigt dagegen die Befunde. Die abschließende Prüfung benötigt den fertigen Fix. Diese Reihenfolge ist ein Gestaltungsvorschlag für den Beispielprozess, keine automatisch garantierte Pipeline.

Anthropic empfiehlt grundsätzlich, komplexe Änderungen zunächst zu untersuchen und zu planen sowie Ergebnisse durch Tests oder andere konkrete Nachweise zu verifizieren. ^[5]

Definiere vorher, wann die Aufgabe fertig ist

Für diesen Beispielfehler könnte deine Abnahme so aussehen:

• Ein gezielter Test zeigt den Fehler vor der Korrektur.
• Nach der Korrektur wird die unzulässige Anfrage abgewiesen.
• Ein berechtigter Zugriff funktioniert weiterhin.
• Der Diff enthält nur nachvollziehbare Änderungen zur Aufgabe.
• Fehlende Prüfungen sind ausdrücklich benannt.

„Der Agent sagt, es funktioniert" erfüllt diese Kriterien noch nicht. Ein Abschlussbericht soll dir ermöglichen, die Korrektur zu beurteilen.

Eigener Kontext schützt nicht vor Dateikonflikten

Wenn mehrere Agenten schreiben dürfen, solltest du ihre Arbeitsbereiche bewusst organisieren. Zwei konkurrierende Änderungen an derselben Funktion sind schwerer zusammenzuführen als zwei unabhängige Analysen.

Claude Code unterstützt dafür Git-Worktrees: getrennte Arbeitsverzeichnisse mit eigenen Branches, aber gemeinsamer Repository-Historie. Subagents können mit Worktree-Isolation arbeiten. ^[6]

Für eine entsprechende Agent-Konfiguration gibt es dieses zusätzliche Feld:

isolation: worktree

Ein Worktree trennt Dateien. Daraus folgt für deine Projektplanung jedoch keine Trennung einer gemeinsam verwendeten Testdatenbank oder externer Dienste. Auch das Zusammenführen und Prüfen der Änderungen bleibt eine eigene Aufgabe. Plane dafür klare Zuständigkeiten ein.

Für den ersten Versuch reicht ein einzelner schreibender Debugger. Ergänze parallele Implementierungen erst, wenn der Nutzen im konkreten Projekt erkennbar ist.

Häufige Fehler beim Erstellen eigener Subagents

Die Rolle beschreibt eine Persönlichkeit statt einer Aufgabe

„Du bist der beste Entwickler der Welt" legt weder den Prüfbereich noch das Ergebnis fest. Schreibe stattdessen, welche Dateien relevant sind, welche Frage beantwortet werden soll und welche Nachweise du erwartest.

Jeder Agent bekommt denselben Großauftrag

Wenn drei Agenten jeweils die gesamte Anwendung „optimieren" sollen, erzeugst du Überschneidungen. Trenne beispielsweise Zugriffskontrolle, Testfälle und die Umsetzung eines belegten Fehlers.

Ein Review enthält nur allgemeine Ratschläge

„Verbessere die Sicherheit" ist noch kein bearbeitbarer Befund. Fordere einen Auslöser, eine konkrete Fundstelle und die erwartete Auswirkung. Kann der Reviewer das nicht liefern, soll er den Punkt als offene Frage kennzeichnen.

Zu viel Kontext wird ungefiltert weitergereicht

Gib einem Spezialisten die relevanten Dateien und Anforderungen. Ein vollständiger Chatverlauf voller verworfener Ideen kann den aktuellen Auftrag unnötig verdecken. Präzise Dateireferenzen und konkrete Erfolgskriterien entsprechen auch Anthropics Empfehlungen für wirksame Coding-Aufträge. ^[5]

Agent-Dateien werden ungeprüft übernommen

Lies bei fremden Vorlagen nicht nur die Rollenbeschreibung, sondern auch Werkzeuge und weitere Konfiguration. Prüfe besonders, ob sie zu deinem Projekt und zu den erlaubten Aktionen passen.

Häufige Fragen zu Claude Code Subagents

Muss ich sofort mehrere Agenten erstellen?

Nein. Beginne mit dem Reviewer und prüfe an einer überschaubaren Änderung, ob seine Befunde dir helfen. Ergänze weitere Rollen für wiederkehrende Aufgaben.

Können Subagents selbst Dateien verändern?

Ja, wenn ihre Werkzeuge und die geltenden Berechtigungen es zulassen. Die ersten beiden Vorlagen sind auf Lesen und Suchen begrenzt. Der Debugger erhält zusätzlich Schreib- und Ausführungswerkzeuge. ^[3][4]

Sind mehrere Agenten automatisch günstiger?

Nein. Zusätzliche Agenten verursachen zusätzlichen Aufwand. Ob sich die Aufteilung lohnt, hängt von Aufgabe, Kontextbedarf und tatsächlich erzieltem Nutzen ab. ^[1]

Warum findet Claude meinen neuen Agenten nicht?

Prüfe Speicherort, YAML und Agentenname. Falls du den Agent-Ordner erst nach Sitzungsbeginn angelegt hast, starte Claude Code erneut. ^[3]

Was ist der beste erste Einsatzfall?

Lass eine kleine, bereits verstandene Änderung prüfen. So kannst du schnell erkennen, ob der Agent relevante Probleme findet, bekannte Anforderungen berücksichtigt und Unsicherheiten ehrlich benennt.

Dein erster sinnvoller Einsatz

Lege code-reviewer.md an und wähle eine überschaubare Funktion. Formuliere eine konkrete Frage wie: „Können Benutzer Daten eines fremden Mandanten ändern?" Beurteile anschließend die Belege und den Korrekturvorschlag.

Damit hast du einen praktischen Maßstab für weitere Spezialisten: Jeder neue Agent sollte eine wiederkehrende Aufgabe übernehmen und ein Ergebnis liefern, das du leichter prüfen kannst. Wie sich Claude Code dabei gegenüber anderen Coding-Agenten schlägt, vergleicht Claude Code vs. OpenAI Codex: Welcher Coding-Agent ist besser? (Zum Artikel).

Weitere verständliche Anleitungen rund um KI, Coding und Systemadministration findest du im KI-Buster Blog.

Quellen und weiterführende Dokumentation

Redaktioneller Stand: 2. Oktober 2026. Primärquellen: [1] Anthropic: How and when to use subagents in Claude Code – Einsatzfälle und Aufwand; bei abweichenden Bedienhinweisen gilt die aktuelle Referenz unter [3]. [2] Claude Code: Extend Claude Code – Abgrenzung von Projektanweisungen, Skills, Subagents, MCP und Hooks. [3] Claude Code: Create custom subagents – Dateiformat, Konfiguration, Aufruf und versionsabhängige Bedienung. [4] Claude Code: Configure permissions – Durchgesetzte Zugriffsregeln und Berechtigungsmodi. [5] Claude Code: Best practices – Arbeitsaufträge, Planung und überprüfbare Ergebnisse. [6] Claude Code: Run parallel sessions with worktrees – Getrennte Arbeitsverzeichnisse und Subagent-Isolation. Die Agent-Prompts und das Bestell-API-Szenario sind eigene Beispiele; es werden keine selbst gemessenen Produktivitätsgewinne oder durchgeführten Projekttests behauptet.