Claude Code Subagents & Hooks: 12 Schritte, 45 Min [2026]

Claude Code kann seit den jüngsten Updates weit mehr als nur Code vorschlagen. Mit Subagents lassen sich Teilaufgaben an isolierte Helfer auslagern, mit Hooks greifen Sie deterministisch in jeden Schritt des Agenten ein, vom ersten Tool-Aufruf bis zum Sessionende. Wer beides richtig kombiniert, baut sich eine Code-Review- und Sicherheits-Pipeline, die zuverlässiger arbeitet als ein einzelner Prompt es je könnte. Dieser Tutorial-Artikel zeigt in zwölf Schritten, wie Sie eigene Subagents schreiben, Hooks in settings.json konfigurieren und am Ende ein komplettes, lauffähiges Projekt stehen haben.

Dieser Artikel setzt eine fertige Claude-Code-Grundinstallation voraus. Wer die CLI noch nie eingerichtet hat, findet die Basisschritte dafür in unserer Anleitung zur Claude-Code-Installation. Für Hintergrund zu den aktuellen Modellen, die in den Beispielen unten als model-Werte auftauchen, lohnt sich zusätzlich ein Blick in unseren Artikel zu Claude Sonnet 5.5. Wer die hier gezeigten Subagents später per Plugin im Team verteilen will, findet den passenden Anschluss in unserem Beitrag zu Claude Code Mods.

Was sind Subagents und Hooks in Claude Code?

Ein Subagent ist ein eigenständiger Claude-Code-Prozess mit eigenem Kontextfenster, eigenem Systemprompt und einer eigenen Werkzeugliste. Die offizielle Dokumentation beschreibt Subagents als Markdown-Dateien mit YAML-Frontmatter, die im Hauptgespräch bei Bedarf delegiert werden. Das hat einen praktischen Vorteil: Der Hauptagent bleibt schlank, während ein Code-Reviewer, ein Testrunner oder ein Security-Checker im Hintergrund arbeitet, ohne den Haupt-Kontext mit Dateiinhalten zu überladen.

Hooks funktionieren anders. Die offizielle Agent-SDK-Dokumentation von Anthropic beschreibt Hooks als Callback-Funktionen, die eigenen Code als Reaktion auf Agent-Ereignisse ausführen, etwa wenn ein Tool aufgerufen wird, eine Session startet oder die Ausführung stoppt. Ein Hook greift also nicht in den Dialog ein, sondern in den Lebenszyklus. Er kann einen Bash-Befehl blockieren, bevor er ausgeführt wird, oder nach jedem Dateizugriff automatisch einen Linter starten. Zusammen ergeben Subagents und Hooks ein zweischichtiges System, Subagents delegieren Arbeit, Hooks erzwingen Regeln. Für Teams, die bereits mit MCP-Servern arbeiten, kommt als dritte Ebene oft noch der direkte Werkzeugzugriff über das Model Context Protocol dazu, dazu mehr in Schritt 10.

Eine dritte Erweiterungsebene, die in der Praxis oft mit Subagents verwechselt wird, sind Skills. Eine Skill ist eine wiederverwendbare Prompt-Vorlage, die Claude Code bei Bedarf nachlädt, aber kein eigenes Kontextfenster besitzt und keine eigenen Hooks definieren kann. Ein Subagent dagegen läuft als eigener Prozess mit eigenem Kontext und kann, wie in Schritt 8 gezeigt, sogar eigene Hooks mitbringen. Wer eine Aufgabe nur als Textbaustein wiederverwenden will, greift zu einer Skill, wer echte Isolation und eigene Tool-Rechte braucht, baut einen Subagent.

Aktuell ist das Thema besonders relevant, weil Anthropic die Modellbasis gerade neu aufgestellt hat. Claude Opus 5.5 ist am 22. September 2026 erschienen und läuft laut offiziellen Release Notes 40 Prozent günstiger als Opus 5. Eine Woche später, am 28. September 2026, folgte Claude Sonnet 5.5 als schnelleres, kostengünstigeres Pendant, und am 7. Oktober 2026 kam mit Claude Haiku 5.5 das bisher schnellste und günstigste Modell der Familie dazu. Wer Subagents mit einem bestimmten Modell verankert, sollte diese drei Namen kennen, denn genau sie tauchen gleich im Frontmatter-Feld model wieder auf.

Voraussetzungen: Versionen, Rechte und Tools

Bevor Sie den ersten Subagent schreiben, brauchen Sie eine aktuelle Claude-Code-Installation. Die GitHub-Releases-Seite des Projekts weist Version 2.1.296 vom 9. Oktober 2026 als aktuellsten Stand aus. Subagent-Hooks und das erweiterte Event-Set für Agent-Hooks sind erst in den Versionen der 2.1er-Reihe vollständig verfügbar, ein Update lohnt sich also in jedem Fall. Die folgende Tabelle fasst zusammen, was auf Ihrem Rechner installiert sein sollte.

Komponente	Mindestversion / Anforderung	Zweck
Node.js	Version 18 oder neuer	Laufzeitumgebung für die Claude-Code-CLI
Claude Code CLI	Aktuell 2.1.296 (Stand 9. Oktober 2026)	Agent, Subagent-Runtime, Hook-Engine
npm	Im Node.js-Paket enthalten	Installation des CLI-Pakets
Bash oder Python 3	Für Hook-Skripte	Ausführung von command-Hooks
Claude-Abo oder API-Key	Pro-, Max- oder API-Zugang	Zugriff auf Sonnet 5.5, Opus 5.5 oder Haiku 5.5
Git-Repository	Beliebige Version	Ablageort für .claude/agents und .claude/settings.json

Rechteseitig reicht ein normaler Benutzer-Account ohne Root-Zugriff, solange Sie Dateien im Projektordner und in Ihrem Home-Verzeichnis anlegen dürfen. Für Hook-Skripte, die auf das Dateisystem zugreifen oder externe Befehle ausführen, sollten Sie zusätzlich wissen, welche Shell auf Ihrem System als Standard läuft, denn davon hängt die Shebang-Zeile in Schritt 6 ab.

Für Teams in Österreich und im restlichen DACH-Raum kommt ein weiterer Punkt dazu: Sobald ein Hook Daten an einen externen Dienst wie eine HTTP-Schnittstelle oder einen MCP-Server weitergibt, verlässt diese Information unter Umständen das eigene Netzwerk. Prüfen Sie bei http- und mcp_tool-Hooks deshalb genau, welche Nutzlast tatsächlich übertragen wird, insbesondere wenn der Hook auf Code aus Projekten mit personenbezogenen Daten reagiert. Ein lokal laufender command-Hook, der nur innerhalb des eigenen Rechners arbeitet, vermeidet diese Frage meist von vornherein.

Erste Schritte: Installation und Projektstruktur

Schritt 1: Claude Code installieren und aktualisieren

Installieren Sie die CLI global über npm und prüfen Sie direkt danach die Version. Wenn bereits eine ältere Installation existiert, holt derselbe Befehl das Update.

npm install -g @anthropic-ai/claude-code
claude --version
claude doctor

Der Befehl claude doctor prüft Pfade, Konfigurationsdateien und die Verbindung zum Modell-Backend. Taucht dabei eine Warnung zu veralteten Einstellungen auf, lohnt sich ein Blick in die offiziellen Release Notes, denn Anthropic verändert das Hook-Schema zwischen Minor-Versionen gelegentlich.

Schritt 2: Ordnerstruktur für Agents und Hooks anlegen

Subagents und projektweite Hook-Einstellungen leben in einem versteckten Ordner namens .claude im Projektstamm. Legen Sie die Struktur einmal konsequent an, dann funktionieren alle folgenden Schritte ohne Anpassung der Pfade.

mkdir -p .claude/agents
mkdir -p .claude/hooks
touch .claude/settings.json
echo '{"hooks": {}}' > .claude/settings.json

Wichtig für Teams: Legt jedes Mitglied eigene, persönliche Subagents an, gehören diese nach ~/.claude/agents/ statt ins Projektverzeichnis. Nur projektweite Agents, die mit dem Repository versioniert werden sollen, kommen unter .claude/agents/ und damit in die Versionskontrolle.

Den ersten eigenen Subagent erstellen

Ein Subagent besteht aus einer einzigen Markdown-Datei. Der Dateiname ist dabei frei wählbar, der name im Frontmatter entscheidet, wie Claude Code den Agenten intern referenziert. Legen Sie als Einstieg einen Code-Reviewer an, der nach jeder Änderung auf Sicherheitslücken und fehlende Fehlerbehandlung prüft. Der Text nach der schließenden Frontmatter-Zeile ist dabei keine Nebensache: Er wird vollständig zum Systemprompt dieses einen Subagents, unabhängig davon, was im Systemprompt des Hauptagenten steht. Je konkreter dieser Text eine Rolle, eine Reihenfolge und ein Ausgabeformat vorgibt, desto konsistenter fallen die Ergebnisse über mehrere Durchläufe hinweg aus.

---
name: code-reviewer
description: Prueft Aenderungen auf Korrektheit, Sicherheitsluecken und Wartbarkeit. Nach jeder Code-Aenderung einsetzen.
tools: Read, Grep, Glob, Bash
model: inherit
---

Du bist ein erfahrener Code-Reviewer.

Pruefe die relevanten Aenderungen und melde:
1. Korrektheitsfehler
2. Sicherheitsluecken
3. Fehlende Fehlerbehandlung
4. Luecken in der Testabdeckung
5. Wartbarkeitsprobleme

Aendere keine Dateien, ausser es wird ausdruecklich verlangt.

Pflichtfelder und optionale Felder im Frontmatter

Die offizielle Dokumentation unter code.claude.com/docs/en/sub-agents nennt nur zwei Pflichtfelder, name und description. Alles andere ist optional, wirkt sich aber direkt auf Kosten und Verhalten aus. Die folgende Tabelle zeigt, welche Felder es gibt und wofür sie stehen.

Feld	Pflicht?	Bedeutung
name	Ja	Eindeutiger Bezeichner des Subagents
description	Ja	Entscheidet, wann Claude den Subagent automatisch delegiert
tools	Nein	Werkzeugliste; ohne Angabe erbt der Subagent alle verfügbaren Tools
model	Nein	z. B. inherit, sonnet-5-5, opus-5-5 oder haiku-5-5
Markdown-Body	Ja (Inhalt)	Wird der alleinige Systemprompt des Subagents, nicht der Haupt-Systemprompt

Die Reihenfolge, nach der Claude Code das Modell bestimmt, ist klar dokumentiert: Zuerst zählt ein Modell, das für den konkreten Aufruf übergeben wird, danach das model-Feld im Frontmatter, dann die Umgebungsvariable CLAUDE_CODE_SUBAGENT_MODEL und erst zuletzt das Modell des Hauptgesprächs. Der Wert inherit überspringt diese Kette bewusst und übernimmt direkt das Modell der Hauptsession.

Tools pro Subagent gezielt einschränken

Ein Subagent, der nur Dateien lesen und nach Mustern suchen soll, braucht keinen Zugriff auf Bash oder Write. Schränken Sie die Werkzeugliste so eng wie möglich ein, das reduziert sowohl Risiko als auch Token-Verbrauch. Darf ein Subagent selbst wieder andere Subagents starten, lässt sich das über die Syntax Agent(security-reviewer), Agent(test-runner) im Feld tools auf bestimmte Agent-Typen begrenzen, statt pauschal jeden verfügbaren Subagent freizugeben.

Ein zweites Beispiel: Testrunner-Subagent

Ein Code-Reviewer allein deckt nicht jeden Anwendungsfall ab. In der Praxis lohnt sich ein zweiter Subagent, der ausschließlich Tests ausführt und deren Ausgabe auswertet, statt selbst Code zu bewerten. Dieser Testrunner braucht im Gegensatz zum Reviewer tatsächlich Bash-Zugriff, aber keinen Zugriff auf Write, damit er Testdateien lesen und Testläufe starten, aber keinen Produktionscode verändern kann.

---
name: test-runner
description: Fuehrt die Testsuite aus und fasst fehlgeschlagene Tests zusammen. Nach jeder Aenderung an src/ einsetzen.
tools: Read, Grep, Bash
model: claude-haiku-5-5
---

Du fuehrst npm test aus und analysierst die Ausgabe.

Bei Fehlschlaegen:
1. Betroffene Testdatei und Zeile nennen
2. Vermutete Ursache in einem Satz zusammenfassen
3. Keine Codeaenderungen vorschlagen, nur melden

Bei vollstaendigem Erfolg: Kurze Bestaetigung ohne weitere Details.

Das Feld model steht hier bewusst auf claude-haiku-5-5 statt auf inherit. Testausgaben zusammenfassen ist eine vergleichsweise einfache Aufgabe, für die sich das schnellste und günstigste Modell der aktuellen Generation anbietet, während der Hauptagent für komplexere Entscheidungen weiterhin ein leistungsfähigeres Modell nutzen kann. Diese Kombination aus mehreren spezialisierten Subagents mit unterschiedlichen Modellen ist einer der größten praktischen Vorteile gegenüber einem einzigen Agenten, der jede Aufgabe mit demselben, oft teureren Modell erledigt.

Schritt 4: Subagents gezielt aufrufen und automatisch delegieren lassen

Es gibt zwei Wege, einen Subagent auszulösen. Der explizite Weg nennt den Agenten direkt in der Eingabe, etwa mit “Nutze den code-reviewer Subagent für diese Änderung”. Der implizite Weg verlässt sich auf die description, Claude entscheidet dann selbst, ob eine Aufgabe zum Subagent passt. In der Praxis liefert eine präzise Beschreibung deutlich bessere Trefferquoten als eine vage Formulierung. Statt “hilft bei Code” sollte die Beschreibung klar benennen, wofür der Agent zuständig ist und wann er greifen soll, etwa “für die Prüfung von Authentifizierung, Autorisierung und Umgang mit Secrets bei sicherheitsrelevanten Änderungen einsetzen”. Beide Wege lassen sich übrigens kombinieren: Nutzen Sie den expliziten Aufruf während der Testphase, um gezielt zu prüfen, ob der Subagent wie erwartet reagiert, und verlassen Sie sich erst danach im Alltag auf die automatische Delegation über die description.

Ein typischer Lauf sieht am Terminal so aus:

> Nutze den code-reviewer Subagent, um die Aenderungen in src/auth.js zu pruefen

[subagent:code-reviewer] gestartet, Kontext isoliert
[subagent:code-reviewer] liest src/auth.js, src/auth.test.js
[subagent:code-reviewer] Befund: Fehlende Rate-Limit-Pruefung in login()
[subagent:code-reviewer] beendet

Zusammenfassung an Hauptagent uebergeben: 1 Sicherheitsbefund, 0 Korrektheitsfehler

Der Hauptvorteil gegenüber einer einfachen Anweisung im Hauptgespräch: Der Subagent arbeitet mit eigenem, isoliertem Kontext. Er liest nur, was er für seine Aufgabe braucht, und überschwemmt das Hauptgespräch nicht mit Dateiinhalten, die dort gar nicht gebraucht werden.

Schritt 5: Die Hook-Lifecycle-Events verstehen

Ein Hook reagiert immer auf ein bestimmtes Ereignis im Lebenszyklus des Agenten. Laut der offiziellen Hooks-Referenz besteht die Konfiguration aus drei Ebenen: zuerst wird ein Hook-Event gewählt, etwa PreToolUse oder Stop, danach eine Matcher-Gruppe, die filtert, wann der Hook greift, zum Beispiel nur für das Bash-Tool, und schließlich ein oder mehrere Hook-Handler, die bei einem Treffer ausgeführt werden (Anthropic, Claude Code Docs). Mehr als zwanzig solcher Events sind inzwischen dokumentiert. Die wichtigsten für den Einstieg zeigt diese Tabelle.

Event	Wann es ausgelöst wird
PreToolUse	Bevor ein Tool ausgeführt wird; kann blockieren, ändern oder freigeben
PostToolUse	Nach erfolgreicher Ausführung eines Tools
PostToolUseFailure	Nach einem fehlgeschlagenen Tool-Aufruf
UserPromptSubmit	Wenn der Nutzer einen Prompt absendet, vor der Verarbeitung
Stop	Wenn Claude die Antwort beenden will
SubagentStart / SubagentStop	Beim Start bzw. kurz vor dem Ende eines Subagents
SessionStart / SessionEnd	Beim Start bzw. Ende einer Claude-Code-Session
PreCompact / PostCompact	Vor bzw. nach der Kontext-Kompaktierung
PermissionRequest / PermissionDenied	Wenn eine Berechtigung angefragt oder verweigert wird

Bei Tool-bezogenen Events wie PreToolUse wird der Matcher gegen das Feld tool_name geprüft, nicht gegen den Befehlstext. Ein Matcher mit dem Wert Bash greift also für jeden Bash-Aufruf, unabhängig davon, welcher konkrete Befehl ausgeführt wird. Für mehrere Tools gleichzeitig funktioniert ein regulärer Ausdruck wie Edit|Write, für MCP-Werkzeuge eignet sich ein Muster wie mcp__.*.

In der Praxis deckt eine Handvoll Events den Großteil der Anwendungsfälle ab. PreToolUse eignet sich für alles, was vor einer riskanten Aktion geprüft werden muss, etwa destruktive Shell-Befehle oder Schreibzugriffe auf geschützte Ordner. PostToolUse passt für Nacharbeiten, die erst nach einer erfolgreichen Aktion Sinn ergeben, zum Beispiel ein automatischer Formatierungslauf nach jedem Edit. SessionStart und SessionEnd eignen sich für Protokollierung und Benachrichtigungen, während SubagentStart und SubagentStop vor allem dann interessant werden, wenn mehrere Subagents parallel laufen und Sie nachvollziehen wollen, welcher Agent wann aktiv war.

Schritt 6: Den ersten Hook in settings.json konfigurieren

Zeit für den ersten praktischen Hook. Das Ziel: Jeder Bash-Befehl wird vor der Ausführung an ein kleines Python-Skript geschickt, das gefährliche Muster abfängt. Öffnen Sie .claude/settings.json und tragen Sie den Hook unter PreToolUse ein.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/check_bash.py",
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Das zugehörige Skript empfängt die Nutzlast als JSON über stdin. Legen Sie es unter .claude/hooks/check_bash.py ab und machen Sie es ausführbar.

#!/usr/bin/env python3
import json
import sys

payload = json.load(sys.stdin)
command = payload.get("tool_input", {}).get("command", "")

gefaehrliche_muster = ["rm -rf /", ":(){:|:&};:", "> /dev/sda"]

for muster in gefaehrliche_muster:
    if muster in command:
        print(f"Blockiert: gefaehrliches Muster '{muster}' erkannt", file=sys.stderr)
        sys.exit(2)

sys.exit(0)

chmod +x .claude/hooks/check_bash.py

Testen Sie den Hook, indem Sie Claude Code bitten, rm -rf / auszuführen. Die Ausgabe sollte etwa so aussehen:

[hook:PreToolUse] matcher=Bash ausgeloest
[hook:PreToolUse] check_bash.py beendet mit exit code 2
[hook:PreToolUse] Tool-Aufruf blockiert: "Blockiert: gefaehrliches Muster 'rm -rf /' erkannt"
Claude: Ich habe den Befehl nicht ausgefuehrt, da er als gefaehrlich eingestuft wurde.

Schritt 7: Hook-Entscheidungen steuern: Exit Codes und JSON-Output

Exit-Code 0 und Exit-Code 2

Command-Hooks kommunizieren über drei Kanäle: den Exit-Code, die Standardausgabe und die Fehlerausgabe. Exit-Code 0 bedeutet, der Hook ist erfolgreich durchgelaufen, die eigentliche Aktion darf weiterlaufen. Exit-Code 2 blockiert die Aktion und nutzt stderr als Begründung, bei einem PreToolUse-Hook verhindert das den Tool-Aufruf vollständig. Jeder andere Exit-Code gilt als Fehler des Hooks selbst und wird nicht als strukturierte Ablehnung interpretiert. Das macht Exit-Codes zu einem groben, aber zuverlässigen Werkzeug für einfache Ja-oder-Nein-Entscheidungen. Für die meisten Teams reicht dieser grobe Mechanismus im Alltag völlig aus, gerade bei Hooks, die nur eine einzige, klar abgrenzbare Bedingung prüfen, etwa ob ein bestimmtes Muster im Befehl vorkommt oder nicht.

Strukturierte JSON-Antworten für feinere Kontrolle

Für feinere Steuerung kann ein Hook statt eines Exit-Codes ein JSON-Objekt auf stdout schreiben. Für PreToolUse sieht eine typische Antwort so aus:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Der Befehl versucht, das Root-Dateisystem zu loeschen."
  }
}

Die drei möglichen Werte für permissionDecision sind allow, deny und ask. Mit allow läuft die Aktion ohne zusätzliche Rückfrage durch, deny blockiert sie und übergibt die Begründung an Claude, ask überlässt die Entscheidung dem normalen Berechtigungsdialog. Ein Hook kann zusätzlich Kontext an Claude zurückgeben, etwa den Hinweis, den Paketmanager des Repositories statt einer globalen Installation zu verwenden. Diese Flexibilität ist der entscheidende Unterschied zu reinen Exit-Codes.

Schritt 8: Hooks direkt im Subagent-Frontmatter scopen

Nicht jeder Hook soll für die ganze Session gelten. Laut der offiziellen Dokumentation gibt es zwei Wege, Hooks zu konfigurieren. Im Frontmatter eines Subagents definierte Hooks laufen nur, während genau dieser Subagent aktiv ist. Hooks in settings.json gelten dagegen sessionweit und feuern auch innerhalb von Subagents mit. Das bedeutet in der Praxis: Ein Hook, der nur für den code-reviewer gelten soll, kommt direkt in dessen Markdown-Datei und nicht in die globale settings.json. Wer beide Ebenen vermischt, riskiert doppelte Prüfungen, etwa wenn ein globaler PreToolUse-Hook und ein subagent-eigener Hook denselben Bash-Befehl zweimal validieren und dadurch unnötig Zeit kosten.

---
name: security-scanner
description: Scannt Aenderungen an Auth- und Payment-Code auf Sicherheitsluecken.
tools: Read, Grep, Glob
model: inherit
hooks:
  PreToolUse:
    - matcher: "Read"
      hooks:
        - type: command
          command: "python3 .claude/hooks/log_file_access.py"
          timeout: 5
---

Du scannst ausschliesslich sicherheitsrelevante Dateien in src/auth/ und src/payment/.

Offiziell bestätigt Anthropic ausdrücklich, dass Subagents eigene Hooks definieren können, die über ihren gesamten Lebenszyklus laufen. Diese Hooks werden also automatisch aufgeräumt, sobald der Subagent fertig ist, Sie müssen sich um keine Bereinigung kümmern. Das macht subagent-eigene Hooks besonders attraktiv für temporäre Prüfungen, die nur in einem engen Kontext Sinn ergeben, etwa das Protokollieren jedes Dateizugriffs während eines einzelnen Security-Scans, ohne dass dieses Protokoll danach für jede andere Aktion im Projekt weiterläuft. Ein weiterer Vorteil: Weil der Hook direkt neben der Beschreibung und den Tools des Subagents steht, sieht jeder, der die Datei öffnet, auf einen Blick, welche zusätzliche Prüfung beim Einsatz dieses konkreten Agents aktiv wird, ohne zwischen mehreren Konfigurationsdateien hin- und herspringen zu müssen.

Schritt 9: Komplettprojekt: Sicherheits-Pipeline aus Subagent und Hook

Jetzt werden die einzelnen Teile zu einem lauffähigen Projekt zusammengesetzt. Ziel ist eine Pipeline, die bei jeder Änderung an sicherheitsrelevantem Code automatisch einen Subagent zur Prüfung startet und gleichzeitig per Hook verhindert, dass gefährliche Shell-Befehle überhaupt erst ausgeführt werden. Die fertige Projektstruktur sieht so aus:

mein-projekt/
├── .claude/
│   ├── agents/
│   │   ├── code-reviewer.md
│   │   └── security-scanner.md
│   ├── hooks/
│   │   ├── check_bash.py
│   │   └── notify_on_stop.py
│   └── settings.json
├── src/
│   ├── auth/
│   └── payment/
└── package.json

Die zentrale settings.json bündelt alle sessionweiten Hooks und sorgt dafür, dass nach jedem erfolgreichen Edit-Vorgang automatisch der code-reviewer vorgeschlagen wird, während der security-scanner nur für die geschützten Ordner zuständig ist.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "python3 .claude/hooks/check_bash.py", "timeout": 10 }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "prompt", "command": "Pruefe kurz, ob die Aenderung Tests benoetigt.", "timeout": 30 }]
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "python3 .claude/hooks/notify_on_stop.py", "timeout": 5 }]
      }
    ]
  }
}

Der Stop-Hook ruft ein kleines Skript auf, das am Ende jeder Session eine Zusammenfassung ausgibt. Das hilft vor allem, wenn mehrere Entwickler am selben Repository mit eigenen Subagents arbeiten und niemand die Übersicht über offene Befunde verlieren soll.

#!/usr/bin/env python3
import json
import sys
from datetime import datetime

payload = json.load(sys.stdin)
session_id = payload.get("session_id", "unbekannt")
zeitstempel = datetime.utcnow().isoformat()

with open(".claude/hooks/logs/sessions.log", "a") as log:
    log.write(f"{zeitstempel} Session {session_id} beendet\n")

print(f"Session {session_id} protokolliert um {zeitstempel}")
sys.exit(0)

Mit diesem Aufbau laufen drei Sicherheitsebenen gleichzeitig: Der PreToolUse-Hook verhindert destruktive Befehle, der PostToolUse-Hook erinnert nach jeder Codeänderung an Tests, und der Stop-Hook löst am Ende der Session eine Benachrichtigung aus. Der code-reviewer und der security-scanner übernehmen die inhaltliche Prüfung, ohne dass der Hauptagent dafür seinen eigenen Kontext aufblähen muss. Genau diese Kombination aus deterministischen Hooks und flexiblen Subagents bildet heute den Kern dessen, was viele Entwickler als Agent Engineering in Claude Code bezeichnen.

So sieht ein vollständiger Durchlauf durch diese Pipeline aus, nachdem eine Entwicklerin eine Änderung an src/auth/login.js vorschlägt:

[hook:PreToolUse] matcher=Edit|Write ausgeloest, Pruefung erfolgreich
[subagent:security-scanner] gestartet fuer src/auth/login.js
[subagent:security-scanner] Befund: Fehlende Rate-Limit-Pruefung
[hook:PostToolUse] Erinnerung an Tests ausgegeben
[subagent:test-runner] gestartet, npm test laeuft
[subagent:test-runner] 42 Tests bestanden, 1 fehlgeschlagen (login.test.js:18)
[hook:Stop] Session protokolliert in .claude/hooks/logs/sessions.log

Ergebnis: 1 Sicherheitsbefund, 1 fehlgeschlagener Test, Review vor Merge empfohlen

Ohne diese Pipeline hätte ein Entwickler denselben Befund nur gefunden, wenn er von sich aus daran gedacht hätte, nach dem Edit sowohl einen Sicherheits-Check als auch die Testsuite anzustoßen. Mit Hooks und Subagents passiert das automatisch, bei jeder einzelnen Änderung und unabhängig davon, wie erfahren oder aufmerksam die Person gerade ist, die den Code schreibt.

Schritt 10 bis 12: MCP-Integration, Timeouts und Produktionsbetrieb

Schritt 10: Agent-Hooks und MCP-Server verbinden

Neben command-, http- und prompt-Hooks kennt Claude Code auch den Typ agent. Der Unterschied zum einfachen Prompt-Hook ist laut Dokumentation deutlich: Ein Prompt-Hook macht genau einen LLM-Aufruf und bewertet eine Situation in einem Schritt, ein Agent-Hook dagegen startet einen vollständigen Subagent, der selbst Dateien lesen, Code durchsuchen und weitere Tools nutzen kann, um eine Bedingung zu prüfen, bevor er seine Entscheidung zurückgibt. Ein Agent-Hook eignet sich damit für Prüfungen, die mehr als eine einzelne Modellanfrage brauchen, etwa das Nachschlagen in mehreren Dateien, bevor ein Edit freigegeben wird. In Kombination mit MCP-Servern, die über den Matcher mcp__.* angesprochen werden, lassen sich auch externe Datenquellen wie Ticket-Systeme oder interne Wikis in die Entscheidung einbeziehen. Ein Beispiel aus der Praxis: Ein Agent-Hook am PreToolUse-Event prüft vor jedem Deployment-Befehl automatisch über einen MCP-Server, ob im Ticket-System noch offene Blocker für den betroffenen Service eingetragen sind, und blockiert den Befehl, falls ja.

Schritt 11: Timeouts und Kontext-Budget im Griff behalten

Jeder Hook-Typ hat ein eigenes Zeitbudget. command-, http- und mcp_tool-Hooks dürfen üblicherweise deutlich länger laufen als Hooks, die unmittelbar die Benutzeroberfläche betreffen. Diese Unterscheidung ergibt Sinn: Ein Linter darf ein paar Sekunden brauchen, eine Oberflächenaktion wie die Anzeige einer Nachricht aber nicht, sonst wirkt die gesamte Sitzung träge. Die folgende Tabelle zeigt die Richtwerte aus der offiziellen Dokumentation.

Hook-Typ	Typisches Timeout	Wann einsetzen
command	Bis zu 10 Minuten	Shell-Skripte, Linter, Tests
http	Bis zu 10 Minuten	Externe APIs, interne Services
mcp_tool	Bis zu 10 Minuten	MCP-Server-Werkzeuge
prompt	30 Sekunden	Schnelle Ein-Satz-Bewertungen durch das Modell
agent	60 Sekunden	Mehrschrittige Prüfungen mit Datei- und Codezugriff

Setzen Sie bei langsamen Prüfungen immer ein explizites timeout-Feld, statt sich auf den Standardwert zu verlassen. Netzwerkaufrufe, Paketinstallationen oder große Repository-Scans gehören nicht in Events mit kurzem Zeitbudget wie MessageDisplay oder SessionEnd, dort liegt das Budget laut Dokumentation im Bereich von anderthalb Sekunden, sofern kein höherer Wert konfiguriert wird.

Schritt 12: Testen, debuggen und ins Team ausrollen

Bevor die Konfiguration ins Team geht, lohnt sich ein Trockenlauf mit absichtlich falschen Eingaben. Lösen Sie jeden Hook einmal gezielt aus, prüfen Sie die Logs und committen Sie erst danach .claude/agents/ und .claude/settings.json ins Repository. Persönliche Hooks, etwa für individuelle Benachrichtigungen, bleiben in ~/.claude/settings.json und damit außerhalb der Versionskontrolle. So vermeiden Sie, dass ein Kollege plötzlich Desktop-Benachrichtigungen bekommt, die eigentlich nur für Ihren Rechner gedacht waren. Ein zweiter sinnvoller Test vor dem Rollout: Lassen Sie einen Kollegen das Repository frisch klonen und prüfen Sie, ob alle Hook-Skripte auch ohne Ihre lokalen Umgebungsvariablen funktionieren. Viele Hooks laufen beim Autor einwandfrei, scheitern aber auf einer frischen Maschine, weil ein Pfad oder ein Python-Paket fest vorausgesetzt wurde. Wer Claude Code auch mobil über die in unserem Artikel zu Claude Code Remote Control beschriebene Fernsteuerung nutzt, sollte Hooks zusätzlich einmal von einem Mobilgerät aus auslösen, da dort andere Standardpfade und Umgebungsvariablen gelten können als am Desktop.

Subagents und Hooks in CI/CD-Pipelines einsetzen

Claude Code läuft nicht nur interaktiv im Terminal, sondern auch headless in Build-Pipelines. Dort zahlt sich die Kombination aus Subagents und Hooks noch stärker aus als in der täglichen Arbeit am eigenen Rechner, weil niemand live zusieht und jeder Fehler erst im nächsten Review auffällt. In einer GitHub-Actions-Pipeline lässt sich der security-scanner aus Schritt 9 beispielsweise automatisch auf jeden Pull Request anwenden, bevor ein Mensch überhaupt draufschaut.

name: claude-security-review
on: pull_request

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Claude Code installieren
        run: npm install -g @anthropic-ai/claude-code
      - name: Security-Subagent ausfuehren
        run: |
          claude --print "Nutze den security-scanner Subagent fuer die geaenderten Dateien in diesem PR"
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
          CLAUDE_CODE_SUBAGENT_MODEL: claude-haiku-5-5

Wichtig für CI-Umgebungen: Setzen Sie CLAUDE_CODE_SUBAGENT_MODEL bewusst auf ein günstigeres Modell wie Haiku 5.5, denn in einer Pipeline, die bei jedem Pull Request neu läuft, summieren sich Kosten schneller als im interaktiven Einsatz. Ein PreToolUse-Hook, der destruktive Befehle blockiert, sollte in CI-Umgebungen genauso aktiv sein wie lokal, denn ein Subagent mit Schreibzugriff auf das Repository kann in einer automatisierten Pipeline ebenso Schaden anrichten wie auf dem eigenen Rechner. Für produktive Pipelines empfiehlt es sich zusätzlich, den Exit-Code des claude --print-Aufrufs auszuwerten und den Workflow bei einem gemeldeten Sicherheitsbefund aktiv fehlschlagen zu lassen, statt die Ausgabe nur zu protokollieren.

Behalten Sie außerdem im Blick, wie oft die Pipeline tatsächlich läuft. Ein Subagent, der bei jedem Push auf jeden Branch startet, erzeugt deutlich mehr Kosten als einer, der nur bei Pull Requests gegen den Hauptbranch greift. Viele Teams beschränken den Workflow deshalb bewusst auf pull_request-Ereignisse und lassen den vollen, teureren Opus-5.5-Lauf nur manuell vor einem Release anstoßen, während der günstigere Haiku-5.5-Subagent bei jedem Commit mitläuft.

Häufige Fehler und Stolperfallen beim Einrichten

Die meisten Probleme mit Subagents und Hooks entstehen nicht durch Bugs in Claude Code selbst, sondern durch Missverständnisse darüber, wie Matcher, Berechtigungen und Delegation genau zusammenspielen. Die folgenden sechs Fehler tauchen in Projekten mit frisch eingerichteten Subagents besonders häufig auf.

• Vage description im Subagent: Formulierungen wie “hilft bei Code” führen dazu, dass Claude den Subagent selten oder nie automatisch auswählt. Beschreiben Sie konkret, wofür und wann der Agent zuständig ist.
• Matcher gegen den Befehlstext statt gegen tool_name: Ein Matcher wie “npm test” greift bei Bash-Aufrufen nicht, weil der Matcher gegen den Tool-Namen prüft, nicht gegen den Inhalt des Befehls.
• Fehlende Ausführungsrechte am Hook-Skript: Ohne chmod +x bricht der Hook mit “Permission denied” ab, bevor er überhaupt startet.
• Rekursive Hooks ohne Schutz: Ein Hook, der selbst wieder ein Tool auslöst, das denselben Hook triggert, kann eine Endlosschleife erzeugen. Eine einfache Markierung über eine Umgebungsvariable verhindert das.
• Zu kurze Timeouts bei langsamen Prüfungen: Ein Linter, der über eine Minute braucht, aber mit Standard-Timeout läuft, wird abgebrochen, ohne dass das sofort ersichtlich ist.
• Persönliche und projektweite Agents vermischt: Wird ein individueller Subagent versehentlich unter .claude/agents/ statt ~/.claude/agents/ abgelegt, landet er im Repository und bei jedem Teammitglied.

Troubleshooting: Die häufigsten Probleme lösen

Wenn ein Subagent oder Hook sich anders verhält als erwartet, lohnt sich zuerst ein Blick auf die Reihenfolge, in der Claude Code Entscheidungen trifft, statt sofort die ganze Konfiguration neu zu schreiben. Die folgende Tabelle listet acht Probleme, die in der Praxis am häufigsten gemeldet werden, zusammen mit der wahrscheinlichsten Ursache und einer konkreten Lösung.

Problem	Wahrscheinliche Ursache	Lösung
Subagent wird nie automatisch delegiert	description zu allgemein formuliert	Beschreibung präzisieren: Aufgabe, Auslöser und erwartetes Ergebnis nennen
Hook feuert gar nicht	Falsches Event oder falscher Matcher gewählt	Event-Name und Matcher-Wert gegen die Referenztabelle in Schritt 5 prüfen
“Permission denied” beim Hook-Start	Skript ist nicht ausführbar	chmod +x auf die Hook-Datei anwenden oder Interpreter explizit angeben
Hook bricht mit Timeout ab	Zeitbudget des Hook-Typs zu knapp	Feld timeout im Hook-Eintrag erhöhen
JSON-Parsing-Fehler im Hook-Skript	stdin wird nicht korrekt gelesen oder ist leer	Mit json.load(sys.stdin) und Fehlerausgabe auf stderr prüfen, was tatsächlich ankommt
Subagent nutzt falsches Modell	Vorrang von Aufruf-Parameter vor Frontmatter missverstanden	Reihenfolge beachten: Aufruf-Parameter, dann model im Frontmatter, dann Umgebungsvariable, dann Hauptmodell
Endlosschleife durch rekursiven Hook	Hook löst ein Tool aus, das denselben Hook erneut triggert	Tiefenzähler über eine Umgebungsvariable einbauen und bei Wiederholung früh beenden
Settings.json wird ignoriert	Datei liegt in der falschen Scope-Ebene	Projektweite Regeln in .claude/settings.json, persönliche in ~/.claude/settings.json ablegen

Erweiterte Tipps für den Produktionseinsatz

Sobald Subagents und Hooks im Projekt laufen, verschiebt sich die eigentliche Arbeit von der Grundkonfiguration zur Feinabstimmung. Die folgenden Punkte haben sich in größeren Repositories mit mehreren aktiven Subagents als besonders hilfreich erwiesen.

• Setzen Sie für kostensensible Subagents wie einfache Formatierungsprüfungen gezielt Claude Haiku 5.5 ein, und reservieren Sie Opus 5.5 für Subagents mit komplexer Analyseaufgabe.
• Nutzen Sie die Umgebungsvariable CLAUDE_CODE_SUBAGENT_MODEL, um in CI-Umgebungen für alle Subagents zentral ein günstigeres Modell zu erzwingen, ohne jede einzelne Markdown-Datei anzufassen.
• Kombinieren Sie mehrere kleine, eng fokussierte Subagents statt eines einzigen Allround-Agents. Das verbessert die Trefferquote bei automatischer Delegation deutlich.
• Verwenden Sie Agent-Hooks gezielt für Prüfungen, die mehrere Dateien einbeziehen müssen, und Prompt-Hooks für einfache Ja-Nein-Bewertungen. Das spart Zeit und Tokens.
• Loggen Sie jeden Hook-Aufruf zentral, etwa in eine Datei unter .claude/hooks/logs/. Ohne Protokoll lässt sich ein nicht feuernder Hook kaum von einem fehlerhaft konfigurierten Matcher unterscheiden.
• Prüfen Sie nach jedem Claude-Code-Update die Release Notes, da sich das Hook-Schema zwischen Versionen wie 2.1.x verändern kann.
• Versionieren Sie .claude/agents/ und .claude/settings.json wie normalen Quellcode, inklusive Pull-Request-Review. Eine Änderung an einem Hook, der Produktions-Deployments blockieren kann, verdient dieselbe Sorgfalt wie eine Änderung an der Deployment-Pipeline selbst.
• Dokumentieren Sie in jedem Subagent kurz, welches Modell er nutzt und warum. Das erleichtert es dem nächsten Teammitglied, die Kosten einer Änderung einzuschätzen, bevor es weitere Subagents hinzufügt.

Die zwölf Schritte in diesem Artikel ergeben zusammen ein Muster, das sich auf nahezu jedes Repository übertragen lässt: einen oder mehrere Subagents für inhaltliche Prüfungen, einen PreToolUse-Hook gegen destruktive Befehle, und optional einen Stop- oder SessionEnd-Hook für Protokollierung. Der größte Hebel liegt dabei selten in der Technik selbst, sondern in präzisen description-Feldern und eng begrenzten Werkzeuglisten, denn beide entscheiden direkt darüber, ob die Automatisierung im Alltag tatsächlich greift oder nur auf dem Papier existiert.

FAQ: Häufige Fragen zu Claude Code Subagents und Hooks

Zum Abschluss die Fragen, die nach dem ersten eigenen Subagent und dem ersten Hook am häufigsten aufkommen, von Grundlagen bis zu Betriebsfragen im Team.

Was ist der Unterschied zwischen Hooks und Subagents in Claude Code?

Ein Subagent delegiert eine Aufgabe an einen eigenständigen Prozess mit eigenem Kontext und eigenem Systemprompt. Ein Hook greift dagegen in den Lebenszyklus des Agenten ein und kann Aktionen blockieren, protokollieren oder verändern, bevor oder nachdem sie passieren.

Brauche ich ein eigenes Abonnement für Subagents und Hooks?

Nein, beide Funktionen sind Teil der normalen Claude-Code-CLI. Sie benötigen lediglich einen funktionierenden Zugang zu einem Claude-Modell, etwa über ein Pro- oder Max-Abo oder einen API-Key, und eine aktuelle Installation der CLI.

Welche Programmiersprache muss ich für Hook-Skripte verwenden?

Keine bestimmte. Ein command-Hook ruft einfach ein ausführbares Programm auf, das JSON über stdin liest. Python und Bash sind in der Praxis am verbreitetsten, weil beide auf nahezu jedem Entwicklerrechner vorhanden sind, es funktioniert aber genauso mit Node.js, Go oder jeder anderen Sprache, die stdin lesen und einen Exit-Code zurückgeben kann.

Können Subagents andere Subagents aufrufen?

Ja, sofern das im Feld tools des übergeordneten Subagents erlaubt ist. Mit einer Syntax wie Agent(security-reviewer), Agent(test-runner) lässt sich genau festlegen, welche Subagents ein Subagent selbst wiederum delegieren darf.

Wie verhindere ich, dass ein Hook eine Endlosschleife auslöst?

Ein Hook kann theoretisch ein weiteres Ereignis auslösen, das denselben Hook erneut startet, etwa wenn ein PostToolUse-Hook selbst eine Datei verändert. Ein einfacher Schutz ist eine Tiefenmarkierung über eine Umgebungsvariable, die der Hook am Anfang prüft und bei der zweiten Ausführung sofort mit Exit-Code 0 beendet.

Funktionieren Hooks auch mit MCP-Servern?

Ja. Für MCP-Werkzeuge eignet sich ein Matcher-Muster wie mcp__.*, und der Hook-Typ mcp_tool kann direkt ein auf einem MCP-Server registriertes Werkzeug als Teil der Entscheidung aufrufen.

Wie finde ich heraus, welche Claude-Code-Version ich installiert habe?

Der Befehl claude --version zeigt die installierte Version direkt im Terminal. Für den vollständigen Änderungsverlauf lohnt sich ein Blick in die GitHub-Releases-Seite des Projekts, dort ist jede Version mit Datum und Änderungen dokumentiert.

Kann ein Hook versehentlich die ganze Produktivität lahmlegen?

Ja, das passiert vor allem, wenn ein PreToolUse-Hook an einem häufig genutzten Tool wie Bash hängt und bei jedem Aufruf ein langsames externes Skript startet. Setzen Sie deshalb enge Timeouts, testen Sie neue Hooks zuerst an einem einzelnen, wenig genutzten Projekt und beobachten Sie die tatsächliche Laufzeit, bevor Sie den Hook auf das ganze Team ausrollen.