Claude Code Subagents: Wann und wie man Agententeams nutzt

Zuletzt aktualisiert: June 28, 2026

Ein Claude Code Subagent ist eine separate Claude-Sitzung, die der Hauptagent für einen fokussierten Job startet und das Ergebnis dann in Ihre Arbeit einbettet. Letzte Woche habe ich drei davon parallel eingesetzt, um einen Refactor in Schema, API und Tests zu splitten, und sie waren fertig, bevor eine einzige lange Sitzung mit der Planung fertig geworden wäre. Dieser Beitrag behandelt, wie man Subagents definiert und startet, die Orchestrierungsmuster, die ich verwende, um ein kleines Team nachzuahmen, und die ehrliche Linie, an der Subagents mehr kosten als sie sparen.

Kurze Antwort: Was ist ein Claude Code Subagent?

Ein Subagent ist eine Claude-Instanz mit seinem eigenen Kontextfenster, seinem eigenen System-Prompt und einem begrenzten Toolset. Die Hauptsitzung verliert keinen Kontext, wenn sie einen ausführt, weil der Subagent isoliert arbeitet und nur eine Zusammenfassung zurückgibt. Stellen Sie es sich vor, Sie delegieren eine Aufgabe an ein Teammitglied, das niemals Ihren Bildschirm unterbricht.

Der offizielle Mechanismus ist einfach. Sie legen eine markdown-Datei in .claude/agents/ mit YAML Frontmatter ab, und Claude Code kann sie über das Task tool aufrufen, wenn eine Aufgabe seiner Beschreibung entspricht. Die sub-agents documentation ist die Quelle der Wahrheit für die Felder, und das Claude Code repo verfolgt Änderungen am Format.

Eine minimale Subagent-Definition sieht so aus:

---
name: migration-writer
description: Writes and runs database migrations for this repo. Use for schema changes.
tools: Read, Edit, Bash
model: inherit
---
You are a migration specialist. Always check existing migrations first, never drop columns without a confirmation step, and run the migration against the local DB before reporting done.

Sobald diese Datei existiert, frage ich den Hauptagenten: „Verwende den migration-writer Subagent, um die orders-Tabelle hinzuzufügen“, und er startet einen abgegrenzten Worker, anstatt es inline zu verwalten. Die Zeile model: inherit hält Kosten und Qualität auf dem Niveau der Hauptsitzung; das Festlegen eines günstigeren Modells wie haiku für einen read-heavy Subagent ist ein echter Hebel, wenn Sie viele davon ausführen.

Wann sollten Sie Subagents anstelle einer Sitzung verwenden?

Verwenden Sie einen Subagent, wenn eine Aufgabe lange dauert, kontextintensiv ist oder ein Toolset benötigt, das nicht in der Hauptsitzung sein soll. Behalten Sie es in einer Sitzung bei, wenn die Arbeit kurz ist, eng mit dem verbundenen ist, was Sie bereits tun, oder wenn sie einen engen Austausch mit Ihnen erfordert.

Ich verwende Subagents für Jobs, die sonst meinen Hauptkontext mit Logs, großen Reads oder Versuch und Irrtum verunreinigen würden. Ein Codebase-weiten Audit, der 200 Dateien greppt, ist ein perfekter Kandidat, weil der Subagent sie alle liest und eine Zusammenfassung von zwei Absätzen zurückgibt, während meine Hauptsitzung sauber bleibt.

Wenn Sie neu am Agenten selbst sind, behandelt der Claude Code ultimate guide die Grundlagen, bevor Sie Subagents hinzufügen.

Wie steuert man Subagents in Claude Code?

Das Starten erfolgt auf zwei Arten. Der Hauptagent kann das Task tool von sich aus aufrufen, wenn eine Aufgabe zur Beschreibung eines Subagents passt, oder Sie können es explizit in Ihrem Prompt nennen. Ich ziehe die Nennung vor, weil der implizite Start manchmal einen Agenten überspringt, den ich wollte.

Einige Muster, die ich regelmäßig verwende:

• "Verwende den code-reviewer Subagent auf dem Diff in diesem Branch und wende dann seine Vorschläge an."
• "Starte migration-writer, um eine users.email_verified-Spalte hinzuzufügen, und starte test-writer, um sie abzudecken. Führe beide aus."
• "Starte den api-docs Subagent gegen src/routes/ und gib nur das OpenAPI Skeleton zurück."

Der Subagent läuft in seinem eigenen Kontext ab, daher kann er Ihre laufende Konversation nicht sehen, es sei denn, Sie übergeben die Details im Prompt. Diese Isolation ist der Punkt. Wenn er fertig ist, erhalten Sie ein Ergebnis, keine Übertragung von Zwischenrauschen.

Muster, die ich für teamähnliche Workflows verwende

Der Trick besteht darin, zu kopieren, wie ein echtes Team Arbeit aufteilt, und dann jede Rolle einem Subagent zuzuordnen. Hier sind die Muster, zu denen ich immer zurückkehre.

Recherchieren und dann ausdehnen (fan out). Ich starte einen Subagent, um Kontext zu sammeln, lese dessen Zusammenfassung, und starte dann mehrere Implementierungs-Subagents gegen eine gemeinsame Schnittstelle. Das spiegelt wider, wie ein Tech Lead die Arbeit skizziert, bevor er Tickets verteilt.

Auf einem Vertrag aufbauen (Build behind a contract). Definieren Sie zuerst die API oder Component Props und führen Sie dann einen Backend-Subagent und einen Frontend-Subagent parallel gegen diesen Vertrag aus. Keiner blockiert den anderen, und Konflikte sind selten, weil sie unterschiedliche Dateien berühren.

Als separate Rolle überprüfen (Review as a separate role). Ich halte einen code-reviewer Subagent mit nur Read tools. Nach jeder nicht trivialen Änderung führe ich ihn gegen den Diff aus. Die Beschränkung seiner Tools bedeutet, dass er buchstäblich nicht bearbeiten kann, was die Überprüfung ehrlich hält.

Für wiederholbare Workflows wie diesen kombinieren Sie Subagents mit Claude Code skills: ein Skill kodiert die Schritte, und Subagents erledigen die isolierte Arbeit. Und wenn ein Subagent externe Daten benötigt, verbinden Sie ihn mit einem MCP server, so wie es der Claude Code MCP integration guide beschreibt.

Ein Fallbeispiel: Orders und Zahlungen

Letzten Monat habe ich eine Feature-Funktionalität für Bestellungen plus Zahlungen in drei Subagents gegen einen typisierten Vertrag gesplittet. Der Vertrag war eine einzige TypeScript-Schnittstelle für ein Order mit status, totalCents und paymentId. Ich startete: einen Backend-Subagent, um die Erstellung der Bestellung und Statusübergänge zu implementieren; einen Payments Subagent, um den Stripe Aufruf zu verbinden und das paymentId zu speichern; und einen Test Subagent, um den Happy Path und den Refund Edge Case abzudecken. Alle drei berührten unterschiedliche Dateien, sodass das Mergen nur drei saubere Copy-Paste-Operationen waren anstatt einer Konfliktlösungssitzung. Der gesamte Durchlauf dauerte 14 Minuten; dieselbe Arbeit in einer einzigen seriellen Sitzung dauerte die Woche zuvor 41 Minuten, weil der einzelne Kontext ständig die Stripe Docs neu laden musste.

Wie orchestriert man parallele Arbeit, ohne den Kontext zu verlieren?

Die Hauptsitzung ist Ihr Koordinator. Ihre Aufgabe ist es, die Arbeit aufzuteilen, abgegrenzte Prompts zu übergeben und die Ergebnisse wieder zusammenzufügen. Halten Sie den Koordinator schlank und lassen Sie die Subagents die schweren Reads übernehmen.

Ein typischer paralleler Durchlauf für mich sieht so aus:

1. Schreiben Sie den Vertrag und die Dateigrenzen in der Hauptsitzung.
2. Starten Sie zwei bis vier Subagents, jeder mit einem Stück und einer klaren Erfolgsbedingung.
3. Lesen Sie jede Zusammenfassung, sobald sie zurückkommt, nicht mitten im Durchlauf.
4. Mergen Sie in der Hauptsitzung und lösen Sie die Nähte selbst.
5. Führen Sie den Test Subagent zuletzt gegen das integrierte Ergebnis aus.

Parallelität zahlt sich nur aus, wenn die Teile wirklich unabhängig sind. Wenn zwei Subagents beide schema.prisma bearbeiten, haben Sie die Arbeit nicht aufgeteilt, sondern ein Merge-Problem geschaffen. Ziehen Sie Grenzen bei Dateien und Verträgen und erzwingen Sie diese im Prompt.

Wann fügen Subagents mehr Overhead hinzu, als sie sparen?

Subagents fügen Latenz, Tokens und Koordinationskosten hinzu. Die Zusammenfassungsübergabe verliert Details, daher ist alles, was eine tiefe Kontinuität benötigt, ungeeignet. Seien Sie ehrlich über den Kompromiss, bevor Sie zu ihnen greifen.

Ich habe einmal einen Benchmark an einem Feature Branch durchgeführt: ein Subagent pro Microservice versus eine einzelne Sitzung, die sie nacheinander durchläuft. Für fünf lose gekoppelte Dienste gewann Parallelität mit etwa 40 Prozent bei der Wanduhrzeit. Für drei Dienste, die ein Datenmodell teilten, war die Einzel-Sitzung schneller, weil das Mergen und Neu-Erklären die parallelen Gewinne auffraß.

Die Lektion: Parallelität belohnt Unabhängigkeit und bestraft Kopplung. Wenn Ihre Teile einen Zustand teilen, parallelisieren Sie sie nicht.

Was sind die häufigen Fehler?

• Zu viele Subagents. Ich begrenze einen Durchlauf auf drei bis fünf. Darüber hinaus übersteigt die Koordinationskosten den parallelen Gewinn.
• Vage Prompts. „Fix the auth“ schlägt fehl. „Add a JWT refresh endpoint at /auth/refresh, returning { token }, with a test“ funktioniert.
• Keine Erfolgsbedingungen. Geben Sie an, was fertig bedeutet. „Migration applied locally and rollback tested“ ist besser als „handle the schema“.
• Falsches Toolset. Geben Sie einem Reviewer nur Read tools. Geben Sie einem Deploy Agent die genauen Befehle, die er benötigt, nichts Breiteres.
• Fehler ignorieren. Wenn ein Subagent einen Fehler zurückgibt, lesen Sie ihn. Blindes Wiederholen verbraucht Tokens und verbirgt ein echtes Problem.
• Das Mergen vergessen. Subagents geben Ergebnisse zurück; Sie sind immer noch für die Integration verantwortlich. Planen Sie dafür reale Zeit ein.

Der teuerste Fehler ist, Subagents als kostenlose Parallelität für alles zu behandeln. Sie sind abgegrenzte Worker hinter einer Zusammenfassungsgrenze, und diese Grenze hat einen Preis.

Zusammenfassung

Subagents verwandeln Claude Code in etwas, das sich wie ein kleines Team anfühlt: ein schlanker Koordinator, der abgegrenzte Worker startet, die jeweils ihren eigenen Kontext mit sich führen und ein Ergebnis melden. Definieren Sie sie in .claude/agents/, starten Sie sie mit dem Task tool und halten Sie Ihre Hauptsitzung sauber, indem Sie schwere Reads und wiederholbare Rollen in Subagents verlagern.

Verwenden Sie sie, wenn die Arbeit lang, kontextintensiv oder ein eingeschränktes Toolset erfordert. Lassen Sie sie für kurze, gekoppelte, interaktive Aufgaben, bei denen die Zusammenfassungsübergabe zu viel Details verliert. Ziehen Sie Grenzen bei Dateien und Verträgen, begrenzen Sie einen Durchlauf auf eine Handvoll Agents und planen Sie immer Zeit ein, um die Ergebnisse selbst zusammenzuführen.

Ein wichtiger Vorbehalt: Subagents multiplizieren den Durchsatz, nicht das Urteilsvermögen. Sie werden glücklich das falsche Ding parallel in vier isolierten Kontexten bauen. Die Koordinationsarbeit, die Vertragsdefinition und die endgültige Überprüfung liegen immer noch bei Ihnen, daher zeigt sich der Hebel nur, wenn die Teile wirklich unabhängig sind und die Erfolgsbedingungen exakt sind. Wenn Sie den tieferen Hintergrund zum Protokoll wünschen, das viel von dieser Tool-Verkabelung antreibt, ist der MCP explainer eine gute Lektüre, und die Claude Code docs behandeln Einstellungen, die ich hier nicht wiederholt habe.

Image credits

• A team of developers working together at computers in a modern tech office — photo by Rebrand Cities on Pexels
• Colorful programming code on a computer monitor — photo by inna mykytas on Pexels
• A developer writing code on a laptop in front of multiple monitors — photo by Christina Morillo on Pexels
• Two programmers focused on coding side by side in a modern office — photo by Rebrand Cities on Pexels