Claude Code Subagents: Der vollständige Guide für spezialisierte KI-Agenten

Wer mit Claude Code arbeitet, kennt das Problem: Komplexe Entwicklungsaufgaben lassen sich nicht einfach in einen einzigen Prompt packen. Genau hier kommen Subagents ins Spiel – spezialisierte KI-Einheiten, die innerhalb von Claude Code eigenständig agieren und gemeinsam leistungsstarke Workflows ermöglichen. Dieser Guide erklärt dir alles, was du über Claude Code Subagents wissen musst – von den Grundlagen bis zu fortgeschrittenen Orchestrierungsstrategien.

Was sind Claude Code Subagents? Grundlagen und Konzepte einfach erklärt

Ein Subagent ist in Claude Code eine eigenständige KI-Instanz, die vom Hauptagenten – dem sogenannten Orchestrator – aufgerufen wird, um eine klar abgegrenzte Aufgabe zu erledigen. Der Begriff leitet sich vom englischen “sub” (untergeordnet) und “agent” (Akteur) ab. Im Deutschen spricht man auch von Unteragenten oder spezialisierten Agenten.

Das Grundprinzip ist simpel: Anstatt eine komplexe Aufgabe einem einzigen Agenten zu übergeben, zerlegt der Orchestrator sie in Teilaufgaben und delegiert jede davon an einen passenden Spezialisten. Dieser Ansatz entspricht dem menschlichen Prinzip der Arbeitsteilung – ein Projektleiter koordiniert verschiedene Experten, jeder macht das, was er am besten kann.

Subagents in Claude Code sind dabei keine dauerhaften Prozesse, sondern temporäre Ausführungsinstanzen. Sie werden für eine konkrete Aufgabe gestartet, führen diese durch und liefern das Ergebnis zurück. Danach hören sie auf zu existieren – was sie leichtgewichtig und präzise einsetzbar macht.

Der Unterschied zwischen Orchestrator und Subagent

Der Orchestrator ist der koordinierende Hauptagent. Er analysiert die Gesamtaufgabe, entscheidet, welche Subagents benötigt werden, und fügt am Ende alle Ergebnisse zusammen. Subagents hingegen sind fokussierte Ausführungseinheiten ohne übergeordneten Überblick.

Wichtig zu verstehen: Ein Subagent kann selbst wieder als Orchestrator fungieren und weitere Subagents aufrufen. Diese hierarchische Verschachtelung ermöglicht hochgradig modulare Systeme. In der Praxis empfiehlt sich jedoch eine flache Hierarchie, um Komplexität zu vermeiden und die Aufgabenverteilung transparent zu halten.

Wie Subagents in Claude Code funktionieren: Architektur und Ablauf

Die technische Architektur hinter Claude Code Subagents basiert auf dem Agent-Tool-Pattern. Claude Code stellt dem Orchestrator ein spezielles Tool zur Verfügung – das Agent-Tool – über das er Subagents instanziieren und beauftragen kann.

Wenn der Orchestrator einen Subagent aufruft, übergibt er dabei drei zentrale Informationen: eine kurze Beschreibung der Aufgabe, einen detaillierten Prompt und optional einen spezifischen Agententyp. Der Subagent erhält diese Informationen, führt seine Aufgabe durch und gibt das Ergebnis als strukturierte Antwort zurück.

Der Datenfluss im Detail

Der Ablauf einer typischen Subagent-Interaktion lässt sich in fünf Schritte unterteilen:

1. Der Orchestrator analysiert die Gesamtaufgabe und identifiziert unabhängige Teilaufgaben.
2. Für jede Teilaufgabe ruft er das Agent-Tool mit einem spezialisierten Prompt auf.
3. Der Subagent wird instanziiert und erhält nur die für ihn relevanten Tools.
4. Der Subagent führt seine Aufgabe eigenständig durch und nutzt dabei seine zugewiesenen Tools.
5. Das Ergebnis wird an den Orchestrator zurückgegeben, der es in den Gesamtkontext integriert.

Dieser Ablauf passiert bei parallelen Subagents gleichzeitig für mehrere Teilaufgaben – was die Gesamtbearbeitungszeit erheblich reduziert.

Isolation und Kontext

Ein wesentliches Merkmal von Subagents ist ihre Kontextisolation. Jeder Subagent startet mit einem frischen Kontext – er sieht nicht den gesamten Gesprächsverlauf des Orchestrators, sondern nur das, was ihm im Prompt mitgeteilt wird. Diese Designentscheidung bringt mehrere Vorteile mit sich:

• Token-Effizienz: Jeder Subagent verbraucht nur den Kontext, den er tatsächlich benötigt.
• Fokus: Ohne irrelevante Informationen trifft der Subagent präzisere Entscheidungen.
• Skalierbarkeit: Viele Subagents können parallel laufen, ohne sich gegenseitig zu beeinflussen.

Die Kehrseite: Der Orchestrator muss sorgfältig planen, welche Informationen er jedem Subagent mitgibt. Zu wenig Kontext führt zu fehlerhaften Ergebnissen, zu viel Kontext verschwendet Tokens und verlangsamt die Verarbeitung.

Subagents erstellen: Schritt-für-Schritt-Anleitung mit Beispielen

In Claude Code gibt es zwei Hauptwege, Subagents zu definieren: über das eingebaute Agent-Tool im laufenden Gespräch oder über vorab definierte Agentendefinitionen in Markdown-Dateien – die sogenannten Skills. Beide Ansätze haben ihren Platz, abhängig davon, ob der Subagent einmalig oder wiederholt genutzt wird.

Methode 1: Subagent direkt über das Agent-Tool aufrufen

Der direkteste Weg ist der Aufruf des Agent-Tools durch den Orchestrator. Dabei wird der gesamte Subagent-Kontext inline übergeben. Hier ein Beispiel, wie ein Orchestrator einen Code-Review-Subagent aufruft:

// Orchestrator ruft Code-Review-Subagent auf
Agent({
  description: "Sicherheits-Review für Authentifizierungsmodul",
  subagent_type: "general-purpose",
  prompt: `Du bist ein erfahrener Code-Reviewer mit Fokus auf Sicherheit.

Reviewe die folgende Python-Funktion auf Sicherheitslücken,
Code-Qualität und Best Practices:

\`\`\`python
def authenticate_user(username, password):
    query = f"SELECT * FROM users WHERE username='{username}'"
    result = db.execute(query)
    if result and result['password'] == password:
        return True
    return False
\`\`\`

Gib deine Analyse als strukturierten Report zurück mit:
1. Kritische Sicherheitsprobleme
2. Code-Qualitätsprobleme
3. Konkrete Verbesserungsvorschläge mit Code-Beispielen`
});

Beachte, wie der Prompt die Rolle des Subagents definiert, ihm konkreten Input gibt und eine klare Ausgabestruktur vorgibt. Das sind die drei Säulen eines guten Subagent-Prompts – Rolle, Input und erwarteter Output.

Methode 2: Spezialisierte Skills als wiederverwendbare Agentendefinitionen

Für wiederkehrende Aufgaben ist es deutlich sinnvoller, Subagents als Skill-Dateien zu definieren. Diese werden in einem speziellen Verzeichnis abgelegt und können jederzeit wiederverwendet werden. Eine solche Skill-Definition sieht in Markdown mit YAML-Frontmatter so aus:

---
name: security-reviewer
description: Spezialisierter Sicherheits-Reviewer für Code-Audits.
             Verwende diesen Agenten für Sicherheitsanalysen von
             Authentifizierungscode, API-Endpunkten und
             Datenbankabfragen.
tools:
  - Read
  - Grep
  - Glob
  - WebSearch
---

Du bist ein erfahrener Sicherheitsexperte mit tiefem Wissen in:
- OWASP Top 10 Sicherheitslücken
- SQL-Injection und XSS-Prävention
- Authentifizierung und Autorisierung
- Kryptografischen Best Practices

## Deine Aufgabe

Analysiere den Code systematisch auf Sicherheitsprobleme.
Priorisiere nach Schweregrad (Kritisch > Hoch > Mittel > Niedrig).

## Ausgabeformat

Strukturiere deinen Report als:
1. Executive Summary (2-3 Sätze)
2. Kritische Befunde mit Code-Stellen
3. Empfehlungen mit konkreten Code-Beispielen
4. Gesamtbewertung (0-10 Sicherheitsscore)

Diese Datei wird im Verzeichnis ~/.claude/agents/ oder im projektspezifischen Verzeichnis .claude/agents/ abgelegt. Claude Code erkennt sie automatisch und stellt sie als verfügbaren Subagent-Typ bereit – ohne weiteren Konfigurationsaufwand.

Methode 3: Modellauswahl je nach Aufgabenkomplexität

Für maximale Kosteneffizienz kannst du für jeden Subagent explizit ein Modell angeben. Einfache, gut definierte Aufgaben müssen nicht das leistungsstärkste Modell verwenden:

// Einfache Übersetzungsaufgabe: günstigeres Modell einsetzen
Agent({
  description: "Technische Dokumentation Englisch nach Deutsch",
  subagent_type: "general-purpose",
  model: "haiku",
  prompt: `Du bist ein professioneller Übersetzer für technische
Dokumentation (Englisch nach Deutsch).

Übersetze den folgenden API-Dokumentationsabschnitt ins Deutsche.
Beachte dabei:
- Fachbegriffe wie "endpoint", "payload", "authentication"
  auf Englisch belassen oder etablierte deutsche Entsprechungen nutzen
- Klaren, sachlichen Stil beibehalten
- Code-Beispiele NICHT übersetzen

Zu übersetzender Text:
[CONTENT_PLACEHOLDER]

Gib NUR den übersetzten Text zurück, ohne Kommentare.`
});

Dieses Muster – schnellere Modelle für einfache Subagents, leistungsstärkere für komplexe Analysen – ist ein wesentlicher Hebel für die Skalierung von Multi-Agent-Systemen ohne explodierende Kosten.

Tool-Zuweisung und Spezialisierung: Den richtigen Expert für jede Aufgabe wählen

Eine der wichtigsten Designentscheidungen beim Einsatz von Subagents ist die Tool-Zuweisung. Welche Tools ein Subagent erhält, definiert fundamental, was er tun kann – und was nicht. Diese Beschränkung ist keine Limitierung, sondern ein gezieltes Feature.

Das Prinzip der minimalen Tool-Zuweisung besagt: Gib jedem Subagent nur genau die Tools, die er für seine spezifische Aufgabe benötigt. Ein lesender Analyst braucht keine Schreibrechte. Ein recherchierender Researcher braucht keinen Zugriff auf das Dateisystem. Dieses Prinzip zieht sich durch die gesamte Tool Assignment Philosophy von Claude Code.

Übersicht gängiger Subagent-Typen und ihre Tool-Profile

Die Tool-Auswahl hat direkten Einfluss auf die Sicherheit und Vorhersagbarkeit deiner Subagent-Workflows. Ein Read-Only-Subagent kann keine ungewollten Dateiänderungen vornehmen – das ist eine strukturelle Garantie, keine Frage des Vertrauens in das Modell.

Spezialisierung durch präzise Rollendefinitionen

Neben der Tool-Zuweisung ist die Rollendefinition der zweite Hebel für echte Spezialisierung. Vergleiche diese beiden Subagent-Prompts:

• Zu generisch: “Analysiere diesen Code und gib Feedback.”
• Gut spezialisiert: “Du bist ein Senior Python-Entwickler mit Schwerpunkt auf Performance-Optimierung. Analysiere diesen Code ausschließlich auf Engpässe, die die Ausführungszeit um mehr als 10% verbessern könnten. Ignoriere Stil-Fragen vollständig.”

Der spezialisierte Prompt reduziert den Entscheidungsraum des Subagents drastisch und führt zu konsistenteren, relevanteren Ergebnissen. Das ist die Tool Assignment Philosophy in der Praxis: Weniger ist mehr, Fokus schlägt Allgemeinheit.

Custom System Prompts für spezialisierte Subagents schreiben

Der System Prompt ist das Herzstück jedes Subagents. Er definiert Persönlichkeit, Expertise, Verhalten und Ausgabeformat. Ein gut geschriebener System Prompt macht den Unterschied zwischen einem generischen KI-Agenten und einem echten Spezialisten, der konsistent hochwertige Ergebnisse liefert.

Die vier Säulen eines effektiven System Prompts

Strukturiere jeden Subagent-Prompt entlang dieser vier Dimensionen:

• Rolle und Expertise: Wer ist dieser Agent? Welches Fachwissen bringt er mit?
• Aufgabenbereich: Was soll er tun? Was soll er explizit nicht tun?
• Arbeitsweise: Wie geht er vor? Welche Schritte folgt er dabei?
• Ausgabeformat: Wie sieht ein gutes Ergebnis aus? Welche Struktur, welcher Stil?

Hier ein vollständiges Beispiel für einen Python-Backend-Spezialisten, der als wiederverwendbarer Subagent definiert wird:

---
name: python-backend-specialist
description: Spezialist für Python Backend-Entwicklung mit FastAPI,
             SQLAlchemy und PostgreSQL. Ideal für API-Implementierungen,
             Datenbankschema-Design und Performance-Optimierungen.
tools:
  - Read
  - Write
  - Edit
  - Bash
  - Grep
  - Glob
---

# Python Backend Specialist

Du bist ein Senior Python-Backend-Entwickler mit 8+ Jahren Erfahrung.
Deine Expertise liegt in:

- FastAPI und Pydantic v2 für moderne API-Entwicklung
- SQLAlchemy 2.0 mit async/await Patterns
- PostgreSQL Performance-Optimierung und Query-Tuning
- Docker und Container-basierte Deployments
- Test-Driven Development mit pytest

## Arbeitsweise

1. Lies zuerst relevante bestehende Code-Dateien, bevor du schreibst
2. Folge dem bestehenden Code-Stil des Projekts konsequent
3. Schreibe immer Type Hints und aussagekräftige Docstrings
4. Erstelle Unit Tests für neue Funktionen
5. Validiere deine Implementierungen durch Ausführung der Tests

## Was du nicht tust

- Frontend-Code (CSS, JavaScript, HTML) schreibst du nicht
- Du änderst keine Konfigurationsdateien ohne explizite Anweisung
- Du löschst keine Dateien, nur weil sie veraltet wirken

## Ausgabeformat

Berichte am Ende strukturiert:
1. Was du implementiert hast (kurze Zusammenfassung)
2. Welche Dateien du erstellt oder geändert hast
3. Wie man die Implementierung testet
4. Eventuelle Stolpersteine oder Abhängigkeiten

Dieser Prompt ist spezifisch genug für konsistente Ergebnisse, aber flexibel genug für verschiedene Backend-Aufgaben. Das ist die Balance, die du beim Schreiben von System Prompts anstreben solltest.

Anti-Patterns beim System Prompt schreiben

Es gibt typische Fehler, die Subagent-Prompts ineffektiv machen. Widersprüchliche Anweisungen – etwa “Sei kreativ” und “Folge dem Schema strikt” – verwirren den Agenten und führen zu inkonsistenten Ergebnissen. Zu vage Rollendefinitionen erzeugen generische, austauschbare Antworten. Fehlende Ausgabeformate machen die automatische Weiterverarbeitung der Ergebnisse schwierig oder unmöglich.

Ein häufiger Fehler ist auch der Versuch, einen Subagent mit zu vielen Rollen zu belasten. Wenn dein System Prompt sagt “Du bist Entwickler, Tester, Reviewer und Dokumentationsschreiber zugleich”, hast du eigentlich vier Subagents in einen gequetscht. Teile solche Prompts lieber auf – das ist die Kernidee hinter der Aufgabenverteilung durch Subagents.

Tool-Beschränkungen gezielt einsetzen für mehr Sicherheit und Fokus

Tool-Beschränkungen sind eines der mächtigsten Features beim Subagent-Design – und werden oft unterschätzt. Indem du genau kontrollierst, welche Tools ein Subagent verwenden darf, steuerst du nicht nur seine Fähigkeiten, sondern auch seine Verhaltenstendenzen und das Risikoprofil deines gesamten Systems.

Ein Subagent ohne Schreibrechte wird automatisch fokussierter in seiner Analyse, weil er weiß, dass er nichts implementieren kann. Ein Subagent ohne Web-Zugriff verlässt sich ausschließlich auf den gegebenen Kontext. Die Grundprinzipien autonomer Software-Agenten beschreiben dieses Konzept als minimalen Fußabdruck – ein Ansatz, der in der KI-Sicherheit breit anerkannt ist.

Sicherheitsebenen durch gestaffelte Tool-Rechte

Für produktive und sichere Subagent-Systeme empfiehlt sich ein gestaffeltes Rechtemodell mit klar definierten Ebenen:

• Analyse-Ebene (Read-Only): Subagents mit Read, Grep, Glob – sie lesen, bewerten und berichten, schreiben aber nie.
• Implementierungs-Ebene: Subagents mit Write, Edit, Bash – sie können Code erstellen und Befehle ausführen.
• Integrations-Ebene: Subagents, die auf externe Systeme zugreifen – WebSearch, WebFetch, API-Calls.

Der Orchestrator koordiniert diese Ebenen. Er ruft zuerst Analyse-Subagents auf, wertet deren Ergebnisse aus, und beauftragt erst dann Implementierungs-Subagents – wenn und nur wenn die Analyse grünes Licht gibt. Das ist defensive Programmierung auf Agentenebene.

Dynamische Tool-Zuweisung je nach Kontext

Fortgeschrittene Orchestratoren passen die Tool-Zuweisung dynamisch an den Kontext an. Für eine einfache Code-Analyse reichen Read und Grep. Wenn sich herausstellt, dass Tests ausgeführt werden müssen, wird ein neuer Subagent mit Bash-Rechten eingesetzt. Dieser modulare Ansatz hält jeden Subagent minimal und das Gesamtsystem maximal sicher.

Für Teams, die Workflow-Automatisierung mit Claude Code aufbauen, ist dieses gestaffelte Rechtemodell besonders wichtig. Automatisierte Pipelines, die ohne menschliche Aufsicht laufen, sollten immer mit den minimalen erforderlichen Rechten arbeiten – nicht mit einem Generalschlüssel für alles.

Parallele Subagents: Mehrere Spezialisten gleichzeitig koordinieren

Einer der größten Leistungsvorteile von Subagents liegt in der parallelen Ausführung. Statt Aufgaben sequentiell abzuarbeiten, kann der Orchestrator mehrere Subagents gleichzeitig starten und auf alle Ergebnisse warten. Das reduziert die Gesamtbearbeitungszeit erheblich – besonders bei zeitintensiven Recherche- oder Analyseaufgaben.

Die parallele Ausführung macht besonders dann Sinn, wenn Aufgaben voneinander unabhängig sind. Das gleichzeitige Analysieren von Frontend- und Backend-Code, das parallele Recherchieren verschiedener Bibliotheken oder das simultane Generieren von Tests für mehrere Funktionen – all das sind ideale Kandidaten für parallele Subagents.

Wann parallel, wann sequentiell?

Die Entscheidung zwischen paralleler und sequentieller Aufgabenverteilung folgt einer einfachen Regel:

• Parallel: Aufgaben sind unabhängig – keine Aufgabe braucht das Ergebnis einer anderen als Input.
• Sequentiell: Aufgaben bauen aufeinander auf – Aufgabe B benötigt das Ergebnis von Aufgabe A.
• Hybrid: Gruppe 1 läuft parallel, dann startet Gruppe 2 auf Basis der Ergebnisse.

Ein praktisches Beispiel für hybride Orchestrierung: Ein Code-Refactoring-Projekt könnte so aussehen – zuerst laufen parallel ein Code-Explorer (analysiert Abhängigkeiten) und ein Researcher (sucht nach neueren API-Versionen). Dann, basierend auf beiden Ergebnissen, startet ein Code-Writer-Subagent die eigentliche Implementierung.

Technische Umsetzung der Parallelisierung

In Claude Code signalisierst du parallele Ausführung durch das gleichzeitige Aufrufen mehrerer Agent-Tools in einer einzigen Nachricht. Die Laufzeitumgebung verarbeitet diese dann tatsächlich parallel – nicht nacheinander:

// Orchestrator startet drei Subagents gleichzeitig in einer Nachricht

// Subagent 1: Frontend-Analyse
Agent({
  description: "Frontend-Codebase auf Performance analysieren",
  prompt: `Analysiere alle React-Komponenten in src/components/
auf Performance-Probleme. Liste die Top 5 Engpässe mit
Dateipfaden und konkreten Verbesserungsvorschlägen.`
});

// Subagent 2: Backend-Analyse
Agent({
  description: "Backend-API auf fehlende Validierung prüfen",
  prompt: `Analysiere alle FastAPI-Endpoints in app/routers/
auf fehlende Input-Validierung und Fehlerbehandlung.
Gib für jeden Befund den Endpoint, die Lücke und einen Fix an.`
});

// Subagent 3: Dependency-Check
Agent({
  description: "Dependencies auf Sicherheitslücken prüfen",
  prompt: `Prüfe package.json und requirements.txt auf veraltete
Dependencies mit bekannten Sicherheitslücken (CVE-Datenbank).
Sortiere nach Schweregrad: Kritisch, Hoch, Mittel.`
});

Alle drei Subagents laufen parallel. Der Orchestrator wartet auf alle Ergebnisse und fasst sie dann in einem Gesamtreport zusammen. Die Zeitersparnis gegenüber sequentieller Ausführung ist erheblich – besonders bei Aufgaben, die externe Ressourcen abfragen oder längere Analysen durchführen.

Ergebnisse zusammenführen und Konflikte auflösen

Nach der parallelen Ausführung hat der Orchestrator die Aufgabe, alle Ergebnisse zu einem kohärenten Gesamtbild zusammenzufügen. Dabei können Konflikte entstehen: Was passiert, wenn Frontend-Analyse und Backend-Analyse zu widersprüchlichen Empfehlungen kommen?

Gute Orchestratoren haben dafür explizite Priorisierungsregeln im System Prompt: Sicherheitsprobleme haben Vorrang vor Performance, kritische Bugs vor Code-Stil, bestehende Tests vor neuen Features. Diese Regeln machen die Konfliktlösung deterministisch und vorhersagbar – unabhängig davon, was die einzelnen Subagents zurückgeben.

Best Practices und häufige Fehler beim Einsatz von Subagents

Nach dem theoretischen Fundament kommen nun die praktischen Erfahrungswerte. Diese Best Practices haben sich im Einsatz echter Entwicklungsprojekte bewährt und helfen dir, häufige Fallstricke von Anfang an zu vermeiden.

Best Practice 1: Prompts isoliert testen, bevor du integrierst

Teste jeden Subagent-Prompt isoliert, bevor du ihn in ein Multi-Agent-System integrierst. Starte mit einfachen, repräsentativen Inputs und überprüfe, ob der Subagent konsistent das gewünschte Ausgabeformat liefert. Nur wenn ein Subagent alleine zuverlässig funktioniert, ist er bereit für die Integration in den Orchestrator.

Best Practice 2: Outputs klar und maschinenlesbar strukturieren

Definiere in jedem Subagent-Prompt, in welchem Format die Ausgabe erwartet wird. JSON für maschinell weiterverarbeitete Daten, Markdown für menschenlesbare Reports, strukturierter Text für gemischte Anwendungsfälle. Der Orchestrator sollte nie raten müssen, wie er ein Subagent-Ergebnis parsen soll – das ist eine häufige Quelle von Folgefehlern.

Best Practice 3: Fehlerbehandlung explizit einbauen

Was soll ein Subagent tun, wenn er seine Aufgabe nicht erfüllen kann? Explizite Fehlerbehandlungsanweisungen im System Prompt verhindern, dass Subagents bei Problemen einfach halluzinieren oder stillschweigend abbrechen. Ein guter Prompt definiert: “Wenn du X nicht finden kannst, antworte mit einem strukturierten Fehler-Objekt.”

Häufige Fehler und wie du sie vermeidest

Der häufigste Fehler ist der Mega-Prompt: Ein einziger Subagent, der alles erledigen soll. Das negiert alle Vorteile der Spezialisierung. Wenn dein Subagent-Prompt länger als eine Seite ist und mehr als zwei klar unterschiedliche Aufgabenbereiche abdeckt, ist das ein starkes Signal zum Aufteilen.

Der zweite häufige Fehler ist fehlender Kontext im Subagent-Prompt. Da Subagents keinen Zugriff auf den Orchestrator-Kontext haben, musst du alle relevanten Informationen explizit übergeben. “Implementiere die Funktion wie besprochen” ist kein gültiger Subagent-Prompt – was besprochen wurde, weiß der Subagent schlichtweg nicht.

Ein dritter Fehler ist die Vernachlässigung der Token-Kosten bei parallelen Subagents. Zehn parallel laufende Subagents erzeugen zehnfache Token-Kosten. Priorisiere Parallelisierung dort, wo die Zeitersparnis den Kostenzuwachs klar rechtfertigt – und nutze günstigere Modelle für einfachere Teilaufgaben.

Best Practice 4: Logging und Nachvollziehbarkeit einbauen

Lass deinen Orchestrator die Ergebnisse aller Subagents protokollieren. Das ermöglicht spätere Analysen: Welcher Subagent hat am längsten gebraucht? Welcher hat konsistent schlechte Ergebnisse geliefert? Diese Daten sind der Schlüssel zur iterativen Verbesserung deines Systems über mehrere Einsatzzyklen hinweg.

Gerade in automatisierten Pipelines, wie sie in einer professionellen KI-Agentur zum Einsatz kommen, ist Nachvollziehbarkeit entscheidend – sowohl für die interne Qualitätssicherung als auch für das Vertrauen der Kunden in die automatisierten Prozesse.

Best Practice 5: Menschliche Überprüfungspunkte strategisch setzen

Nicht jede Subagent-Aktion sollte vollautomatisch ablaufen. Für destruktive oder irreversible Operationen – Dateien löschen, externe APIs aufrufen, Datenbanken modifizieren – empfiehlt sich ein menschlicher Überprüfungspunkt, bevor der Orchestrator die Aktion freigibt. Gute Systeme unterscheiden klar zwischen Analyse-Aktionen (sicher automatisierbar) und Änderungs-Aktionen (erfordern Bestätigung).

Wer tiefer in die Möglichkeiten von Claude Code einsteigen möchte, findet in einem umfassenden KI-Unterstützungsangebot professionelle Begleitung – von der Architektur komplexer Multi-Agent-Systeme bis zur produktiven Implementierung in bestehende Entwicklungsworkflows.

Häufig gestellte Fragen zu Claude Code Subagents

Was ist der Unterschied zwischen einem Subagent und einem normalen Claude-Prompt?

Ein normaler Claude-Prompt läuft in einem einzelnen Konversationskontext. Ein Subagent ist eine eigenständige, isolierte Instanz mit eigenem Kontext, eigenen Tool-Rechten und einem spezifischen System Prompt. Subagents können parallel ausgeführt werden und geben ihre Ergebnisse an einen übergeordneten Orchestrator zurück – das ist mit normalen Prompts strukturell nicht möglich.

Wie viele Subagents kann ich gleichzeitig laufen lassen?

Technisch gibt es keine feste Obergrenze, praktisch limitieren Token-Kosten und Antwortzeiten den sinnvollen Bereich. Für die meisten Projekte sind 3 bis 7 parallele Subagents optimal. Bei sehr großen Codebasen können es auch mehr sein. Wichtiger als die Zahl ist, dass jeder Subagent eine klar abgegrenzte, unabhängige Aufgabe hat.

Können Subagents direkt miteinander kommunizieren?

In der Standardarchitektur von Claude Code kommunizieren Subagents nicht direkt miteinander – sie geben ihre Ergebnisse ausschließlich an den Orchestrator zurück. Der Orchestrator ist das einzige Bindeglied zwischen den Subagents. Diese Hub-and-Spoke-Architektur ist bewusst gewählt, um Komplexität zu vermeiden und die Nachvollziehbarkeit zu wahren.

Welches Modell wird für Subagents verwendet?

Standardmäßig erben Subagents das Modell des Orchestrators. Du kannst jedoch für jeden Subagent explizit ein anderes Modell angeben. Für einfache, gut definierte Aufgaben – Übersetzungen, Formatierungen, einfache Textanalysen – lohnt sich der Einsatz von Claude Haiku: deutlich schneller, günstiger und für diese Aufgaben ausreichend leistungsfähig.

Wie gehe ich mit Subagents um, die Fehler zurückgeben?

Implementiere im Orchestrator eine explizite Fehlerbehandlungsstrategie. Sinnvolle Optionen sind: Wiederholung des Subagent-Aufrufs mit angepasstem Prompt, Eskalation an einen Fallback-Subagent mit weniger strikten Anforderungen oder Markierung der Aufgabe als “requires human review”. Welche Strategie passt, hängt von der Kritikalität der jeweiligen Aufgabe ab.

Kann ich eigene Subagent-Typen definieren und wiederverwenden?

Ja, genau das ist die Stärke des Skill-Systems in Claude Code. Durch Markdown-Dateien mit YAML-Frontmatter definierst du wiederverwendbare Subagent-Profile, die sowohl projektspezifisch in .claude/agents/ als auch global in ~/.claude/agents/ gespeichert werden. Diese sind sofort verfügbar und müssen nicht jedes Mal neu definiert werden – ein echter Effizienzgewinn bei wiederkehrenden Aufgaben.

Sind Subagents sicher für den Einsatz in Produktionsumgebungen?

Mit den richtigen Sicherheitsmaßnahmen ja. Zentral sind: minimale Tool-Rechte nach dem Least-Privilege-Prinzip, menschliche Überprüfungspunkte für destruktive Aktionen, klare Logging-Strategien und eine gestaffelte Rechtestruktur. Subagents ohne Schreibrechte können per Definition keine ungewollten Änderungen vornehmen. Für produktionskritische Systeme empfiehlt sich zusätzlich eine Sandbox-Umgebung für die initiale Testphase.

Wie unterscheidet sich die Orchestrierung von Subagents von klassischen Microservices?

Microservices sind persistente, dauerhaft laufende Dienste mit eigenen Ressourcen und Schnittstellen. Subagents sind temporäre, aufgabengebundene Instanzen ohne eigenen Zustand – sie werden für eine Aufgabe gestartet und nach Abschluss beendet. Die Orchestrierung passiert zur Laufzeit durch den Hauptagenten, nicht durch statische Service-Discovery-Mechanismen. Der Ansatz ist dynamischer und flexibler, dafür ohne Persistenz zwischen Aufrufen.