Claude Code Subagents 2026: Multi-Agent-Systeme bauen

Warum ein Agent nicht reicht

Wenn du Claude Code für einfache Aufgaben nutzt — einen Bug fixen, eine Funktion schreiben — braucht du keinen Subagenten. Aber sobald du Folgendes versuchst, stößt ein einzelner Agent an seine Grenzen:

• Parallele Tasks: Drei Code-Reviews gleichzeitig, während Tests laufen
• Spezialisierung: Ein Agent der gleichzeitig Security-Audit, Deployment und Dokumentation macht — und in keinem davon gut ist
• Kontext-Limit: Eine komplexe Codebasis, ein langer Task-History, und noch genug Platz für neue Gedanken
• Isolation: Kritische Operationen (Produktions-Deployments) sollen in einem separaten, sauberen Kontext laufen

Wie Subagents in Claude Code funktionieren

In Claude Code werden Subagents über das Task-Tool gestartet. Wenn Claude das Task-Tool aufruft, startet er eine neue, vollständig isolierte Claude-Instanz mit eigenem Kontext-Fenster. Diese Instanz arbeitet asynchron — der Orchestrator kann im Hintergrund laufen während Subagents arbeiten.

Die Subagent-Instanz hat:

• Eigenes, leeres Kontext-Fenster (kein Carry-Over aus dem Elternprozess)
• Zugriff auf dieselben Tools (Bash, Edit, Write, Glob, Grep, …)
• Den Prompt als einzigen Startkontext
• Isoliertes Dateisystem (oder Worktree, wenn konfiguriert)

Hierarchie-Architektur: CEO → HoD → Worker

Die bewährteste Multi-Agent-Architektur ist eine Hierarchie. Unsere Produktionsinfrastruktur bei Agentic Movers nutzt drei Ebenen:

Das Prinzip dahinter:

• CEO (teures Modell): Nur für Entscheidungen die wirklich Reasoning brauchen
• HoDs (mittleres Modell): Koordination, Planung, Delegation
• Worker (günstiges Modell): Repetitive Ausführung, einfache Aufgaben

Das Ergebnis: Kosten von ~€0.10/Stunde statt €10/Stunde wenn alles auf Opus läuft.

Code-Beispiele: Subagents spawnen

In Claude Code spawnt der Orchestrator Subagents über das Task-Tool im Prompt. Der Subagent-Typ bestimmt welche Tools verfügbar sind:

# Orchestrator beschreibt Task-Tool-Aufruf für Claude Code
# Claude Code spawnt dann intern die Subagenten

# Sequenziell (einer nach dem anderen)
Task(
    description="Backend API Review",
    prompt="""
    Du bist ein Senior Backend Developer. Reviewe diese API-Endpunkte:

    Repo: /home/user/project/src/api/
    Fokus: Sicherheit, Performance, Error Handling

    Gib eine priorisierte Liste mit: Kritisch / Warnung / Info
    Erstelle direkt Fixes für alle kritischen Issues.
    """
)

# Parallel (alle gleichzeitig starten)
# Claude Code startet mehrere Tasks gleichzeitig wenn der Prompt
# explizit parallele Ausführung beschreibt:

Agent(
    subagent_type="coder",
    name="frontend-worker",
    prompt="Implementiere die Login-Komponente nach dieser Spec: ...",
    run_in_background=True  # Nicht auf Ergebnis warten
)

Agent(
    subagent_type="tester",
    name="qa-worker",
    prompt="Schreibe E2E-Tests für die bestehenden Signup-Flows: ...",
    run_in_background=True
)

# Beide laufen parallel — Orchestrator arbeitet weiter
# Ergebnisse kommen via SendMessage zurück

Verfügbare Subagent-Typen

# Spezialisierte Agenten (haben nur die nötigen Tools)
subagent_type="coder"        # Bash, Read, Write, Edit, Glob, Grep
subagent_type="researcher"    # WebSearch, WebFetch, Read, Glob, Grep
subagent_type="reviewer"      # Read, Glob, Grep (kein Write)
subagent_type="tester"        # Bash, Read, Write (für Test-Ausführung)

# Generalist (alle Tools verfügbar)
subagent_type="general-purpose"  # Alle Tools + Agent-Tool (kann selbst spawnen)

3 bewährte Multi-Agent-Muster

# Orchestrator splittet:
# → Security-Agent reviewt Auth-Code
# → Performance-Agent analysiert DB-Queries
# → Style-Agent prüft Code-Konventionen
# Alle parallel, Orchestrator merged Ergebnisse

# Pipeline für Blog-Artikel:
# 1. Researcher: Recherche zu Keyword → outline.md
# 2. Writer: outline.md → draft.html
# 3. SEO-Agent: draft.html → final.html (meta, links, schema)
# 4. QA-Agent: final.html → deploy wenn OK

# Loop bis Tests grün:
while not tests_passing:
    coder = Agent(subagent_type="coder", prompt=fix_prompt)
    result = coder.result
    tests_passing = run_tests(result)
    fix_prompt = f"Tests fehlgeschlagen: {test_output}. Fix: ..."

Kommunikation zwischen Agenten

Agenten können nicht direkt miteinander kommunizieren — jeder hat seinen eigenen Kontext. Es gibt drei Kommunikationskanäle:

1. Dateisystem (einfachste Methode)

# Agent A schreibt Ergebnis
write_file("/tmp/agent-a-output.json", results)

# Agent B liest es
data = read_file("/tmp/agent-a-output.json")
# → Einfach, robust, kein Setup nötig

2. Shared Memory (für persistente Infos)

# Agenten schreiben in gemeinsame Datei
/home/claude/clawd/shared-memory/strategy_status.md

# Andere Agenten lesen beim Start
# → Gut für Status-Updates, KPIs, Cross-Agent-Kontext

3. SendMessage (für laufende Team-Feature-Agenten)

# Direktnachricht an benannten Agenten
SendMessage(to="ict-hod", content="[CEO] Bug P0 in Auth-Service — Fix bis 17:00")

# Broadcast an alle aktiven Agenten
SendMessage(type="broadcast", content="[CEO] Sprint-Update: Prio wechselt zu Revenue")

Häufige Fehler und wie du sie vermeidest

Fehler 1: Zu wenig Kontext im Subagent-Prompt

Der häufigste Fehler. Der Subagent hat keinen Zugriff auf die Eltern-Session — alles was er wissen muss, muss im Prompt stehen.

# FALSCH:
Agent(prompt="Fix den Bug wie wir besprochen haben")

# RICHTIG:
Agent(prompt="""
Fix folgenden Bug:
- Datei: /src/auth/login.ts Zeile 47
- Problem: JWT-Token wird nicht validiert wenn user_id fehlt
- Erwartetes Verhalten: 401 zurückgeben wenn user_id null ist
- Bestehende Tests: /tests/auth/login.test.ts
Erstelle einen Test der den Fix verifiziert.
""")

Fehler 2: Alle Tasks auf teurem Modell

Wenn alle Subagents Opus verwenden, explodieren die Kosten. Worker-Tasks brauchen kein starkes Reasoning — Haiku reicht für 90% der Fälle.

# Kosten-Vergleich für 8h Multi-Agent-Betrieb:
# Alle Opus:   ~€40-80/Tag
# Hierarchie:  ~€3-8/Tag
# → 10x Kostenreduktion durch Modell-Hierarchie

Fehler 3: Kein Crash-Schutz

Ein abgestürzter Subagent verliert seinen Kontext. Ohne Checkpoints ist die Arbeit weg.

# Subagents sollten nach jedem logischen Schritt committen:
# CLAUDE.md des Subagents:
## Commit-Pflicht
- Nach jeder abgeschlossenen Dateiänderung sofort committen
- Format: [worker] step-N: kurze Beschreibung
- Nie mehr als 3 Änderungen ohne Commit

Fehler 4: Endlose Rekursion

Ein Subagent der selbst Subagents spawnt die wieder Subagents spawnen — ohne Tiefenlimit. Definiere in der CLAUDE.md explizit ob ein Agent spawnen darf.

# CLAUDE.md für Worker-Ebene:
## Spawn-Verbot
Du darfst KEINE Subagents spawnen. Du bist Worker-Ebene.
Wenn eine Aufgabe zu groß ist, melde es dem Orchestrator.

Zusammenfassung

Multi-Agent-Systeme mit Claude Code skalieren dort wo ein einzelner Agent versagt. Die wichtigsten Prinzipien:

• Hierarchie: CEO (Opus) → HoDs (Sonnet) → Worker (Haiku) — spart 90% Kosten
• Expliziter Kontext: Jeder Subagent bekommt alles was er braucht im Prompt
• Parallelisierung: Unabhängige Tasks gleichzeitig ausführen — run_in_background=True
• Crash-Sicherheit: Subagents committen nach jedem Schritt
• Kommunikation: Dateisystem für Outputs, Shared-Memory für Status, SendMessage für Echtzeit