Claude Code Agents: So nutzt du Subagenten effektiv in deinen Projekten

Claude Code Agents revolutionieren die Art, wie Entwickler komplexe Aufgaben automatisieren. Wer mit Subagenten arbeitet, kann parallele Workflows aufsetzen, spezialisierte Teilaufgaben delegieren und ganze Entwicklungspipelines orchestrieren – alles innerhalb einer einzigen Claude-Sitzung.

Dieser Artikel zeigt dir Schritt für Schritt, wie du Claude Code Agents konfigurierst, Subagenten sinnvoll einsetzt und dabei häufige Fallstricke vermeidest. Die Beispiele sind praxisnah und direkt in deinen Projekten einsetzbar.

Was sind Claude Code Agents und Subagenten?

Claude Code ist eine KI-gestützte Entwicklungsumgebung, die direkt im Terminal läuft und Zugriff auf dein Dateisystem, deine Git-Historie und ausführbare Befehle hat. Im Kern des Systems stehen Agenten – autonome Einheiten, die Aufgaben eigenständig planen und ausführen.

Ein Subagent ist dabei ein spezialisierter Agent, der von einem übergeordneten Agenten (dem sogenannten Parent Agent) mit einer konkreten Teilaufgabe beauftragt wird. Der Parent Agent orchestriert den Ablauf, während Subagenten die eigentliche Arbeit erledigen – zum Beispiel Code schreiben, Dateien analysieren oder externe APIs abfragen.

Das Prinzip der Agenten-Hierarchie

Claude Code Agents folgen einem klaren Hierarchiemodell. Der Hauptagent in deiner Sitzung kann über das Agent-Tool beliebig viele Subagenten starten. Jeder Subagent bekommt einen eigenen Kontext, eigene Tools und eine klar definierte Aufgabe.

Das Besondere: Subagenten laufen isoliert und sehen den vollständigen Gesprächsverlauf des Parent Agents nicht. Das hält den Kontext schlank und ermöglicht parallele Ausführung ohne Interferenz zwischen den einzelnen Einheiten.

Unterschied zwischen Agent und Subagent

Das Konzept erinnert an Microservices in der Softwarearchitektur: Statt einen monolithischen Prozess zu haben, verteilst du die Arbeit auf spezialisierte Einheiten – mit allen Vorteilen in Sachen Skalierbarkeit und Wartbarkeit. Mehr zum Thema Workflow-Automatisierung mit KI findest du in unserem ausführlichen Überblick.

Schnellstart: Deinen ersten Subagenten erstellen

Der einfachste Weg, einen Subagenten zu starten, ist das Agent-Tool direkt in einer Claude-Code-Sitzung. Du definierst dabei drei Kernparameter: eine kurze Beschreibung, den eigentlichen Prompt und optional den Agent-Typ.

Ein minimales Beispiel: Du möchtest einen Subagenten beauftragen, alle TypeScript-Dateien in deinem Projekt auf veraltete API-Aufrufe zu prüfen.

Agent({
  description: "TypeScript API-Audit",
  prompt: "Durchsuche alle .ts und .tsx Dateien im Verzeichnis src/ nach veralteten fetch()-Aufrufen ohne Error-Handling. Liste alle gefundenen Stellen mit Dateiname und Zeilennummer auf. Gib nur Fundstellen aus, keine Korrekturen."
})

Dieser Aufruf startet einen allgemeinen Agenten, der die Aufgabe eigenständig abarbeitet und das Ergebnis zurückgibt. Der Parent Agent wartet standardmäßig auf die Antwort, bevor er weitermacht.

Parallele Subagenten starten

Einer der größten Vorteile von Claude Code Agents ist die Möglichkeit, mehrere Subagenten gleichzeitig laufen zu lassen. Das reduziert die Gesamtlaufzeit bei unabhängigen Aufgaben dramatisch.

// Beide Agenten in einer Nachricht starten = parallele Ausführung
Agent({
  description: "Frontend-Audit",
  prompt: "Analysiere alle React-Komponenten in src/components/ auf fehlende PropTypes oder TypeScript-Typen. Erstelle eine strukturierte Liste."
})

Agent({
  description: "Backend-Audit",
  prompt: "Durchsuche alle API-Routen in src/api/ nach fehlenden Authentifizierungsprüfungen. Gib eine priorisierte Liste aus."
})

Wichtig: Beide Agent-Aufrufe müssen in derselben Nachricht stehen, damit Claude sie parallel ausführt. Werden sie in separaten Nachrichten übergeben, laufen sie sequenziell.

Hintergrundagenten für lang laufende Aufgaben

Für Aufgaben, die mehrere Minuten dauern können – zum Beispiel das Durchsuchen eines großen Codebase oder das Ausführen umfangreicher Tests – empfiehlt sich die Hintergrundausführung.

Agent({
  description: "Vollständige Testsuiten-Analyse",
  prompt: "Führe alle Unit-Tests in /tests/ aus, analysiere fehlgeschlagene Tests und erstelle einen detaillierten Fehlerbericht mit Vorschlägen zur Behebung.",
  run_in_background: true
})

Mit run_in_background: true läuft der Subagent asynchron. Du wirst automatisch benachrichtigt, sobald er abgeschlossen hat – kein manuelles Polling erforderlich.

Subagenten konfigurieren und anpassen

Claude Code bietet verschiedene spezialisierte Agent-Typen, die für spezifische Aufgaben optimiert sind. Über den Parameter subagent_type wählst du den passenden Typ aus.

Die verfügbaren Typen unterscheiden sich vor allem im Tool-Zugriff und im Fokus ihrer Systemanweisungen. Ein general-purpose-Agent hat Zugriff auf alle Tools, während spezialisierte Typen wie Explore auf lesende Operationen beschränkt sind.

Den richtigen Agent-Typ wählen

Für einfache Codebase-Erkundungen ohne Schreibzugriff ist Explore die sicherste Wahl. Er kann keine Dateien verändern, selbst wenn der Prompt es versehentlich nahelegt.

Agent konfigurieren: Modell und Isolation

Über den model-Parameter steuerst du, welches Claude-Modell der Subagent verwendet. Das erlaubt dir, teure Modelle gezielt nur für komplexe Aufgaben einzusetzen.

Agent({
  description: "Architektur-Review",
  subagent_type: "Plan",
  model: "opus",
  prompt: "Analysiere die Gesamtarchitektur des Projekts unter /src. Identifiziere Engpässe, zirkuläre Abhängigkeiten und Verbesserungspotenziale. Erstelle einen priorisierten Maßnahmenplan."
})

Mit isolation: "worktree" kannst du einen Subagenten in einer vollständig isolierten Git-Kopie des Repositories arbeiten lassen. Änderungen betreffen nicht dein Hauptarbeitsverzeichnis, bis du sie explizit übernimmst.

Agent({
  description: "Feature-Implementierung in Isolation",
  subagent_type: "general-purpose",
  isolation: "worktree",
  prompt: "Implementiere das User-Authentication-Modul gemäß den Spezifikationen in docs/auth-spec.md. Schreibe Tests und stelle sicher, dass alle bestehenden Tests weiterhin grün sind."
})

Skills und Plugins gezielt einsetzen

Skills sind wiederverwendbare Verhaltensvorlagen, die du in Claude Code Agents integrieren kannst. Sie funktionieren ähnlich wie spezialisierte System-Prompts: Ein Skill definiert, wie ein Agent an bestimmte Aufgaben herangeht – welche Schritte er durchläuft, welche Qualitätsstandards er einhält und welche Tools er priorisiert.

Plugins erweitern das Skill-System um installierbare Pakete, die neue Fähigkeiten, MCP-Server-Anbindungen oder spezialisierte Agenten-Definitionen mitbringen. Das OpenClaude-Ökosystem auf GitHub bietet eine wachsende Sammlung von Community-Plugins für verschiedene Entwicklungsszenarien.

Eigene Skills erstellen

Ein Skill ist eine Markdown-Datei mit YAML-Frontmatter. Sie liegt im .claude/skills/-Verzeichnis deines Projekts und wird automatisch erkannt.

---
name: api-testing
description: Verwende diesen Skill zum Testen von REST-APIs mit strukturierten Reports
---

## Vorgehensweise

1. Identifiziere alle API-Endpunkte in der Codebasis
2. Erstelle für jeden Endpunkt einen Testfall mit Happy Path und Edge Cases
3. Führe Tests aus und dokumentiere Ergebnisse im Format: Status, Latenz, Payload
4. Erstelle einen Zusammenfassungsreport mit Empfehlungen

## Qualitätsstandards

- Jeder Test muss einen erwarteten Status-Code definieren
- Response-Zeiten über 500ms werden als kritisch markiert
- Authentifizierungsflows immer separat testen

Sobald ein Skill existiert, kannst du ihn in deinen Subagenten-Prompts referenzieren oder ihn über das Skill-Tool aktivieren. Claude erkennt automatisch, welche Skills für eine Aufgabe relevant sein könnten.

Plugins installieren und verwalten

Plugins werden über die Claude-Code-Konfiguration eingebunden. Ein Plugin kann MCP-Server-Definitionen, neue Skills und Hook-Konfigurationen bündeln.

# Plugin aus einem GitHub-Repository installieren
claude plugin install github:username/plugin-name

# Verfügbare Plugins auflisten
claude plugin list

# Plugin deaktivieren ohne Deinstallation
claude plugin disable plugin-name

Für Enterprise-Setups empfiehlt sich die Versionierung von Plugins über eine package.json-ähnliche Manifest-Datei in deinem Projektverzeichnis. So bleibt das Setup reproduzierbar und lässt sich im Team einheitlich nutzen.

Hooks und Security: Best Practices für den produktiven Einsatz

Hooks sind automatisch ausgelöste Aktionen, die zu bestimmten Zeitpunkten in der Agent-Lebenszeit ausgeführt werden. Sie ermöglichen es dir, Vorbedingungen zu prüfen, Logging einzurichten oder Nachbearbeitungsschritte zu automatisieren – ohne dass der Agent selbst daran denken muss.

Die wichtigsten Hook-Typen in Claude Code sind Pre-Tool-Hooks (laufen vor einem Tool-Aufruf), Post-Tool-Hooks (laufen nach einem Tool-Aufruf) und Session-Hooks (laufen beim Start oder Ende einer Sitzung).

Hooks konfigurieren

Hooks werden in der settings.json deines .claude/-Verzeichnisses definiert. Das folgende Beispiel loggt jeden Bash-Befehl, der von einem Agenten ausgeführt wird:

{
  "hooks": {
    "postToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"[AUDIT] $(date): Bash-Befehl ausgeführt\" >> ~/.claude/audit.log"
          }
        ]
      }
    ]
  }
}

Hooks können auch als Sicherheitsnetz dienen: Ein Pre-Tool-Hook kann destruktive Operationen abfangen, bevor sie ausgeführt werden. Das ist besonders in Produktionsumgebungen wichtig.

Sicherheit bei Subagenten: Das Least-Privilege-Prinzip

Jeder Subagent sollte nur die Rechte haben, die er für seine konkrete Aufgabe benötigt. Das Anthropic Model Card betont, dass KI-Systeme mit minimalen Berechtigungen operieren sollten, um unbeabsichtigte Seiteneffekte zu minimieren.

Konkret bedeutet das für Claude Code Agents:

• Explore-Typ für Analysen: Wenn ein Subagent nur lesen muss, gib ihm keinen Schreibzugriff.
• Worktree-Isolation: Lass Subagenten, die Code ändern, in isolierten Worktrees arbeiten.
• Erlaubnislisten statt Blocklisten: Definiere explizit, welche Bash-Befehle ein Agent ausführen darf.
• Audit-Logs: Nutze Post-Tool-Hooks, um alle Aktionen zu protokollieren.

Berechtigungen granular steuern

In der settings.json kannst du Erlaubnislisten für Bash-Befehle definieren. Das verhindert, dass ein Subagent unerwartete Systemoperationen ausführt.

{
  "permissions": {
    "allow": [
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(npm test*)",
      "Bash(cat *)",
      "Read(*)",
      "Glob(*)"
    ],
    "deny": [
      "Bash(rm *)",
      "Bash(git push*)",
      "Bash(curl * | bash)"
    ]
  }
}

Diese Konfiguration erlaubt lesende Git-Operationen und Testausführungen, blockiert aber destruktive Befehle und das Ausführen von heruntergeladenen Skripten – eine der häufigsten Angriffsvektoren bei automatisierten Systemen.

Häufige Fehler vermeiden und Subagenten debuggen

Auch erfahrene Entwickler machen beim ersten Einsatz von Claude Code Agents typische Fehler. Das frühzeitige Erkennen dieser Muster spart erhebliche Debugging-Zeit.

Fehler 1: Zu viel Kontext im Subagenten-Prompt

Da Subagenten keine Kenntnis vom übergeordneten Gesprächsverlauf haben, musst du ihnen alle notwendigen Informationen im Prompt mitgeben. Gleichzeitig solltest du ihn nicht überladen – ein Prompt mit 5.000 Token ist schwerer zu verarbeiten als einer mit 500 Token, der präzise auf den Punkt kommt.

Statt dem Subagenten den gesamten Projektkontext zu geben, übergib nur die für die Aufgabe relevanten Informationen: den Dateipfad, das erwartete Ausgabeformat und etwaige Einschränkungen.

Fehler 2: Sequenzielle Ausführung statt Parallelisierung

Viele Entwickler nutzen Subagenten, starten sie aber der Reihe nach in separaten Nachrichten. Der eigentliche Vorteil – parallele Ausführung – geht dabei verloren. Immer wenn zwei Aufgaben keine Abhängigkeiten voneinander haben, sollten sie in einer einzigen Nachricht als parallele Agenten gestartet werden.

Fehler 3: Fehlende Ausgabeformatierung

Ein Subagent ohne klare Ausgabe-Spezifikation liefert oft unleserliche oder schwer weiterverarbeitbare Ergebnisse. Definiere immer explizit, wie die Ausgabe aussehen soll.

// Schlecht: Keine Formatierungsvorgabe
"Analysiere alle Abhängigkeiten."

// Gut: Klares Ausgabeformat
"Analysiere alle npm-Abhängigkeiten in package.json. Ausgabe als JSON-Array mit folgendem Schema:
[{
  'name': string,
  'version': string,
  'latestVersion': string,
  'updateRequired': boolean,
  'severity': 'critical' | 'minor' | 'none'
}]"

Subagenten debuggen: Schritt für Schritt

Wenn ein Subagent unerwartet scheitert oder falsche Ergebnisse liefert, gehe systematisch vor:

1. Starte den Subagenten im Vordergrund (kein run_in_background), um die vollständige Ausgabe zu sehen.
2. Reduziere den Scope: Lass den Subagenten zunächst nur eine einzelne Datei analysieren.
3. Prüfe die Berechtigungen: Hat der Agent Zugriff auf alle benötigten Dateien?
4. Kontrolliere das Ausgabeformat: Entspricht es dem, was du weiterverarbeiten möchtest?
5. Teste den Prompt isoliert mit einem manuellen Aufruf in einer neuen Claude-Sitzung.

Für komplexe Debugging-Szenarien bietet Claude Code das TaskOutput-Tool, mit dem du die vollständige Ausgabe eines Hintergrundagenten abrufen kannst. Mehr über den systematischen Aufbau solcher KI-gestützten Prozesse erklärt unser Artikel über KI-Unterstützung in der täglichen Arbeit.

Fortgeschrittene Patterns: Agenten-Ketten und Orchestrierung

Für komplexe Entwicklungsaufgaben reicht ein einzelner Subagent oft nicht aus. Agenten-Ketten – bei denen das Ergebnis eines Agenten als Input für den nächsten dient – ermöglichen mehrstufige Automatisierungen, die manuelle Eingriffe weitgehend eliminieren.

Das Researcher-Planner-Implementer-Pattern

Ein bewährtes Pattern für Feature-Entwicklung besteht aus drei aufeinanderfolgenden Agenten:

// Schritt 1: Research-Agent
const researchResult = await Agent({
  description: "Anforderungsanalyse",
  subagent_type: "Explore",
  prompt: "Analysiere die bestehende Codebasis und dokumentiere: 1) Bestehende Auth-Mechanismen, 2) Datenbankschema für User-Tabellen, 3) Vorhandene Test-Patterns. Gib strukturiertes JSON zurück."
})

// Schritt 2: Plan-Agent (nutzt Research-Ergebnis)
const planResult = await Agent({
  description: "Implementierungsplan",
  subagent_type: "Plan",
  prompt: `Basierend auf dieser Analyse: ${researchResult}
  Erstelle einen detaillierten Implementierungsplan für OAuth2-Integration.
  Plan muss Datei-für-Datei Änderungen und Teststrategie enthalten.`
})

// Schritt 3: Implementierungs-Agent
await Agent({
  description: "OAuth2 Implementierung",
  isolation: "worktree",
  prompt: `Implementiere OAuth2 gemäß diesem Plan: ${planResult}
  Schreibe Tests, stelle sicher dass bestehende Tests grün bleiben.`
})

Self-Healing Pipelines mit Retry-Logik

Robuste Automatisierungspipelines müssen mit Fehlern umgehen können. Eine einfache Retry-Logik lässt sich durch bedingte Agenten-Aufrufe implementieren:

// Erst Tests ausführen lassen
const testResult = await Agent({
  description: "Test-Ausführung",
  prompt: "Führe npm test aus. Gib zurück: { passed: boolean, failedTests: string[] }"
})

// Bei Fehler: Debugging-Agent starten
if (!testResult.passed) {
  await Agent({
    description: "Test-Debugging",
    prompt: `Diese Tests schlagen fehl: ${testResult.failedTests.join(', ')}.
    Analysiere die Fehlerursachen und behebe sie. Führe danach die Tests erneut aus.`
  })
}

Dieses Pattern macht deine Entwicklungspipelines widerstandsfähiger gegenüber unerwarteten Zuständen – ein wesentlicher Aspekt, wenn du Claude Code Agents in CI/CD-Workflows integrierst.

Claude Code Agents in CI/CD integrieren

Claude Code Agents lassen sich auch in automatisierte Build-Pipelines einbinden. Über den --headless-Modus und die Remote-Trigger-Funktionalität können Agenten durch externe Events gestartet werden – zum Beispiel bei einem Pull-Request oder einem fehlgeschlagenen Build.

# Claude Code im Headless-Modus für CI/CD
claude --headless --prompt "Analysiere die Änderungen in diesem PR und erstelle einen Code-Review-Report. Fokus auf: Sicherheitslücken, Performance-Probleme, fehlende Tests." --output json

Die JSON-Ausgabe kann dann von CI/CD-Systemen wie GitHub Actions, GitLab CI oder Jenkins weiterverarbeitet werden – etwa um automatische Review-Kommentare zu posten oder Deployments bei kritischen Befunden zu blockieren.

FAQ: Häufige Fragen zu Claude Code Agents

Was ist der Unterschied zwischen Agent und Subagent?

Ein Agent ist jede Instanz von Claude Code, die Aufgaben eigenständig ausführt. Als Subagent bezeichnet man einen Agenten, der von einem übergeordneten Agenten (dem Parent Agent) mit einer Teilaufgabe beauftragt wird. Der Subagent hat keinen Zugriff auf den Gesprächsverlauf des Parent Agents – er bekommt nur den Inhalt seines eigenen Prompts. Diese Isolation ermöglicht parallele Ausführung und verhindert Kontextkontamination zwischen verschiedenen Aufgabensträngen.

Wie viele Subagenten kann ich gleichzeitig starten?

Claude Code setzt keine feste Obergrenze für parallele Subagenten. In der Praxis empfehlen sich 3–8 parallele Agenten pro Sitzung, abhängig von der Komplexität der Aufgaben und der verfügbaren API-Kapazität. Mehr Agenten bedeuten auch mehr Token-Verbrauch – starte deshalb nur so viele Subagenten, wie wirklich parallel sinnvoll sind.

Wie sichere ich Subagenten gegen unerwünschte Aktionen ab?

Die wichtigsten Sicherheitsmaßnahmen sind: erstens Berechtigungslisten in der settings.json (explizit erlaubte und verbotene Bash-Befehle), zweitens die Verwendung des Explore-Agent-Typs für rein lesende Operationen, drittens isolation: "worktree" für Agenten, die Code ändern, und viertens Audit-Logging über Post-Tool-Hooks. Eine Kombination dieser Maßnahmen schützt dich vor den häufigsten ungewollten Seiteneffekten.

Können Subagenten auf das Internet zugreifen?

Ja, sofern sie Zugriff auf die entsprechenden Tools haben. Tools wie WebSearch und WebFetch ermöglichen Internet-Zugriff. Ob ein Subagent diese Tools nutzen kann, hängt vom gewählten Agent-Typ ab. Der Explore-Typ hat beispielsweise keinen Web-Zugriff, während general-purpose-Agenten standardmäßig alle Tools nutzen können.

Funktionieren Skills in Subagenten?

Skills werden automatisch in Subagenten geladen, wenn sie im .claude/skills/-Verzeichnis des Projekts liegen und der Subagent den Skill explizit im Prompt referenziert. Alternativ kannst du den Skill-Inhalt direkt in den Subagenten-Prompt einfügen, wenn du absolute Kontrolle über das Verhalten haben möchtest. Das erhöht den Prompt-Umfang, ist aber deterministischer.

Wie debugge ich einen Subagenten, der nicht das erwartete Ergebnis liefert?

Starte den Subagenten zunächst im Vordergrund (ohne run_in_background) und reduziere den Scope auf eine minimale Testaufgabe. Prüfe dann schrittweise: Hat der Agent Zugriff auf die benötigten Dateien? Ist das Ausgabeformat präzise definiert? Ist der Prompt klar und ohne widersprüchliche Anweisungen? In den meisten Fällen liegt das Problem entweder an fehlenden Berechtigungen oder an einem zu vagen Prompt ohne klare Ausgabe-Spezifikation.