Claude Code Subagents funktionieren dann gut, wenn du sechs Regeln einhältst: Jeder Subagent bekommt eine eigene Datei in .claude/agents/ mit einer klaren description, er bekommt nur die Werkzeuge, die seine Aufgabe braucht, das Modell wählst du je Rolle statt pauschal, du lässt weniger Subagents parallel laufen als die Doku erlaubt, du gibst ihm im Auftrag alles mit, weil er dein Gespräch nicht sieht, und alles, was nach außen geht, prüft eine zweite, getrennte Rolle im frischen Kontext, bei mir meistens ein Subagent. Zurück kommt nie der ganze Arbeitsverlauf, sondern nur die Zusammenfassung. Das ist der Grund, Subagents überhaupt zu nutzen: Dein Hauptgespräch bleibt schlank, während die laute Arbeit (Recherche, Tests, Logs) woanders passiert.
Ich betreibe meine KI-Belegschaft auf Claude-Basis, und mehrere Mitarbeiter darin sind als Subagent definiert. Was hier steht, kommt aus der offiziellen Doku und aus unseren Protokollen, in denen belegt ist, wann ein Subagent-Lauf funktioniert hat und wann er an einer Freigabe scheiterte. Was ein Subagent im Vergleich zu Skill und Agent überhaupt ist, erkläre ich in Claude Subagents, Skills und Agents; hier geht es um die Praxisregeln. Alles zu Claude sammle ich auf der Seite Claude.
Was ein Subagent sieht, was nicht und was zurückkommt
Ein Subagent ist laut Anthropic-Doku zu Subagents eine eigene Claude-Instanz mit eigenem System-Prompt, eigenem Kontextfenster und eigenem Werkzeugsatz. Er sieht seinen System-Prompt, deinen Auftragstext, die CLAUDE.md-Hierarchie des Projekts und die Skills, die du ihm im Frontmatter vorlädst. Er sieht nicht: deinen bisherigen Gesprächsverlauf, das Auto-Memory der Hauptsitzung und Skills, die du im Hauptgespräch schon aufgerufen hast.
Daraus folgt die wichtigste Regel für den Auftrag: Alles, was der Subagent wissen muss, steht im Auftragstext oder in Dateien, die er selbst lesen darf. „Mach das wie vorhin besprochen" funktioniert nicht, weil es kein Vorhin gibt. Bei uns bekommt ein Subagent deshalb immer einen Brief mit meinem Wortlaut, Links auf den Kontext und den Pflicht-Checks, statt einer Kopie des Inhalts.
Zurück ins Hauptgespräch kommt nur der Abschlussbericht des Subagenten. Die Doku nennt das als Kernnutzen: „use subagents to keep research out of it", weil das Kontextfenster die knappste Ressource ist. Wer zehn Dateien durchsuchen lässt, will die Schlussfolgerung im Hauptgespräch, nicht die zehn Dateien. Wie die Hauptsitzung ihr Wissen dauerhaft hält, steht in CLAUDE.md: das Gedächtnis von Claude Code.
Die Datei anlegen: Ort, Pflichtfelder, ein Beispiel
Wo ein Subagent liegt und welche Felder es überhaupt gibt, steht kurz in Claude Subagents, Skills und Agents; hier geht es darum, welche Felder im Alltag den Unterschied machen. Subagents liegen als Markdown-Datei mit Frontmatter in .claude/agents/ im Projekt oder in ~/.claude/agents/ für alle Projekte. Beide Ordner werden laut Doku rekursiv gelesen; bei gleichem Namen gewinnt die höhere Ebene, in verschachtelten Projekten die Datei, die deinem Arbeitsverzeichnis am nächsten liegt. Pflicht sind nur name (Kleinbuchstaben und Bindestriche) und description. Optional sind unter anderem tools, disallowedTools, model, permissionMode, maxTurns, skills, memory, isolation, background und hooks.
So sieht eine minimale, lauffähige Datei aus. Sie ist an unseren SEO-Mitarbeiter angelehnt und nicht seine echte Datei; die veröffentliche ich nicht. Den Modellwert setzt du je Rolle, siehe nächster Abschnitt:
---
name: seo-pruefer
description: Bewertet eine Website mit echten Tools und liefert einen priorisierten Maßnahmenplan. Nutzen, wenn ein SEO-Audit oder eine Nachmessung ansteht.
tools: Read, Glob, Grep, Bash, Write, WebSearch, WebFetch
model: inherit
memory: project
---
Du bist der SEO-Prüfer. Jede Bewertung stützt sich auf einen Tool-Output,
der im Auftragsordner liegt. Keine erfundenen Messwerte, keine Versprechen.
Melde am Ende nur die Befunde mit Fundort, nicht den Weg dorthin.
Der Text unter dem Frontmatter ist der System-Prompt des Subagenten. Die description entscheidet, wann Claude Code den Subagent von selbst wählt; die Doku empfiehlt Formulierungen wie „use proactively" und hält die Summe aller descriptions unter 15.000 Tokens. Aufrufen kannst du ihn auch direkt mit @agent-seo-pruefer, mit einem natürlichen Satz oder sitzungsweit mit claude --agent seo-pruefer. Sebastian ist bei mir nach demselben Muster als Subagent mit isoliertem Kontext definiert.
Modellwahl je Rolle: die Auflösungsreihenfolge
Claude Code bestimmt das Modell eines Subagenten in dieser Reihenfolge: erstens der Parameter beim Aufruf, zweitens das Feld model im Frontmatter, drittens die Umgebungsvariable CLAUDE_CODE_SUBAGENT_MODEL, viertens das Modell der Hauptsitzung. Im Frontmatter darfst du ein kleines, mittleres oder großes Modell der aktuellen Familie eintragen, eine vollständige Modell-ID oder inherit.
Die Doku selbst nutzt in ihren Beispielen ein großes Modell für den Sicherheits-Reviewer, ein mittleres für den Code-Reviewer und ein kleines für den Test-Läufer. Die Logik dahinter: Wer nur Tests startet und Fehlermeldungen zusammenfasst, braucht kein teures Modell; wer Sicherheitslücken beurteilt, schon. Ob das bei dir Kosten spart, ist eine Hypothese, keine Messung. Ich habe für meine Belegschaft keine getrennten Verbrauchszahlen je Modell, deshalb bleibt meine Empfehlung vorsichtig: Fang mit inherit an und weiche erst ab, wenn du eine Rolle hast, die nachweisbar mit weniger auskommt.
Parallel arbeiten: Limits, Hintergrund, Worktrees
Laut Doku laufen standardmäßig bis zu 20 Subagents gleichzeitig (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS), und Subagents dürfen bis zu drei Ebenen tief weitere Subagents starten (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH). Ein Subagent im Vordergrund blockiert deine Hauptsitzung, bis er fertig ist; im Hintergrund (background) läuft er parallel mit einem reduzierten Werkzeugsatz, und du bekommst eine Meldung, sobald er fertig ist. Mit isolation: worktree bekommt jeder Subagent einen eigenen Git-Worktree vom Standard-Branch, der aufgeräumt wird, wenn er nichts geändert hat. Die Best-Practices-Seite beschreibt dazu /batch, das eine Änderung auf viele Subagents mit je eigenem Pull Request verteilt. Worktrees und /batch kenne ich aus der Doku, nicht aus meinem Betrieb.
Die Zahl 20 ist ein Limit, keine Empfehlung. Meine Regel im Betrieb lautet: lieber weniger parallel. Der Grund ist einfach. Jeder Subagent liest die CLAUDE.md-Hierarchie und seine vorgeladenen Skills neu ein, und jede parallele Instanz zahlt diesen Einstieg. Dazu kommt ein belegter Fehler aus unseren Learnings: Am 08.09.2026 liefen bei Conny Bau und Prüfung parallel, die Meldung „fertig und geprüft" musste sie zurücknehmen. Parallel lohnt sich, wenn die Aufgaben wirklich unabhängig sind: fünf Blogbeiträge zu fünf Themen ja, fünf Änderungen an derselben Datei nein.
Werkzeugrechte: tools und disallowedTools
Ohne Angabe erbt ein Subagent alle Werkzeuge der Hauptsitzung, auch die MCP-Server. Mit tools gibst du eine Positivliste, mit disallowedTools nimmst du einzelne weg. Ein Detail aus der Doku, das leicht schiefgeht: disallowedTools: Bash(git push *) entfernt das ganze Bash-Werkzeug, nicht nur den einen Befehl. Selektive Sperren gehören in permissions.deny der Einstellungen. Die eingebauten Subagents Explore und Plan sind laut Doku nur lesend, Write und Edit sind für sie gesperrt; general-purpose hat alle Werkzeuge.
Die Doku-Beispiele zeigen das Prinzip: Der Sicherheits-Reviewer bekommt Read, Grep, Glob und Bash, aber kein Write; der Datenbank-Leser bekommt Bash mit einem Hook davor, der schreibende Befehle abfängt. Bei mir sieht das anders aus, und das sage ich offen: Was ein Mitarbeiter darf, steht in drei Stufen in seiner Personalakte, frei, nur nach Freigabe, nie. Das ist eine Rollenregel in einer Textdatei, keine technische Sperre. Meine prüfenden Subagents laufen nicht mit beschnittenen Werkzeugrechten; die zweite und dritte Stufe setze ich über Claude Code Hooks: Regeln, die immer gelten und das Freigabe-Gate im Gespräch durch. Wer die Rolle technisch absichern will, nimmt dafür tools, so empfiehlt es die Doku. MCP-Server, die ein Subagent braucht, trägst du im Feld mcpServers ein; wie du einen einrichtest, steht in Claude MCP Server einrichten.
Subagent, Skill oder Hauptgespräch: die Entscheidungsregel
Die Doku gibt eine klare Regel: Hauptgespräch bei Iteration und geteiltem Kontext, Subagent bei viel Ausgabe, Werkzeugbeschränkung, abgeschlossener Aufgabe oder Parallelität, Skill bei wiederverwendbaren Abläufen, die den Gesprächsverlauf brauchen. Skills lassen sich einem Subagent im Feld skills vorladen; wie du Skills schreibst, zeige ich in Claude Skills: erstellen und nutzen.
Meine Belegschaft als Claude Code Subagents: drei belegte Fälle
Der erste Fall ist eine Regel, kein Einzelereignis: Alles, was bei uns das Haus verlässt, prüft eine getrennte Rolle, nie derselbe Kontext, der es erstellt hat. Unsere Spielregeln verweisen dafür auf Huang et al. (ICLR 2024): Ein Modell, das seine eigene Arbeit im selben Kontext prüft, findet seine Fehler schlecht. Die Anthropic-Doku nennt dasselbe Muster „adversarial review step": Ein Reviewer-Subagent im frischen Kontext sieht nur den Diff und die Kriterien. Sie warnt zugleich, dass ein Reviewer, den du zum Lückenfinden aufforderst, immer Lücken meldet; deshalb steht im Auftrag „nur Lücken melden, die die Richtigkeit betreffen". Der Hebel ist bei mir der frische Kontext und der andere Auftrag, nicht ein beschnittener Werkzeugsatz. Beim Lektorat am 07.09.2026 hat diese getrennte Rolle in gut der Hälfte der Kubernetes-Beiträge fachliche Fehler korrigiert und bei Claude-Beiträgen unbelegte Preisaussagen entfernt.
Der zweite Fall zeigt, wann ein Subagent die Rettung ist. Am 07.09.2026 schrieb Sebastian die Übergabe für ein Blog-Release an Ralf, ich gab um 18:24 Uhr frei. Die Zustellung an Ralfs laufende Sitzung scheiterte an der Freigabe, also lief Ralf als Subagent: frischer Kontext, Übergabebrief als Auftrag, danach prüfte Sebastian live. Die Arbeit endete nicht beim Subagent, sondern bei meiner Freigabe und einer Prüfung durch eine zweite Rolle.
Der dritte Fall ist Alltag. Am 16.09.2026 fragte Sebastian per Postfach bei Conny nach Erfahrungen für fünf Beiträge. Conny antwortete als Subagent mit einem Brief in Sebastians Eingang. Das Postfach-Protokoll ist bei uns der Weg, wie Subagents ohne gemeinsamen Kontext zusammenarbeiten: Absender legt die Übergabe in seinen Ausgang und eine Kopie in den Eingang des Empfängers, mit Link auf den Kontext statt einer Kopie des Inhalts. Alles bleibt nachvollziehbar, und ich sehe, wer wann was übergeben hat.
Sieben Regeln aus der Doku plus meine Ergänzungen
Die Doku-Liste lautet: descriptions so schreiben, dass Claude den Subagent von selbst wählt; die Summe aller descriptions unter 15.000 Tokens halten; laute Aufgaben wie Tests und Logs auslagern; memory: project für Wissensaufbau über Sitzungen nutzen; Skills vorladen statt im Auftrag zu wiederholen; Grenzen über tools und disallowedTools erzwingen; und Abschlussberichte auf befehlsförmige Muster prüfen, weil ein Subagent, der fremde Inhalte gelesen hat, keine Anweisungen daraus weitergeben darf.
Meine drei Ergänzungen aus dem Betrieb: Erstens, jeder Subagent-Auftrag ist ein Brief mit Wortlaut, Kontext-Links und Pflicht-Checks, nie ein Halbsatz. Zweitens, weniger parallel als erlaubt, weil jede Instanz Einstiegskosten hat. Drittens, ein Subagent endet an einer Regel, einem Briefing oder einem Freigabe-Gate; was Zustand ändert oder das Haus verlässt, gebe ich selbst frei, und der Mitarbeiter dokumentiert die Freigabe mit Zeitpunkt.
Häufige Fragen
Sieht ein Subagent meine CLAUDE.md und meinen bisherigen Chat?
Die CLAUDE.md-Hierarchie ja, außer du setzt omitClaudeMd. Den bisherigen Chat nein, ebenso wenig das Auto-Memory der Hauptsitzung oder Skills, die dort schon aufgerufen wurden. Alles, was er wissen muss, gehört in den Auftrag oder in Dateien, die er lesen darf.
Wie viele Claude Code Subagents kann ich parallel laufen lassen?
Standardmäßig 20 gleichzeitig, einstellbar über CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS, mit bis zu drei Ebenen Verschachtelung. Meine Regel lautet trotzdem: lieber weniger parallel, weil jede Instanz Kontext und Tokens kostet und sich parallele Instanzen bei derselben Datei in die Quere kommen.
Welches Model nimmt ein Claude Code Subagent, wenn ich nichts angebe?
Das Modell der Hauptsitzung, sofern weder ein Parameter beim Aufruf, noch model im Frontmatter, noch die Umgebungsvariable CLAUDE_CODE_SUBAGENT_MODEL gesetzt ist. Die Reihenfolge ist genau diese: Aufruf, Frontmatter, Umgebungsvariable, Hauptsitzung.
Claude Code Subagents vs Skills: was ist der Unterschied?
Ein Skill ist ein wiederverwendbarer Ablauf, der im Hauptgespräch läuft und dessen Verlauf sieht. Ein Subagent ist eine eigene Instanz mit frischem Kontext und eigenem Werkzeugsatz. Beides lässt sich kombinieren: Im Feld skills lädst du einem Subagent die Skills vor, die er braucht.
Kann ein Subagent Dateien in meinem Projekt kaputt machen?
Ja, wenn er Write, Edit oder Bash bekommt. Deshalb gibst du mit tools nur, was die Rolle braucht, nutzt permissionMode: plan für reine Prüfer, isolation: worktree für riskante Änderungen und lässt alles, was Zustand ändert, durch eine Freigabe laufen.
Wo liegt die Subagent-Datei, im Projekt oder für alle Projekte?
Beides geht: .claude/agents/ im Projekt gilt nur dort, ~/.claude/agents/ gilt für alle Projekte. Bei gleichem Namen gewinnt laut Doku die höhere Ebene; noch davor kommen verwaltete Einstellungen und das --agents-Flag beim Start.
Was passiert, wenn ein Subagent fertig ist?
Er liefert seinen Abschlussbericht ins Hauptgespräch, der Arbeitsverlauf bleibt bei ihm. Mit SendMessage und seiner Agent-ID kannst du ihn wieder aufnehmen, sein Verlauf bleibt erhalten. Für die eingebauten Subagents Explore und Plan gilt das laut Doku nicht.
Wie du weitermachst
Leg einen einzigen Subagent an, den Reviewer, mit dem Auftrag „nur Lücken melden, die die Richtigkeit betreffen". Die Doku empfiehlt dafür Read, Grep und Glob ohne Write; bei mir ist die Trennung von Ersteller und Prüfer eine Rollenregel, und auch so trägt sie. Lass ihn eine Woche lang jedes Ergebnis prüfen, das du sonst ungeprüft weitergegeben hättest. Wenn das trägt, kommt der zweite Subagent für die laute Arbeit. Die Begriffe hinter alldem erkläre ich in Claude Subagents, Skills und Agents, die ersten Schritte im Terminal in Claude Code: Anleitung für Einsteiger.
