Die Steuerungsmechanismen von Claude Code: CLAUDE.md, Rules, Skills, Subagents und Hooks

Die Steuerungsmechanismen von Claude Code: CLAUDE.md, Rules, Skills, Subagents und Hooks

Zwischen dem Sprachmodell und dem Dateisystem liegt bei Claude Code ein Harness, eine Laufzeitumgebung, die festlegt, welche Anweisungen wann ins Kontextfenster gelangen, welche Werkzeuge das Modell aufrufen kann und welche Aufrufe tatsächlich ausgeführt werden. Gesteuert wird dieser Harness über eine Reihe von Mechanismen mit eigenen Dateiformaten und Ladezeitpunkten: CLAUDE.md, Rules, das Auto-Memory, Skills, Subagents, Hooks und die Settings mit ihren Permissions. Plugins bündeln einen Teil davon, nämlich Skills, Subagents und Hooks, zusammen mit MCP-Servern zu installierbaren Paketen.

Jeder dieser Mechanismen kann auf mehreren Ebenen definiert sein, von der Organisation über den einzelnen Nutzer bis zum Projekt und seinen Unterverzeichnissen. Die interessante Frage ist deshalb weniger, was es gibt, als wie sich die Ebenen überlagern: Bei welchen Mechanismen addieren sich die Ebenen, bei welchen verdrängt eine höhere Ebene die niedrigere, und in welcher Reihenfolge. Die Antwort fällt je nach Mechanismus verschieden aus. Dieser Beitrag ordnet das ein, Stand September 2026, auf Basis der offiziellen Dokumentation unter code.claude.com.

Zur Begrifflichkeit: „Claude Code“ bezeichnet im Folgenden das Programm, also den Harness. „Das Modell“ bezeichnet das Sprachmodell, das darin arbeitet. Die Ebenen heißen einheitlich Managed (von der Organisation verteilt), User (persönlich, für alle Projekte), Projekt und Lokal. Die Dokumentation nennt die Managed-Ebene bei Skills „Enterprise“, gemeint ist dasselbe.

Anweisung und Erzwingung

Die Mechanismen wirken auf zwei grundsätzlich verschiedene Arten.

Die erste Art ist die Anweisung: Text, den Claude Code ins Kontextfenster lädt und den das Modell befolgen soll. Dazu gehören CLAUDE.md, Rules, das Auto-Memory, Skills und die Beschreibungen von Subagents. Dass sie befolgt wird, garantiert die Dokumentation ausdrücklich nicht. CLAUDE.md wird als User-Message nach dem System-Prompt eingespielt, das Modell liest den Inhalt und versucht ihn zu befolgen. Sind Anweisungen vage oder widersprechen sich, entscheidet das Modell, welcher es folgt.

Die zweite Art ist die Erzwingung: Hooks, Permissions und Managed Settings greifen im Harness selbst, bevor oder nachdem das Modell handelt, und unabhängig davon, wie es entscheidet. Ein PreToolUse-Hook, der mit Exit-Code 2 endet, verhindert den Werkzeugaufruf, auch wenn CLAUDE.md den Aufruf ausdrücklich erlaubt. Die Dokumentation rät ausdrücklich, Schutzregeln so umzusetzen: Eine Zeile wie „nie .env editieren“ in CLAUDE.md sei eine Bitte, erst der blockierende Hook setze sie durch.

Daraus folgt eine Faustregel für die Wahl des Mechanismus. Was ausnahmslos gelten muss, gehört in einen Hook oder eine Permission. Was Urteilsvermögen verlangt, gehört in eine Anweisung.

CLAUDE.md

CLAUDE.md ist eine Markdown-Datei mit dauerhaften Anweisungen. Es gibt sie auf vier Ebenen:

Übergeordnete Verzeichnisse. Beim Start lädt Claude Code CLAUDE.md und CLAUDE.local.md aus dem Arbeitsverzeichnis und aus jedem Verzeichnis darüber. Wer in foo/bar/ startet, bekommt foo/bar/CLAUDE.md und foo/CLAUDE.md.

Unterverzeichnisse. CLAUDE.md-Dateien unterhalb des Arbeitsverzeichnisses lädt Claude Code nicht beim Start. Sie kommen hinzu, sobald das Modell eine Datei in ihrem Unterverzeichnis liest. In einem Monorepo erscheint die CLAUDE.md von apps/web/ also erst, wenn die Arbeit dort ankommt.

Konkatenation. Keine Datei verdrängt eine andere. Claude Code hängt alle gefundenen Dateien aneinander, geordnet vom Wurzelverzeichnis zum Arbeitsverzeichnis. Innerhalb eines Verzeichnisses folgt CLAUDE.local.md auf CLAUDE.md. Die spezifischste Anweisung steht damit am Ende. Einen formalen Vorrang gibt es trotzdem nicht: Widersprechen sich zwei Dateien, löst das Modell den Konflikt nach eigenem Ermessen auf.

Über die Einstellung claudeMdExcludes lassen sich einzelne Dateien per Pfad oder Glob-Muster vom Laden ausnehmen, etwa die CLAUDE.md anderer Teams in einem Monorepo. Ausgenommen davon ist nur die Managed-Datei, sie wird immer geladen.

Imports. Mit @pfad/zur/datei bindet eine CLAUDE.md weitere Dateien ein. Relative Pfade beziehen sich auf die importierende Datei, die Rekursionstiefe ist auf vier Stufen begrenzt. Importierte Dateien landen beim Start vollständig im Kontextfenster. Ein Import gliedert die Dateien, spart aber keine Token.

Eine Projekt-CLAUDE.md hat kein Frontmatter. Sie kann kurz sein und auf weitere Dateien verweisen:

# Shop-Frontend

- Paketmanager ist pnpm, Tests laufen mit `pnpm test`.
- Vor jedem Commit `pnpm lint` ausführen.
- Architektur und Modulgrenzen: @docs/architektur.md
- Persönliche Einstellungen: @~/.claude/shop-frontend.md

Größe und Compaction. Die Dokumentation empfiehlt unter 200 Zeilen pro Datei, weil das Modell längere Dateien schlechter befolgt und sie in jeder Anfrage Token kosten. Die harte Grenze liegt bei 4 MiB, Claude Code überspringt größere Dateien. Wird das Kontextfenster voll, fasst Claude Code den bisherigen Verlauf zusammen, die sogenannte Compaction. Danach liest Claude Code die CLAUDE.md im Projektwurzelverzeichnis neu von der Platte. Verschachtelte CLAUDE.md-Dateien aus Unterverzeichnissen fallen dabei heraus und werden erst wieder geladen, wenn das Modell erneut eine Datei in ihrem Verzeichnis liest.

Seit Version 2.1.277 liest Claude Code ersatzweise AGENTS.md, die herstellerübergreifende Konventionsdatei, die auch andere Coding-Agenten auswerten. Standardmäßig geschieht das nur, wenn im Arbeitsverzeichnis und darüber weder CLAUDE.md noch .claude/CLAUDE.md noch CLAUDE.local.md existiert. Die User- und die Managed-Datei zählen dabei nicht mit.

Rules

Rules sind Markdown-Dateien unter .claude/rules/ im Projekt oder unter ~/.claude/rules/ auf User-Ebene. Unterverzeichnisse werden rekursiv durchsucht. Inhaltlich sind Rules ausgelagerte Teile von CLAUDE.md, der Unterschied liegt im Ladezeitpunkt.

Das Frontmatter kennt genau ein Feld:

---
paths:
  - "src/api/**/*.ts"
---

# API-Regeln
- Jeder Endpunkt validiert seine Eingaben.

paths nimmt Glob-Muster als YAML-Liste oder kommagetrennten String. Claude Code lädt eine Rule ohne paths beim Start, wie eine CLAUDE.md. Eine Rule mit paths lädt es erst, wenn das Modell eine passende Datei liest. Andere Frontmatter-Felder ignoriert Claude Code ohne Fehlermeldung.

Lässt sich der YAML-Block nicht parsen, verwirft Claude Code das Frontmatter und lädt die Rule ohne Pfadbindung, also in jeder Session.

Claude Code liest User-Rules zuerst ein, Projekt-Rules folgen und stehen damit weiter unten im Kontextfenster. Verdrängt wird auch hier nichts. Widersprechen sich zwei Rules, kann das Modell laut Dokumentation jeder der beiden folgen.

Auto-Memory

Neben den Dateien, die Menschen schreiben, legt das Modell selbst Notizen an, unter ~/.claude/projects/<projekt>/memory/. Das Segment <projekt> leitet sich aus dem Git-Repository ab, alle Worktrees eines Repositorys teilen sich also ein Verzeichnis.

Die Datei MEMORY.md dient als Index mit einer Zeile pro Eintrag. Claude Code lädt davon die ersten 200 Zeilen oder 25 KB, je nachdem, was zuerst erreicht ist. Die eigentlichen Einträge liegen in eigenen Themendateien, die das Modell erst bei Bedarf mit den normalen Dateiwerkzeugen liest. Das Auto-Memory liegt nur auf der jeweiligen Maschine und ist nicht versioniert. Für Wissen, das ein Team teilen soll, ist es der falsche Ort.

Skills

Ein Skill ist ein Verzeichnis mit einer Datei SKILL.md und optional weiteren Dateien wie Vorlagen, Skripten oder Referenzmaterial. Skills decken zwei Anwendungsfälle ab: Nachschlagewissen, etwa einen API-Styleguide, und Abläufe, die der Nutzer mit /name oder das Modell selbst startet.

Progressive Disclosure. Beim Start stehen von jedem Skill nur Name und Beschreibung im Kontextfenster, die Beschreibung samt when_to_use auf höchstens 1.536 Zeichen gekürzt. Ausgenommen sind Skills, die nur der Nutzer aufrufen darf, und Skills aus Unterverzeichnissen, die erst später hinzukommen. Anhand dieser Beschreibung entscheidet das Modell, ob ein Skill zur Aufgabe passt. Erst beim Aufruf lädt Claude Code den vollständigen Inhalt, als einzelne Nachricht, die im Verlauf bleibt. Nach einer Compaction hängt Claude Code von jedem Skill den letzten Aufruf wieder an, beginnend beim jüngsten, jeweils die ersten 5.000 Token, zusammen höchstens 25.000 Token. Wer in einer Session viele Skills aufruft, verliert die älteren dabei unter Umständen ganz.

Speicherorte.

Anders als bei CLAUDE.md verdrängt bei Skills gleichen Namens die höhere Ebene die niedrigere. Die Rangfolge lautet Managed vor User vor Projekt. Liegt ein Skill deploy sowohl in ~/.claude/skills/ als auch im Projekt, gewinnt der des Users. Plugin-Skills kollidieren nicht, weil ihr Aufruf den Plugin-Namen als Präfix trägt, etwa /mein-plugin:deploy. Skills in Unterverzeichnissen verhalten sich wie verschachtelte CLAUDE.md-Dateien: Claude Code lädt sie, sobald das Modell eine Datei in ihrem Unterverzeichnis liest, und macht sie zusätzlich unter dem qualifizierten Namen /apps/web:deploy verfügbar.

Frontmatter. Die wichtigsten Felder:

Die Freigaben aus allowed-tools enden mit der nächsten Nutzernachricht, während der Skill-Text im Verlauf bleibt. Für Abläufe mit Seiteneffekten wie ein Deployment empfiehlt die Dokumentation disable-model-invocation, damit das Modell sie nicht von sich aus startet, sobald die Beschreibung zur Aufgabe passt.

Beispiele. Ein Ablauf-Skill, den nur der Nutzer startet, unter .claude/skills/release/SKILL.md:

---
name: release
description: Bereitet ein Release vor. Erzeugt den Changelog aus den Commits seit dem letzten Tag, hebt die Versionsnummer an und setzt den Tag.
disable-model-invocation: true
argument-hint: [version]
allowed-tools: Bash(git log *) Bash(git tag *) Read Edit
---

Bereite das Release $ARGUMENTS vor:

1. Commits seit dem letzten Tag mit `git log` lesen.
2. `CHANGELOG.md` um einen Abschnitt für $ARGUMENTS ergänzen.
3. Version in `package.json` anheben und den Tag setzen.

Ein Wissens-Skill, den nur das Modell lädt, und zwar nur bei Arbeit an der API:

---
name: api-konventionen
description: Konventionen für REST-Endpunkte im Shop-Backend, Fehlerformat, Paginierung und Versionierung. Nutzen beim Anlegen oder Ändern von Endpunkten.
user-invocable: false
paths:
  - "src/api/**/*.ts"
---

# API-Konventionen
- Fehler folgen RFC 7807 (`application/problem+json`).
- Listen-Endpunkte paginieren per Cursor, nie per Offset.

Ein Skill, der in einem isolierten Subagent recherchiert:

---
name: tiefenrecherche
description: Untersucht eine Frage im Code gründlich und liefert eine Zusammenfassung mit Dateiverweisen.
context: fork
agent: Explore
---

Untersuche $ARGUMENTS: passende Dateien mit Glob und Grep finden, lesen, Befunde mit Dateiverweisen zusammenfassen.

Das Altformat .claude/commands/. Einzeldateien in diesem Verzeichnis funktionieren weiter als Slash-Befehle. Sie unterstützen dasselbe Frontmatter bis auf name und paths, aber keine Begleitdateien. Für Neues sind Skills vorgesehen.

Subagents

Ein Subagent ist eine eigene Modell-Session mit eigenem Kontextfenster. Das Hauptgespräch delegiert eine Aufgabe, der Subagent arbeitet sie ab und liefert eine Zusammenfassung zurück. Der Zweck ist Isolation: Ein Subagent kann Dutzende Dateien lesen, ohne dass deren Inhalt das Hauptgespräch füllt. Subagents können ihrerseits Subagents starten, standardmäßig bis zu drei Verschachtelungsstufen unter dem Hauptgespräch.

Definiert wird ein Subagent als Markdown-Datei. Der Text wird zu seinem System-Prompt, das Frontmatter konfiguriert ihn:

Ein Review-Agent unter .claude/agents/code-reviewer.md, der nur lesen darf:

---
name: code-reviewer
description: Prüft geänderten Code auf Fehler, Sicherheitsprobleme und Verstöße gegen die API-Konventionen. Nutzen nach jeder größeren Änderung.
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: plan
skills:
  - api-konventionen
memory: project
maxTurns: 20
color: blue
---

Du bist Reviewer für das Shop-Backend. Lies den Diff mit `git diff`,
prüfe jede Änderung und liefere eine Liste der Befunde, schwerste zuerst,
jeweils mit Datei und Zeile. Ändere selbst keine Dateien.

Womit er startet. Ein Subagent bekommt seinen eigenen System-Prompt, die Delegationsnachricht, die CLAUDE.md-Dateien einschließlich AGENTS.md, den Git-Status und die in skills genannten Skills. Er bekommt nicht den bisherigen Gesprächsverlauf, nicht das Auto-Memory des Hauptgesprächs, nicht den Output Style (die Einstellung für Ton und Antwortformat der Session) und nicht die Skills, die im Hauptgespräch bereits aufgerufen wurden. Die eingebauten Subagents Explore und Plan, die Claude Code für Recherche und Planung mitbringt, verzichten zusätzlich auf CLAUDE.md und Git-Status.

Speicherorte und Rangfolge. Bei gleichem Namen gilt: Managed vor dem Kommandozeilen-Flag --agents vor .claude/agents/ im Projekt vor ~/.claude/agents/ auf User-Ebene vor Plugins. Projekt und User stehen damit in umgekehrter Reihenfolge wie bei den Skills, bei denen die User-Ebene gewinnt. Subagents aus Plugins ignorieren aus Sicherheitsgründen hooks, mcpServers und permissionMode.

Hooks

Hooks sind der zentrale erzwingende Mechanismus. Ein Hook ist ein Handler, den Claude Code an einem Lifecycle-Event ausführt: ein Shell-Befehl, ein HTTP-Request, ein MCP-Tool-Aufruf, ein einzelner Prompt an ein Modell oder, experimentell, ein Subagent. Ob ein Hook läuft, entscheidet nicht das Modell. Beim Prompt- und beim Subagent-Typ fällt allerdings ein Modell das Urteil darüber, ob blockiert wird.

Die Dokumentation listet über dreißig Events auf. Die wichtigsten:

Exit-Codes. Exit 0 bedeutet Erfolg. Bei SessionStart und UserPromptSubmit übernimmt Claude Code die Textausgabe ins Kontextfenster. Exit 2 blockiert bei den dafür vorgesehenen Events, und zwar unabhängig von allem, was der Hook sonst ausgibt. Dazu gehören unter anderem PreToolUse (der Aufruf unterbleibt), UserPromptSubmit (der Prompt wird verworfen) und Stop (das Modell muss weiterarbeiten). Bei PreToolUse und Stop bekommt das Modell die Begründung aus stderr zu sehen und kann darauf reagieren.

Konfiguration. Hooks stehen in den Settings-Dateien aller Ebenen, in einem Plugin unter hooks/hooks.json oder im Frontmatter eines Skills oder Subagents. Claude Code führt sie über alle Quellen hinweg zusammen, kein Hook verdrängt einen anderen. Die Ausnahme sind die bereits genannten Plugin-Subagents, deren Hooks nicht registriert werden.

Ein Beispiel in .claude/settings.json: Vor jeder Dateiänderung prüft ein Skript, ob eine geschützte Datei betroffen ist, nach jeder Änderung formatiert Prettier die Datei.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
        ]
      }
    ]
  }
}

Das Skript bekommt den geplanten Aufruf als JSON auf stdin und blockiert mit Exit 2:

#!/bin/bash
# .claude/hooks/protect-files.sh
FILE_PATH=$(jq -r '.tool_input.file_path // empty')

for pattern in ".env" "package-lock.json" ".git/"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH ist geschützt ($pattern)" >&2
    exit 2
  fi
done
exit 0

Im Frontmatter eines Skills oder Subagents steht dieselbe Struktur als YAML:

hooks:
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "pnpm lint"

Settings, Permissions und Plugins

Die Datei settings.json trägt die verbindliche Konfiguration: Permissions, Hooks, Umgebungsvariablen, Modellwahl. Für Einzelwerte gilt eine strenge Rangfolge: Managed vor Kommandozeile vor .claude/settings.local.json vor .claude/settings.json vor ~/.claude/settings.json. Listen wie permissions.allow und permissions.deny werden dagegen über alle Ebenen zusammengeführt, jede Ebene kann Einträge beisteuern. Eine Deny-Regel wie Bash(git push *) wirkt im Harness, bevor das Werkzeug läuft, und gehört damit zur Erzwingung.

{
  "permissions": {
    "allow": ["Bash(pnpm test *)", "Bash(pnpm lint)"],
    "deny": ["Bash(git push *)", "Read(./.env)"]
  },
  "env": { "NODE_ENV": "development" }
}

Ein Plugin ist die Verpackungseinheit. Es bündelt Skills, Subagents, Hooks und MCP-Server in einem installierbaren Paket mit Manifest unter .claude-plugin/plugin.json. Verteilt werden Plugins über Marketplaces, Kataloge von Plugins, die etwa als Git-Repository bereitstehen. Ein Plugin-Verzeichnis sieht so aus:

shop-tools/
├── .claude-plugin/
│   └── plugin.json
├── skills/
│   └── release/SKILL.md
├── agents/
│   └── code-reviewer.md
└── hooks/
    └── hooks.json

{
  "name": "shop-tools",
  "description": "Release-Ablauf, Code-Review und Schutz-Hooks für die Shop-Projekte",
  "version": "1.0.0"
}

Nach der Installation heißt der Release-Skill /shop-tools:release.

Das Zusammenspiel im Überblick

Grenzen

Die Zweiteilung in Anweisung und Erzwingung trennt weniger sauber, als die Tabelle nahelegt. Skills und Subagents sind im Kern Anweisungen, tragen aber mit allowed-tools, tools und permissionMode Einstellungen, die Claude Code im Harness durchsetzt. Umgekehrt spielen Hooks bei SessionStart und UserPromptSubmit Text ins Kontextfenster ein, der danach wie jede andere Anweisung behandelt wird. Die Unterscheidung beschreibt also, wie ein einzelnes Feld wirkt, und nicht den Mechanismus als Ganzes.

Auf der Anweisungsseite hängt die Wirkung am Text. Ob das Modell einen Skill auswählt, hängt an der Formulierung seiner Beschreibung. Ob es eine Regel aus CLAUDE.md befolgt, hängt an ihrer Eindeutigkeit und daran, ob irgendwo eine widersprechende steht. Ladereihenfolgen legen fest, was das Modell sieht, nicht was es tut.

Jede Anweisung, die beim Start geladen wird, kostet außerdem in jeder Anfrage Token. Die Aufteilung in dauerhaft geladene, pfadgebundene und bei Bedarf geladene Anweisungen ist die eigentliche Designentscheidung beim Aufsetzen eines Projekts, die Dokumentation gibt dafür aber nur Faustregeln.

Schließlich veraltet eine solche Übersicht schnell. Das Lesen von AGENTS.md etwa setzt Version 2.1.277 voraus, und viele andere Details tragen in der Dokumentation ähnliche Versionsvermerke. Wer eine Konfiguration auf ein bestimmtes Verhalten stützt, sollte es an der aktuellen Dokumentation prüfen.

Zwischen den Coding-Agenten verschiedener Hersteller gleicht sich ein Teil der Mechanik bereits an. MCP als Schnittstelle zu Werkzeugen und AGENTS.md als Anweisungsdatei liegen inzwischen bei der Agentic AI Foundation unter dem Dach der Linux Foundation. Das Skill-Format hat Anthropic im Dezember 2025 als offenen Standard veröffentlicht, Agenten wie OpenAI Codex, Gemini CLI, Cursor und GitHub Copilot lesen es. Portabel ist allerdings nur der Kern: name, description, allowed-tools und einige Metadaten. Felder wie disable-model-invocation, context, paths und hooks wertet nur Claude Code aus, ebenso gelten die Ladezeitpunkte, die Rangfolgen der Ebenen und das Hook-System in der hier beschriebenen Form nur dort.