Claude Code Subagents: Aufbau, 5 Rollen und Orchestrierung

Was ist ein Subagent in Claude Code, und warum ist er „nicht einfach nur ein weiterer Skill“?#

Die Claude-Code-Dokumentation definiert es so:

Mit einem Beispiel, das Unternehmer verstehen: Stell dir eine Immobilienagentur vor. Es gibt einen Direktor, einen Marketer, einen Juristen und Vertriebsmanager. Wenn eine Person zwischen all diesen Rollen wechselt, ist das kein Team, sondern eine überlastete Person. Ein Team entsteht, wenn jede Person ihren eigenen Kontext und Verantwortungsbereich hat, während der Direktor nur Aufgaben verteilt und die Ergebnisse zusammenführt.

Subagents in Claude Code funktionieren genauso. Der Hauptchat ist der Direktor. Ein Subagent ist ein Spezialist mit einer klar abgegrenzten Aufgabe, eigenem Kontext und eigenen Tools. Wenn eine Aufgabe zur Beschreibung eines Spezialisten passt, delegiert der Direktor sie an ihn – und verliert sich nicht in den Details.

5 Ziele, für die Anthropic Subagents entwickelt hat

In der Dokumentation von Anthropic werden genau fünf Gründe genannt, einen eigenen Subagenten zu erstellen:

Der praktischste Punkt auf dieser Liste für Nicht-Programmierer ist die Kostenkontrolle. Du kannst eine aufwendige Rechercheaufgabe an das günstige Modell Haiku senden und das Hauptgespräch mit Sonnet oder Opus fortsetzen. Die Token-Ersparnis ist direkt proportional.

Verschachtelungsunterstützung der installierten Version prüfen

Die Vorlagen dieses Leitfadens verwenden eine Hauptsitzung, die direkt an Worker delegiert. Behandle ältere Dokumentation mit „Subagents können keine anderen Subagents starten“ nicht als zeitlose Regel. Verschachtelung hängt von installierter Version und erlaubten Tools ab. Der eigene Leitfaden zu verschachtelten Subagenten beschreibt ein versionsbezogenes Rezept. Prüfe die Unterstützung deiner Installation vor tieferer Delegation.

Worin unterscheidet sich ein Subagent von einem Skill, Slash-Befehl und Hook?#

Der vorherige Leitfaden zu Skills erklärt, dass Skills und Slash-Befehle in Claude Code praktisch zu einem Format verschmolzen sind. Ein Subagent ist jedoch eine andere Einheit – nicht einfach „ein größerer Skill“.

Eine Übersichtstabelle der vier Mechanismen:

Eine gute Formulierung für einen englischsprachigen Leitfaden lautet: Skills sind Rezepte; Subagents sind spezialisierte Kollegen.

Put simply: Skills are recipes; subagents are specialized colleagues.

In der Praxis funktioniert es so: Skills werden automatisch aktiviert, wenn ihre Beschreibung zur Aufgabe passt, während Subagents ausdrücklich aufgerufen werden – entweder entscheidet der Hauptchat, zu delegieren, oder du rufst einen namentlich auf.

Entscheidungsbaum: „Welchen soll ich wählen?“

Wenn du denkst: „Ich brauche Claude für X“, gehe diese vier Fragen durch:

1. Ist das Wissen, das immer verfügbar sein sollte? Zum Beispiel: „Wir lokalisieren in die vom Benutzer bevorzugte Sprache“ oder „Wir verwenden keine Gedankenstriche.“ Schreibe es in CLAUDE.md.
2. Ist es eine ausgelöste Methode, die du derzeit manuell ausführst? Zum Beispiel: „Ich schreibe jeden Montag einen Vertriebsbericht.“ Erstelle einen Skill.
3. Wird diese Aufgabe den Kontext des Hauptchats beanspruchen, oder kann sie parallel ausgeführt werden? Zum Beispiel: „gründliche Recherche über 30 Quellen“ oder „ein Sicherheitsaudit, während ich ein neues Feature schreibe.“ Erstelle einen Subagenten.
4. Brauchst du eine automatische Reaktion auf ein Ereignis in Claude Code? Zum Beispiel: „Führe nach jedem Edit den Linter aus.“ Schreibe einen Hook.

90 % der Aufgaben von Unternehmern fallen in die ersten beiden Kategorien. Subagents sind ein Werkzeug für Fortgeschrittene, wenn du von „eine Aufgabe nach der anderen“ zur Orchestrierung übergehst.

Wo befinden sich Subagents, und welcher hat Vorrang?#

Die Hierarchie der Subagents umfasst fünf Ebenen, geordnet von der höchsten zur niedrigsten Priorität:

Die Prioritätslogik entspricht der für Skills und CLAUDE.md: Organisation hat Vorrang vor CLI, CLI vor Projekt, Projekt vor persönlich und persönlich vor Plugin.

Was du über das Laden wissen solltest

Subagents werden geladen, wenn eine Claude-Code-Sitzung startet. Wenn du eine Agent-Datei manuell auf der Festplatte bearbeitest, werden die Änderungen erst nach einem Neustart der Sitzung übernommen. Änderungen über die interaktive /agents-Oberfläche gelten sofort.

Pro Geltungsbereich ein Subagent bedeutet eine Datei. Wenn .claude/agents/ die Datei code-reviewer.md und daneben eine weitere code-reviewer.md enthält (zum Beispiel aus einem alten Backup), ignoriert Claude Code stillschweigend eine davon. Es gibt keine Benachrichtigung.

Plugin-Subagents sind ein Sonderfall. Für sie gelten Sicherheitseinschränkungen: Sie unterstützen die Felder hooks, mcpServers und permissionMode nicht. Dadurch wird verhindert, dass ein Drittanbieter-Plugin die Berechtigung erhält, beliebigen Code auf deinem Rechner auszuführen.

KI Agenten bauen: Aufbau einer Subagent-Datei mit Frontmatter und Inhalt#

Ein minimales Beispiel aus der offiziellen Dokumentation – nur 9 Zeilen:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

Das genügt. Wenn ein Benutzer im Hauptchat sagt: „Überprüfe meinen PR“, gleicht Claude „Reviewer / Code / Qualität“ mit der Beschreibung ab und delegiert die Aufgabe an den Subagenten. Dieser liest den Diff, verfasst Kommentare und gibt dem Hauptchat eine Zusammenfassung zurück. Der Hauptchat wird nicht mit Protokollen und Zwischenanalysen überladen.

Vollständiges Frontmatter-Schema

Das Feld model: haiku ist genau die erwähnte „Kostenkontrolle“ aus der Liste der fünf Ziele. Wenn du einen Recherche-Agenten hast, der 50 Seiten Dokumentation liest, führe ihn mit Haiku aus, um im Vergleich zu Opus das 5–7-Fache zu sparen.

Das Feld isolation: worktree löst ein wichtiges Problem: Ein Subagent nimmt möglicherweise gefährliche Änderungen vor (Refactoring, Migration), aber du möchtest nicht, dass er deine Arbeitskopie anfasst. Setze isolation: worktree, und Claude Code erstellt eine temporäre Git-Kopie des Projekts; der Subagent arbeitet dort und gibt einen Diff zur Prüfung zurück.

Der Dateiinhalt ist der System-Prompt

Nach dem Frontmatter folgt gewöhnliches Markdown – das ist der System-Prompt des Subagenten. Eine besondere Struktur ist nicht erforderlich, aber dieses Muster hat sich bewährt:

1. Wer du bist – ein Satz: „Du bist ein Code-Reviewer“, „Du bist ein Sicherheitsauditor“, „Du betreust die Dokumentation.“
2. Wann du aufgerufen wirst und was du zuerst tust – die ersten 2–3 Aktionen nach Erhalt der Aufgabe.
3. Eine Checkliste der Prüfungen oder Schritte – 5–10 Punkte, denen der Subagent folgt.
4. Was du zurückgibst – Format des Abschlussberichts. Das ist entscheidend: Wenn du kein Format vorgibst, erstellt der Subagent einen „Essay“ statt einer strukturierten Zusammenfassung.
5. Was du NICHT tust – ausdrückliche Einschränkungen. Ohne diesen Abschnitt improvisiert der Subagent.

Beschränke den Dateiinhalt auf 200–500 Zeilen. Wenn er länger wird, verschiebe ausführliche Referenzen in separate Dateien in der Nähe und verweise im Prompt darauf.

So formulierst du eine Beschreibung, damit Claude deinen Subagenten mit Sicherheit aufruft#

Das Hauptproblem in Hacker-News-Diskussionen besteht darin, dass jemand einen Subagenten für Code-Reviews einrichtet, Claude aber alles selbst erledigt, ohne den Agenten zu verwenden. Meist gibt es dafür einen Grund: Die Beschreibung lautet „Helfer für Code-Reviews“. Claude versteht nicht, wann er den Agenten auslösen soll.

Formel für eine wirksame Beschreibung (3 Teile)

Teil 1 – was er tut. Ein Satz zum Ergebnis, nicht zum Ablauf. Nicht „analysiert Code“, sondern „findet Schwachstellen im Code und gibt eine Liste mit Schweregrad und Lösung zurück“.

Teil 2 – wann er ausgelöst werden soll. 3–5 Formulierungen in Anführungszeichen, wie Benutzer tatsächlich Anfragen stellen. Nicht raten – sieh dir deinen Chatverlauf und die wirklichen Formulierungen an.

Teil 3 – wann er NICHT ausgelöst werden soll. 1–2 Formulierungen zu ähnlichen Aufgaben, auf die dieser Subagent nicht reagieren soll. Ohne diesen Abschnitt geraten zwei ähnliche Agents ständig in Konflikt.

Die magische Formulierung „Use Proactively“

Die offizielle Dokumentation von Anthropic gibt eine direkte Empfehlung:

Anders gesagt: Claude tendiert standardmäßig dazu, einen Subagenten nicht aufzurufen, wenn die Beschreibung keine klaren Signale enthält. Füge „use proactively“ oder „use immediately after writing code“ hinzu, und die Aktivierung steigt deutlich.

Eine starke Beschreibung sieht so aus

description: |
  Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or
  modifying code. Returns prioritized list of issues with severity
  and fix recommendations.
  Do not invoke for documentation changes, README edits, or commit
  message rewrites - these are handled by doc-maintainer.

Was hier funktioniert:

• Die Verben „reviews“ + „returns“ geben ein konkretes Ergebnis an, keinen Ablauf.
• „Proactively“ und „immediately after“ sind ausdrückliche Auslöser.
• „Do not invoke for...“ verhindert Konflikte mit einem ähnlichen Subagenten.
• Englisch in der Beschreibung ist üblich. Claude gleicht Aufgaben auf Englisch besser ab.

KI Agenten Beispiele: 5 sofort einsetzbare Subagent-Rollen#

Jede der folgenden Rollen ist eine einzelne Datei: .claude/agents/<name>.md. Starte Claude Code nach dem Erstellen der Datei neu, öffne /agents und prüfe, ob der neue Agent in der Liste erscheint. Anschließend kannst du ihn mit @agent-name aufrufen.

1. code-reviewer – Code nach jeder Änderung überprüfen

Dies ist das offizielle Beispiel aus der Dokumentation von Anthropic, angepasst an einen Arbeitsablauf:

---
name: code-reviewer
description: |
  Expert code review specialist. Proactively reviews code for quality,
  security, and maintainability. Use immediately after writing or
  modifying code.
tools: Read, Grep, Glob
model: inherit
color: blue
---

You are a senior code reviewer ensuring high standards of code quality.

Bei Aufruf:
1. Lies Diff und Liste geänderter Dateien aus der Hauptsitzung. Fehlen sie, fordere sie an.
2. Prüfe relevante Dateien mit Read, Grep und Glob.
3. Liefere Funde, ohne Dateien zu ändern oder Shellbefehle auszuführen.

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Test coverage adequate
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix before merge)
- Warnings (should fix)
- Suggestions (consider improving)

Format: for each issue - file:line + 1 sentence why it's a problem + concrete fix.

Entscheidend sind tools: Read, Grep, Glob: Lese- und Suchtools ohne Bash, Write und Edit. Die Hauptsitzung erstellt und übergibt den Diff. Eine bloße Anweisung, ausschließlich git diff auszuführen, beschränkt kein vollständig freigegebenes Bash-Tool.

2. security-auditor – Schwachstellen und Datenlecks finden

Diese Rolle nutzt opus für tieferes Schlussfolgern und dieselbe Beschränkung auf Read, Grep und Glob. Dauerhafter Agentenspeicher fehlt in dieser Nur-Lese-Vorlage bewusst: Seine Aktivierung gewährt zugleich Schreibmöglichkeiten für Speicherdateien:

---
name: security-auditor
description: |
  Security audit specialist. Use proactively to find OWASP Top 10
  vulnerabilities, exposed secrets, injection risks, broken auth.
  Run before any deploy or merge to main.
tools: Read, Grep, Glob
model: opus
color: red
---

You are a security auditor. Find exploitable vulnerabilities, not style issues.

Audit checklist:
- SQL / NoSQL injection
- XSS (stored, reflected, DOM-based)
- CSRF / SSRF risks
- Hardcoded secrets (API keys, tokens, passwords)
- Broken auth / session management
- Insecure deserialization
- Missing input validation
- Path traversal
- Open redirects
- Insecure direct object references (IDOR)

For each finding:
- Severity: Critical / High / Medium / Low
- File:line
- Attack scenario in 1–2 sentences
- Fix recommendation with code example

Skip linter or style noise. Report only exploitable issues.

Was die Tools angeht, schreibgeschützt, mit model: opus für komplexe Prüfungen wie Schwachstellenketten.

3. research-agent – gründliche Recherche über 8+ Quellen

Dieses Muster wird von Anthropic selbst in einem Artikel über das Multi-Agent-Recherchesystem beschrieben. Entscheidend sind ein ausdrückliches Ausgabeformat und das Verbot, Rohdaten auszugeben:

---
name: research-agent
description: |
  Deep web research specialist. Use proactively for fact-finding,
  competitive analysis, gathering external documentation, comparing
  approaches across multiple sources.
tools: WebFetch, WebSearch, Read, Write
model: sonnet
maxTurns: 30
color: purple
---

You are a research analyst. Goal: synthesized brief, not raw search dumps.

Process:
1. Decompose the question into 3–5 sub-queries
2. WebSearch each sub-query, fetch top 3–5 sources per query
3. Cross-verify claims across at least 2 independent sources
4. Reject SEO-farm and aggregator content; prefer primary sources
5. Quote verbatim with URL attribution for any specific claim
6. Return: TL;DR (3 bullets) + Findings + Sources (8+ domains minimum)

Anti-patterns to avoid:
- Don't cite a fact from a single source
- Don't paraphrase quotes as if they were verbatim
- Don't return raw search result dumps to the parent
- Don't include filler intro / outro ("Hope this helps")

maxTurns: 30 schützt davor, dass sich die Recherche in endlosen Wiederholungen verliert. Anthropic nennt diese Zahl in seinem Multi-Agent-System:

Die 90 Prozent beziehen sich auf Forschungs-Benchmark-Aufgaben. In der Praxis fällt der Zugewinn bei Geschäftsaufgaben geringer aus, doch die Größenordnung ist ähnlich.

4. doc-maintainer – Dokumentation mit dem Code synchron halten

Diese Rolle verwendet model: haiku – ein typisches Beispiel für „Kostenkontrolle“. Für Dokumentation ist Opus nicht erforderlich; Haiku erledigt die Aufgabe für ein Drittel des Preises:

---
name: doc-maintainer
description: |
  Documentation sync specialist. Use after merging features to update
  README, API docs, CHANGELOG. Reads recent commits, identifies
  undocumented changes, updates docs proactively.
tools: Read, Write, Edit, Glob, Grep, Bash
model: haiku
memory: project
color: green
---

You maintain documentation in sync with code.

When invoked:
1. Run `git log --since="last release"` to see recent changes
2. Read README.md, docs/, CHANGELOG.md
3. Identify gaps: new features without docs, removed APIs still
   documented, version mismatches

Output:
- Updated files (use Edit, not Write - preserve existing structure)
- CHANGELOG.md entry in Keep-A-Changelog format
- List of changes you made (actual diff summary, not paraphrase)

Style rules:
- Active voice, present tense
- Code examples must be copy-pasteable
- No marketing language ("powerful", "robust", "seamless")
- No filler ("This guide will help you...")

5. refactor-agent – sicheres Refactoring über einen Worktree

Diese Rolle verwendet isolation: worktree – der Subagent arbeitet in einer separaten Repository-Kopie, und du übernimmst Änderungen nur, wenn sie in Ordnung sind:

---
name: refactor-agent
description: |
  Safe refactor specialist. Use for renames, extracts, inlines that
  shouldn't touch your working copy until reviewed. Runs in a
  temporary git worktree.
tools: Read, Edit, Write, Bash, Grep, Glob
model: sonnet
isolation: worktree
permissionMode: acceptEdits
color: yellow
---

You refactor code without changing behavior.

Strict rules:
1. Tests must pass BEFORE and AFTER the refactor.
   If pre-refactor tests fail, STOP and report.
2. One atomic refactor per commit (extract, rename, inline).
3. Never change public APIs without explicit instruction.
4. Never modify tests unless they test the refactored implementation
   directly.

Process:
- Run test suite -> baseline
- Make atomic refactor
- Run test suite -> verify
- Commit with conventional message: refactor(scope): what

Return: summary of changes + worktree path so user can diff and merge.

Mit dieser Rolle verschwindet das lästigste Refactoring-Problem – „Ich habe etwas kaputtgemacht und weiß nicht, wie ich es rückgängig machen kann“: Die ursprüngliche Kopie bleibt unangetastet, und der Subagent arbeitet in einem isolierten Worktree.

Möchtest du nicht nur fertige Subagents kopieren, sondern eine Kombination zusammenstellen, die Claude zu einem verlässlichen Werkzeug macht? Subagents sind Teil deines KI-Klons: eine Möglichkeit, Claude ein spezialisiertes Team zu geben, das nach deiner Logik arbeitet. Die drei Säulen dieser Methode sind: KI-Klon (Skills + Subagents) + Second Brain + Context Engineering. Diese Kombination macht aus Claude einen Assistenten, der nicht rät, sondern nach deiner Logik denkt.

5 Subagents parallel starten: Orchestrator + Worker#

Parallele Orchestrierung funktioniert nach dem Muster „Dirigent + Orchester“. Der Dirigent hält den Plan, schreibt keine Noten und prüft, was die Musiker spielen. Wenn jemand einen falschen Ton trifft, bittet der Dirigent ihn, noch einmal zu spielen, statt zu versuchen, an seiner Stelle fertig zu werden.

Für Unternehmer ist eine Marketingagentur, die eine Strategie für einen neuen Kunden ausarbeitet, ein passenderer Vergleich. Ein Analyst erstellt eine SWOT-Analyse, ein anderer analysiert Wettbewerber, ein dritter erstellt ein Zielgruppenprofil, ein leitender Analyst filtert Hypothesen heraus, die nicht zum Budget passen, und der Projektmanager setzt die endgültige Präsentation zusammen. In Claude Code beginnt diese Pipeline mit einem Satz – und der Kritiker ist von Anfang an in den Prozess eingebaut, statt erst nachträglich dazuzukommen.

Minimaler Orchestrierungs-Prompt

Ein Satz im Hauptchat genügt:

Launch five subagents in parallel: three research-agents on different sources
(Anthropic docs, GitHub repos, AI bloggers), one critic-agent to filter out
weak conclusions, and one summary-agent for the final document.

Context: I am writing a guide about X. Target length: 2,000 words with sources.
Before starting, each one reads CLAUDE.md.

Claude delegiert die Aufgaben dann an die fünf Agents. Jeder arbeitet in seinem eigenen Kontext: Die Recherche-Agents nutzen ihre jeweiligen Quellen, der Kritiker filtert, und der Zusammenfassungs-Agent erstellt das Dokument. Nur abschließende Zusammenfassungen gelangen zurück in den Hauptchat.

Wo sich Parallelität auszahlt

Nicht überall. Parallele Ausführung ist nur sinnvoll, wenn:

1. Die Aufgaben unabhängig sind. Wenn research-agent #2 auf das Ergebnis von research-agent #1 wartet, gibt es keine Parallelität – sie arbeiten faktisch nacheinander.
2. Die Aufgaben lange dauern. „Nachgestellte Leerzeichen entfernen“ zu parallelisieren ist sinnlos; der Aufwand für den Start der Subagents übersteigt den Gewinn.
3. Du über ausreichende Kontingente verfügst. Mehr dazu in einem eigenen Abschnitt weiter unten – parallele Subagents verbrauchen schnell viele Tokens.

Anthropic Multi-Agent v2: der nächste Schritt

Im Mai 2026 veröffentlichte Anthropic Multi-Agent Orchestration v2 mit drei wichtigen Unterschieden zur klassischen Vorgehensweise, parallele Subagents zu starten. Mehr dazu im nächsten Abschnitt.

Was ist neu bei Multi-Agent v2: Orchestrierung, Outcomes, Dreaming#

Multi-Agent Orchestration: gemeinsames Dateisystem + Zwischenabstimmungen

Anthropic beschreibt die Funktion so:

Der entscheidende Unterschied zu klassischen Subagents ist ein gemeinsames Dateisystem. Früher arbeitete jeder Subagent vollständig isoliert, und der Austausch erfolgte nur über die zurückgegebene Zusammenfassung. Jetzt können Spezialisten in einen gemeinsamen Ordner schreiben, und der leitende Agent kann die Ergebnisse bereits während der Arbeit lesen, nicht erst am Ende. Damit wird das Problem gelöst, dass „alle den ganzen Tag gearbeitet haben und sich am Ende herausstellt, dass zwei Personen unvereinbare Ansätze verfolgt haben“.

Zweitens gibt es Zwischenabstimmungen. Der leitende Agent kann pausieren und einen beliebigen Spezialisten fragen: „Wie läuft es?“, und dann den Gesamtplan anpassen. Das kommt der Arbeit eines echten Teammanagers nahe.

Outcomes: Erfolgskriterien statt Schritt-für-Schritt-Anweisungen

Mit Outcomes formulierst du Erfolgskriterien, und der Agent findet einen Weg, sie zu erfüllen. Ein separater Grader prüft das Ergebnis in seinem eigenen Kontext, damit es nicht von den Überlegungen des Haupt-Agents „kontaminiert“ wird.

Zehn Prozent bei schwierigen Aufgaben sind ein erheblicher Zugewinn. Besonders, wenn die Aufgabe lautet: „Erstelle einen ausführlichen Artikel, der diese Qualitätskriterien erfüllt“, statt „Befolge die Schritte 1–7“.

Dreaming: Agents sammeln zwischen Sitzungen Erfahrungen

Das ist die konzeptionell neuartigste Funktion. Ein Agent durchläuft frühere Sitzungen, findet Muster bei Erfolgen und Fehlern und aktualisiert den Speicher. Du kannst vor der Übernahme von Änderungen eine manuelle Prüfung vorsehen oder dem Agenten erlauben, den Speicher selbst zu bearbeiten.

Anthropic berichtet, dass Harvey (ein Legal-Tech-Unternehmen) nach der Einführung von Dreaming bei juristischen Entwurfsaufgaben eine etwa sechsfache Steigerung der Erfolgsquote verzeichnete. Das funktioniert bereits in der Produktion und ist nicht bloß eine Demo.

Was das für Unternehmer bedeutet, die nicht programmieren

Multi-Agent Orchestration ist derzeit über das Claude Agent SDK verfügbar, nicht direkt über die Claude-Code-CLI. Die Richtung ist jedoch klar: Orchestrierung entwickelt sich von „Du startest manuell N Subagents“ zu „Du beschreibst die Aufgabe, und der leitende Agent entscheidet, an wen und wie er delegiert.“ Wenn du gerade erst mit Subagents anfängst, musst du dir über v2 noch keine Gedanken machen. Lerne zuerst das klassische Muster „1 Hauptchat + 3–5 Subagents mit unterschiedlichen Rollen“; in 3–6 Monaten kannst du dann auf natürliche Weise zu Managed Agents wechseln.

7 Fehler, die Subagents ausbremsen#

Fehler 1. Beschreibungen wie „Helfer für X“ lösen keine Aktivierung aus

Symptom: Du hast einen Subagenten geschrieben, die Struktur geprüft, und alles ist gültig, aber Claude ruft ihn bei Benutzeranfragen nicht auf. Der Grund ist fast immer derselbe: Die Beschreibung ist abstrakt, etwa „Helfer für Code-Reviews“. Die Lösung: Füge direkt in die Beschreibung 3–5 echte Benutzerformulierungen in Anführungszeichen ein, außerdem „use proactively“ / „use immediately after“.

Fehler 2. Einen Subagenten erstellen, obwohl ein Skill nötig ist

Ein Subagent ist kostspieliger als ein Skill – er erstellt einen eigenen Kontext, lädt seinen eigenen System-Prompt und verbraucht mehr Tokens. Wenn eine Aufgabe kurz ist, den Hauptkontext nicht beansprucht und in einem Durchgang erledigt werden kann, sollte sie ein Skill sein, kein Subagent. Ein Beispiel für ein Anti-Pattern: Ein Subagent format-validator prüft ein JSON-Schema anhand von 20 Regeln. Das sollte ein Skill sein: ein Modell, keine Isolation erforderlich, kein zusätzlicher Kontext wird geladen.

Fehler 3. Von Anfang an „60 parallele Agents“ starten

Das ist die verbreitetste Illusion. Du siehst einen Tweet mit „Ich habe 1.500 Agents am Laufen“ und denkst: „Das sollte ich auch machen.“ In der Praxis verbrauchen 60 Agents innerhalb einer Stunde das Kontingent eines Pro-Plans, erzeugen einen Berg widersprüchlicher Ergebnisse, und am Ende des Tages hast du nichts fertiggestellt.

Ein Praktiker auf Medium formuliert es so:

Die Lösung: Beginne mit einem Subagenten für eine Aufgabe. Wenn du das beherrschst, füge einen zweiten mit einer anderen Rolle hinzu. Sobald du die Orchestrierung von zwei Agents beherrschst, gehe zu einem Team von 3–5 über. Der Sprung von „Claude Code gestern installiert“ zu „heute 20 parallel“ führt mit Sicherheit zu fehlerhaftem Code und aufgebrauchten Kontingenten.

Fehler 4. Jedem Agenten alle Tools geben

Wenn dein Code-Reviewer Zugriff auf Bash, Write und WebFetch hat, ist das ein großes Sicherheits- und Kostenrisiko. Ein Reviewer sollte keine Dateien schreiben dürfen, geschweige denn Zugriff auf das Internet haben.

Die Lösung: Beschränke tools strikt. Ein Code-Reviewer erhält nur Read, Grep, Glob. Ein Sicherheitsauditor erhält dieselben Lese-/Suchtools und einen von der Hauptsitzung gelieferten Diff. Bash gewährt Shellfähigkeiten und beschränkt den Agenten nicht automatisch auf git diff. Ein Recherche-Agent erhält WebFetch, WebSearch, Read, Write. Gib einem Subagenten für eine bestimmte Aufgabe nicht mehr Berechtigungen, als er dafür benötigt.

Fehler 5. Ein Subagent gibt Rohdaten an den Hauptkontext zurück

Wenn ein Recherche-Agent dem Hauptchat antwortet: „Hier sind alle 30 Seiten, die ich gefunden habe; mach dir selbst einen Reim darauf“, ist der größte Vorteil von Subagents verloren: die Abschirmung von Störinformationen. Die Lösung: Verlange im System-Prompt des Subagenten ausdrücklich ein Ausgabeformat. „Gib NUR Folgendes zurück: TL;DR mit 3 Stichpunkten + Liste mit 5 Quellen. KEINE Code-Ausgaben, KEINE rohen Suchergebnisse.“ Das Format sollte verbindlich sein – der Subagent sollte nicht frei entscheiden dürfen, „daraus einen Essay zu machen“.

Fehler 6. Vage Aufträge: unklare Delegationsanfragen

Ein Subagent kann den Verlauf des Hauptdialogs nicht sehen. Er startet mit einem leeren Kontext + CLAUDE.md + allem, was du ihm ausdrücklich mitgeteilt hast. Wenn du schreibst „Behebe die Authentifizierung“, wird der Subagent Dinge erfinden. Schreibe stattdessen: „Behebe die OAuth-Weiterleitungsschleife, bei der der Benutzer nach erfolgreicher Anmeldung zu /login statt zu /dashboard weitergeleitet wird. Datei: src/lib/auth.ts.“

Eine klare Regel: Wenn du delegierst, gib dem Subagenten so viel Kontext, wie du einem neuen Auftragnehmer geben würdest, der gerade zum Projekt gestoßen ist.

Fehler 7. Agents nach Rollen statt nach Aufgaben organisieren

Ein verlockendes Muster ist: „Erstellen wir einen Frontend-Entwickler, einen Backend-Entwickler und einen QA-Ingenieur und lassen sie als Team arbeiten.“ Das funktioniert nicht. Jede „Rolle“ verliert den Überblick über das Gesamtprojekt, und die Agents können sich nicht auf Details einigen, weil sie einander nicht sehen können.

Die Lösung: Ein Subagent sollte eine wiederkehrende Aufgabe mit einem klaren Ergebnis übernehmen, keine Rolle. Nicht „Frontend-Entwickler“, sondern „explore-ui-tree“, „refactor-component“, „audit-accessibility“. Jeder aufgabenbasierte Subagent erledigt eine konkrete Arbeit und liefert ein konkretes Ergebnis zurück.

Was kosten parallele Subagents, und wann zahlen sie sich aus?#

Ein Pro-Plan ist innerhalb einer Stunde aufgebraucht, wenn du 5 parallele Subagents für komplexe Aufgaben startest. Max 5x ($100) ist das realistische Minimum für regelmäßige parallele Arbeit. Bei Teams und Enterprise ist die Kostenfrage bereits auf Ebene des Tooling-Budgets geklärt.

Weitere Tipps zum Tokensparen in Claude Code findest du im separaten Leitfaden zu Kontingenten. Für Subagents gilt die entscheidende Regel: Sie lohnen sich bei Aufgaben, die mindestens 10 Minuten konzentrierte Arbeit erfordern. Bei kürzeren Aufgaben solltest du keinen Subagenten erstellen, sondern sie im Hauptchat oder mit einem Skill erledigen.

Wie integrierst du Subagents in deinen KI-Klon und dein Second Brain?#

Ein Subagent stützt sich auf drei Dinge, die in deinem Projekt vorhanden sein sollten, bevor du deinen ersten Spezialisten erstellst:

1. Die richtige CLAUDE.md. Ein Subagent liest CLAUDE.md, bevor er anfängt – sie ist sein „Arbeitsvertrag“. Ohne sie kennt er weder den Projektkontext noch die Einschränkungen oder den Ton. Er wird Dinge erfinden.

2. Grundlegende Skills. Ein Skill ist eine gebündelte Methode. Ein Subagent lädt nur die Skills, die er benötigt, nicht alles auf einmal. Ohne Skills wiederholt er jedes Mal dieselbe Arbeit von Grund auf.

3. Second Brain: eine Wissensstruktur. Der Ordner business/ (oder ein entsprechendes Verzeichnis in deinem Fachgebiet) ist eine Bibliothek, die alle Subagents konsultieren. Ohne sie liefert ein Subagent eine durchschnittliche ChatGPT-Antwort, die sich nicht von der aller anderen unterscheidet.

Diese Reihenfolge umzukehren bedeutet, Hype ohne Ergebnisse zu bekommen. „Ich habe 60 parallele Subagents“ bei einem leeren Ordner business/ bedeutet 60 durchschnittliche ChatGPT-Sitzungen mit demselben Ansatz.

Die vollständige Kombination – KI-Klon + Second Brain + Context Engineering – sind die drei Säulen, die Claude verlässlich machen. Subagents sind Teil des KI-Klons: eine Möglichkeit, Claude ein spezialisiertes Team zu geben, das nach deiner Logik arbeitet.

Am schnellsten geht es so: Kopiere code-reviewer aus dem ersten Beispiel oben nach .claude/agents/code-reviewer.md, starte Claude Code neu und rufe @agent-code-reviewer bei deinem nächsten Commit auf. In 5 Minuten weißt du, ob du Subagents brauchst oder ob der Hauptchat ausreicht.