Was sind Subagenten und wie nutzt man sie in Coding-Tools?

Ein Subagent arbeitet in eigenem Kontext und liefert Ihnen das Ergebnis

Bekommt ein Coding-Agent eine große Aufgabe, gibt es zwei Wege: Die Hauptkonversation erledigt alles selbst, oder sie übergibt einen Teil der Arbeit an einen Subagenten. Der Subagent erledigt diesen Teil in seinem eigenen Kontext. Die Dateien, die er liest, und die Tests, die er laufen lässt, füllen nicht die Hauptkonversation.

Die Dokumentation von Cursor sagt es in zwei Sätzen: “Intermediate output stays in the subagent. The parent only sees the final summary.” Stand 18. Oktober 2026 gibt es Subagenten in fünf Tools: Claude Code, Codex von OpenAI, Cursor, Gemini CLI von Google und GitHub Copilot. Claude Code, Cursor und Copilot sprechen vom eigenen Kontextfenster des Subagenten. Gemini CLI spricht von einer eigenen Kontextschleife, und Codex startet Agenten parallel und sammelt ihre Ergebnisse in einer einzigen Antwort.

Deshalb lohnen sich Subagenten bei zwei Arten von Arbeit: bei Aufgaben mit viel Ausgabe (Tests laufen lassen, Logs durchsuchen, Dutzende Dateien lesen) und bei Recherchen, die nicht voneinander abhängen. Die Beispiele stammen aus dem Repository, in dem wir diffox jeden Tag weiterentwickeln; dort läuft Claude Code.

Ein Subagent sieht Ihren Gesprächsverlauf nicht, also muss der Auftrag für sich stehen

Der häufigste Fehler mit Subagenten ist die Annahme, sie wüssten, was in der Hauptkonversation besprochen wurde. Laut der Dokumentation von Claude Code startet ein Subagent mit einem neuen Kontextfenster: Ihren Gesprächsverlauf, die schon aufgerufenen Skills und die Dateien, die Claude gelesen hat, sieht er nicht. Beim Start hat er Folgendes:

Deshalb muss der Auftrag für sich allein sagen, was das Ziel ist, welche Dateien der Subagent anfassen darf und was er berichten soll. Was Sie in der Hauptkonversation „diesen Fehler“ genannt haben, gibt es für den Subagenten nicht; schreiben Sie Dateipfad, Fehlermeldung und die erwartete Ausgabe hinein. Die Dokumentation von Cursor sagt dasselbe: Subagenten starten mit leerem Kontext und haben keinen Zugriff auf den bisherigen Gesprächsverlauf. Die Dokumentationen von Codex, Gemini CLI und Copilot erwähnen das nicht. Mit welchem Tool Sie auch arbeiten: Ein Auftrag, der für sich allein verständlich ist, ist der sichere Weg. Die Dokumentation von Codex empfiehlt außerdem, vom Subagenten statt der Zwischenausgaben eine Zusammenfassung zurückzufordern.

Wie die fünf Tools Subagenten definieren und wann sie Arbeit abgeben

In allen fünf Tools wird ein Subagent mit einer Datei definiert, die auf Projekt- oder Benutzerebene liegt. Die Tools unterscheiden sich vor allem darin, ob der Hauptagent Arbeit von sich aus abgibt:

Quelle: die Subagent-Dokumentation des jeweiligen Tools, 18. Oktober 2026. In Codex ist die Definition eine TOML-Datei, in den anderen eine Markdown-Datei mit YAML-Kopf. Der Browser-Agent von Gemini CLI ist standardmäßig aus. Die Liste der eingebauten Agenten von Copilot ist nicht auf jeder Seite gleich: Die Referenzseite zählt sieben, die Anleitungsseite vier.

Die Tools unterscheiden sich vor allem in der dritten Spalte. In Codex hängt die Antwort von der Effort-Stufe ab: Die Seite zu den Modellen schreibt, dass die höchste Stufe, Ultra, die Arbeit auf Subagenten verteilt. Die Seite zu Subagenten sagt, dass das lokale Codex einen Subagenten auf eine direkte Bitte wie „starte zwei Agenten“ hin startet oder auf eine Anweisung in AGENTS.md oder einem Skill. In den anderen vier Tools kann der Hauptagent Arbeit auch von sich aus abgeben; die Dokumentation von Copilot sagt außerdem ausdrücklich, dass das Modell die Arbeit auch selbst erledigen kann, statt sie abzugeben.

Definitionen wandern zwischen den Tools: Cursor liest auch die Ordner .claude/agents/ und .codex/agents/ (bei gleichem Namen gewinnt .cursor/), und die Copilot CLI liest .claude/agents/. Eine Datei unter .claude/agents/ lesen also Claude Code, Cursor und die Copilot CLI. Dass die Frontmatter-Felder in allen dreien gleich wirken, garantieren die Dokumentationen nicht.

Google hat Gemini CLI am 18. Juni 2026 für kostenlose Nutzer sowie für Abonnenten von Google AI Pro und Ultra eingestellt und sie auf Antigravity CLI verwiesen; mit einem kostenpflichtigen API-Schlüssel oder einer Firmenlizenz können Sie Gemini CLI weiter nutzen. Die Subagent-Dokumentation von Antigravity haben wir am 28. Oktober 2026 gelesen. Subagenten werden für ein Projekt in .agents/agents/ und für den Benutzer in ~/.gemini/config/agents/ definiert. Der Hauptagent übergibt eine Aufgabe anhand der Beschreibung des Subagenten; drei Agenten sind eingebaut: research, browser und self. Ein Subagent bekommt den Gesprächsverlauf des Hauptagenten nicht und beginnt mit einem leeren Kontext; nennt seine Definition kein Modell, läuft er mit dem Modell des Hauptagenten. Verschachteln lassen sich Subagenten bis zu 10 Ebenen tief.

Ein guter Subagent hat eine enge Aufgabe, wenige Werkzeuge und berichtet kurz

Die Definitionsdatei legt drei Dinge fest: wann der Subagent aufgerufen wird (Beschreibung), worauf er zugreift (Werkzeuge) und was er zurückgibt (Prompt). In Claude Code sieht sie so aus; Pflichtfelder sind name und description:

---
name: test-runner
description: Führt die Tests aus und meldet nur die fehlgeschlagenen
tools: Read, Grep, Glob, Bash
model: haiku
---

Führe die Testsuite aus. Melde nur die fehlgeschlagenen Tests, jeden
mit seiner Fehlermeldung. Bearbeite keine Datei.

• Die Beschreibung ist ein Auslöser. Claude Code und Gemini CLI geben Arbeit anhand der Beschreibung ab. Schreiben Sie hinein, wann der Agent aufgerufen werden soll, nicht, was er ist.
• Schränken Sie die Werkzeuge ein. In Claude Code begrenzt das Feld tools, welche Werkzeuge der Subagent nutzen darf. Lassen Sie es weg, erbt er alle Werkzeuge, die Subagenten zur Verfügung stehen. Geben Sie einem Agenten, der nur lesen soll, kein Werkzeug zum Schreiben.
• Berechtigungen kommen vom Hauptagenten. In Codex erbt der Subagent die Berechtigungen, den Anbieter und die MCP-Server des Hauptagenten; die Definitionsdatei kann daran nichts ändern. Auch Sandbox und Freigabe-Einstellung sind die des Hauptagenten.
• Fordern Sie einen kurzen Bericht an. Der letzte Satz des Prompts sollte sagen, was zurückkommt: fehlgeschlagene Tests, gefundene Dateien, eine Entscheidung. Wandert lange Zwischenausgabe zurück in die Hauptkonversation, ist der Vorteil des Subagenten dahin.
• Sie können die automatische Nutzung abschalten. Im Cloud-Agenten von Copilot läuft ein Agent mit disable-model-invocation: true nur, wenn er von Hand ausgewählt wird. Der Prompt eines benutzerdefinierten Agenten darf in Copilot höchstens 30.000 Zeichen lang sein.

Modell, Parallelität und Verschachtelung regelt jedes Tool anders

Steht in der Definition kein Modell, läuft der Subagent laut Dokumentation in Claude Code, Codex, Cursor und Copilot mit dem Modell des Hauptagenten. Die Subagent-Seite von Gemini CLI schreibt dasselbe. Die Modell-Seite derselben Dokumentation sagt aber, dass der Befehl /model und das Flag --model das Modell der Subagenten nicht ändern; beides passt nicht ganz zusammen. Wie viele Subagenten gleichzeitig laufen können und ob ein Subagent selbst einen Subagenten starten kann, ist von Tool zu Tool verschieden:

Quelle: die Subagent-Dokumentation des jeweiligen Tools, 18. Oktober 2026. „Steht nicht in der Dokumentation“ heißt: Auf den Seiten, die wir an diesem Tag gelesen haben, fanden wir keinen Satz mit dieser Angabe. Die Referenzseite der Copilot CLI nennt im Abschnitt zu Umgebungsvariablen eine Tiefe von 4, in der Tabelle der Grenzen 6. Gemini CLI begrenzt jeden Subagenten standardmäßig auf 30 Runden und 10 Minuten.

Claude Code sucht das Modell der Reihe nach an vier Stellen: im Parameter model des jeweiligen Aufrufs, im Feld model der Definition, in der Umgebungsvariable CLAUDE_CODE_SUBAGENT_MODEL und zuletzt beim Modell der Hauptkonversation. Auch was an der Grenze passiert, ist dokumentiert: Laufen 20 Subagenten, lässt sich kein neuer starten, und die Fehlermeldung sagt Claude, es nicht noch einmal zu versuchen. Gemini CLI schaltet verschachtelte Aufrufe ab, um Endlosschleifen und übermäßigen Token-Verbrauch zu verhindern.

Die Effort-Stufe ändert in den meisten Tools nichts an der Zahl der Subagenten

Alle fünf Tools haben eine Einstellung dafür, wie gründlich das Modell nachdenkt, bevor es antwortet: Effort oder Reasoning-Stufe. Für Subagenten zählen dabei zwei Fragen: Erbt der Subagent die Stufe des Hauptagenten, und kann er seine eigene wählen?

Quelle: die Modell- und Subagent-Dokumentation des jeweiligen Tools, 18. Oktober 2026. In Cursor heißen die Stufen je nach Modell anders.

Die Dokumentationen von Claude Code, Cursor, Gemini CLI und Copilot verknüpfen Effort nicht mit der Zahl der Subagenten. Die Dokumentation von Claude Code beschreibt den Unterschied auf hoher Stufe so: “tested more edge cases and verified more of its work before answering. It also made more choices on its own.” Von der Zahl der Subagenten ist dort keine Rede. In Copilot hängen parallele Subagenten nicht am Effort, sondern an einem eigenen Modus: Beim Befehl /fleet entscheidet der Hauptagent selbst, ob er die Arbeit in Teile zerlegt.

Die Ausnahme ist die höchste Stufe von Codex, ultra. Die Seite zu den Modellen schreibt für CLI, App und IDE denselben Satz: “Ultra mode goes beyond a single-agent run. It uses subagents to accelerate complex work.” Auch in ChatGPT Work erlaubt Ultra, passende Arbeit von selbst an Subagenten abzugeben. Auf den anderen Stufen startet das lokale Codex laut der Seite zu Subagenten einen Subagenten, wenn Sie darum bitten oder AGENTS.md oder ein Skill es vorgibt.

Ultracode verteilt in Claude Code die Arbeit auf Dutzende Subagenten

Im Regler /effort von Claude Code gibt es neben den Effort-Stufen auch einen Schalter für ultracode. Die Dokumentation beschreibt ihn nicht als Stufe, sondern als eigene Einstellung: “a Claude Code setting rather than a model effort level”. Ist er an, plant Claude für jede nicht triviale Aufgabe ungefragt einen dynamischen Workflow: Es schreibt ein Skript, das die Arbeit aufteilt und die Subagenten steuert, und eine Laufzeitumgebung führt das Skript im Hintergrund aus. Ihre Sitzung reagiert währenddessen weiter.

Einschalten lässt sich ultracode auf vier Wegen:

• Für eine einzelne Aufgabe: Schreiben Sie das Wort ultracode in Ihren Prompt; die Effort-Stufe der Sitzung bleibt gleich. Das Wort zählt nur in einem Prompt, den Sie selbst geschrieben haben.
• Für die ganze Sitzung: /effort ultracode oder der Schalter im Regler.
• Beim Start: claude --effort ultracode; das setzt auch die Effort-Stufe auf xhigh.
• In jeder Sitzung: "ultracode": true in der Einstellungsdatei.

Die Kehrseite nennt die Dokumentation offen: Jede Anfrage verbraucht mehr Tokens und dauert länger, und im Abo erreichen Sie das Sitzungs- oder Wochenlimit früher. Mit ultracode gilt die Grenze von 20 Subagenten nicht; der Workflow hat eigene Grenzen: standardmäßig 16 Agenten gleichzeitig und höchstens 1.000 Agenten pro Lauf. Ohne ultracode zeigt ein Workflow mit mehr als 25 Agenten oder einer Schätzung von über 1,5 Millionen Tokens die Warnung “Large workflow”; mit ultracode erscheint auch diese Warnung nicht.

Dynamische Workflows kamen Ende Mai 2026 und wurden im Wochenrückblick als “research preview” angekündigt; auf der Workflow-Seite stand am 18. Oktober 2026 kein Status-Hinweis. Verwechseln Sie ultracode nicht mit zwei ähnlich klingenden Dingen: ultrathink verlangt nur für diese Runde gründlicheres Nachdenken und ändert die Effort-Stufe nicht. /code-review ultra ist ein eigener Befehl, der Review-Agenten in der Cloud laufen lässt, und Claude startet ihn nicht von selbst.

Ob Subagenten miteinander sprechen können, hängt vom Tool ab

Das Ergebnis eines Subagenten geht an den, der ihn aufgerufen hat; das ist in allen fünf Tools gleich. Unterschiede gibt es bei drei Fragen: Können Subagenten einander schreiben? Kann der Hauptagent einem laufenden oder fertigen Subagenten nachträglich schreiben? Gibt es eine Team-Funktion?

Quelle: die Dokumentation des jeweiligen Tools, 18. Oktober 2026. Damit Copilot-Agenten ihren Geschwistern schreiben können, muss die gemeinsame Geschwister-Kommunikation aktiv sein; wie man sie einschaltet, steht nicht in der Dokumentation.

Die Agent Teams von Claude Code gehen hier am weitesten: Eine Sitzung leitet das Team, die Mitglieder sind eigene Sitzungen, jedes arbeitet in seinem eigenen Kontextfenster und schreibt den anderen mit Namen. Eine Nachricht an alle gibt es nicht; jeder Empfänger bekommt eine eigene. Das Kriterium der Dokumentation: “Use subagents when you need quick, focused workers that report back. Use agent teams when teammates need to share findings, challenge each other, and coordinate on their own.” Agent Teams sind experimentell und standardmäßig aus. Sie verbrauchen mehr Tokens, weil jedes Mitglied eine eigene Claude-Instanz ist.

Dass Agenten einander schreiben können, heißt nicht, dass man sich darauf stützen sollte. Am robustesten ist es weiterhin, die Arbeit in unabhängige Teile zu zerlegen und die Ergebnisse im Hauptagenten zusammenzuführen. Das sagt auch die Fleet-Dokumentation von Copilot: Koordiniert wird über einen ausdrücklichen Zustand, nicht über ein stillschweigend geteiltes Gedächtnis, und Subagenten behalten zwischen zwei Aufrufen keinen Zustand. Geben Sie jedem den vollständigen Kontext.

Parallele Agenten arbeiten sicher mit eigenem Worktree und eigenen Dateien

Subagenten, die nur lesen, können im selben Verzeichnis nebeneinander arbeiten. Das Problem beginnt, wenn mehrere Agenten Dateien bearbeiten und committen: Sie teilen sich Verzeichnis, Branch und Git-Index. Das ist ein Git-Problem, ganz gleich, welches Tool Sie nutzen. In unserem Repository gibt es dafür vier Regeln.

Eigener Worktree. Schreiben Sie in Claude Code isolation: worktree in die Definition, bekommt der Subagent einen temporären Worktree, also ein eigenes Arbeitsverzeichnis des Repositorys. Endet der Subagent ohne Änderungen, wird der Worktree automatisch entfernt. Laut Dokumentation entsteht dieser Worktree standardmäßig nicht aus dem Branch, auf dem Sie gerade arbeiten, sondern aus dem Standard-Branch des Repositorys.

Eigene Dateien. Für Agenten, die sich ein Verzeichnis teilen, gilt bei uns: Jeder committet nur seine eigenen Pfade (git commit --only <Pfade>), denn ein bloßes git commit nimmt den ganzen Index mit, auch die Arbeit, die ein anderer Agent vorbereitet hat. Geben Sie beim Aufteilen jedem Agenten eine eigene Gruppe von Dateien.

Ein Auftrag, der für sich steht. In Claude Code und Cursor sieht der Subagent Ihren Gesprächsverlauf nicht. Der Auftrag muss für sich allein sagen, was das Ziel ist, welche Dateien er anfassen darf und was er berichten soll. Hooks aus der Einstellungsdatei greifen dagegen von selbst: In Claude Code läuft ein PreToolUse-Hook auch vor den Werkzeugaufrufen eines Subagenten.

Aufräumen. Ein Worktree mit Änderungen bleibt auf der Festplatte. In unserem Repository hatten sich am 27. August 2026 41 Worktrees angesammelt, 37 davon aus einer einzigen Review-Runde. Die Unordnung kam nicht von Menschen, sondern von Workflows, also wurde auch die Lösung dort eingebaut: Jede Sitzung beginnt mit einem Skript, das die Branches gemergter Pull Requests und die Worktrees abgeschlossener Arbeit entfernt.

Nicht jede Aufgabe braucht einen Subagenten

Ein Subagent schont den Kontext, baut seinen eigenen aber von Grund auf neu auf. Auch den Auftrag zu schreiben und das Ergebnis zu lesen, kostet etwas. Die Dokumentation von Claude Code empfiehlt in diesen Fällen die Hauptkonversation:

• Wenn viel Hin und Her nötig ist. Sie verbessern die Arbeit gemeinsam, Schritt für Schritt.
• Wenn die Phasen denselben Kontext teilen. Planung, Umsetzung und Tests stützen sich auf dasselbe Wissen.
• Wenn die Änderung klein und das Ziel klar ist. Ein paar Zeilen in einer Datei.
• Wenn es auf Tempo ankommt. Ein Subagent fängt bei null an, und Kontext zu sammeln braucht Zeit.

Subagenten passen zu Aufgaben, die eine einzelne Frage für sich beantworten: „Lass die Tests laufen und bring mir die fehlgeschlagenen“, „Wer ruft dieses Modul auf?“, „Vergleiche diese drei Bibliotheken“. Auch das Review von diffox beruht auf dieser Idee: Es teilt das KI-Code-Review auf spezialisierte Agenten auf, und jeder sieht sich die Änderung mit seiner eigenen Frage an. Wie sie ausgewählt werden, beschreibt unser Architekturbeitrag.