Zum Hauptinhalt springen

Subagenten & parallele Agenten

Experte
What you'll learn
  • Was ein Subagent ist — ein separater Claude mit eigenem Kontextfenster und einem eingegrenzten Tool-Satz
  • Die drei Gründe zu delegieren: Kontext schützen, spezialisieren und parallelisieren
  • Die eingebauten Agenten, an die Claude bereits delegiert: Explore, Plan, General-purpose
  • Wie du deinen eigenen Subagenten in .claude/agents/ definierst und warum description + tools die zwei tragenden Felder sind
  • Wann du NICHT parallelisieren solltest und wie sich das mit API-Agenten und Workflows in Flottengröße verbindet

Ein Subagent ist eine separate Claude-Instanz mit ihrem eigenen Kontextfenster und einem eingegrenzten Satz an Tools, an die deine Hauptsitzung einen Teil der Arbeit delegiert. Er meldet ein Ergebnis zurück, nicht sein gesamtes Transkript — so bleibt die Hauptsitzung fokussiert und übersichtlich.

Warum delegieren​

Drei Aufgaben, ein Werkzeug. Behalte sie jedes Mal im Kopf, wenn du zu einem Subagenten greifst:

  • Schütze den Hauptkontext. Eine Recherche-Tiefenbohrung oder ein großer Datei-Sweep kann Tausende Tokens verbrennen; mach das in einem Subagenten, und nur die Schlussfolgerung kommt zurück.
  • Spezialisiere. Gib einem Subagenten einen maßgeschneiderten System-Prompt und nur die Tools, die er braucht (z. B. einen schreibgeschützten Reviewer).
  • Parallelisiere. Führe unabhängige Teilaufgaben gleichzeitig aus — z. B. drei Module gleichzeitig erkunden.

Die eingebauten, die du schon hast​

Bevor du deine eigenen definierst, solltest du wissen: Claude Code bringt Subagenten mit, an die es automatisch delegiert:

EingebautWas er tut
ExploreEin schneller, schreibgeschützter Agent (läuft auf einem günstigeren Modell) zum Durchsuchen und Verstehen einer Codebasis, ohne sie anzufassen.
PlanSammelt Kontext im Plan-Modus, damit die Recherche aus der hauptsächlichen, schreibgeschützten Konversation herausbleibt.
General-purposeEin Agent mit vollem Tool-Satz für komplexe, mehrstufige Arbeit, die Erkundung und Änderungen mischt.

Du rufst diese selten beim Namen auf; Claude greift zu ihnen, wenn eine Aufgabe passt. Eigene Subagenten sind für die Arbeiter, die du immer wieder mit denselben Anweisungen neu erstellst.

Eigene definieren​

Ein Subagent ist eine Markdown-Datei mit YAML-Frontmatter (der Inhalt wird zu seinem System-Prompt). Nur name und description sind erforderlich; alles andere ist optional. Speichere ihn projektbezogen in .claude/agents/ (checke ihn in git ein, damit das Team ihn teilt) oder nutzerbezogen in ~/.claude/agents/. Erstelle einen mit dem /agents-Befehl oder von Hand.

Guided walkthrough1 of 5
  1. Projektbezogen in .claude/agents/ (committe ihn, damit das Team ihn teilt) oder nutzerbezogen in ~/.claude/agents/.

Ein Starter-Subagent code-reviewer:

code-reviewer subagent (.claude/agents/code-reviewer.md)

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes.
tools: Read, Glob, Grep
model: sonnet
---

You are a senior reviewer. Read the changed files, then report only
high-confidence issues: correctness bugs, security risks, and missing
tests. For each, show the file:line, the problem, and a concrete fix.
Do not restate what the code does. Never edit files.

Zwei Dinge machen einen Subagenten gut:

  • Die description ist das Routing-Signal. Claude liest sie, um zu entscheiden, wann delegiert wird, also schreibe sie wie einen Auslöser — "Use proactively after code changes" zieht ihn automatisch hinein; ein vages "helps with code" tut das nicht. Das ist die wirkungsvollste Zeile in der Datei.
  • Grenze die Tools eng ein. Das tools-Feld ist eine Allowlist (oder nutze disallowedTools als Denylist). Ein Reviewer, der nur Read, Glob, Grep kann, kann deinen Code nicht versehentlich bearbeiten — die Einschränkung ist eine Garantie, kein Hinweis. Lasse tools weg, und der Subagent erbt alles, was die Hauptsitzung hat.

Durchgespieltes Beispiel: ein paralleler Review-Fan-out​

Du hast ein Feature fertiggestellt, das drei Module berührt, und willst eine schnelle, unabhängige Prüfung jedes Moduls. In deiner Hauptsitzung:

Fan out three reviewers at once

Review the changes in auth/, billing/, and api/ — use the code-reviewer subagent on each, in parallel.

Claude startet drei code-reviewer-Instanzen gleichzeitig. Jede liest nur ihr Modul, verbrennt ihren eigenen Kontext auf den Dateiinhalten und gibt eine kurze Befundliste zurück. Deine Hauptsitzung sieht nie die rohen Diffs — nur drei aufgeräumte Berichte — und das Ganze ist ungefähr in der Zeit der langsamsten Einzel-Review fertig statt der Summe aller drei. Da der Reviewer schreibgeschützt ist, können drei gleichzeitig arbeitende Agenten beim Schreiben nicht kollidieren.

Wann du NICHT parallelisieren solltest​

Watch out
  • Abhängige Schritte müssen sequenziell sein — fächere keine Arbeit aus, bei der Schritt B die Ausgabe von Schritt A braucht.
  • Gemeinsame Datei-Schreibvorgänge können kollidieren; isoliere sie (siehe Git Worktrees) oder serialisiere sie.
  • Der Koordinationsaufwand kann den Nutzen bei kleinen Aufgaben übersteigen. Delegiere, wenn die Teilaufgabe umfangreich und unabhängig ist.

Zum Isolieren kollidierender Schreibvorgänge siehe Git Worktrees.

Subagent vs. die "Agenten" der API/des SDK​

Diese Seite handelt von der eingebauten Delegation von Claude Code. Deine eigenen Agenten programmatisch zu bauen, ist Agenten auf der API bauen. Das mentale Modell — ein Ziel, eine Tool-Schleife, isolierter Kontext — ist dasselbe.

Häufige Fehler​

Fallstricke — drehe jede Karte für die Lösung um
Drücke Enter oder die Leertaste, um die Karte umzudrehen. Nutze die Pfeiltasten links und rechts, um zwischen den Karten zu wechseln.Begriff angezeigt.
1 / 4

Wenn ein paar Agenten nicht genug sind​

Eine Handvoll Subagenten pro Runde zu delegieren ist das Kerngeschäft dieser Seite. Wenn eine Aufgabe Dutzende oder Hunderte von Agenten braucht — ein codebasisweiter Sweep, eine 500-Dateien-Migration, über viele Quellen gegengeprüfte Recherche — wächst die Orchestrierung über ein einzelnes Kontextfenster hinaus. Genau dafür sind Dynamic Workflows & ultracode da: Claude schreibt ein Skript, das den Plan hält, und eine Laufzeitumgebung fächert die Agenten im Hintergrund aus.

Teste dich selbst

0/3
  1. Welches Feld im Frontmatter eines Subagenten ist das Routing-Signal, das Claude liest, um zu entscheiden, WANN delegiert wird?
  2. Ein Reviewer-Subagent bekommt tools: Read, Glob, Grep. Was garantiert diese Allowlist?
  3. Wann hilft das Parallelisieren von Subagenten NICHT?
Key takeaways
  • Ein Subagent ist ein separater Claude mit eigenem Kontextfenster und eingegrenzten Tools; er gibt ein Ergebnis zurück, nicht sein Transkript.
  • Delegiere, um den Hauptkontext zu schützen, zu spezialisieren oder unabhängige Arbeit zu parallelisieren.
  • Claude bringt bereits Explore, Plan und General-purpose als eingebaute Agenten mit und greift automatisch zu ihnen.
  • name und description sind die einzigen erforderlichen Frontmatter-Felder — und description ist das Routing-Signal, das entscheidet, wann Claude delegiert.
  • Eine Tools-Allowlist macht aus Absicht eine Garantie; fächere nur unabhängige Teilaufgaben aus und isoliere gemeinsame Schreibvorgänge.

Weiter​