Erweiterung 2
Subagenten konfigurieren
Vertiefung zu Modul 8 · Kontext, Gedächtnis, Grenzen
Was dieses Deck ergänzt
Modul 2 sagt, was ein Subagent ist. Hier geht es darum, was man an ihm einstellen kann — und was dabei überrascht.
- Ein Subagent sieht euren Verlauf nicht — aber CLAUDE.md schon. Welche Ausnahmen gelten, ist der wichtigste Punkt.
- Werkzeuge werden zweimal verengt, nicht einmal. Dieselbe Datei kann verschiedene Werkzeuge haben.
- Wissen kommt auf zwei Wegen hinein: vorgeladene Skills und ein eigenes Gedächtnis.
- Grenzen setzt man mit Hooks, nicht mit der Werkzeugliste — wenn das Werkzeug erlaubt, die Verwendung aber eingeschränkt sein soll.
# Begleitprojekt: fuenf Subagenten
examples/agent-scaffolding/
.claude/agents/
code-reviewer.md # Gedaechtnis
debugger.md # enge tools
api-developer.md # skills:
db-reader.md # hooks:
no-nesting.md # kein Agent
.claude/settings.json # Start/Stop
Was hineinkommt
Und was garantiert nicht
Der Startkontext
Ein Subagent startet mit frischem, abgetrenntem Kontextfenster. Er sieht euren Gesprächsverlauf nicht, nicht die ausgelösten Skills, nicht die gelesenen Dateien.
Ist drin
- der eigene System-Prompt, nicht der von Claude Code
- die Auftragsnachricht, die beim Delegieren formuliert wird
- die ganze CLAUDE.md-Hierarchie samt Projektregeln
- der Git-Status als Momentaufnahme vom Sitzungsstart
- vorgeladene Skills, vollständig
Ist nicht drin
- euer Gesprächsverlauf
- euer Output Style — er läuft mit eigenem System-Prompt
- das Auto-Memory der Hauptunterhaltung
- die Kontextfenstergröße des Elternteils: sie richtet sich nach seinem Modell
checked am 2026-07-29 gegen code.claude.com/docs/en/sub-agents
Explore und Plan sind anders
Die zwei eingebauten Recherche-Agenten lassen CLAUDE.md und den Git-Status weg, um klein zu bleiben. Ändern lässt sich das nicht.
- Kein Frontmatter-Feld, keine Einstellung. Explore und Plan sind die einzigen mit dieser Ausnahme, und sie ist fest.
- Sie laden auch keine Skills vor. Das gilt für alle eingebauten Agenten.
- Meist ist das kein Problem: die Hauptunterhaltung liest ihr Ergebnis mit vollem CLAUDE.md-Kontext, die Regeln greifen also danach.
- Muss eine Regel doch hinein — etwa „ignoriere
vendor/" — gehört sie in den Auftragstext.
Ein Fork ist die Gegenausnahme: er erbt die Elternunterhaltung samt Output Style und bekommt genau deren Werkzeuge. Alles auf dieser Folie gilt für ihn nicht.
checked am 2026-07-29 gegen code.claude.com/docs/en/sub-agents
Zwei Werkzeugfilter, nicht einer
Der zweite Filter greift nur im Hintergrund — und Hintergrund ist die Vorgabe. Dieselbe Agentendatei kann deshalb verschiedene Werkzeuge haben.
- Filter 1 gilt immer und entfernt unter anderem
AskUserQuestion, EnterPlanMode, Workflow — auch wenn sie in tools stehen.
- Filter 2 gilt im Hintergrund und lässt von den eingebauten Werkzeugen nur einen festen Satz übrig. Alle Werkzeuge fremder Systeme bleiben.
- Ohne Fehlermeldung. Die Entfernung wird nicht gemeldet — außer die Liste löst danach auf nichts mehr auf.
- Ein Fork überspringt beide Filter.
Wenn ein Subagent „nichts tut", ist das die erste Stelle zum Nachsehen: Er läuft im Hintergrund, und das Werkzeug, das sein Ablauf braucht, wurde ihm stillschweigend genommen. Abhilfe: background: false.
checked am 2026-07-29 gegen code.claude.com/docs/en/sub-agents
Die Felder
16 Felder, davon zwei Pflicht. Der Vergleich rechts ist das ganze Prinzip: derselbe Aufbau, ein Werkzeug Unterschied — und daraus folgt der Verwendungszweck.
- Identität:
name, description — Pflicht. Hooks bekommen name als Agententyp.
- Werkzeuge:
tools, disallowedTools, mcpServers.
- Ausstattung:
model, effort, maxTurns, permissionMode.
- Kontext:
skills, memory.
- Lauf:
hooks, background, isolation, initialPrompt, color.
# code-reviewer: darf nicht aendern
tools: Read, Grep, Glob, Bash
# debugger: MUSS aendern
tools: Read, Edit, Bash, Grep, Glob
# Ein Wort Unterschied.
# Beheben heisst aendern,
# Pruefen heisst es nicht.
Bei Subagenten heißt es disallowedTools in Binnenmajuskel, bei Skills disallowed-tools mit Bindestrich. Ein verwechseltes Feld wird stillschweigend ignoriert.
checked am 2026-07-29 gegen code.claude.com/docs/en/sub-agents
Wissen mitgeben
Skills vorladen und ein eigenes Gedächtnis
Skills vorladen
skills: setzt den vollen Inhalt der genannten Skills beim Start in den Kontext. Der Agent muss sie nicht suchen — er weiß es schon.
- Das Feld steuert nur das Vorladen, nicht die Erreichbarkeit: ohne es kann der Agent Skills weiterhin selbst finden und auslösen.
- Ganz unterbinden geht nur, indem
Skill aus tools fehlt oder in disallowedTools steht.
- Nicht vorladbar: Skills mit
disable-model-invocation — auch die gebündelten /verify und /code-review nicht.
- Fehlt ein Skill, startet der Agent trotzdem und die Warnung landet nur im Debug-Log. Kein Fehler, aber auch kein Wissen.
# api-developer.md
---
name: api-developer
tools: Read, Edit, Write, Grep, Glob
skills:
- java-conventions
---
Die Konventionen sind dir beim
Start bereits vorgeladen — suche
sie nicht, sie stehen in deinem
Kontext.
checked am 2026-07-29 gegen code.claude.com/docs/en/sub-agents
Die Umkehrung von context: fork
Skills und Subagenten greifen in beide Richtungen ineinander. Es ist derselbe Unterbau — die Frage ist nur, wer die Aufgabe trägt und wer den System-Prompt.
| Weg | System-Prompt kommt von | Aufgabe kommt von |
|---|
Skill mit context: fork | dem Agententyp | dem Skill-Inhalt |
Subagent mit skills: | dem Agenten selbst | der Auftragsnachricht |
Faustregel: Ist der Ablauf das Besondere, schreibt man einen Skill und schickt ihn mit context: fork weg. Ist die Rolle das Besondere, schreibt man einen Subagenten und gibt ihm Skills mit.
checked am 2026-07-29 gegen code.claude.com/docs/en/skills
Persistentes Gedächtnis
memory: gibt dem Agenten ein Verzeichnis, das Unterhaltungen überlebt. Er baut damit über Zeit Wissen auf — Muster, Fundstellen, Entscheidungen.
project ist die Empfehlung — das Wissen liegt im Repository und ist teilbar. user gilt überall, local bleibt ungeteilt.- Die ersten 200 Zeilen der MEMORY.md kommen in den System-Prompt, mit der Auflage, sie zu pflegen.
- Bitten hilft: „sieh vorher ins Gedächtnis" und „schreib danach, was du gelernt hast" — am besten gleich im Agenten selbst.
- Hängt an Auto-Memory. Ist das abgeschaltet, hat
memory keine Wirkung.
memory aktiviert Read, Write und Edit automatisch — damit der Agent seine Gedächtnisdateien pflegen kann. Ein bewusst nur lesend gebauter Reviewer kann damit schreiben. Wer das nicht will, verzichtet auf das Feld.
checked am 2026-07-29 gegen code.claude.com/docs/en/sub-agents
Grenzen setzen
Hooks im Frontmatter, Lebenszyklus, Abschalten
Werkzeug erlaubt, Verwendung eingeschränkt
Eine Werkzeugliste kennt nur ganz oder gar nicht. Wer Bash erlauben, aber schreibendes SQL (Structured Query Language) verbieten will, braucht einen Hook.
- Im Frontmatter des Agenten definiert, laufen sie nur solange er aktiv ist, und werden danach aufgeräumt.
- Der Vertrag: Eingabe als JSON auf der Standardeingabe, Exit-Code 2 blockiert, die Meldung sieht der Agent.
Stop wird zur Laufzeit zu SubagentStop, wenn der Agent als Subagent läuft.- Ohne Ausführungsrecht scheitert der Hook, statt zu blockieren.
chmod +x nicht vergessen.
# db-reader.md
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "...validate.sh"
# und im Skript:
grep -iqE '\b(INSERT|UPDATE|DROP)\b' \
&& { echo "Blockiert" >&2; exit 2; }
checked am 2026-07-29 gegen code.claude.com/docs/en/sub-agents
Lebenszyklus im Projekt
Zwei Ereignisse in der settings.json: wenn ein Subagent beginnt und wenn er fertig ist. Damit lässt sich aufbauen und aufräumen — Verbindung auf, Verbindung zu.
SubagentStart und SubagentStop, beide mit optionalem Matcher auf den Agententyp.- Der Matcher gehört verankert. Unverankert ist er ein regulärer Ausdruck:
db-agent trifft dann auch prod-db-agent.
- Ohne Matcher feuert es für jeden Subagenten — genau richtig fürs Aufräumen.
"SubagentStart": [{
"matcher": "^db-reader$",
"hooks": [{ /* aufbauen */ }]
}],
"SubagentStop": [{
/* kein matcher = jeder Agent */
"hooks": [{ /* aufraeumen */ }]
}]
Diese Hooks werden nur aus dem aktuellen Arbeitsverzeichnis geladen, ohne Rückgriff nach oben. Wer Claude Code im Repo-Wurzelverzeichnis startet, sieht nichts — und sucht am falschen Ende.
checked am 2026-07-29 gegen code.claude.com/docs/en/sub-agents
Einen Subagenten abschalten
Subagenten sind Werkzeuge und werden wie Werkzeuge verboten — über die Permissions, mit Agent(Name).
- Gilt für eingebaute und eigene gleichermaßen:
Agent(Explore) genauso wie Agent(mein-agent).
- Für einen Lauf geht auch
--disallowedTools auf der Kommandozeile.
- Ein
deny auf irgendeiner Ebene gewinnt. Keine andere Ebene kann es zurücknehmen — auch kein Kommandozeilenargument.
// .claude/settings.json
{
"permissions": {
"deny": [
"Agent(Explore)",
"Agent(db-reader)"
]
}
}
checked am 2026-07-29 gegen code.claude.com/docs/en/permissions
Drei Zähler
Und was Verschachtelung wirklich kostet
Drei Zähler, die verwechselt werden
Die Doku sagt es selbst: drei getrennte Grenzen, jede mit eigener Umgebungsvariable und eigenem Fehlerbild.
| Grenze | Vorgabe | Umgebungsvariable |
|---|
| pro Sitzung insgesamt | 200 | CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION |
| gleichzeitig laufend | 20 | CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS |
| Verschachtelungstiefe | 3 | CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH |
Diese Zahlen sind die flüchtigsten im ganzen Kurs. Die Standardtiefe war in 2.1.172 bis 2.1.216 fünf, in 2.1.217 bis 2.1.218 eins, seit 2.1.219 drei — dreimal geändert in acht Fehlerbehebungs-Versionen. Vor dem Kurstag nachsehen.
checked am 2026-07-29 gegen Claude Code 2.1.220
Verschachtelung
Ein Subagent darf selbst delegieren. Der Gewinn ist nicht Geschwindigkeit, sondern dass die Zwischenergebnisse nie bei euch ankommen.
- Der Fall, für den es gedacht ist: ein Reviewer, der pro Fund einen Prüfer losschickt. Nur seine Zusammenfassung kommt zurück.
- An der Grenze wird
Agent entzogen, und der Subagent macht die Arbeit selbst statt sie abzulehnen.
- Einem einzelnen Agenten nimmt man es, indem
Agent aus tools fehlt oder in disallowedTools steht.
- Tiefe auf 1 schaltet Verschachtelung ganz ab.
# no-nesting.md
---
name: no-nesting
tools: Read, Grep, Glob, Bash
disallowedTools: Agent
---
Du erledigst die Aufgabe selbst.
Wenn der Umfang sie unloesbar
macht, sag das statt still zu
kuerzen.
Verdichtung und Transkripte
Subagenten verdichten nach derselben Logik wie die Hauptunterhaltung. Ihre Transkripte liegen aber getrennt — und das ist praktisch nützlich.
- Verdichtet die Hauptunterhaltung, bleiben sie unberührt. Eigene Dateien, eigenes Leben.
- Sie überleben einen Neustart von Claude Code, solange dieselbe Sitzung fortgesetzt wird.
- Gelöscht nach
cleanupPeriodDays — standardmäßig 30 Tage.
- Zum Nachlesen brauchbar: im Transkript steht, wie viele Token vor der Verdichtung verbraucht waren.
# wo die Transkripte liegen
~/.claude/projects/{projekt}/
{sitzung}/subagents/
agent-{id}.jsonl
# und was drinsteht
"subtype": "compact_boundary",
"trigger": "auto",
"preTokens": 167189
checked am 2026-07-29 gegen code.claude.com/docs/en/sub-agents
Fortsetzen und entscheiden
Ketten, Wiederaufnehmen — und wann überhaupt ein Subagent
Ketten und Fortsetzen
Jeder Aufruf erzeugt eine neue Instanz mit frischem Kontext. Wer weitermachen will, muss den alten fortsetzen — nicht neu beauftragen.
- Ketten ist einfach: nacheinander beauftragen, Claude Code gibt den nötigen Teil weiter.
- Fortsetzen behält alles — Verlauf, Werkzeugaufrufe, Ergebnisse. Der Agent macht dort weiter, wo er aufgehört hat.
- Explore und Plan sind einmalig und lassen sich nicht fortsetzen. Dafür braucht es einen eigenen Agenten.
- Ein selbst gestoppter Agent nimmt nichts wieder auf, bis man ihn selbst wieder anspricht.
Zwei Grenzen gelten immer, egal wer schreibt: Keine Nachricht eines Agenten zählt als Freigabe für eine offene Berechtigungsanfrage, und keine kann die Rechte, CLAUDE.md oder die Konfiguration eines Subagenten ändern. Nur die Permissions und ihr selbst können das.
checked am 2026-07-29 gegen code.claude.com/docs/en/sub-agents
Subagent, Hauptunterhaltung oder Skill?
Die Entscheidungsfolie. Ein Subagent ist nicht die bessere Wahl, sondern eine andere — und oft die falsche.
Subagent, wenn
- viel Ausgabe entsteht, die später niemand mehr braucht
- Werkzeug- oder Rechtegrenzen durchgesetzt werden sollen
- die Arbeit in sich abgeschlossen ist und eine Zusammenfassung genügt
Hauptunterhaltung, wenn
- es viel Hin und Her braucht
- mehrere Phasen sich denselben Kontext teilen
- es eine kleine, gezielte Änderung ist
- Latenz zählt — Subagenten starten bei null
Für eine Zwischenfrage zu etwas, das schon im Gespräch steht, ist beides falsch: /btw sieht den vollen Kontext, hat keinen Werkzeugzugriff, und die Antwort wird verworfen statt in den Verlauf aufgenommen.
checked am 2026-07-29 gegen code.claude.com/docs/en/sub-agents
Erweiterung 2 in fünf Sätzen
Was von diesem Deck hängenbleiben soll.
- CLAUDE.md ist drin, euer Verlauf nicht. Explore und Plan lassen auch CLAUDE.md weg — und das lässt sich nicht ändern.
- Werkzeuge werden zweimal verengt. Im Hintergrund, also standardmäßig, fehlen eingebaute Werkzeuge ohne Fehlermeldung.
- Wissen kommt über
skills, Erfahrung über memory — und memory schaltet stillschweigend Schreibrechte dazu.
- Grenzen zieht ein Hook, nicht die Werkzeugliste, wenn das Werkzeug erlaubt und nur die Verwendung eingeschränkt sein soll. Exit-Code 2 blockiert.
- Es gibt drei Zähler, nicht einen — Sitzung, Gleichzeitigkeit, Tiefe. Und ihre Standardwerte ändern sich häufiger als alles andere im Kurs.
Glossar Glossar
Subagent
Eine zweite Instanz mit eigenem Kontextfenster, eigenem System-Prompt und eigenen Werkzeugen. Sie erledigt eine abgegrenzte Aufgabe und gibt nur ihre Zusammenfassung zurück.
Fork (Kopie der Unterhaltung)
Sonderfall eines Subagenten: er erbt die laufende Unterhaltung statt frisch zu starten, samt Output Style und Werkzeugpool. Die Filter für Subagenten gelten für ihn nicht.
Agent-Gedächtnis
Ein Verzeichnis, das ein Subagent über Unterhaltungen hinweg behält. Gesteuert über das Feld memory; die Datei MEMORY.md darin kommt anteilig in seinen System-Prompt.
Verdichtung (Auto-Compaction)
Automatisches Zusammenfassen einer Unterhaltung, wenn das Kontextfenster voll wird. Gilt für Subagenten nach derselben Logik wie für die Hauptunterhaltung.
SQL (Structured Query Language)
Abfragesprache für relationale Datenbanken. Lesende Befehle beginnen mit SELECT, schreibende mit INSERT, UPDATE oder DELETE — die Unterscheidung, die der Beispiel-Hook trifft.
© 2026 CGS IT Solutions GmbH
Alle Rechte vorbehalten
Diese Schulungsunterlagen sind urheberrechtlich geschützt. Vervielfältigung,
Weitergabe oder kommerzielle Nutzung — auch in Auszügen — nur mit
ausdrücklicher schriftlicher Genehmigung der CGS IT Solutions GmbH.
cgsit-claude-training · Erweiterung 2 · Subagenten · v0.10.1
