Wer länger mit Claude Code arbeitet, kennt das Problem: Nach einer ausgiebigen Suche durch die Codebasis ist das Kontextfenster voll mit Dateiinhalten, die für die eigentliche Umsetzung kaum noch relevant sind. Subagents lösen das, indem sie Teilaufgaben in einem eigenen, getrennten Kontext erledigen und nur das Ergebnis zurückmelden. Richtig eingesetzt werden sie zu spezialisierten Kollegen für Review, Tests oder Recherche. Falsch eingesetzt erzeugen sie vor allem Overhead. Hier erfahren Sie, wie Sie den Unterschied treffen.
Wie Subagents technisch funktionieren
Ein Subagent ist eine Markdown-Datei mit YAML-Frontmatter im Ordner .claude/agents des Projekts oder im Benutzerverzeichnis. Das Frontmatter enthält einen Namen, eine Beschreibung, optional eine Liste erlaubter Tools und ein Modell. Der Text darunter ist der Systemprompt des Subagents.
Der Hauptagent entscheidet anhand der Beschreibung, wann er einen Subagent aufruft, oder Sie fordern ihn explizit an. Der Subagent startet mit frischem Kontext, arbeitet seine Aufgabe ab und liefert eine Zusammenfassung. Die vielen Zwischenschritte landen nicht im Hauptgespräch. Mit dem Befehl /agents legen Sie Subagents interaktiv an und bearbeiten sie.
Projekt-Subagents im Repository haben Vorrang vor gleichnamigen Subagents im Benutzerverzeichnis. Das ist praktisch, wenn ein Team einen gemeinsamen Reviewer pflegt, einzelne Personen aber zusätzlich eigene Helfer für ihre Arbeitsweise nutzen möchten. Achten Sie darauf, dass Namen eindeutig sind und in Kleinbuchstaben mit Bindestrichen geschrieben werden, damit Aufrufe zuverlässig funktionieren.
Wann sich ein Subagent lohnt
Faustregel: Ein Subagent lohnt sich, wenn die Teilaufgabe viel Kontext liest, aber wenig Ergebnis produziert. Klassische Beispiele sind die Suche nach allen Stellen, an denen eine Funktion verwendet wird, die Analyse eines fehlschlagenden Testlaufs oder ein unabhängiges Code-Review des eigenen Diffs. Auch für Aufgaben, die mit eingeschränkten Rechten laufen sollen, sind Subagents ideal: Ein Review-Agent braucht nur Lese-Tools, keinen Schreibzugriff.
Kein Subagent ist nötig für kleine, eng verzahnte Änderungen, bei denen der Hauptagent ohnehin jede Zeile kennen muss. Jede Übergabe kostet Zeit und Token, und Informationen, die nicht in der Zusammenfassung stehen, gehen verloren.
Eine einfache Prüffrage hilft bei der Entscheidung: Würde ein erfahrener Kollege diese Teilaufgabe an jemanden abgeben und nur das Ergebnis lesen wollen? Wenn ja, ist sie ein guter Kandidat für einen Subagent. Wenn er dagegen jeden Zwischenschritt selbst sehen müsste, bleibt die Arbeit besser beim Hauptagenten.
Einen guten Subagent schreiben
Die Beschreibung ist der wichtigste Teil, denn sie steuert die automatische Auswahl. Formulieren Sie konkret, wann der Agent zum Einsatz kommt, etwa: nach jeder abgeschlossenen Änderung an Backend-Code einsetzen, um Sicherheitsprobleme und fehlende Tests zu finden.
- Legen Sie mit /agents einen neuen Projekt-Subagent an, damit er im Repository versioniert wird.
- Schränken Sie die Tools auf das Nötige ein, für ein Review etwa Read, Grep und Glob.
- Beschreiben Sie im Systemprompt das erwartete Ausgabeformat, zum Beispiel eine priorisierte Liste mit Datei und Zeile.
- Wählen Sie bei einfachen Rechercheaufgaben ein schnelleres, günstigeres Modell.
- Testen Sie den Subagent an zwei, drei echten Aufgaben und schärfen Sie Beschreibung und Prompt nach.
Bewährte Rollen für Teams
In vielen Projekten haben sich vier Rollen etabliert: ein Code-Reviewer mit Leserechten, ein Test-Runner, der Tests ausführt und Fehler zusammenfasst, ein Explorer für Architekturfragen in fremden Modulen und ein Dokumentations-Agent, der nach Änderungen README und Kommentare prüft. Wichtig ist, dass die Rollen sich nicht überlappen, sonst wählt der Hauptagent unzuverlässig.
Ein häufiger Fehler ist ein Subagent mit vagem Namen wie helper und allen Tools. Er wird entweder nie oder ständig aufgerufen und bringt keinen Vorteil gegenüber dem Hauptagenten.
Ebenso problematisch sind Subagents, deren Ausgabe zu lang ist. Wenn der Reviewer seitenweise Anmerkungen zurückgibt, wandert der eingesparte Kontext doch wieder ins Hauptgespräch. Begrenzen Sie die Rückmeldung deshalb ausdrücklich, etwa auf die zehn wichtigsten Punkte mit kurzer Begründung, und lassen Sie Details bei Bedarf gezielt nachfragen.
Subagents in der Praxis verankern
Subagents entfalten ihren Wert, wenn sie zur Arbeitsweise des Teams passen und gemeinsam gepflegt werden. Im Agentic-Coding-Training von neooutput entwerfen unsere AI Code Engineers mit Ihnen passende Rollen für Ihre Codebasis und zeigen, wie Subagents mit Hooks, Slash Commands und CLAUDE.md zusammenspielen. Für einen ersten Abgleich Ihrer Ideen reicht ein kostenloses 15-Minuten-Erstgespräch.
Häufige Fragen
Teilen Subagents den Kontext mit dem Hauptagenten?
Nein. Jeder Subagent startet mit eigenem Kontextfenster und bekommt nur die Aufgabe, die der Hauptagent ihm übergibt. Zurück fließt lediglich das Ergebnis. Genau das hält das Hauptgespräch schlank.
Können Subagents parallel laufen?
Ja, Claude Code kann mehrere Subagents gleichzeitig starten, etwa um verschiedene Verzeichnisse parallel zu durchsuchen. Bei Aufgaben mit Schreibzugriff auf dieselben Dateien sollten Sie Parallelität vermeiden, um Konflikte auszuschließen.
Wo speichere ich Subagents für das ganze Team?
Im Ordner .claude/agents im Repository. So sind sie versioniert und für alle verfügbar. Persönliche Subagents gehören in das Agents-Verzeichnis unter Ihrem Benutzerordner.