CGS IT Solutions GmbH — Claude Code Training · Modul 8d · Subagenten konfigurieren · v2.0.1

Modul 8d

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

Modul 2 zeigt, was ein Subagent ist — dieses Deck zeigt, wie man ihn konfiguriert.
Links der ganze db-reader aus dem Begleitprojekt, 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-readonly-query.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 dem Subagenten 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 — eine Anweisung an den Subagenten, nicht an euch.
Neue und geänderte Agent-Dateien erkennt Claude Code ohne Neustart.
Fehlte der Ordner .claude/agents/ beim Start ganz, hilft nur ein Neustart.
checked am 2026-09-26 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
- eure bereits geladenen Skills
- euer Output Style
- das Auto-Memory der Session
- 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 — der Subagent läuft mit eigenem System-Prompt.
  5. Kostenfallstrick: an ein kleineres Modell delegieren heißt auch, ein kleineres Fenster zu bekommen.
Mit omitClaudeMd: true startet ein eigener Subagent ohne die CLAUDE.md-Dateien von Nutzer und Projekt.
Gedacht für Agenten, die alles Nötige im Auftrag bekommen.
checked am 2026-09-26 gegen docs/en/sub-agents

Explore und Plan sind anders

Die eingebauten Recherche-Agenten Explore und Plan lassen CLAUDE.md und den Git-Status weg, um klein zu bleiben.
Kein Feld schaltet das wieder ein.

# 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. Nur ein eigener Agent namens Explore ändert das — er ersetzt den eingebauten.
  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-09-26 gegen docs/en/sub-agents

Im Hintergrund fehlen Werkzeuge ohne Meldung

Claude Code filtert die Werkzeugliste zweimal.
Der zweite Filter greift im Hintergrund — und Hintergrund ist die Vorgabe.

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 — und dort laufen Subagenten in einer interaktiven Session immer, solange der Fork-Modus an ist.
  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-09-26 gegen docs/en/sub-agents

Ein Werkzeug entscheidet: prüfen oder beheben

code-reviewer und debugger aus dem Begleitprojekt unterscheiden sich in einem Werkzeug: nur der debugger darf Edit.
Rechts alle Felder, die eine Agent-Datei kennt.

# 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, experimental.
  4. Kontext: skills, memory, omitClaudeMd.
  5. Lauf: hooks, background, isolation, color, initialPrompt.
Bei Subagenten heißt es disallowedTools in Binnenmajuskel, bei Skills disallowed-tools mit Bindestrich.
Ein verwechseltes Feld wird stillschweigend ignoriert.
checked am 2026-09-26 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, Bash
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 der gebündelte /verify 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-09-26 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-09-26 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 (höchstens 25 Kilobyte) 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-09-26 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-09-26 gegen docs/en/sub-agents

Subagenten-Lebenszyklus in der settings.json

Zwei Ereignisse in der settings.json: aufbauen, wenn ein Subagent beginnt, aufräumen, wenn er fertig ist.
Das Begleitprojekt schreibt dafür je eine Zeile ins Log.

// .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 unbekannt
  1. Mit Matcher gezielt, ohne Matcher für jeden — der Start nur für db-reader, das Aufräumen für alle.
  2. Ohne Matcher feuert SubagentStop auch für interne Agenten, etwa bei /btw. Welcher Agent es war, steht nur im Feld agent_type der Hook-Eingabe — und kann leer sein.
  3. Der Beleg sind die Zeilen im Log.
Claude Code liest die .claude/settings.json nur aus dem Startverzeichnis, ohne Rückgriff nach oben.
Wer Claude Code im Repo-Wurzelverzeichnis startet, sieht nichts — und sucht am falschen Ende.
checked am 2026-09-26 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-09-26 gegen docs/en/sub-agents

Die Zähler

Und was Verschachtelung wirklich kostet

Grenzen für Subagenten: Gleichzeitigkeit und Tiefe

Zwei getrennte Grenzen, jede mit eigener Umgebungsvariable und eigenem Verhalten.
Eine Obergrenze pro Session gibt es seit Version 2.1.224 nicht mehr.

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

# Fehlerbild beim Gleichzeitigkeitslimit:
Concurrent subagent limit reached

# an der Tiefengrenze: kein Fehler,
# das Agent-Werkzeug fehlt einfach
  1. Es gibt keinen Settings-Schlüssel dafür — nur diese zwei Variablen, gesetzt im env-Block.
  2. Am Gleichzeitigkeitslimit scheitert jeder weitere Start, und Claude soll es nicht erneut versuchen. Sobald einer fertig ist, geht es wieder.
  3. Das Fortsetzen eines Agenten belegt einen frischen Platz ohne Prüfung und kann die laufende Zahl über die Grenze schieben.
  4. An der Tiefengrenze wird Agent entzogen — der Subagent macht die Arbeit selbst.
Diese Zahlen sind die flüchtigsten im Kurs. Die Standardtiefe war fünf, dann eins, seit 2.1.219 drei; die Grenze pro Session fiel mit 2.1.224 weg.
Vor dem Kurstag nachsehen.
checked am 2026-09-26 gegen docs/en/sub-agents

Subagenten starten Subagenten

Ein Subagent darf selbst delegieren.
Der Gewinn: die Zwischenergebnisse kommen nie bei euch an, nur eine Zusammenfassung.

ihr
eigener Kontext
Reviewer
Prüfer 1
Prüfer 2
Prüfer 3
nur das
eine
Zusammenfassung
Subagentwas ihr nie seht
  1. Bis drei Ebenen unter der Hauptunterhaltung dürfen Subagenten eigene starten — die Vorgabe.
  2. Einem einzelnen Agenten nimmt man es mit disallowedTools: Agent — oder indem Agent aus tools fehlt.
  3. Wer die Delegation nimmt, schreibt eine Ausstiegszeile dazu: „Wenn der Umfang die Aufgabe unlösbar macht, sag das statt still zu kürzen." Sonst kürzt der Agent still.
checked am 2026-09-26 gegen docs/en/sub-agents

Jeder Subagent schreibt ein eigenes Transkript

Im Transkript steht, was der Subagent wirklich gesehen und getan hat.
Bei einem schlechten Ergebnis ist es die erste Stelle zum Nachsehen.

# wo sie liegen
~/.claude/projects/{projekt}/
  {session}/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 Session fortgesetzt wird.
  3. Die Agent-Kennung steht im Dateinamen — damit lässt sich genau dieser Agent fortsetzen.
  4. Bei Kostenfragen ist preTokens der Anhaltspunkt: so viel war verbraucht, als der Subagent sein eigenes /compact auslöste.
checked am 2026-09-26 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. Claude schickt dem Agenten dazu per SendMessage eine Nachricht an seine Kennung oder seinen Namen.
  2. Für Fortsetzbares braucht es general-purpose oder einen eigenen Agenten.
  3. Einen Agenten, den ihr selbst gestoppt habt (x in /tasks), setzt Claude nicht fort — nur ihr, indem ihr in sein Transkript tippt.
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-09-26 gegen docs/en/sub-agents

Subagent, Hauptunterhaltung oder Skill?

Drei Aufgaben, drei Werkzeuge: Subagent, Hauptunterhaltung, Skill.
Die Wahl hängt daran, wie viel Ausgabe entsteht und wer sie noch braucht.

# 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.
  4. Eigener Cache: Ein Subagent liest nicht aus dem Cache der Hauptunterhaltung, er baut seinen eigenen auf — mit fünf Minuten Lebensdauer, auch im Abo. Ein Fork liest mit.
checked am 2026-09-26 gegen docs/en/sub-agents + docs/en/prompt-caching

Modul 8d 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 — kein Feld schaltet es ein.
  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. Gleichzeitigkeit und Tiefe sind getrennte Grenzen. 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.
Fork-Modus Einstellung, mit der Claude die laufende Unterhaltung forken darf. In interaktiven Sessions standardmäßig an; dann laufen alle Subagenten im Hintergrund, und für sie gilt der kleinere Werkzeugsatz.
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 · Modul 8d · Subagenten · v2.0.1