Claude Code Subagenten — Rollenteilung über das Task-Tool

Die Stärke von Claude Code, die die meisten Nutzenden als Letztes erschließen, sind Subagenten (das Task-Tool). Wer alles in einer einzigen Sitzung abwickelt, füllt den Kontext des Hauptagenten schnell auf, und große Aufgaben stauen sich in einem einzigen Thread. Behandelt man Subagenten als Abstraktionsschicht — Explorer sucht und fasst zusammen, Reviewer sieht nur den Diff —, bewältigt man in derselben Zeit doppelt so viel Arbeit.

Dieser Leitfaden richtet sich an Claude Code 1.x und baut den täglichen Workflow eine Ebene über Claude Code einrichten und Hooks hinaus aus.

TL;DR

1. Hauptagent übernimmt direkte Bearbeitungen + Builds/Tests — kurze, schnelle Arbeitsschritte
2. Explorer-Subagent — „Wo ist X in dieser Codebase?" Sucht und fasst zusammen; zieht keine umfangreichen Ergebnisse in den Hauptagenten
3. Plan-Subagent — Liefert ausschließlich einen Schritt-für-Schritt-Plan für größere Änderungen zurück
4. Reviewer-Subagent — Zweitmeinung-Review des Diffs des Hauptagenten
5. Spezialist — Domänenspezifische Subagenten wie claude-api / security-review

Kernprinzip: Kontext-Schutz + Parallelismus.

Voraussetzungen

• Claude Code 1.x installiert — Claude Code einrichten
• Projektgrundlagen vorhanden: CLAUDE.md + .claude/settings.json
• (Optional) Hooks-Grundlage — einige Hooks des Hauptagenten gelten auch für Subagenten

1. Task-Tool-Aufrufmodell

Das Task-Tool startet innerhalb von Claude Code einen neuen Agenten mit einem einzigen Prompt. Der Subagent besitzt ein eigenes Kontextfenster — er teilt keine Nachrichten mit dem Hauptagenten, und nur die finale Ergebnisnachricht wird zurückgegeben.

Hauptagent
   │
   ├─ Task("Explore", "Token-Validierungslogik in src/auth/ finden; nur Funktionsnamen + Dateipfade zurückgeben")
   │   ↓ (separater Kontext, bis zu 100k Token frei)
   │   ↑ "validateToken: src/auth/verify.ts:42"  ← Hauptagent empfängt nur das Ergebnis
   │
   └─ Task("Reviewer", "Diff des letzten Commits auf Sicherheitsprobleme scannen")
       ↓
       ↑ "1 Befund: src/api/user.ts:88 — mögliche SQL-Injektion"

Dem Kontext des Hauptagenten wird nur eine finale Zusammenfassung hinzugefügt. Der Subagent kann 200 Dateien gelesen haben; der Hauptagent empfängt eine einzeilige Information.

2. Vier Kernmuster

2.1 Explorer — Große Suchergebnisse isolieren

Das häufigste Muster: „Wo ist X definiert?"-Fragen an einen Subagenten delegieren.

"An einen Explorer-Subagenten delegieren:
'Die useAuth-Hook-Definition + alle Verwendungen in src/ finden. Zurückgeben:
- Def: Datei:Zeile
- Verwendungen: Datei:Zeile × alle
Auf 30 Zeilen begrenzen. Keine Code-Rümpfe einfügen.'"

Der Hauptagent erhält 30 Zeilen. Direkt ausgeführt, hätte dieselbe Suche via grep und Mehrfachdatei-Lesungen 5–20k Token verbraucht.

Wann einsetzen:

• Einstieg in eine neue Codebase
• „Wo ist dieses Feature implementiert?"
• „Wie nutzen wir diese Bibliothek?"
• Abhängigkeits-Auswirkungsanalyse

Ungünstige Fälle:

• Kleine Suchen — der Hauptagent kann ein grep in einer Zeile ausführen
• Ergebnisse, die vollständig gelesen werden müssen — direktes Lesen ist schneller

2.2 Plan — Schritt-für-Schritt nur für große Änderungen

Bei 5+ Datei-Änderungen, neuen Modulen oder Architekturänderungen führt ein Plan-Subagent Recherche und Abwägungsanalyse durch und liefert ausschließlich den Plan zurück.

"An einen Plan-Subagenten delegieren:
'Nur einen Schritt-für-Schritt-Ausführungsplan zurückgeben.
Anforderung: Seeds von ~7/Kategorie auf 10 erweitern.
Einschränkungen: Build unter 1 Min, verify:assets 100%.
Ausgabe: Kategorie · Thema · hat-Asset · geschätzte-Zeilen-Tabelle + Schreibreihenfolge.
Keinen Code schreiben.'"

Der Hauptagent empfängt den Plan; die Ausführung findet im Hauptagenten statt oder wird auf weitere Subagenten verteilt.

2.3 Reviewer — Zweitmeinung

Ein Agent mit eigenem Kontext reviewt den Diff des Hauptagenten. Frische Augen erfassen, was dem Hauptagenten entgeht.

"An einen Reviewer-Subagenten delegieren:
'Den Diff von Commit 4d2f0 unter dem Sicherheitswinkel reviewen.
Konkret: SQL-Injektion, XSS, hardkodierte Secrets, Race Conditions.
Ausgabe: N Befunde + Datei:Zeile + 1-Zeilen-Notiz jeweils. Oder „sauber".'"

Hauptagenten übersehen Probleme im eigenen Code, weil sie ihn kennen. Der Reviewer betrachtet denselben Sachverhalt aus einer anderen Perspektive.

2.4 Spezialist — Domänenspezifisch

Subagenten für spezifische Bereiche (claude-api, security-review, code-reviewer, build-validator usw.) mit tiefem Domänenwissen und bereichsgerechten Ausgabeformaten.

"An security-review delegieren:
'Umfassende Sicherheitsbewertung der Änderungen des aktuellen Branches.
Umfang: Authn / Authz / Eingabevalidierung / Secrets / Sessions / CSRF.'"

Spezialisten besitzen in der Regel System-Prompts, die auf ihren Bereich zugeschnitten sind — das steigert die Ergebnisqualität spürbar.

3. Den Delegations-Prompt schreiben

Der Subagent sieht den Kontext des Hauptagenten nicht. Der Prompt muss daher vollständig eigenständig sein.

Guter Prompt

"Diese Muster in src/ finden:
- `fetch(...)`-Aufrufe, bei denen baseURL hardkodiert ist
- Ergebnis: Datei:Zeile + 1 Code-Zeile + erschlossene baseURL-Domain
- Limit 30; wenn mehr, '+N weitere' anhängen
- Keine Code-Rümpfe anhängen — nur die Zeile"

Schlechte Prompts

"Das fetch-Ding von vorhin reviewen"   ← kein Kontext, zu vage

"Alle fetch-Aufrufe finden"   ← kein Ausgabeformat, Risiko einer riesigen Ausgabe

Checkliste für den Prompt-Autor

• Ziel — was soll in Erfahrung gebracht werden
• Umfang — wo (Verzeichnis / Datei / Bereich)
• Ausgabeformat — Tabelle / Zeilen-Level / Zusammenfassungslänge
• Ausschlüsse — was NICHT zurückgeben (Code-Rümpfe, große Diffs)
• Stoppbedingung — N Befunde, dann anhalten
• Unbekannter Fall — „Wenn du es nicht weißt, sag es; kein Raten"

4. Parallele Ausführung — Unabhängige Delegationen zusammen senden

Voneinander unabhängige Arbeitsschritte können in einer einzigen Antwort mit mehreren Task-Aufrufen gebündelt werden. Claude Code startet sie parallel.

"Drei Delegationen auf einmal:
1) Explorer — zusammenfassen, wo die Auth-Dateien liegen
2) Explorer — DB-Migrationshistorie zusammenfassen
3) Reviewer — Sicherheits-Review der letzten 5 Commits

Nach Empfang aller drei eine integrierte Analyse durchführen."

Der Hauptagent erhält alle drei Ergebnisse gleichzeitig. Zeitersparnis: Faktor 3.

Nicht parallelisieren:

• As Ausgabe ist Bs Eingabe — sequenziell ausführen
• Zwei Aufgaben bearbeiten dieselbe Datei — Race-Condition-Risiko

5. Kontextverwaltung — Delegieren vs. Direkt

Faustregel: Wenn die Aufgabe 20 % des Kontexts des Hauptagenten verbrauchen würde, Delegation erwägen.

6. Echte Szenarien

A. Einstieg in eine neue Codebase

1. Explorer — Ordnerstruktur + Zusammenfassung der 5 Schlüsselmodule
2. Explorer — README + CLAUDE.md (falls vorhanden) Kernpunkte
3. Explorer — Zusammenfassung der letzten 10 Commits
↓
4. Hauptagent — in „ein Absatz über dieses Repo" zusammenführen

B. 5+ Datei-Änderung

1. Plan — Änderungsumfang + Schritte + Risikotabelle
2. Hauptagent — Plan reviewen, Schritt für Schritt vorgehen
3. Nach jedem Schritt: Reviewer — Diff-Review
4. Vor finalem Commit: Reviewer — Zweitmeinung zur Gesamtänderung

C. Debugging

1. Hauptagent — Fehlerlog + Reproduktionspfad definieren
2. Explorer — verwandte Code-Pfade verfolgen (aus dem Stack-Trace)
3. Hauptagent — Hypothese aufstellen + Lösung versuchen
4. Hauptagent — mit Build/Test verifizieren

D. Direkt vor dem PR-Merge

1. Reviewer — Diff-Sicherheits-/Performance-Review
2. Reviewer — Konventionskonsistenz mit dem bestehenden Code
3. Spezialist (security-review) — umfassende Bewertung
4. Hauptagent — Befunde in PR-Kommentare oder Fixes konsolidieren

7. Kombination mit Hooks

Claude Code Hooks' PreToolUse kann auch Task-Aufrufe abfangen.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Task",
        "hooks": [
          {
            "type": "command",
            "command": "/bin/bash -lc 'echo \"[Delegation] $(jq -r .tool_input.description)\" >> ~/.claude/delegate.log'"
          }
        ]
      }
    ]
  }
}

Delegationsanzahl und -inhalt zu protokollieren ermöglicht eine Auswertung, was delegiert und was direkt erledigt wurde. Nützlich für Kostenverfolgung und das Erkennen von Mustern.

8. Anti-Muster — Delegation falsch einsetzen

8.1 Alles Delegieren

"Sogar eine 1-Datei-Bearbeitung delegieren"   ← fügt nur Overhead hinzu

Subagenten-Aufrufe verursachen Token- und Zeitkosten. Einen 1-Sekunden-Job in eine 30-Sekunden-Delegation umzuwandeln ist ein reiner Verlust.

8.2 Hauptagent Sucht nach der Delegation Erneut

"Explorer fasst Auth-Datei-Speicherorte zusammen → Hauptagent grep anschließend dieselben Dateien selbst"

→ Die Delegation war umsonst. Dem Ergebnis vertrauen und zum nächsten Schritt übergehen.

8.3 Zu Viel Ausgabe Anfordern

"Den vollständigen Code jeder Datei + 5-Zeilen-Erklärung + Verwendungs-Rümpfe mitbringen"

→ Delegation reduziert den Kontext des Hauptagenten nicht automatisch. Ausgabegröße im Prompt explizit begrenzen.

8.4 Parallele Delegation mit Abhängigkeiten

"As Ergebnis fließt in B — aber beide gleichzeitig delegiert"

→ B kennt As Ergebnis nicht; fehlerhafte Annahmen sind die Folge. Sequenziell ausführen ist korrekt.

9. Verteilungsmatrix — Wer macht was

Was als Nächstes Kommt

• Claude Code einrichten — Grundlage des Hauptagenten
• Claude Code Hooks — Delegationen protokollieren/validieren
• Multi-Agenten-Workflow — Multi-Tool/Agenten-Integrationsszenarien
• Agent Runner — autonome Läufe + Subagenten kombiniert

Referenzen

• Claude Code offiziell — Task-Tool
• Anthropic — Agent-Design-Muster — allgemeine Prinzipien

Changelog

• 2026-05-12 — Erster Entwurf (devAlice M3 Seed-Erweiterung)