CGS IT Solutions GmbH — Claude Code Training · Erweiterung 2 · Subagenten konfigurieren · v0.11.5

Erweiterung 2

Subagenten konfigurieren

Vertiefung zu Modul 8 · Kontext, Gedächtnis, Grenzen

Inhalt

1Was hineinkommt — und was garantiert nicht 2Wissen mitgeben — Skills vorladen, Gedächtnis 3Grenzen setzen — Hooks, Lebenszyklus, Abschalten 4Die Zähler — und was Verschachtelung kostet 5Fortsetzen und entscheiden — wann überhaupt ein Subagent Glossar — Begriffe zum Nachschlagen

Ein Subagent ist eine Datei

Links der ganze db-reader aus dem Begleitprojekt — Frontmatter und Auftrag.
Rechts, was jede Zeile bewirkt.

# .claude/agents/db-reader.md
---
name: db-reader
description: Beantwortet Fragen zum
  Seminarbestand mit lesenden Abfragen.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "...validate.sh"
color: cyan
---
Du beantwortest Fragen zum Bestand.
Benutze python3 data/seminars.py.
Du darfst nur lesen.
  1. name — Hooks bekommen genau diesen Wert als Agententyp.
  2. description — daran entscheidet Claude Code, ob delegiert wird.
  3. tools: Bash — alles andere ist ihm genommen, auch Read und Edit.
  4. hooks — ein Skript prüft jeden Befehl, bevor er läuft, und kann ihn blocken.
  5. Der Rumpf ist sein System-Prompt. Nicht Anweisung an euch, sondern an ihn.
checked am 2026-07-29 gegen docs/en/sub-agents

Was hineinkommt

Und was garantiert nicht

Der Startkontext

Ein Subagent startet mit frischem Kontextfenster — er sieht euren Verlauf nicht, aber mehr, als die meisten annehmen.

# was beim Start in seinem Kontext liegt
+ sein eigener System-Prompt
+ die Auftragsnachricht
+ CLAUDE.md, ganze Hierarchie *
+ Git-Status -- Branch, geaenderte Dateien *
+ vorgeladene Skills, vollstaendig

- euer Gespraechsverlauf
- euer Output Style
- das Auto-Memory der Sitzung
- die Fenstergroesse des Elternteils
  model: haiku # = sein kleineres Fenster

* nicht bei Explore und Plan — 2 von 3 Built-ins
  1. Der Git-Status ist drin — ohne einen Befehl weiß der Subagent, auf welchem Branch ihr seid und was geändert ist. Fehlt ohne Git-Repository oder bei includeGitInstructions: false.
  2. CLAUDE.md ist drin — auch Projektregeln und CLAUDE.local.md. „Der Agent kennt unsere Regeln nicht" stimmt meist nicht.
  3. Der Verlauf ist es nicht. Was nur im Gespräch stand, muss in den Auftrag.
  4. Der Output Style greift nicht — er läuft mit eigenem System-Prompt.
  5. Kostenfallstrick: an ein kleineres Modell delegieren heißt auch, ein kleineres Fenster zu bekommen.
Der Git-Status ist eine Momentaufnahme vom Start eurer Sitzung, nicht vom Start des Subagenten — nach zwei Stunden Arbeit beschreibt er einen Baum, den es so nicht mehr gibt.
checked am 2026-07-30 gegen 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.

# Fork-Skill mit Explore: sieht NUR
# den Skill-Inhalt, kein CLAUDE.md
---
name: finding-validations
context: fork
agent: Explore
---
Durchsuche das Repository nach ...
# Regel muss HIER stehen:
Ignoriere das Verzeichnis vendor/.

# in CLAUDE.md wuerde sie nicht ankommen
  1. Kein Feld, keine Einstellung. Explore und Plan sind die einzigen mit dieser Ausnahme, und sie ist fest.
  2. Sie laden auch keine Skills vor. Das gilt für alle eingebauten Agenten.
  3. Meist kein Problem: die Hauptunterhaltung liest ihr Ergebnis mit vollem CLAUDE.md-Kontext.
  4. Muss eine Regel doch hinein, gehört sie in den Auftragstext — wie im Beispiel.
Ein Fork ist die Gegenausnahme: er erbt die Elternunterhaltung samt Output Style und Werkzeugpool.
Alles auf dieser Folie gilt für ihn nicht.
checked am 2026-07-29 gegen docs/en/sub-agents

Zwei Werkzeugfilter, nicht einer

Der zweite Filter greift nur im Hintergrund — und Hintergrund ist die Vorgabe.
Dieselbe Datei kann verschiedene Werkzeuge haben.

tools: Read, Grep, Glob, Bash,
AskUserQuestion, Workflow
Filter 1 — gilt immerAskUserQuestion, Workflow raus
Filter 2 — nur im Hintergrundund Hintergrund ist die Vorgabe
was übrig bleibt —
ohne Fehlermeldung
immernur im Hintergrund
  1. Filter 1 gilt immer — auch für Werkzeuge, die ausdrücklich in tools stehen.
  2. Filter 2 gilt im Hintergrund, also standardmäßig seit Version 2.1.198.
  3. Ohne Fehlermeldung. Die Entfernung wird nicht gemeldet — außer die Liste löst danach auf nichts mehr auf.
  4. Ein Fork überspringt beide Filter und bekommt den Pool der Hauptunterhaltung.
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.
checked am 2026-07-29 gegen docs/en/sub-agents

Ein Wort Unterschied

Derselbe Aufbau, ein Werkzeug Unterschied — und daraus folgt der ganze Verwendungszweck.
Beide Dateien stehen im Begleitprojekt.

# code-reviewer.md: darf NICHT aendern
tools: Read, Grep, Glob, Bash
model: inherit
memory: project

# debugger.md: MUSS aendern
tools: Read, Edit, Bash, Grep, Glob

# Beheben heisst aendern,
# Pruefen heisst es nicht.
  1. Identität: name, description — die zwei Pflichtfelder.
  2. Werkzeuge: tools, disallowedTools, mcpServers.
  3. Ausstattung: model, effort, maxTurns, permissionMode.
  4. Kontext: skills, memory.
  5. Lauf: hooks, background, isolation, color.
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 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.

# .claude/agents/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.

# Beobachtung: kein Grep, kein Read
# auf den Skill -- er weiss es schon
  1. Das Feld steuert nur das Vorladen, nicht die Erreichbarkeit: ohne es findet der Agent Skills weiterhin selbst.
  2. Ganz unterbinden geht nur, indem Skill aus tools fehlt oder in disallowedTools steht.
  3. Nicht vorladbar: Skills mit disable-model-invocation — auch die gebündelten /verify und /code-review nicht.
  4. Fehlt ein Skill, startet der Agent trotzdem. Die Warnung landet nur im Debug-Log — ein Tippfehler fällt nie auf.
checked am 2026-07-29 gegen docs/en/sub-agents

Zwei Richtungen, ein Unterbau

Skill und Subagent greifen in beide Richtungen ineinander.
Die Frage ist nur, wer die Aufgabe trägt und wer den System-Prompt.

A
Skill
context: fork
läuft als Agententyp
Aufgabe = Skill-Inhalt
Prompt = vom Agententyp
B
Subagent
skills: […]
zieht Skills mit
Aufgabe = Auftragsnachricht
Prompt = der Agent-Rumpf
SkillSubagent
  1. Ist der Ablauf das Besondere, schreibt man einen Skill und schickt ihn mit context: fork weg. Beispiel: „durchsuche das Repo nach X".
  2. Ist die Rolle das Besondere, schreibt man einen Subagenten und gibt ihm Skills mit. Beispiel: „du bist Reviewer und achtest immer auf Y".
  3. Es ist derselbe Unterbau — deshalb fühlt sich die Wahl beliebig an, bis man die Frage so stellt.
checked am 2026-07-29 gegen docs/en/skills

Persistentes Gedächtnis

memory: gibt dem Agenten ein Verzeichnis, das Unterhaltungen überlebt.
Links die Konfiguration, rechts was daraus entsteht.

# .claude/agents/code-reviewer.md
tools: Read, Grep, Glob, Bash
memory: project
---
Sieh vor der Arbeit in dein Gedaechtnis.
Halte danach fest, was du gelernt hast.

# nach dem ERSTEN Lauf entsteht:
.claude/agent-memory/code-reviewer/
  MEMORY.md

# und darin zum Beispiel:
## Wiederkehrende Befunde
- Booking.java: Geld als double,
  schon zweimal aufgefallen
- Resource-Klassen tragen Fachlogik
  1. project ist die Empfehlung — das Wissen liegt im Repository und ist teilbar. user gilt überall, local bleibt ungeteilt.
  2. Die ersten 200 Zeilen der MEMORY.md kommen in seinen System-Prompt, mit der Auflage, sie zu pflegen.
  3. Der zweite Lauf kennt den ersten. Das ist der Beobachtungsweg: einmal laufen lassen, Datei ansehen, wieder laufen lassen.
  4. Hängt an Auto-Memory. Ist das abgeschaltet, hat memory keine Wirkung.
memory aktiviert Read, Write und Edit — auch bei einem Agenten, dessen tools keine Schreibwerkzeuge nennen.
checked am 2026-07-29 gegen 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.

# validate-readonly-query.sh
EINGABE=$(cat)
BEFEHL=$(printf '%s' "$EINGABE" \
  | jq -r '.tool_input.command')

printf '%s' "$BEFEHL" | grep -iqE \
  '\b(INSERT|UPDATE|DELETE|DROP)\b' \
  && { echo "Blockiert" >&2; exit 2; }
exit 0

# beobachtbar:
SELECT ... laeuft
UPDATE ... Blockiert (exit 2)
  1. Im Frontmatter definiert, laufen sie nur solange der Agent aktiv ist, und werden danach aufgeräumt.
  2. Der Vertrag: Eingabe als JSON auf der Standardeingabe, Exit-Code 2 blockiert, die Meldung sieht der Agent.
  3. Stop wird zur Laufzeit zu SubagentStop, wenn der Agent als Subagent läuft.
  4. Ohne chmod +x scheitert der Hook, statt zu blockieren — das Gate wirkt dann nicht.
checked am 2026-07-29 gegen docs/en/sub-agents

Lebenszyklus im Projekt

Zwei Ereignisse in der settings.json: Aufbauen, wenn er beginnt, Aufräumen, wenn er fertig ist.
Verbindung auf, Verbindung zu.

// .claude/settings.json
"SubagentStart": [{
  "matcher": "^db-reader$",
  "hooks": [{ /* aufbauen */ }]
}],
"SubagentStop": [{
  /* kein matcher = JEDER Agent */
  "hooks": [{ /* aufraeumen */ }]
}]

# und im Log entstehen zwei Zeilen:
2026-07-29T20:36:04Z START db-reader
2026-07-29T20:36:04Z STOP db-reader
  1. Mit Matcher gezielt, ohne Matcher für jeden — genau richtig fürs Aufräumen.
  2. Der Matcher gehört verankert. Unverankert ist er ein regulärer Ausdruck: db-agent trifft dann auch prod-db-agent.
  3. Der Beleg sind die zwei Zeilen im Log — ehrlicher als jede Behauptung über Lebenszyklus.
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 docs/en/sub-agents

Einen Subagenten abschalten

Subagenten sind Werkzeuge und werden wie Werkzeuge verboten — über die Permissions.

// .claude/settings.json
{
  "permissions": {
    "deny": [
      "Agent(Explore)",
      "Agent(db-reader)"
    ]
  }
}

# fuer einen einzelnen Lauf:
claude --disallowedTools "Agent(Explore)"
  1. Gilt für eingebaute und eigene gleichermaßen.
  2. Ein deny auf irgendeiner Ebene gewinnt. Keine andere Ebene kann es zurücknehmen — auch kein Kommandozeilenargument.
  3. Auch der Weg, einen Agenten aus einem Plugin abzuschalten, den man nicht selbst geschrieben hat.
checked am 2026-07-29 gegen docs/permissions

Die Zähler

Und was Verschachtelung wirklich kostet

Zähler, die verwechselt werden

Drei getrennte Grenzen, jede mit eigener Umgebungsvariable und eigenem Fehlerbild.
Links, wie man sie setzt.

// .claude/settings.json
"env": {
  // pro Sitzung insgesamt, Vorgabe 200
  "CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION":
    "400",
  // gleichzeitig laufend, Vorgabe 20
  "CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS":
    "10",
  // Verschachtelungstiefe, Vorgabe 3
  "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH":
    "1" // 1 = keine Verschachtelung
}

# Fehlerbilder zum Wiedererkennen:
Subagent spawn limit reached
Concurrent subagent limit reached
  1. Es gibt keinen Settings-Schlüssel dafür — nur diese drei Variablen, gesetzt im env-Block.
  2. Ein fertiger Subagent zählt weiter beim Sitzungslimit. /clear setzt es zurück.
  3. Das Fortsetzen eines Agenten belegt einen frischen Platz ohne Prüfung und kann die laufende Zahl über die Grenze schieben.
Diese Zahlen sind die flüchtigsten im 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 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.

ihr
eigener Kontext
Reviewer
Prüfer 1
Prüfer 2
Prüfer 3
nur das
eine
Zusammenfassung
Subagentwas ihr nie seht
  1. An der Grenze wird Agent entzogen, und der Subagent macht die Arbeit selbst statt sie abzulehnen.
  2. Einem einzelnen Agenten nimmt man es mit disallowedTools: Agent — oder indem Agent aus tools fehlt.
  3. Die letzte Zeile im Beispiel ist der Trick: ein Agent ohne Delegation kürzt sonst still.

Jeder Subagent schreibt sein eigenes Transkript

Jeder Subagent schreibt ein eigenes Transkript.
Das ist die beste Fehlersuche, die es gibt: man sieht, was er wirklich gesehen und getan hat.

# wo sie liegen
~/.claude/projects/{projekt}/
  {sitzung}/subagents/
    agent-{id}.jsonl

# eine Zeile daraus
"subtype": "compact_boundary",
"trigger": "auto",
"preTokens": 167189

# Aufraeumfrist
cleanupPeriodDays: 30
  1. Eigene Dateien, eigenes Leben. Läuft /compact in der Hauptunterhaltung, bleiben sie unberührt.
  2. Sie überleben einen Neustart, solange dieselbe Sitzung fortgesetzt wird.
  3. Bei schlechtem Ergebnis hier nachsehen, statt zu raten — im Transkript steht der ganze Lauf.
  4. Bei Kostenfragen ist preTokens der Anhaltspunkt: so viel war verbraucht, bevor gekürzt wurde.
Wie /compact selbst arbeitet und was es von Skills übrig lässt, steht in Erweiterung 1 — hier zählt nur, dass die Transkripte davon nicht betroffen sind.
checked am 2026-07-29 gegen 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 fortsetzen — nicht neu beauftragen.

# ketten: nacheinander beauftragen
Nimm den code-reviewer fuer das
Auth-Modul, dann den debugger fuer
die Befunde.

# fortsetzen: derselbe Agent, voller
# Verlauf -- nicht neu beauftragen
Mach das Review weiter und sieh dir
jetzt die Autorisierung an.

# NICHT fortsetzbar, weil einmalig:
Explore, Plan — sie geben keine
Agent-Kennung zurueck
  1. Fortsetzen behält alles — Verlauf, Werkzeugaufrufe, Ergebnisse. Er macht dort weiter, wo er aufgehört hat.
  2. Für Fortsetzbares braucht es general-purpose oder einen eigenen Agenten.
  3. Ein selbst gestoppter Agent nimmt nichts wieder auf, bis man ihn selbst anspricht.
Zwei Grenzen gelten immer, egal wer schreibt: keine Nachricht eines Agenten zählt als Freigabe für eine offene Berechtigungsanfrage, und keine kann Rechte, CLAUDE.md oder Konfiguration eines Subagenten ändern.
checked am 2026-07-29 gegen docs/en/sub-agents

Subagent, Hauptunterhaltung oder Skill?

Ein Subagent ist nicht die bessere Wahl, sondern eine andere — und oft die falsche.
Drei Fälle, drei Antworten.

# viel Ausgabe, die keiner mehr braucht
# -> SUBAGENT
Finde alle Stellen, an denen eine
Buchung geprueft wird.

# kleine gezielte Aenderung, Hin und Her
# -> HAUPTUNTERHALTUNG
Zieh das Feld price auf BigDecimal.

# wiederverwendbarer Ablauf im Kontext
# -> SKILL
/checking-conventions

# Zwischenfrage zu etwas, das schon
# im Gespraech steht -> /btw
  1. Subagent, wenn viel Ausgabe entsteht, Grenzen durchgesetzt werden sollen, oder eine Zusammenfassung genügt.
  2. Hauptunterhaltung, wenn es Hin und Her braucht, Phasen denselben Kontext teilen — oder Latenz zählt: Subagenten starten bei null.
  3. /btw sieht den vollen Kontext, hat keinen Werkzeugzugriff, und die Antwort wird verworfen statt in den Verlauf aufgenommen.
checked am 2026-07-29 gegen docs/en/sub-agents

Erweiterung 2 in fünf Sätzen

Was von diesem Deck hängenbleiben soll.

  1. CLAUDE.md ist drin, euer Verlauf nicht. Explore und Plan lassen auch CLAUDE.md weg — und das lässt sich nicht ändern.
  2. Werkzeuge werden zweimal verengt. Im Hintergrund, also standardmäßig, fehlen eingebaute Werkzeuge ohne Fehlermeldung.
  3. Wissen kommt über skills, Erfahrung über memory — und memory schaltet stillschweigend Schreibrechte dazu.
  4. Grenzen zieht ein Hook, nicht die Werkzeugliste, wenn das Werkzeug erlaubt und nur die Verwendung eingeschränkt sein soll. Exit-Code 2 blockiert.
  5. Es gibt drei Zähler, nicht einen — Sitzung, Gleichzeitigkeit, Tiefe. 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.
Agententyp Der Wert des Frontmatter-Feldes name. Hooks bekommen ihn als Kennung, und SubagentStart- und SubagentStop-Matcher treffen darauf.
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.11.5