Parallele Subagents: Arbeit auf frische Kontexte verteilen

# Parallele Subagents: Arbeit auf frische Kontexte verteilen

Eine einzelne Claude-Code-Konversation kann nur eine begrenzte Menge gleichzeitig verarbeiten. Wenn eine Aufgabe wirklich breit ist, schieben Sie also nicht alles in einen Kontext, sondern verteilen die Arbeit auf Subagents: separate Claude-Instanzen, die jeweils ihr eigenes frisches Context WindowContext WindowThe context window is the maximum amount of text (measured in tokens) a language model can process at once, including both the input prompt and the generated output.Vollständige Definition ansehen → bekommen, unabhängig arbeiten und nur ihre Ergebnisse zurückmelden.

Sie wissen bereits, dass das Context WindowContext WindowThe context window is the maximum amount of text (measured in tokens) a language model can process at once, including both the input prompt and the generated output.Vollständige Definition ansehen → endlich ist und dass Überfüllen die Qualität verschlechtert. Subagents sind die strukturelle Antwort auf dieses Problem innerhalb von Claude Code. In dieser Lektion geht es darum, wann Sie darauf zurückgreifen, wie Sie eigene definieren und was Sie dafür aufgeben.

Was ein Subagent tatsächlich ist

Ein Subagent ist ein Child-Task, den Claude Code startet, um einen Teil der Arbeit zu übernehmen. ErErThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → läuft mit einem sauberen Kontext, erledigt seine Aufgabe mit eigenem Tool-Zugriff und gibt eine Zusammenfassung an den Hauptagenten (den Orchestrator) zurück, der ihn gestartet hat.

Drei Eigenschaften sind wichtig:

• Frischer Kontext. Jeder Subagent startet leer. ErErThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → erbt nicht die Historie Ihrer Hauptkonversation. Genau das ist der Sinn: ErErThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → konkurriert nicht um Platz mit allem anderen, was Sie bisher gemacht haben.
• Unabhängige Ausführung. Mehrere Subagents kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen gleichzeitig laufen. Claude Code schickt sie los und wartet, bis alle fertig sind.
• Nur Zusammenfassung zurück. Sie bekommen nicht das vollständige Transkript des Subagents in Ihren Hauptkontext. Sie bekommen sein Ergebnis. Das unübersichtliche Zwischendenken bleibt isoliert.

Die letzte Eigenschaft ist der Trick, der Fan-out skalierbar macht. Wenn ein Subagent 40 Dateien liest, um eine Frage zu beantworten, berühren diese 40 Dateien nie Ihr Hauptfenster. Nur die Antwort tut das.

Wann paralleles Fan-out besser ist als eine lange Konversation

Fan-out gewinnt, wenn die Arbeit breit und trennbar ist. Die Teile hängen nicht von den Ergebnissen der anderen ab, sie sequenziell auszuführen wäre also nur langsamer, ohne Vorteil.

Gute Kandidaten:

• Breite Code-Suche. „Finde jede Stelle, an der wir die Payments-APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → aufrufen, und prüfe, ob wir den Timeout-Fall behandeln.“ Ein einzelner Agent, der seriell greppt und liest, verbraucht seinen Kontext. Teilen Sie nach Verzeichnis oder nach Service.
• Audits über mehrere Dateien. Security Review, Dependency Review, Accessibility-Durchgang. Jedes Thema ist eine eigene Linse über denselben Baum.
• Mehrere wirklich unabhängige Aufgaben. Docs aktualisieren, Migration schreiben und Changelog entwerfen. Kein gemeinsamer State, also kein Grund zu serialisieren.

Fan-out ist das falsche Werkzeug, wenn die Arbeit tief und sequenziell ist: ein Refactoring, bei dem Schritt drei vom Ergebnis von Schritt zwei abhängt, oder Debugging eines einzelnen Fehlers, bei dem jeder Befund die nächste Frage eingrenzt. Dort hält eine durchgehende Konversation den Faden. Subagents, die einander nicht sehen kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen, würden denselben Kontext neu herleiten und sich möglicherweise widersprechen.

Das Mental Model: Breite geht an Subagents, Tiefe bleibt im Hauptthread.

Die Briefing-Steuer

Weil jeder Subagent bei null anfängt, zahlen Sie einen Preis: Sie müssen ihn vollständig briefen. ErErThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → kennt Ihre Architektur nicht, Ihre Namenskonventionen nicht und nicht, wie „fertig“ aussieht, solange Sie es ihm nicht im Dispatch sagen.

Ein vager Dispatch („review the auth module“) produziert eine vage Zusammenfassung. Ein Subagent kann Ihnen mitten in der Aufgabe keine Rückfrage stellen, wie es eine interaktive Session kann. Der Prompt, den Sie ihm geben, muss also in sich geschlossen sein:

• Worauf ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → schauen soll (Scope)
• Worauf ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → achten soll (die konkrete Frage)
• In welchem Format ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → berichten soll

Das ist die Disziplin, die Fan-out Ihnen abverlangt. Es ist dieselbe Disziplin, die gute Delegation von einem Menschen verlangt: Je klarer der Brief, desto nützlicher das Ergebnis.

Eigene Subagent-Typen

Sie kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen wiederverwendbare Subagent-Typen definieren, damit Sie nicht jedes Mal Briefs neu schreiben. In Claude Code liegen Subagents als Markdown-Dateien mit YAML-Frontmatter, entweder in .claude/agents/ für ein bestimmtes Projekt oder in Ihrer User-Config für alle Projekte.

Das Frontmatter legt Identität und Berechtigungen des Agenten fest. Der Body ist sein System Prompt: die stehenden Anweisungen, die ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → bei jedem Lauf bekommt.

---
name: security-auditor
description: Reviews a directory for injection, auth, and secret-handling flaws. Use for security-focused code review.
tools: Read, Grep, Glob
---

You are a security reviewer. Given a directory path, inspect the code for:
- unsanitized inputs reaching queries, shell calls, or file paths
- missing authentication or authorization checks on sensitive routes
- secrets, tokens, or keys committed in source

Report only confirmed or strongly suspected issues. For each, give the
file, the line range, the risk, and a one-line fix. If you find nothing,
say so plainly. Do not summarize the whole codebase.

Zwei Dinge sind hier bemerkenswert. Die description ist das, was der Orchestrator liest, um zu entscheiden, wann ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → an diesen Agenten delegiert. Schreiben Sie sie also für den Router, nicht für sich selbst. Und tools ist absichtlich eng gehalten: Dieser Agent kann lesen und suchen, aber nicht schreiben oder Befehle ausführen. Least Privilege gilt für Subagents genauso wie für jede andere Automatisierung.

Das vollständige SchemaSchemaA schema is the formal blueprint that defines how data is structured, named, typed, and related within a database, file, or message.Vollständige Definition ansehen → und der Unterschied zwischen Agents auf Projekt- und User-Ebene sind im Claude Code subagents guide dokumentiert.

Ein konkretes Beispiel: eine Codebase parallel auditieren

Angenommen, Sie haben einen Service übernommen mit vier großen Bereichen: api/, billing/, auth/ und workers/. Sie wollen vor einem Release einen schnellen Security-Durchgang über alle. Sequenziell würde ein Agent den gesamten Baum lesen und irgendwo um workers/ herum knapp an Platz werden.

Stattdessen sagen Sie dem Orchestrator, ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → soll fan-out machen. In einer interaktiven Claude-Code-Session heißt das einfach, es in normaler Sprache zu verlangen:

Use the security-auditor subagent to review each of these
directories in parallel: api/, billing/, auth/, and workers/.
Give me one consolidated table of findings sorted by severity.

Claude Code startet vier Instanzen von security-auditor, eine pro Verzeichnis. Jede bekommt einen frischen Kontext, liest nur ihren zugewiesenen Teil und gibt eine kurze Liste der Findings zurück. Der Orchestrator wartet auf alle vier und fügt sie dann zu der Tabelle zusammen, die Sie angefordert haben.

Was Sie in Ihrem Hauptkontext zurückbekommen, ist kompakt: vier Zusammenfassungen und eine zusammengeführte Tabelle. Was Sie *nicht* bekommen, sind die hunderte Zeilen, die jeder Agent gelesen hat, um diese Zusammenfassungen zu erstellen. Genau richtig. Sie wollten das Urteil, nicht die Beratung.

Vergleichen Sie das mit einer langen Session, die dasselbe Review macht. Bis sie bei workers/ angekommen wäre, lägen die Details von api/ weit oben im Kontext begraben, würden um Aufmerksamkeit konkurrieren und die Präzision des Modells still verschlechtern. Fan-out umgeht das vollständig, weil kein einzelner Agent mehr als seinen Teil hält.

Programmatischer Dispatch mit dem Agent SDK

Der interaktive Ablauf ist gut für einmalige Arbeit. Wenn Sie Fan-out innerhalb eines Skripts oder einer CI-PipelinePipelineAll active sales opportunities across the stages of the sales process, together with their combined potential value and probability of closing.Vollständige Definition ansehen → wollen, gibt Ihnen das Claude Agent SDK dieselbe Subagent-Mechanik im Code, sodass Sie ein Audit über mehrere Dateien in einen Pre-Release-Check einbauen kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen, der über die GitHub-Integration bei jedem Pull Request läuft.

Das Muster ist identisch: Definieren Sie die Agent-Typen einmal, dann lassen Sie den Orchestrator Arbeitsteile an sie routen. Das SDK übernimmt die parallele Ausführung und das Einsammeln der Zusammenfassungen, sodass Sie keine Threads selbst verwalten.

Die Tradeoffs, klar benannt

Fan-out ist mächtig, aber nicht kostenlos. Behalten Sie vier Kosten im Blick.

Sie verlieren das Transkript. Die Zusammenfassung ist alles, was Sie bekommen. Wenn ein Subagent zu einem falschen Schluss kommt, kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen Sie nicht einfach nachvollziehen, *wie* ererThe ratio of interactions (likes, comments, shares) to reach for a given piece of content, used to gauge how well audiences respond relative to how many people saw it.Vollständige Definition ansehen → dahin gekommen ist, ohne ihn erneut laufen zu lassen. Gestalten Sie Ihre Agent-Prompts so, dass sie Belege berichten (Datei, Zeile, Grund), nicht nur Urteile, damit die Zusammenfassung für sich prüfbar ist.

Keine gemeinsamen Erkenntnisse. Wenn der auth/-Agent ein Muster findet, das auch dem api/-Agenten helfen würde: Pech, sie kkThe average number of new users each existing user generates through referrals. Above 1.0, growth compounds on itself and becomes exponential.Vollständige Definition ansehen →önnen nicht miteinander reden. Wenn übergreifendes Wissen wichtig ist, machen Sie entweder einen ersten Durchgang, um gemeinsamen Kontext herzustellen, und packen den in jeden Brief, oder Sie halten die Arbeit in einem Thread.

Mehr Agents heißt mehr Tokens. Vier frische Kontexte, die jeweils Dateien lesen, sind insgesamt mehr Arbeit als ein Kontext, der alles einmal liest, auch wenn es in Echtzeit schneller fertig ist. Sie tauschen TokenTokenA token is the basic unit of text that language models process, often a word fragment, whole word, or punctuation mark rather than a single character.Vollständige Definition ansehen →-Effizienz gegen Geschwindigkeit und Qualität. Bei breiten Aufgaben lohnt sich das meistens, bei kleinen ist es Verschwendung.

Orchestrierungs-Overhead. Aufteilen, Dispatchen und Zusammenführen kostet selbst etwas im Hauptkontext. Wenn eine Aufgabe klein genug ist, dass ein Agent sie bequem erledigt, fügt Fan-out nur Zeremonie hinzu. Reservieren Sie es für Aufgaben, die einen einzelnen Kontext wirklich überlaufen lassen.

Eine schnelle Entscheidungsregel

Bevor Sie fan-out machen, fragen Sie: Kann ich das in Teile aufteilen, die die Ergebnisse der anderen nicht sehen müssen? Wenn ja und es mehr als zwei oder drei sind: fan out. Wenn die Teile verflochten sind oder es nur ein paar sind, bleiben Sie in einer Konversation.

Wie das in das größere Ökosystem passt

Subagents sind ein Claude-Code-Konstrukt, aber dieselbe Form taucht im gesamten Tooling von Anthropic auf. Das Agent SDK stellt es für Produktions-Agents bereit. Die Messages APIAPIApplication Programming Interface: a standardised interface that lets applications communicate and exchange data without knowing each other's internal workings.Vollständige Definition ansehen → gibt Ihnen das rohe Primitive, um eigene Orchestrierung zu bauen, wenn Sie etwas MaMaUsing software to automate repetitive marketing tasks and campaigns, enabling personalisation at scale across channels like email, web, and social.Vollständige Definition ansehen →ßgeschneidertes brauchen. Und weil Subagents MCP-Verbindungen erben, kann jeder von ihnen dieselben Tools und Datenquellen erreichen (über das Model Context Protocol), die auch Ihre Hauptsession nutzt, ohne dass Sie pro Agent etwas neu verkabeln.

Die Linie durch alles: Claudes Tooling gibt Ihnen immer wieder Wege, Kontext bewusst zu *isolieren*, statt ihn standardmäßig anwachsen zu lassen. Projects isolieren Wissen pro Workspace. Skills isolieren wiederverwendbare Abläufe. Subagents isolieren eine Arbeitseinheit. Jedes ist eine andere Antwort auf dieselbe Realität des endlichen Kontexts.

Key Takeaways

• Fan out, wenn die Arbeit breit und trennbar ist, nicht tief und sequenziell. Breite Suchen, Audits über mehrere Dateien und unabhängige Aufgaben sind der Sweet Spot. Refactorings und die Jagd nach einem einzelnen Bug gehören in einen Thread.
• Briefen Sie jeden Subagent vollständig. Frischer Kontext heißt keine gemeinsame Historie und keine Möglichkeit, Rückfragen zu stellen. Scope, Frage und Berichtsformat gehören in den Dispatch.
• Definieren Sie wiederverwendbare Agent-Typen in `.claude/agents/`. Schreiben Sie die description für den Router und geben Sie nur die Tools frei, die jeder Agent braucht.
• Gestalten Sie Prompts so, dass sie Belege zurückgeben, nicht nur Urteile. Sie bekommen nur die Zusammenfassung zurück, machen Sie sie also für sich prüfbar.
• Kennen Sie den Handel: Geschwindigkeit und Kontextqualität hoch, Token-Kosten und agentenübergreifende Sichtbarkeit runter. Reservieren Sie Fan-out für Aufgaben, die einen einzelnen Kontext wirklich überlaufen lassen.