Claude Code Masterkurs – KI-gestuetztes Programmieren lernen mit Anthropics Coding-Agent

Subagents Deep Dive

Level 2 | 35 Minuten

Verstehe und nutze das Subagent-System für komplexe Tasks

Lernziele

Was sind Subagents?

Subagents sind eines der mächtigsten Features von Claude Code — und gleichzeitig eines der am meisten missverstandenen. Im Kern sind Subagents eigenständige Claude-Instanzen die in ihrem eigenen, isolierten Context Window arbeiten. Stell dir vor, du hast einen Assistenten (deine Hauptsession), und dieser Assistent kann seinerseits Spezialisten beauftragen, die einzelne Aufgaben erledigen und dann nur das Ergebnis zurückmelden. Warum ist das so wertvoll? Wegen des Context Windows. Deine Hauptsession hat ein begrenztes Gedächtnis — alles was Claude liest, schreibt und analysiert, verbraucht Platz. Wenn du Claude bittest 50 Dateien zu durchsuchen um einen Bug zu finden, füllt das deinen Kontext mit Informationen die danach nicht mehr relevant sind. Ein Subagent erledigt diese Suche in seinem eigenen Kontext, findet den Bug, und meldet nur zurück: 'Der Bug ist in Zeile 42 von auth.ts, eine fehlende Null-Prüfung.' Dein Hauptkontext bleibt sauber. Claude Code unterstützt bis zu 7 parallele Subagents gleichzeitig. Das bedeutet: Du kannst sieben verschiedene Aufgaben gleichzeitig laufen lassen. Während ein Subagent Tests schreibt, kann ein anderer die Dokumentation aktualisieren, ein dritter Code-Review machen und ein vierter nach Security-Problemen suchen — alles parallel und ohne sich gegenseitig zu beeinflussen. Jeder Subagent kann ein anderes Modell nutzen. Für einfache Explorationsaufgaben wie Dateisuche reicht Haiku (schnell und günstig), für komplexe Implementierungen nutzt du Sonnet oder Opus. Diese gezielte Modellwahl spart erhebliche Kosten. Subagents werden entweder automatisch von Claude erstellt (wenn es erkennt dass eine Aufgabe von Isolation profitieren würde) oder von dir explizit angefordert. Du kannst auch Custom Subagents definieren — spezialisierte Agents mit eigenem System-Prompt, eigenen Tools und eigener Persönlichkeit. Der wichtigste Unterschied zu einfachen Prompts: Subagents kehren mit einem ZUSAMMENFASSENDEN Ergebnis zurück. Die gesamte Detailarbeit bleibt in ihrem isolierten Kontext — nur die Schlussfolgerung wird in deinen Hauptkontext übernommen.

SUBAGENT ARCHITEKTUR
━━━━━━━━━━━━━━━━━━━━

┌─────────────────────────────────────┐
│         MAIN AGENT (Claude)         │
│   - Koordiniert Tasks               │
│   - Volle Tool-Permissions          │
│   - Entscheidet wann Subagents      │
└────────────┬────────────────────────┘
             │
    ┌────────┼────────┐
    ▼        ▼        ▼
┌───────┐ ┌───────┐ ┌───────┐
│ Code  │ │ Test  │ │ Docs  │
│ Agent │ │ Agent │ │ Agent │
└───────┘ └───────┘ └───────┘
   │         │         │
   └─────────┴─────────┘
             │
      Eingeschränkte Tools
      Fokussierte Aufgabe

Built-in Subagents

Claude Code bringt mehrere eingebaute Subagent-Typen mit, die du sofort nutzen kannst ohne sie konfigurieren zu müssen. Diese Built-in Subagents sind für die häufigsten Aufgaben optimiert und decken den Großteil der typischen Entwicklungsarbeit ab. Der wichtigste Built-in Subagent ist der 'Explore' Agent. Er ist spezialisiert auf Codebase-Exploration: Dateien suchen, Patterns finden, Abhängigkeiten verstehen, Code-Strukturen analysieren. Wenn du Claude fragst 'Wie funktioniert die Authentifizierung in diesem Projekt?', nutzt es oft automatisch den Explore Agent um die relevanten Dateien zu finden und zu analysieren — ohne deinen Hauptkontext mit den Details zu füllen. Der 'General Purpose' Agent ist der Allrounder. Er kann lesen, schreiben, suchen und Befehle ausführen. Claude nutzt ihn für Aufgaben die nicht in eine spezielle Kategorie fallen — zum Beispiel wenn es parallel verschiedene Aspekte eines Problems untersuchen will. Der 'Plan' Agent wird im Plan-Modus eingesetzt. Er analysiert dein Projekt und erstellt Implementierungspläne ohne tatsächlich Code zu ändern. Besonders nützlich wenn du erst eine Strategie entwickeln willst bevor du mit der Implementierung beginnst. Wie erkennst du ob Claude einen Subagent nutzt? In der Ausgabe siehst du Hinweise wie 'Spawning subagent...' oder 'Subagent exploring...'. Am Ende meldet der Subagent seine Ergebnisse zurück, und Claude fasst sie für dich zusammen. Die Built-in Subagents nutzen standardmäßig das Sonnet-Modell, aber du kannst das über die Umgebungsvariable CLAUDE_CODE_SUBAGENT_MODEL ändern. Für Kosteneinsparungen empfiehlt sich Haiku für Explore-Tasks — es ist 15x günstiger als Opus und für reine Suche/Analyse mehr als ausreichend. Ein Praxis-Tipp: Du musst Claude nicht explizit bitten Subagents zu nutzen. Es entscheidet selbst wann Isolation sinnvoll ist. Aber du kannst es ermutigen mit Formulierungen wie 'Untersuche parallel...' oder 'Analysiere diese drei Aspekte gleichzeitig...'.

CLAUDE CODE BUILT-IN SUBAGENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📁 FILE EXPLORER
   - Navigiert durch Codebase
   - Findet relevante Dateien
   - Read-only Zugriff

🔍 CODE ANALYZER
   - Statische Code-Analyse
   - Pattern-Erkennung
   - Dependency-Analyse

🧪 TEST RUNNER
   - Führt Tests aus
   - Analysiert Failures
   - Bash + Read Tools

📝 DOCUMENTATION
   - Generiert Docs
   - Aktualisiert READMEs
   - Edit + Write Tools

🔧 REFACTORER
   - Code-Transformationen
   - Rename Operations
   - Edit-fokussiert

Subagents manuell aufrufen

Obwohl Claude Code Subagents oft automatisch einsetzt, gibt es Situationen in denen du die Delegation bewusst steuern willst. Manuelles Aufrufen gibt dir volle Kontrolle darüber wann ein Subagent gestartet wird, was er tun soll und wie die Ergebnisse zurückkommen. Der einfachste Weg einen Subagent manuell zu triggern ist über den Prompt. Formulierungen wie 'Nutze einen Subagent um...' oder 'Delegiere an einen Subagent...' machen Claude klar, dass du explizit einen isolierten Kontext willst. Du kannst auch spezifischer sein: 'Starte drei parallele Subagents — einer sucht nach Performance-Problemen, einer nach Security-Issues und einer nach Code-Duplikaten.' Für noch mehr Kontrolle gibt es das Task-Tool. In Slash Commands und Skills kannst du Subagents direkt definieren: Welche Aufgabe soll erledigt werden, welches Modell soll genutzt werden, welche Tools sind erlaubt. Das Task-Tool gibt dir eine API-artige Schnittstelle zu den Subagent-Fähigkeiten. Wann solltest du Subagents manuell aufrufen? Drei typische Szenarien: Erstens, wenn du parallel arbeiten willst — 'Analysiere gleichzeitig die Frontend-Performance und die API-Response-Zeiten'. Zweitens, wenn du eine aufwändige Exploration brauchst die deinen Hauptkontext nicht verschmutzen soll — 'Durchsuche alle 200 Testdateien nach veralteten Mocking-Patterns'. Drittens, wenn du ein günstigeres Modell für eine einfache Aufgabe nutzen willst — 'Nutze Haiku um alle TODO-Kommentare im Projekt zu finden'. Bei der Formulierung des Subagent-Auftrags gelten die gleichen Regeln wie für jeden Prompt: Sei spezifisch, gib Kontext, definiere das erwartete Ergebnis. 'Analysiere src/auth/' ist vage. 'Analysiere src/auth/ auf potenzielle SQL-Injection-Schwachstellen, prüfe besonders die Stellen wo User-Input in Datenbankqueries verwendet wird, und liste alle Fundstellen mit Dateiname, Zeile und Schweregrad auf' ist ein ausgezeichneter Subagent-Auftrag. Denk daran: Der Subagent sieht nicht was in deiner Hauptsession passiert ist. Gib ihm alle Informationen die er braucht.

# In einer Claude Session kannst du Subagents ansprechen:

> "Nutze einen Subagent um alle TODO-Kommentare zu finden"
# → Claude spawnt File Explorer Subagent

> "Lass einen Test-Agent alle failing tests analysieren"
# → Claude spawnt Test Runner Subagent

> "Starte parallele Agents für Frontend und Backend Änderungen"
# → Claude spawnt mehrere spezialisierte Subagents

# Subagent mit spezifischem Modell
> "Nutze einen Haiku-Subagent für die Dateisuche"

Custom Subagent erstellen

Für wiederkehrende Aufgaben lohnt es sich, eigene Subagent-Definitionen zu erstellen. Ein Custom Subagent ist wie ein spezialisierter Mitarbeiter den du einmal trainierst und dann immer wieder für die gleiche Art von Aufgabe einsetzen kannst — mit konsistent hoher Qualität. Ein Custom Subagent wird als Markdown-Datei im .claude/agents/ Verzeichnis definiert. Die Datei enthält den System-Prompt (die Persönlichkeit und Aufgabenbeschreibung des Agents), erlaubte Tools, das gewünschte Modell und optional weitere Konfiguration. Du rufst den Agent dann über seinen Namen auf — entweder per Slash-Command oder indem du @agentname erwähnst. Stell dir vor, du brauchst regelmäßig Security-Reviews. Statt jedes Mal aufs Neue zu erklären was geprüft werden soll, erstellst du einen security-reviewer Agent. Sein System-Prompt enthält: Welche Schwachstellen soll er suchen (SQLi, XSS, CSRF, Path Traversal), welche Dateien sind besonders kritisch (Auth, API, Datenbankzugriff), welches Bewertungsschema soll er nutzen (Critical, High, Medium, Low), und wie soll der Report strukturiert sein. Die Tool-Berechtigungen sind besonders wichtig bei Custom Subagents. Ein reiner Analyse-Agent braucht nur Read, Grep und Glob. Ein Agent der auch Fixes vornehmen soll, braucht zusätzlich Edit und Write. Ein Agent der Tests ausführen soll, braucht Bash. Vergib nur die minimal nötigen Berechtigungen — das Principle of Least Privilege gilt auch für KI-Agents. Die Modellwahl pro Agent ist ein mächtiges Feature für Kostenoptimierung. Dein Security-Review-Agent braucht Opus für die tiefe Analyse, aber ein Agent der nur Dateien nach einem Pattern durchsucht, kommt mit Haiku aus. Durch diese gezielte Modellzuweisung kannst du die Kosten um 50-80% reduzieren. Mein Workflow für neue Custom Agents: Erst die Aufgabe 2-3 Mal manuell mit normalen Prompts durchführen. Dabei notieren was gut funktioniert und was nicht. Dann den besten Prompt als System-Prompt für den Agent verwenden. Testen, verfeinern, fertig.

# .claude/agents/security-scanner/AGENT.md

---
name: security-scanner
description: Scannt Code auf Security Vulnerabilities
model: sonnet
tools:
  - Read
  - Grep
  - Bash
permissions:
  - read_files
hooks:
  on_complete: "echo 'Security scan complete'"
---

# Security Scanner Agent

Du bist ein Security-Experte. Deine Aufgabe:

## Scan-Bereiche

1. Hardcoded Secrets
   - API Keys
   - Passwords
   - Tokens

2. Injection Vulnerabilities
   - SQL Injection
   - XSS
   - Command Injection

3. Dependencies
   - npm audit
   - Known CVEs

## Output Format

`json
{
  "severity": "high|medium|low",
  "findings": [...],
  "recommendations": [...]
}
`

Multi-Agent Patterns

Die wahre Stärke von Subagents zeigt sich wenn mehrere Agents koordiniert zusammenarbeiten. Statt alles sequentiell in einer einzelnen Session zu erledigen, verteilst du die Arbeit auf spezialisierte Agents die parallel oder in einer Pipeline arbeiten. Das ist schneller, billiger und produziert bessere Ergebnisse. Das einfachste Pattern ist Fan-Out/Fan-In: Du startest mehrere Subagents gleichzeitig, jeder bearbeitet einen Aspekt des Problems, und die Ergebnisse werden am Ende zusammengeführt. Zum Beispiel bei einem Code Review: Agent 1 prüft Funktionalität und Korrektheit, Agent 2 prüft Performance, Agent 3 prüft Security, Agent 4 prüft Code Style. Jeder Agent ist auf sein Gebiet spezialisiert und arbeitet in seinem eigenen Kontext. Am Ende fasst die Hauptsession alle Ergebnisse zusammen. Das Pipeline-Pattern ist sinnvoll wenn Schritte aufeinander aufbauen: Erst analysiert ein Agent das Problem, dann plant ein zweiter Agent die Lösung basierend auf der Analyse, dann implementiert ein dritter Agent den Plan, und ein vierter Agent testet die Implementierung. Jeder Agent übergibt sein Ergebnis an den nächsten. Das Specialist-Pattern weist verschiedene Dateitypen oder Projektbereiche verschiedenen Agents zu: Ein Frontend-Agent für React-Komponenten, ein Backend-Agent für die API, ein Database-Agent für Migrationen und Queries. Jeder kennt seinen Bereich und seine Konventionen. Claude Code unterstützt bis zu 7 parallele Subagents. Bei mehr Tasks musst du sie in Batches aufteilen. Die Koordination übernimmt deine Hauptsession — sie ist der Dirigent, die Subagents sind das Orchester. Ein wichtiger Praxistipp: Multi-Agent Patterns sind mächtig, aber nicht für jede Aufgabe nötig. Wenn du eine einzelne Datei editieren willst, brauchst du keine drei Subagents. Nutze Multi-Agent Patterns für große, parallelisierbare Aufgaben: Feature-Implementierung, große Refactorings, umfassende Code Reviews.

MULTI-AGENT ORCHESTRATION PATTERNS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. PARALLEL EXECUTION
   ┌─────────────────────────┐
   │     Coordinator         │
   └───┬─────┬─────┬─────────┘
       │     │     │
       ▼     ▼     ▼
      A1    A2    A3   (parallel)
       │     │     │
       └─────┴─────┘
             │
        Merge Results

2. PIPELINE (Sequential)
   Input → A1 → A2 → A3 → Output
   Jeder Agent transformiert/erweitert

3. SUPERVISOR
   ┌──────────────┐
   │  Supervisor  │ ◄── Überwacht
   └──────────────┘
         │
   ┌─────┼─────┐
   ▼     ▼     ▼
  A1    A2    A3
   │     │     │
   └─────┴─────┘
         │
   Supervisor validiert

4. SWARM
   Agents kommunizieren untereinander
   Dezentrale Koordination
   Für sehr komplexe Tasks

Praktisches Beispiel: Feature Development

Lass uns ein realistisches Multi-Agent Szenario durchspielen: Die Implementierung eines neuen Features — User-Benachrichtigungen für eine Web-App. Dieses Beispiel zeigt, wie mehrere Subagents koordiniert zusammenarbeiten um ein Feature von der Analyse bis zum fertigen Code zu bringen. Du startest mit einem klaren Auftrag an deine Hauptsession: 'Implementiere ein Benachrichtigungssystem. User sollen bei neuen Nachrichten, Kommentaren und System-Events benachrichtigt werden. Es braucht: API-Endpoints, Database-Schema, Frontend-Komponenten und Tests.' Claude erkennt die Komplexität und orchestriert automatisch mehrere Subagents: Subagent 1 (Explore/Haiku) analysiert die bestehende Codebasis — welche Patterns werden genutzt, wo müssen die neuen Dateien hin, welche bestehenden Module werden betroffen. Subagent 2 (Plan/Sonnet) erstellt basierend auf der Analyse einen Implementierungsplan mit Dateien, API-Struktur und Datenbankschema. Nach der Planung kommen die Implementierungs-Agents: Subagent 3 erstellt das Datenbankschema und die Migrations-Datei. Subagent 4 implementiert die Backend-API Endpoints. Subagent 5 erstellt die Frontend-Komponenten. Subagent 6 schreibt Tests für alle Teile. Diese vier können teilweise parallel laufen — Backend und Frontend sind unabhängig, aber beide hängen vom Datenbankschema ab. Die Hauptsession koordiniert den gesamten Prozess: Sie wartet bis das Schema fertig ist bevor sie Backend und Frontend startet, sammelt alle Ergebnisse, prüft auf Konsistenz und erstellt am Ende einen zusammenfassenden PR. Das Ergebnis: Statt einer langen Session die deinen gesamten Kontext füllt, hast du einen sauberen, orchestrierten Workflow. Jeder Agent hat seinen klar definierten Bereich, und die Hauptsession behält den Überblick. In der Praxis dauert dieser Prozess 3-5 Minuten statt der 20-30 Minuten die du für manuelles Arbeiten bräuchtest. Und die Qualität ist konsistenter weil jeder Agent seinen vollen Kontext für seine spezielle Aufgabe hat.

FEATURE DEVELOPMENT MIT SUBAGENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Du sagst: "Implementiere User Authentication"

Claude (Coordinator):
├── Analysiert Requirements
├── Erstellt Implementation Plan
│
├── Spawnt Backend-Agent
│   └── Erstellt Auth API Routes
│   └── Implementiert JWT Logic
│
├── Spawnt Frontend-Agent (parallel)
│   └── Erstellt Login Component
│   └── Implementiert Auth Context
│
├── Spawnt Test-Agent (parallel)
│   └── Schreibt Unit Tests
│   └── Schreibt Integration Tests
│
├── Wartet auf Completion
│
├── Spawnt Review-Agent
│   └── Prüft alle Änderungen
│   └── Gibt Feedback
│
└── Merged alles & Committed
💡 Dynamic Model Selection Claude kann automatisch das beste Modell für jeden Subagent wählen: - Haiku: Einfache Tasks (Dateisuche, Formatting) - Sonnet: Standard Tasks (Code schreiben, Tests) - Opus: Komplexe Tasks (Architecture, Security Audit) Du kannst dies auch manuell steuern: "Nutze Opus für das Security Review"

Subagent Konfiguration

Subagents lassen sich bis ins Detail konfigurieren. Von der Modellwahl über Tool-Berechtigungen bis zu Timeout-Einstellungen — du hast volle Kontrolle über jeden Aspekt. Die richtige Konfiguration ist der Unterschied zwischen einem Subagent der effizient arbeitet und einem der Tokens verschwendet. Die wichtigste Konfigurationsoption ist das Modell. Standardmäßig nutzen Subagents das gleiche Modell wie die Hauptsession (meist Sonnet). Aber du kannst über die CLAUDE_CODE_SUBAGENT_MODEL Umgebungsvariable ein günstigeres Modell setzen. Für die meisten Explore-Tasks reicht Haiku völlig aus — es ist 15x günstiger als Opus und für Dateisuche und Pattern-Erkennung mehr als ausreichend. Die Tool-Berechtigungen steuern was ein Subagent tun darf. Die Grundregel: Vergib nur die Tools die der Subagent wirklich braucht. Ein Analyse-Agent braucht Read, Grep und Glob. Ein Implementierungs-Agent braucht zusätzlich Write und Edit. Ein Test-Agent braucht Bash. MCP-Tools können per Server freigeschaltet werden mit dem Muster mcp__servername__*. Timeout-Einstellungen sind besonders bei aufwändigen Aufgaben wichtig. Der Standard-Timeout kann zu kurz sein wenn ein Subagent eine große Codebasis durchsucht oder komplexe Tests ausführt. Du kannst den Timeout pro Subagent erhöhen um vorzeitige Abbrüche zu vermeiden. Für Custom Subagents gibt es zusätzliche Konfigurationsmöglichkeiten: Ein eigener System-Prompt der die Rolle und Aufgabe definiert, maximale Turns (wie viele Iterationen der Agent machen darf), und Output-Format-Vorgaben (Text, JSON, Markdown). Die Konfiguration kann auf verschiedenen Ebenen erfolgen: Global in ~/.claude/settings.json, pro Projekt in .claude/settings.json, per CLI-Flag beim Start, oder direkt in der Subagent-Definition. Projektspezifische Einstellungen überschreiben globale. Mein Praxis-Tipp: Beginne mit den Standardeinstellungen und optimiere erst wenn du Probleme siehst — zu hohe Kosten, zu langsame Ausführung oder unzureichende Ergebnisse. Dann justiere gezielt das Modell, die Tools oder den Timeout.

# .claude/agents/config.yaml

agents:
  code-writer:
    model: sonnet
    tools: [Read, Edit, Write]
    max_tokens: 8000
    temperature: 0.3

  test-runner:
    model: haiku
    tools: [Read, Bash]
    max_tokens: 4000
    timeout: 120

  architect:
    model: opus
    tools: [Read, Edit, Write, Bash]
    max_tokens: 16000
    temperature: 0.5
    context_files:
      - "ARCHITECTURE.md"
      - "src/types/**/*.ts"

Subagent Debugging

Wenn Subagents nicht die erwarteten Ergebnisse liefern oder sich unerwartet verhalten, brauchst du effektive Debug-Strategien. Die häufigsten Probleme sind: Der Subagent hat nicht genug Kontext, das falsche Modell wurde gewählt, die Berechtigungen sind zu restriktiv, oder der Context ist übergelaufen. Das erste Debug-Werkzeug ist der Verbose-Modus. Starte Claude Code mit 'claude --verbose' um detaillierte Logs über Subagent-Aktivitäten zu sehen: Wann werden Subagents gestartet, welches Modell nutzen sie, welche Tools rufen sie auf, wie viele Tokens verbrauchen sie, und was ist das Ergebnis. Das zweithäufigste Problem: Der Subagent versteht die Aufgabe nicht richtig. Denk daran — ein Subagent sieht NICHT den Kontext deiner Hauptsession. Er bekommt nur den Auftrag den du ihm gibst. Wenn der Auftrag zu vage ist ('Schau mal drüber'), kann der Subagent nicht viel damit anfangen. Sei spezifisch: Welche Dateien soll er analysieren? Was genau sucht er? In welchem Format soll das Ergebnis sein? Modell-Probleme erkennst du daran, dass der Subagent bei komplexen Aufgaben oberflächliche oder falsche Ergebnisse liefert. Wenn du das Subagent-Modell auf Haiku gesetzt hast, ist es für Exploration perfekt, aber für tiefe Code-Analyse oder Implementierung reicht es nicht. Wechsle zu Sonnet oder Opus für anspruchsvollere Aufgaben. Berechtigungsprobleme zeigen sich durch Fehlermeldungen wie 'Permission denied' oder 'Tool not available'. Prüfe ob der Subagent die nötigen Tools hat. Ein häufiger Fehler: Der Subagent braucht Bash-Zugriff um Tests auszuführen, hat aber nur Read-Berechtigung. Context-Overflow beim Subagent erkennst du an abnehmender Qualität gegen Ende seiner Arbeit. Wenn ein Subagent zu viele Dateien liest, wird sein eigener Kontext voll. Die Lösung: Teile die Aufgabe in kleinere Teile auf oder gib dem Subagent klare Grenzen ('Analysiere nur die Dateien in src/api/, nicht das gesamte Projekt').

# Verbose Mode für Subagent-Tracking
claude --verbose

# Output zeigt:
# [SUBAGENT] Spawning: code-writer (sonnet)
# [SUBAGENT] Task: "Create LoginComponent"
# [SUBAGENT] Tools: Read, Edit, Write
# [SUBAGENT] Status: Running...
# [SUBAGENT] Complete: 2.3s, 1,500 tokens

# Subagent-Logs in separater Session
/subagent-logs

# Aktive Subagents anzeigen
/subagents