Subagenten in Claude Code: Kontextisolation, Orchestrator und Reviewer, wann sie nicht nötig sind

Was Subagenten in Claude Code sind

Ein Subagent ist eine weitere Instanz des Agenten, die der Hauptagent für eine abgegrenzte Aufgabe startet. Er hat ein eigenes Kontextfenster, einen eigenen Systemprompt und eine eigene Liste erlaubter Werkzeuge. Der Hauptagent übergibt ihm die Beschreibung der Aufgabe, der Subagent arbeitet selbstständig – liest Dateien, startet Befehle – und liefert zurück nur die abschließende Nachricht.

Das Schlüsselwort ist Isolation. Alles, was der Subagent unterwegs gelesen hat – Dutzende Dateien, lange Testausgaben, Sackgassen –, bleibt in seinem Kontext und gelangt nicht in den Kontext der Hauptsitzung. Der Hauptagent sieht nur ein kurzes Ergebnis: »Der Fehler liegt in Funktion X, Ursache ist dies, betroffen sind drei Stellen.«

Subagenten in Claude Code sind ein Spezialfall der allgemeinen Idee der Multiagentensysteme: Statt eines einzigen Zyklus »denken – handeln – prüfen« entsteht ein Graph aus mehreren Knoten, jeder mit eigener Rolle und eigener Verantwortung.

Wozu Kontextisolation dient

Das Kontextfenster ist die wichtigste Ressource des Agenten. Darin liegen gleichzeitig die Anweisungen aus CLAUDE.md, der Verlauf des Dialogs, der gelesene Code und Befehlsausgaben. Sucht der Agent eine halbe Stunde nach der Ursache eines Fehlers, füllt sich der Kontext mit Ballast: Dateien, die nichts damit zu tun haben, und Logs, aus denen nur eine Zeile wichtig ist.

Die Folgen kennt jeder, der lange mit Agenten arbeitet: Das Modell hält die Projektregeln schlechter ein, verwechselt Details, und bei der automatischen Verdichtung des Verlaufs geht das Wichtige verloren. Der Subagent löst das strukturell: Die schmutzige Arbeit geschieht in einem eigenen Kontext, der nach der Antwort verworfen wird.

• Suche und Erkundung. »Finde alle Stellen, an denen die Zahlungsfunktion aufgerufen wird, und beschreibe, wie sie aufgebaut sind« – eine typische Aufgabe für einen Subagenten.
• Verrauschte Prüfungen. Den Testlauf und die Analyse der fehlgeschlagenen Tests an einen Subagenten geben und eine Liste der Ursachen zurückbekommen.
• Lesen großer Dokumente. Eine Spezifikation mit hunderten Seiten wird für wenige Fakten gebraucht – der Subagent soll sie herausziehen.

Einen Subagenten einrichten: der Ordner .claude/agents

Ein eigener Subagent wird durch eine Markdown-Datei mit YAML-Kopf beschrieben. Projektdateien liegen im Repository unter .claude/agents/ und sind über Git für das ganze Team verfügbar, persönliche liegen unter ~/.claude/agents/ und funktionieren in all Ihren Projekten. Anlegen und Bearbeiten geht auch interaktiv über den Befehl /agents in Claude Code.

---
name: code-reviewer
description: Prüft Codeänderungen auf Fehler und Verstöße gegen die Projektregeln. Nach Abschluss einer Aufgabe, vor dem Commit verwenden.
tools: Read, Grep, Glob, Bash
---
Du bist Code-Reviewer. Du sollst nichts korrigieren.

1. Sieh dir die Änderungen an: git diff.
2. Prüfe jede Änderung auf Logikfehler, Fehlerbehandlung,
   Sicherheit (SQL, Escaping der Ausgabe, Geheimnisse).
3. Gleiche sie mit den Regeln aus AGENTS.md ab.
4. Gib eine Liste der Hinweise zurück: Datei, Zeile, Problem, warum es wichtig ist.
   Gibt es keine Hinweise, schreibe genau das.

Die Felder bedeuten:

Der Dateikörper ist der Systemprompt des Subagenten. Er sieht den Verlauf Ihres Dialogs nicht, deshalb muss alles, was er über seine Rolle und das Antwortformat wissen muss, im Prompt oder in der Aufgabe stehen, die der Hauptagent übergibt.

So ruft man einen Subagenten auf

Der Hauptagent kann den Subagenten selbst wählen, wenn die Aufgabe zu seiner description passt. Zuverlässiger ist es, ausdrücklich darum zu bitten: »Verwende den Subagenten code-reviewer, um die Änderungen zu prüfen.« Formulierungen wie »verwende proaktiv« in der Beschreibung erhöhen die Chance, dass der Agent ihn ohne Erinnerung aufruft, garantieren es aber nicht.

Der Subagent als Explorer

Eine zweite Datei, die sich in fast jedem Projekt lohnt, ist ein Explorer, der nur liest. Er beantwortet Fragen zum Code und ändert nichts.

---
name: explorer
description: Sucht in der Codebasis Antworten darauf, wo und wie etwas aufgebaut ist. Verwenden, wenn viele Dateien gelesen werden müssen, um eine kurze Antwort zu bekommen.
tools: Read, Grep, Glob
---
Du untersuchst den Code und änderst nichts.
Gib zurück: eine knappe Antwort auf die Frage, eine Liste der Dateien mit Zeilen,
auf die sie sich stützt, und was sich nicht prüfen ließ.

Besonders nützlich ist ein solcher Subagent am Anfang einer Aufgabe: Der Hauptagent bekommt eine Karte der relevanten Stellen, ohne seinen Kontext mit allem Möglichen zu füllen, und arbeitet danach mit konkreten Dateien weiter.

Das Schema »Orchestrator und Ausführende«

Die verbreitetste Multiagentenform: Ein Orchestrator hält den Plan und das Gesamtbild und verteilt die einzelnen Schritte an Ausführende. Der Orchestrator liest nicht den ganzen Code selbst – er formuliert Aufgaben, nimmt Ergebnisse entgegen und entscheidet, was als Nächstes kommt.

1. Der Orchestrator zerlegt die Aufgabe in unabhängige Teile und schreibt für jeden Teil einen in sich geschlossenen Auftrag: Ziel, wo zu suchen ist, was als fertig gilt, in welcher Form die Antwort zurückkommen soll.
2. Die Ausführenden erledigen die Aufträge in ihren Kontexten.
3. Der Orchestrator sammelt die Antworten, prüft, ob die Teile zusammenpassen, und startet den nächsten Schritt oder rollt auf den vorherigen zurück.

Die Schwachstelle des Schemas ist die Übergabe. Ein Subagent kennt nur das, was ihm geschrieben wurde. Der Auftrag »behebe den Fehler, den wir besprochen haben« ist für ihn leer: Er hat die Besprechung nicht gesehen. Ein guter Auftrag liest sich wie eine Aufgabe für einen neuen Kollegen, der das Repository zum ersten Mal öffnet.

Was der Ausführende zurückgeben soll

Legen Sie das Antwortformat im Voraus fest: Liste der Dateien, Ausgabe, gefundene Ursachen, was nicht geprüft werden konnte. Eine kurze strukturierte Antwort schont den Kontext des Orchestrators, und der Punkt »was nicht geprüft wurde« schützt vor falscher Sicherheit – der Ausführende neigt, wie jeder Agent, dazu, Erfolg zu melden.

Ein eigener Reviewer: warum man Richter und Ausführenden trennt

Wenn ein und derselbe Agent den Code schreibt und ihn selbst prüft, sitzen Richter und Angeklagter in einem Kopf. Der Agent erinnert sich an seine Absicht und sieht im Code seinen Plan, nicht das, was tatsächlich dasteht. Außerdem will er fertig werden – die Prüfung wird zur Formalität.

Ein Reviewer im eigenen Kontext hat diese Probleme nicht. Er kennt die Entscheidungshistorie nicht, sieht nur den Diff und die Projektregeln und bewertet das Ergebnis mit frischem Blick. Das ist dasselbe Prinzip wie im echten Team: Der Autor nimmt seinen eigenen Pull Request nicht ab.

• Geben Sie dem Reviewer nur Werkzeuge zum Lesen und Ausführen von Prüfungen – ohne Schreibrecht. Dann beginnt er nicht, »still zu korrigieren«, statt das Problem zu melden.
• Beschreiben Sie die Prüfkriterien ausdrücklich: was als Fehler gilt, welche Projektregeln verbindlich sind.
• Die Entscheidung, was mit den Hinweisen geschieht, bleibt beim Orchestrator oder beim Menschen. Der Reviewer findet, der Ausführende behebt.

Der Reviewer ersetzt keine mechanischen Prüfungen. Tests, Linter und Typprüfung sind deterministische Knoten und zuverlässiger als jedes Modell. Der Reviewer fängt, was die Mechanik nicht sieht: falsche Logik, verletzte Absprachen, unnötige Komplexität.

Parallele Subagenten

Claude Code kann mehrere Subagenten gleichzeitig starten. Das beschleunigt die Arbeit, wenn Teile der Aufgabe wirklich unabhängig sind: drei Module gleichzeitig untersuchen, einen Diff aus drei Blickwinkeln prüfen (Sicherheit, Performance, Tests), Informationen aus mehreren Quellen sammeln.

Parallelität funktioniert gut beim Lesen und schlecht beim Schreiben. Bearbeiten zwei Ausführende gleichzeitig dieselben Dateien, überschreiben sie gegenseitig ihre Änderungen, und keiner merkt es. In der Sprache des Agentengraphen ist das ein gemeinsamer Zustand ohne Zusammenführungsregel. Praktische Regeln:

• Parallel laufen Recherche, Analyse und Review. Nacheinander laufen Änderungen an sich überschneidenden Dateien.
• Schreiben Ausführende trotzdem parallel, teilen Sie die Zonen auf: Jeder arbeitet nur in seinen Dateien oder in einer eigenen Kopie des Repositorys (zum Beispiel in einem eigenen git worktree).
• Die Ergebnisse führt ein Knoten zusammen – der Orchestrator, nicht die Ausführenden untereinander.

Wann Subagenten nicht nötig sind

Ein Multiagentenschema hat seinen Preis: mehr Token, mehr Zeit, mehr Stellen, an denen Informationen bei der Übergabe verloren gehen. Subagenten lohnen sich nicht immer.

Bevor Sie einen Graphen aus Agenten bauen, beantworten Sie einfache Fragen: Wer besitzt das gemeinsame Ziel, wer kann ein Veto einlegen und eine Änderung zurücknehmen, welche Kennzahlen gelten als Erfolg? Ohne diese Antworten vervielfachen mehrere Agenten nur die Verwirrung eines Einzelnen.

Typische Fehler mit Subagenten

Unscharfe Beschreibung

Die Beschreibung »Helfer für Code« hilft dem Hauptagenten nicht zu entscheiden, wann er ihn aufruft. Schreiben Sie den Auslöser: »nach Änderungen im Ordner api/, vor dem Commit«.

Auftrag ohne Kontext

Der Subagent bekommt eine Aufgabe ohne Pfade, ohne Fertigkriterien und ohne Grenzen – und verbringt die Hälfte der Arbeit damit zu raten, was man von ihm will. Abhilfe bietet eine Vorlage für Aufträge: Ziel, Eingaben, Einschränkungen, Antwortformat.

Zu weite Rechte

Explorer und Reviewer brauchen kein Schreibrecht. Die Einschränkung tools ist eine günstige Methode, eine Rolle durch Mechanik statt durch eine Bitte im Prompt durchzusetzen.

Vertrauen in den Bericht ohne Prüfung

»Alle Tests sind durchgelaufen« in der Antwort eines Subagenten ist eine Behauptung, kein Fakt. Der Orchestrator muss sich auf Prüfbares stützen: Ausgabe eines Befehls, Rückgabecode, konkrete Zeilen.

Kurz gesagt

Subagenten in Claude Code dienen drei Zwecken: den Hauptkontext sauber zu halten, Prüfung von Ausführung zu trennen und unabhängige Arbeit zu parallelisieren. Beschrieben werden sie durch kurze Markdown-Dateien in .claude/agents/, und ihre Arbeitsqualität hängt fast vollständig von der Beschreibung der Rolle, dem Werkzeugsatz und davon ab, wie in sich geschlossen der Auftrag formuliert ist. Ist die Aufgabe klein oder eng mit dem Dialog verknüpft, bleibt ein einzelner Agent besser. Der Übergang von einem Zyklus zu einem System aus Knoten, Kanten und gemeinsamem Zustand wird im Kurs zum Harness-Engineering praktisch durchgespielt.