Agent-Architektur: KI-gestützte Entwicklungsumgebungen aufbauen

TL;DR: Claude Code ist keine Chatbox mit Dateizugriff. Es ist eine programmierbare Laufzeitumgebung mit 22 Lifecycle-Events, von denen jedes einzelne über Shell-Skripte hookbar ist, die das Modell nicht überspringen kann. Schichten Sie hooks zu Dispatchern, Dispatcher zu skills, skills zu Agenten, Agenten zu Workflows – und Sie erhalten ein autonomes Entwicklungs-harness, das Einschränkungen durchsetzt, Arbeit delegiert, Memory sitzungsübergreifend persistiert und Multi-Agenten-Deliberation orchestriert. Dieser Leitfaden behandelt jede Schicht dieses Stacks: von einem einzelnen hook bis zu einem 10-Agenten-Konsenssystem. Keine Frameworks erforderlich. Alles in Bash und JSON.

Andrej Karpathy prägte einen Begriff für das, was um einen LLM-Agenten herum wächst: Krallen. Die hooks, Skripte und Orchestrierung, die dem Agenten ermöglichen, die Welt außerhalb seines Kontextfensters zu greifen.¹ Die meisten Entwickler behandeln KI-Coding-Agenten als interaktive Assistenten. Sie tippen einen Prompt ein, beobachten, wie er eine Datei bearbeitet, und machen weiter. Dieses Denkmodell begrenzt die Produktivität auf das, was Sie persönlich beaufsichtigen können.

Das Infrastruktur-Denkmodell ist ein anderes: Ein KI-Coding-Agent ist eine programmierbare Laufzeitumgebung mit einem LLM-Kernel. Jede Aktion, die das Modell ausführt, durchläuft hooks, die Sie kontrollieren. Sie definieren Richtlinien, keine Prompts. Das Modell arbeitet innerhalb Ihrer Infrastruktur genauso, wie ein Webserver innerhalb von nginx-Regeln arbeitet. Sie sitzen nicht an nginx und tippen Anfragen ein. Sie konfigurieren es, deployen es und überwachen es.

Diese Unterscheidung ist entscheidend, weil Infrastruktur kumuliert. Ein hook, der Zugangsdaten in Bash-Befehlen blockiert, schützt jede Sitzung, jeden Agenten, jeden autonomen Durchlauf. Ein skill, der Ihre Bewertungsrubrik kodiert, wird konsistent angewendet – unabhängig davon, ob Sie ihn aufrufen oder ein Agent. Ein Agent, der Code auf Sicherheitslücken überprüft, führt dieselben Prüfungen durch, ob Sie zusehen oder nicht.²

Zentrale Erkenntnisse

• Hooks garantieren Ausführung; Prompts nicht. Verwenden Sie hooks für Linting, Formatierung, Sicherheitsprüfungen und alles, was bei jedem Durchlauf unabhängig vom Modellverhalten ausgeführt werden muss. Exit-Code 2 blockiert Aktionen. Exit-Code 1 gibt lediglich eine Warnung aus.³
• Skills kodieren Domänenwissen, das sich automatisch aktiviert. Das description-Feld bestimmt alles. Claude nutzt LLM-Reasoning (kein Keyword-Matching), um zu entscheiden, wann ein skill angewendet wird.⁴
• Subagents verhindern Kontextaufblähung. Isolierte Kontextfenster für Exploration und Analyse halten die Hauptsitzung schlank. Bis zu 10 können parallel laufen.⁵
• Memory lebt im Dateisystem. Dateien persistieren über Kontextfenster hinweg. CLAUDE.md, MEMORY.md, Rules-Verzeichnisse und Handoff-Dokumente bilden ein strukturiertes externes Gedächtnissystem.⁶
• Multi-Agenten-Deliberation deckt blinde Flecken auf. Einzelne Agenten können ihre eigenen Annahmen nicht hinterfragen. Zwei unabhängige Agenten mit unterschiedlichen Bewertungsprioritäten erkennen strukturelle Fehler, die quality gates allein nicht adressieren können.⁷
• Das harness-Pattern ist das System. CLAUDE.md, hooks, skills, Agenten und Memory sind keine voneinander unabhängigen Funktionen. Sie fügen sich zu einer deterministischen Schicht zwischen Ihnen und dem Modell zusammen, die mit zunehmender Automatisierung skaliert.

So nutzen Sie diesen Leitfaden

Jeder Abschnitt baut auf dem vorherigen auf. Das Entscheidungs-Framework am Ende bietet eine Nachschlagetabelle, um den richtigen Mechanismus für jeden Problemtyp auszuwählen.

Warum Agentenarchitektur wichtig ist

Simon Willison fasst den aktuellen Moment mit einer einzigen Beobachtung zusammen: Code zu schreiben ist jetzt billig.⁸ Richtig. Doch die Konsequenz daraus ist, dass die Verifikation nun der teure Teil ist. Billiger Code ohne Verifikationsinfrastruktur produziert Fehler im großen Maßstab. Die Investition, die sich auszahlt, ist kein besserer Prompt – sondern das System rund um das Modell, das auffängt, was das Modell übersieht.

Drei Kräfte machen Agentenarchitektur notwendig:

Kontextfenster sind endlich und verlustbehaftet. Jede gelesene Datei, jede Tool-Ausgabe und jeder Gesprächswechsel verbraucht Tokens. Microsoft Research und Salesforce testeten 15 LLMs in über 200.000 simulierten Konversationen und stellten einen durchschnittlichen Leistungsabfall von 39 % zwischen Einzelrunden- und Mehrrunden-Interaktion fest.⁹ Die Verschlechterung beginnt bereits nach zwei Runden und folgt einer vorhersagbaren Kurve: Präzise Mehrdatei-Bearbeitungen in den ersten 30 Minuten degenerieren bis Minute 90 zu Einzeldatei-Tunnelblick. Größere Kontextfenster lösen dieses Problem nicht. Die „Concat”-Bedingung derselben Studie (vollständige Konversation als einzelner Prompt) erreichte 95,1 % der Einzelrunden-Leistung bei identischem Inhalt. Die Verschlechterung entsteht durch Rundengrenzen, nicht durch Token-Limits.

Modellverhalten ist probabilistisch, nicht deterministisch. Claude die Anweisung zu geben „führe Prettier immer nach dem Bearbeiten von Dateien aus” funktioniert in etwa 80 % der Fälle.³ Das Modell könnte es vergessen, Geschwindigkeit priorisieren oder entscheiden, die Änderung sei „zu klein”. Für Compliance, Sicherheit und Teamstandards sind 80 % nicht akzeptabel. Hooks garantieren die Ausführung: Jeder Edit- oder Write-Aufruf löst Ihren Formatter aus – jedes Mal, ohne Ausnahmen. Deterministisch schlägt probabilistisch.

Einzelne Perspektiven übersehen mehrdimensionale Probleme. Ein einzelner Agent, der einen API-Endpunkt überprüfte, kontrollierte Authentifizierung, validierte Eingabebereinigung und verifizierte CORS-Header. Sauberes Ergebnis. Ein zweiter Agent, separat als Penetrationstester instruiert, fand heraus, dass der Endpunkt unbegrenzte Query-Parameter akzeptierte, die durch Datenbank-Query-Amplifikation eine Denial-of-Service-Attacke auslösen konnten.⁷ Der erste Agent prüfte dies nie, weil nichts in seinem Bewertungsrahmen Query-Komplexität als Sicherheitsoberfläche behandelte. Diese Lücke ist strukturell bedingt. Kein noch so gutes Prompt-Engineering kann sie beheben.

Agentenarchitektur adressiert alle drei Probleme: Hooks erzwingen deterministische Einschränkungen, subagents verwalten Kontextisolation und Multi-Agenten-Orchestrierung bietet unabhängige Perspektiven. Zusammen bilden sie den harness.

Das Harness-Pattern

Der harness ist kein Framework. Er ist ein Pattern: ein komponierbarer Satz aus Dateien, Skripten und Konventionen, der einen KI-Coding-Agenten in deterministische Infrastruktur einbettet. Die Komponenten:

┌──────────────────────────────────────────────────────────────┐
│                      THE HARNESS PATTERN                      │
├──────────────────────────────────────────────────────────────┤
│  ORCHESTRATION                                                │
│  ┌────────────┐  ┌────────────┐  ┌────────────┐             │
│  │   Agent     │  │   Agent    │  │  Consensus │             │
│  │   Teams     │  │  Spawning  │  │  Validation│             │
│  └────────────┘  └────────────┘  └────────────┘             │
│  Multi-agent deliberation, parallel research, voting          │
├──────────────────────────────────────────────────────────────┤
│  EXTENSION LAYER                                              │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐    │
│  │  Skills   │  │  Hooks   │  │  Memory  │  │  Agents  │    │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘    │
│  Domain expertise, deterministic gates, persistent state,     │
│  specialized subagents                                        │
├──────────────────────────────────────────────────────────────┤
│  INSTRUCTION LAYER                                            │
│  ┌──────────────────────────────────────────────────────┐    │
│  │     CLAUDE.md  +  .claude/rules/  +  MEMORY.md       │    │
│  └──────────────────────────────────────────────────────┘    │
│  Project context, operational policy, cross-session memory    │
├──────────────────────────────────────────────────────────────┤
│  CORE LAYER                                                   │
│  ┌──────────────────────────────────────────────────────┐    │
│  │           Main Conversation Context (LLM)             │    │
│  └──────────────────────────────────────────────────────┘    │
│  Your primary interaction; finite context; costs money        │
└──────────────────────────────────────────────────────────────┘

Instruction Layer: CLAUDE.md-Dateien und Rules-Verzeichnisse definieren, was der Agent über Ihr Projekt weiß. Sie werden automatisch beim Sitzungsstart und nach jeder Kompaktierung geladen. Dies ist das langfristige Architekturgedächtnis des Agenten.

Extension Layer: Skills stellen Domänenexpertise bereit, die sich kontextbasiert automatisch aktiviert. Hooks bieten deterministische Gates, die bei jedem passenden Tool-Aufruf ausgelöst werden. Memory-Dateien persistieren Zustand über Sitzungen hinweg. Benutzerdefinierte Agents stellen spezialisierte Subagent-Konfigurationen bereit.

Orchestration Layer: Multi-Agenten-Patterns koordinieren unabhängige Agenten für Recherche, Review und Deliberation. Spawn-Budgets verhindern unkontrollierte Rekursion. Konsensvalidierung stellt Qualität sicher.

Die zentrale Erkenntnis: Die meisten Benutzer arbeiten ausschließlich im Core Layer und beobachten, wie Kontext aufbläht und Kosten steigen. Fortgeschrittene Benutzer konfigurieren den Instruction und Extension Layer und nutzen den Core Layer nur noch für Orchestrierung und finale Entscheidungen.²

Wie der Harness auf der Festplatte aussieht

~/.claude/
├── CLAUDE.md                    # Personal global instructions
├── settings.json                # User-level hooks and permissions
├── skills/                      # Personal skills (44+)
│   ├── code-reviewer/SKILL.md
│   ├── security-auditor/SKILL.md
│   └── api-designer/SKILL.md
├── agents/                      # Custom subagent definitions
│   ├── security-reviewer.md
│   └── code-explorer.md
├── rules/                       # Categorized rule files
│   ├── security.md
│   ├── testing.md
│   └── git-workflow.md
├── hooks/                       # Hook scripts
│   ├── validate-bash.sh
│   ├── auto-format.sh
│   └── recursion-guard.sh
├── configs/                     # JSON configuration
│   ├── recursion-limits.json
│   └── deliberation-config.json
├── state/                       # Runtime state
│   ├── recursion-depth.json
│   └── agent-lineage.json
├── handoffs/                    # Session handoff documents
│   └── deliberation-prd-7.md
└── projects/                    # Per-project memory
    └── {project}/memory/MEMORY.md

.claude/                         # Project-level (in repo)
├── CLAUDE.md                    # Project instructions
├── settings.json                # Project hooks
├── skills/                      # Team-shared skills
├── agents/                      # Team-shared agents
└── rules/                       # Project rules

Jede Datei in dieser Struktur erfüllt einen Zweck. Der ~/.claude/-Baum ist persönliche Infrastruktur, die für alle Projekte gilt. Der .claude/-Baum in jedem Repository ist projektspezifisch und wird über Git geteilt. Zusammen bilden sie den vollständigen harness.

Skills-System

Skills sind modellaufgerufene Erweiterungen. Claude entdeckt und wendet sie automatisch kontextbasiert an, ohne dass Sie sie explizit aufrufen müssen.⁴ Der Moment, in dem Sie sich dabei ertappen, denselben Kontext über Sitzungen hinweg immer wieder zu erklären, ist der Moment, in dem Sie einen Skill erstellen sollten.

Wann Sie einen Skill erstellen sollten

Skills sind für Wissen, das Claude stets verfügbar hat. Slash-Befehle sind für Aktionen, die Sie explizit auslösen. Wenn Sie zwischen beiden abwägen, fragen Sie sich: „Soll Claude dies automatisch anwenden, oder soll ich entscheiden, wann es ausgeführt wird?”

Einen Skill erstellen

Skills können an vier verschiedenen Orten liegen, vom breitesten bis zum engsten Geltungsbereich:⁴

Jeder Skill erfordert eine SKILL.md-Datei mit YAML-Frontmatter:

---
name: code-reviewer
description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.
allowed-tools: Read, Grep, Glob
---

# Code Review Expertise

## Sicherheitsprüfungen
Überprüfen Sie bei der Code-Überprüfung Folgendes:

### Eingabevalidierung
- Alle Benutzereingaben vor Datenbankoperationen bereinigt
- Parametrisierte Abfragen (keine String-Interpolation in SQL)
- Ausgabekodierung für gerenderte HTML-Inhalte

### Authentifizierung
- Session-Tokens bei jedem geschützten Endpunkt validiert
- Berechtigungsprüfungen vor Datenänderungen
- Keine hartkodierten Anmeldedaten oder API-Schlüssel im Quellcode

Frontmatter-Referenz

Das Description-Feld ist entscheidend

Beim Sitzungsstart extrahiert Claude Code name und description jedes Skills und fügt sie in den Kontext von Claude ein. Wenn Sie eine Nachricht senden, entscheidet Claude mittels Sprachmodell-Reasoning, ob ein Skill relevant ist. Eine unabhängige Analyse des Claude Code-Quellcodes bestätigt den Mechanismus: Skill-Beschreibungen werden in einen available_skills-Abschnitt des System-Prompts eingefügt, und das Modell nutzt standardmäßiges Sprachverständnis, um relevante Skills auszuwählen.¹⁰

Schlechte Beschreibung:

description: Helps with code

Effektive Beschreibung:

description: Review code for security vulnerabilities, performance issues,
  and best practice violations. Use when examining code changes, reviewing
  PRs, analyzing code quality, or when asked to review, audit, or check code.

Die effektive Beschreibung enthält: was der Skill tut (Code auf bestimmte Problemtypen prüfen), wann er eingesetzt werden soll (bei Änderungen, PRs, Qualitätsanalysen) und Auslösebegriffe (review, audit, check), die Benutzer natürlicherweise eingeben.

Kontextbudget

Alle Skill-Beschreibungen teilen sich ein Kontextbudget, das dynamisch auf 2 % des Kontextfensters skaliert, mit einem Fallback von 16.000 Zeichen.⁴ Bei vielen Skills sollten Sie jede Beschreibung knapp halten. Das Budget lässt sich über die Umgebungsvariable SLASH_COMMAND_TOOL_CHAR_BUDGET überschreiben,¹¹ doch die bessere Lösung sind kürzere, präzisere Beschreibungen. Führen Sie während einer Sitzung /context aus, um zu prüfen, ob Skills ausgeschlossen werden.

Unterstützende Dateien und Organisation

Skills können auf zusätzliche Dateien im selben Ordner verweisen:

~/.claude/skills/code-reviewer/
├── SKILL.md                    # Required: frontmatter + core expertise
├── SECURITY_PATTERNS.md        # Referenced: detailed vulnerability patterns
└── PERFORMANCE_CHECKLIST.md    # Referenced: optimization guidelines

Verweisen Sie aus SKILL.md mit relativen Links darauf. Claude liest diese Dateien bei Bedarf, sobald der Skill aktiviert wird. Halten Sie SKILL.md unter 500 Zeilen und lagern Sie detailliertes Referenzmaterial in unterstützende Dateien aus.¹²

Skills über Git teilen

Projekt-Skills (.claude/skills/ im Repository-Stammverzeichnis) werden über Versionskontrolle geteilt:⁴

mkdir -p .claude/skills/domain-expert
# ... write SKILL.md ...
git add .claude/skills/
git commit -m "feat: add domain-expert skill for payment processing rules"
git push

Wenn Teammitglieder pullen, erhalten sie den Skill automatisch. Keine Installation, keine Konfiguration. Dies ist der effektivste Weg, um Expertise teamübergreifend zu standardisieren.

Skills als Prompt-Bibliothek

Über einzelne Einsatzzwecke hinaus funktioniert die Ordnerstruktur als organisierte Prompt-Bibliothek:

~/.claude/skills/
├── code-reviewer/          # Activates on: review, audit, check
├── api-designer/           # Activates on: design API, endpoint, schema
├── sql-analyst/            # Activates on: query, database, migration
├── deploy-checker/         # Activates on: deploy, release, production
└── incident-responder/     # Activates on: error, failure, outage, debug

Jeder Skill kodiert eine andere Facette Ihrer Expertise. Zusammen bilden sie eine Wissensbasis, aus der Claude kontextabhängig automatisch schöpft. Ein Junior-Entwickler erhält Guidance auf Senior-Niveau, ohne danach fragen zu müssen.

Skills und Hooks im Zusammenspiel

Skills können in ihrem Frontmatter eigene Hooks definieren, die nur während der Ausführung des Skills aktiv sind. So entsteht domänenspezifisches Verhalten, das andere Sitzungen nicht beeinträchtigt:²

---
name: deploy-checker
description: Verify deployment readiness. Use when preparing to deploy,
  release, or push to production.
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: "bash -c 'INPUT=$(cat); CMD=$(echo \"$INPUT\" | jq -r \".tool_input.command\"); if echo \"$CMD\" | grep -qE \"deploy|release|publish\"; then echo \"DEPLOYMENT COMMAND DETECTED. Running pre-flight checks.\" >&2; fi'"
---

Philosophie-Skills aktivieren sich automatisch über SessionStart-Hooks und fügen Qualitätsanforderungen in jede Sitzung ein – ohne expliziten Aufruf. Der Skill selbst ist Wissen. Der Hook ist die Durchsetzung. Zusammen bilden sie eine Richtlinienebene.

Häufige Skill-Fehler

Zu breite Beschreibungen. Ein git-rebase-helper-Skill, der bei jedem Git-bezogenen Prompt aktiviert wird (Rebases, Merges, Cherry-Picks, sogar git status), verschmutzt den Kontext in 80 % der Sitzungen. Die Lösung besteht entweder darin, die Beschreibung einzugrenzen oder disable-model-invocation: true hinzuzufügen und einen expliziten /skill-name-Aufruf zu verlangen.⁴

Zu viele Skills konkurrieren um das Budget. Mehr Skills bedeuten mehr Beschreibungen, die um das 2 %-Kontextbudget konkurrieren. Wenn Sie bemerken, dass Skills nicht aktiviert werden, prüfen Sie über /context, ob welche ausgeschlossen sind. Bevorzugen Sie wenige, gut beschriebene Skills gegenüber vielen vagen.

Kritische Informationen in unterstützenden Dateien versteckt. Claude liest SKILL.md sofort, greift aber erst bei Bedarf auf unterstützende Dateien zu. Befinden sich kritische Informationen in einer unterstützenden Datei, findet Claude sie möglicherweise nicht. Platzieren Sie wesentliche Informationen direkt in SKILL.md.⁴

Hook-Architektur

Hooks sind Shell-Befehle, die durch Claude Code-Lifecycle-Events ausgelöst werden.³ Sie laufen außerhalb des LLM als einfache Skripte – nicht als Prompts, die vom Modell interpretiert werden. Das Modell möchte rm -rf / ausführen? Ein 10-zeiliges Bash-Skript prüft den Befehl gegen eine Blockliste und lehnt ihn ab, bevor die Shell ihn jemals zu sehen bekommt. Der Hook wird ausgelöst, ob das Modell es will oder nicht.

Verfügbare Events

Claude Code stellt 22 Lifecycle-Events in sechs Kategorien bereit:¹³

Exit-Code-Semantik

Exit-Codes bestimmen, ob Hooks Aktionen blockieren:³

Entscheidend: Jeder Sicherheits-Hook muss exit 2 verwenden, nicht exit 1. Exit 1 ist eine nicht-blockierende Warnung – der gefährliche Befehl wird trotzdem ausgeführt. Dies ist der häufigste Hook-Fehler in Teams.¹⁴

Hook-Konfiguration

Hooks befinden sich in Einstellungsdateien. Projektebene (.claude/settings.json) für gemeinsam genutzte Hooks. Benutzerebene (~/.claude/settings.json) für persönliche Hooks:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/validate-bash.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

Das matcher-Feld ist ein Regex, der Tool-Namen abgleicht: Bash, Write, Edit, Read, Glob, Grep, Agent oder * für alle Tools. Verwenden Sie "" (leerer String) für Events ohne Tools wie UserPromptSubmit.

Hook-Ein-/Ausgabeprotokoll

Hooks empfangen JSON über stdin mit vollständigem Kontext:

{
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "session_id": "abc-123",
  "agent_id": "main",
  "agent_type": "main"
}

Für erweiterte Steuerung können PreToolUse-Hooks JSON ausgeben, um Tool-Eingaben zu modifizieren, Kontext einzufügen oder Berechtigungsentscheidungen zu treffen:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "allow",
    "permissionDecisionReason": "Command validated and modified",
    "updatedInput": {
      "command": "npm test -- --coverage --ci"
    },
    "additionalContext": "Note: This database has a 5-second query timeout."
  }
}

Drei Arten von Garantien

Bevor Sie einen Hook schreiben, fragen Sie sich: Welche Art von Garantie brauche ich?¹⁴

Formatierungsgarantien stellen Konsistenz im Nachhinein sicher. PostToolUse-Hooks auf Write/Edit führen Ihren Formatter nach jeder Dateiänderung aus. Die Ausgabe des Modells spielt keine Rolle, da der Formatter alles normalisiert.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'if [[ \"$FILE_PATH\" == *.py ]]; then black --quiet \"$FILE_PATH\" 2>/dev/null; elif [[ \"$FILE_PATH\" == *.js ]] || [[ \"$FILE_PATH\" == *.ts ]]; then npx prettier --write \"$FILE_PATH\" 2>/dev/null; fi'"
          }
        ]
      }
    ]
  }
}

Sicherheitsgarantien verhindern gefährliche Aktionen, bevor sie ausgeführt werden. PreToolUse-Hooks auf Bash inspizieren Befehle und blockieren destruktive Muster mit Exit-Code 2:

#!/bin/bash
# validate-bash.sh — block dangerous commands
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "rm\s+-rf\s+/|git\s+push\s+(-f|--force)\s+(origin\s+)?main|git\s+reset\s+--hard|DROP\s+TABLE"; then
    echo "BLOCKED: Dangerous command detected: $CMD" >&2
    exit 2
fi

Qualitätsgarantien validieren den Zustand an Entscheidungspunkten. PreToolUse-Hooks auf git commit-Befehle führen Ihren Linter oder Ihre Testsuite aus und blockieren den Commit, wenn Qualitätsprüfungen fehlschlagen:

#!/bin/bash
# quality-gate.sh — lint before commit
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if echo "$CMD" | grep -qE "^git\s+commit"; then
    if ! LINT_OUTPUT=$(ruff check . --select E,F,W 2>&1); then
        echo "LINT FAILED -- fix before committing:" >&2
        echo "$LINT_OUTPUT" >&2
        exit 2
    fi
fi

Hook-Typen jenseits von Shell-Befehlen

Claude Code unterstützt drei Hook-Typen:¹³

Command-Hooks (type: "command") führen Shell-Skripte aus. Schnell, deterministisch, keine Token-Kosten.

Prompt-Hooks (type: "prompt") senden einen Single-Turn-Prompt an ein schnelles Claude-Modell. Das Modell gibt { "ok": true } zum Erlauben oder { "ok": false, "reason": "..." } zum Blockieren zurück. Geeignet für nuancierte Bewertungen, die sich per Regex nicht ausdrücken lassen.

Agent-Hooks (type: "agent") starten einen Subagent mit Tool-Zugriff (Read, Grep, Glob) für Multi-Turn-Verifikation. Verwenden Sie diese, wenn die Prüfung eine Inspektion tatsächlicher Dateien oder Testausgaben erfordert:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify all unit tests pass. Run the test suite and check results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Asynchrone Hooks

Hooks können im Hintergrund laufen, ohne die Ausführung zu blockieren. Fügen Sie async: true für unkritische Operationen wie Benachrichtigungen und Logging hinzu:¹³

{
  "type": "command",
  "command": ".claude/hooks/notify-slack.sh",
  "async": true
}

Verwenden Sie async für Benachrichtigungen, Telemetrie und Backups. Verwenden Sie async niemals für Formatierung, Validierung oder Aktionen, die vor dem nächsten Schritt abgeschlossen sein müssen.

Dispatcher statt unabhängiger Hooks

Sieben Hooks, die alle beim selben Event feuern und jeweils unabhängig stdin lesen, erzeugen Race Conditions. Zwei Hooks, die gleichzeitig in dieselbe JSON-Statusdatei schreiben, kürzen den JSON-Inhalt ab. Jeder nachgelagerte Hook, der diese Datei parst, bricht zusammen.²

Die Lösung: ein Dispatcher pro Event, der Hooks sequenziell mit gecachtem stdin ausführt:

#!/bin/bash
# dispatcher.sh — run hooks sequentially with cached stdin
INPUT=$(cat)
HOOK_DIR="$HOME/.claude/hooks/pre-tool-use.d"

for hook in "$HOOK_DIR"/*.sh; do
    [ -x "$hook" ] || continue
    echo "$INPUT" | "$hook"
    EXIT_CODE=$?
    if [ "$EXIT_CODE" -eq 2 ]; then
        exit 2  # Propagate block
    fi
done

Hooks debuggen

Fünf Techniken für das Debugging von Hooks, die stillschweigend fehlschlagen:¹⁴

1. Skripte unabhängig testen. Beispiel-JSON per Pipe übergeben: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Stderr für Debug-Ausgaben nutzen. Alles, was nach stderr geschrieben wird, erscheint im Kontext von Claude.
3. Auf jq-Fehler achten. Falsche JSON-Pfade geben stillschweigend null zurück. Testen Sie jq-Ausdrücke gegen echte Tool-Eingaben.
4. Exit-Codes überprüfen. Ein PreToolUse-Hook mit exit 1 bietet keinerlei Durchsetzung, obwohl er funktionierend erscheint.
5. Hooks schnell halten. Hooks laufen synchron. Halten Sie alle Hooks unter 2 Sekunden, idealerweise unter 500 ms.

Speicher und Kontext

Jede KI-Konversation arbeitet innerhalb eines endlichen Kontextfensters. Wenn die Konversation wächst, komprimiert das System frühere Gesprächsrunden, um Platz für neue Inhalte zu schaffen. Diese Komprimierung ist verlustbehaftet. Architekturentscheidungen, die in Runde 3 dokumentiert wurden, überleben möglicherweise nicht bis Runde 15.⁹

Die drei Mechanismen des Multi-Turn-Kollapses

Die MSR/Salesforce-Studie identifizierte drei unabhängige Mechanismen, von denen jeder eine andere Intervention erfordert:⁹

Strategie 1: Dateisystem als Speicher

Der zuverlässigste Speicher über Kontextgrenzen hinweg liegt im Dateisystem. Claude Code liest CLAUDE.md und Speicherdateien zu Beginn jeder Sitzung und nach jeder Komprimierung.⁶

~/.claude/
├── configs/           # 14 JSON configs (thresholds, rules, budgets)
│   ├── deliberation-config.json
│   ├── recursion-limits.json
│   └── consensus-profiles.json
├── hooks/             # 95 lifecycle event handlers
├── skills/            # 44 reusable knowledge modules
├── state/             # Runtime state (recursion depth, agent lineage)
├── handoffs/          # 49 multi-session context documents
├── docs/              # 40+ system documentation files
└── projects/          # Per-project memory directories
    └── {project}/memory/
        └── MEMORY.md  # Always loaded into context

Die Datei MEMORY.md erfasst Fehler, Entscheidungen und Muster über Sitzungen hinweg. Wenn Sie feststellen, dass ((VAR++)) mit set -e in Bash fehlschlägt, sobald VAR den Wert 0 hat, halten Sie dies fest. Drei Sitzungen später, wenn ein ähnlicher Integer-Grenzfall in Python auftritt, bringt der MEMORY.md-Eintrag das Muster wieder an die Oberfläche.¹⁵

Auto Memory (v2.1.32+): Claude Code zeichnet Projektkontext automatisch auf und ruft ihn ab. Während Sie arbeiten, schreibt Claude Beobachtungen nach ~/.claude/projects/{project-path}/memory/MEMORY.md. Auto Memory lädt die ersten 200 Zeilen beim Sitzungsstart in Ihren System-Prompt. Halten Sie den Inhalt prägnant und verlinken Sie auf separate Themendateien für detaillierte Notizen.⁶

Strategie 2: Proaktive Komprimierung

Der /compact-Befehl von Claude Code fasst die Konversation zusammen und gibt Kontextplatz frei, während wichtige Entscheidungen, Dateiinhalte und der Aufgabenstatus erhalten bleiben.¹⁵

Wann Sie komprimieren sollten: - Nach Abschluss einer abgrenzbaren Teilaufgabe (Feature implementiert, Bug behoben) - Bevor Sie in einen neuen Bereich der Codebasis wechseln - Wenn Claude beginnt, sich zu wiederholen oder früheren Kontext zu vergessen - Ungefähr alle 25–30 Minuten während intensiver Sitzungen

Benutzerdefinierte Komprimierungsanweisungen in CLAUDE.md:

# Summary Instructions
When using compact, focus on:
- Recent code changes
- Test results
- Architecture decisions made this session

Strategie 3: Sitzungsübergaben

Für Aufgaben, die sich über mehrere Sitzungen erstrecken, erstellen Sie Übergabedokumente, die den vollständigen Zustand erfassen:

## Handoff: Deliberation Infrastructure PRD-7
**Status:** Hook wiring complete, 81 Python unit tests passing
**Files changed:** hooks/post-deliberation.sh, hooks/deliberation-pride-check.sh
**Decision:** Placed post-deliberation in PostToolUse:Task, pride-check in Stop
**Blocked:** Spawn budget model needs inheritance instead of depth increment
**Next:** PRD-8 integration tests in tests/test_deliberation_lib.py

Die Struktur aus Status/Files/Decision/Blocked/Next liefert der nachfolgenden Sitzung den vollständigen Kontext bei minimalem Token-Verbrauch. Eine neue Sitzung mit claude -c (fortsetzen) zu starten oder das Übergabedokument zu lesen, führt direkt zur Implementierung.¹⁵

Strategie 4: Iteration mit frischem Kontext (Die Ralph-Schleife)

Bei Sitzungen, die 60–90 Minuten überschreiten, starten Sie eine neue Claude-Instanz pro Iteration. Der Zustand wird über das Dateisystem persistiert, nicht über den Konversationsspeicher. Jede Iteration erhält das volle Kontextbudget:¹⁶

Iteration 1: [200K tokens] -> writes code, creates files, updates state
Iteration 2: [200K tokens] -> reads state from disk, continues
Iteration 3: [200K tokens] -> reads updated state, continues
...
Iteration N: [200K tokens] -> reads final state, verifies criteria

Im Vergleich dazu eine einzelne lange Sitzung:

Minute 0:   [200K tokens available] -> productive
Minute 30:  [150K tokens available] -> somewhat productive
Minute 60:  [100K tokens available] -> degraded
Minute 90:  [50K tokens available]  -> significantly degraded
Minute 120: [compressed, lossy]     -> errors accumulate

Der Ansatz mit frischem Kontext pro Iteration tauscht 15–20 % Overhead für den Orientierungsschritt (Zustandsdateien lesen, Git-Historie durchsuchen) gegen volle kognitive Ressourcen pro Iteration ein.¹⁶ Die Kosten-Nutzen-Rechnung: Bei Sitzungen unter 60 Minuten ist eine einzelne Konversation effizienter. Jenseits von 90 Minuten liefert der Ansatz mit frischem Kontext trotz des Overheads qualitativ hochwertigere Ergebnisse.

Die Anti-Patterns

Ganze Dateien lesen, wenn Sie nur 10 Zeilen brauchen. Ein einziges Lesen einer 2.000-Zeilen-Datei verbraucht 15.000–20.000 Token. Verwenden Sie Zeilen-Offsets: Read file.py offset=100 limit=20 spart den Großteil dieser Kosten.¹⁵

Ausführliche Fehlerausgaben im Kontext belassen. Nach dem Debuggen eines Bugs enthält Ihr Kontext über 40 Stack-Traces aus fehlgeschlagenen Iterationen. Ein einzelnes /compact nach der Fehlerbehebung befreit Sie von diesem toten Ballast.

Jede Sitzung damit beginnen, jede Datei zu lesen. Nutzen Sie stattdessen die Glob- und Grep-Werkzeuge von Claude Code, um relevante Dateien bei Bedarf zu finden – das spart über 100.000 Token an unnötigem Vorladen.¹⁵

Subagent-Muster

Subagents sind spezialisierte Claude-Instanzen, die komplexe Aufgaben eigenständig bearbeiten. Sie starten mit einem sauberen Kontext (keine Verunreinigung durch die Hauptkonversation), arbeiten mit festgelegten Tools und liefern Ergebnisse als Zusammenfassungen zurück. Die Explorationsergebnisse blähen Ihre Hauptkonversation nicht auf – nur die Schlussfolgerungen werden zurückgegeben.⁵

Integrierte Subagent-Typen

Eigene Subagents erstellen

Definieren Sie Subagents in .claude/agents/ (Projekt) oder ~/.claude/agents/ (persönlich):

---
name: security-reviewer
description: Expert security code reviewer. Use PROACTIVELY after any code
  changes to authentication, authorization, or data handling.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

You are a senior security engineer reviewing code for vulnerabilities.

When invoked:
1. Identify the files that were recently changed
2. Analyze for OWASP Top 10 vulnerabilities
3. Check for secrets, hardcoded credentials, SQL injection
4. Report findings with severity levels and remediation steps

Focus on actionable security findings, not style issues.

Konfigurationsfelder für Subagents

Worktree-Isolation

Subagents können in temporären Git-Worktrees arbeiten und erhalten dadurch eine vollständig isolierte Kopie des Repositorys:⁵

---
name: experimental-refactor
description: Attempt risky refactoring in isolation
isolation: worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

You have an isolated copy of the repository. Make changes freely.
If the refactoring succeeds, the changes can be merged back.
If it fails, the worktree is discarded with no impact on the main branch.

Worktree-Isolation ist unverzichtbar für experimentelle Arbeiten, die die Codebase beschädigen könnten.

Parallele Subagents

Claude Code unterstützt bis zu 10 parallele Subagents.⁵ Nutzen Sie parallele Ausführung für voneinander unabhängige Rechercheaufgaben:

> Have three explore agents search in parallel:
> 1. Authentication code
> 2. Database models
> 3. API routes

Jeder Agent läuft in seinem eigenen Kontextfenster, findet relevanten Code und liefert eine Zusammenfassung zurück. Der Hauptkontext bleibt sauber.

Der Rekursionsschutz

Ohne Spawn-Limits delegieren Agents an Agents, die wiederum an Agents delegieren – jeder verliert dabei Kontext und verbraucht Tokens. Das Rekursionsschutz-Muster erzwingt Budgets:¹⁶

#!/bin/bash
# recursion-guard.sh — enforce spawn budget
CONFIG_FILE="${HOME}/.claude/configs/recursion-limits.json"
STATE_FILE="${HOME}/.claude/state/recursion-depth.json"

MAX_DEPTH=2
MAX_CHILDREN=5
DELIB_SPAWN_BUDGET=2
DELIB_MAX_AGENTS=12

# Read current depth
current_depth=$(jq -r '.depth // 0' "$STATE_FILE" 2>/dev/null)

if [[ "$current_depth" -ge "$MAX_DEPTH" ]]; then
    echo "BLOCKED: Maximum recursion depth ($MAX_DEPTH) reached" >&2
    exit 2
fi

# Increment depth using safe arithmetic (not ((VAR++)) with set -e)
new_depth=$((current_depth + 1))
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

Entscheidende Erkenntnis: Verwenden Sie Spawn-Budgets, nicht nur Tiefenlimits. Tiefenbasierte Limits verfolgen Eltern-Kind-Ketten (blockiert bei Tiefe 3), übersehen allerdings die Breite: 23 Agents auf Tiefe 1 gelten immer noch als „Tiefe 1”. Ein Spawn-Budget verfolgt die Gesamtzahl aktiver Kinder pro Elternelement, begrenzt auf ein konfigurierbares Maximum. Das Budgetmodell bildet den tatsächlichen Fehlermodus ab (zu viele Agents insgesamt) statt einer Proxy-Metrik (zu viele Verschachtelungsebenen).⁷

Agent Teams (Research Preview)

Agent Teams koordinieren mehrere Claude Code-Instanzen, die unabhängig voneinander arbeiten, über ein gemeinsames Postfach und eine Aufgabenliste kommunizieren und die Ergebnisse der anderen hinterfragen können:⁵

Aktivierung mit: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Wann Agent Teams statt Subagents einsetzen:

Multi-Agent-Orchestrierung

KI-Systeme mit nur einem Agenten haben einen strukturellen blinden Fleck: Sie können ihre eigenen Annahmen nicht hinterfragen.⁷ Multi-Agent-Deliberation erzwingt eine unabhängige Bewertung aus mehreren Perspektiven, bevor eine Entscheidung feststeht.

Minimale Deliberation

Beginnen Sie mit 2 Agenten und 1 Regel: Agenten müssen unabhängig voneinander bewerten, bevor sie die Ergebnisse des jeweils anderen sehen.⁷

Decision arrives
  |
  v
Confidence check: is this risky, ambiguous, or irreversible?
  |
  +-- NO  -> Single agent decides (normal flow)
  |
  +-- YES -> Spawn 2 agents with different system prompts
             Agent A: "Argue FOR this approach"
             Agent B: "Argue AGAINST this approach"
             |
             v
             Compare findings
             |
             +-- Agreement with different reasoning -> Proceed
             +-- Genuine disagreement -> Investigate the conflict
             +-- Agreement with same reasoning -> Suspect herding

Dieses Muster deckt 80 % des Nutzens ab. Alles Weitere bringt nur inkrementelle Verbesserungen.

Der Konfidenz-Trigger

Nicht jede Aufgabe erfordert Deliberation. Ein Konfidenz-Scoring-Modul bewertet vier Dimensionen:¹⁷

1. Mehrdeutigkeit – Lässt sich die Anfrage auf mehrere gültige Weisen interpretieren?
2. Domänenkomplexität – Ist Spezialwissen erforderlich?
3. Tragweite – Ist die Entscheidung reversibel?
4. Kontextabhängigkeit – Muss das übergeordnete System verstanden werden?

Der Score wird drei Stufen zugeordnet:

Der Schwellenwert passt sich dem Aufgabentyp an. Sicherheitsentscheidungen erfordern einen Konsens von 0,85. Dokumentationsänderungen benötigen lediglich 0,50. So wird verhindert, dass einfache Aufgaben überentwickelt werden, während riskante Entscheidungen die nötige Prüfung erhalten.⁷

Die Zustandsmaschine

Sieben Phasen, jede durch die vorherige bedingt:⁷

IDLE -> RESEARCH -> DELIBERATION -> RANKING -> PRD_GENERATION -> COMPLETE
                                                                    |
                                                              (or FAILED)

RESEARCH: Unabhängige Agenten untersuchen das Thema. Jeder Agent erhält eine eigene Persona (Technical Architect, Security Analyst, Performance Engineer und weitere). Kontextisolierung stellt sicher, dass Agenten während der Recherchephase gegenseitig keinen Einblick in ihre Ergebnisse haben.

DELIBERATION: Agenten sehen alle Rechercheergebnisse und generieren Alternativen. Der Debate-Agent identifiziert Konflikte. Der Synthesis-Agent kombiniert nicht-widersprüchliche Erkenntnisse.

RANKING: Jeder Agent bewertet jeden vorgeschlagenen Ansatz anhand von 5 gewichteten Dimensionen:

Die Zwei-Gate-Validierungsarchitektur

Zwei Validierungsgates fangen Probleme in unterschiedlichen Phasen ab:⁷

Gate 1: Konsensvalidierung (PostToolUse hook). Wird unmittelbar nach Abschluss jedes Deliberationsagenten ausgeführt: 1. Die Phase muss mindestens RANKING erreicht haben 2. Mindestens 2 Agenten abgeschlossen (konfigurierbar) 3. Der Konsenswert erreicht den aufgabenadaptiven Schwellenwert 4. Falls ein Agent abweichend votiert hat, müssen die Bedenken dokumentiert sein

Gate 2: Pride Check (Stop hook). Wird ausgeführt, bevor die Sitzung beendet werden kann: 1. Methodenvielfalt: mehrere unterschiedliche Personas vertreten 2. Widerspruchstransparenz: abweichende Meinungen mit dokumentierten Begründungen 3. Komplexitätsbehandlung: mindestens 2 Alternativen generiert 4. Konsensvertrauen: klassifiziert als stark (über 0,85) oder moderat (0,70–0,84) 5. Verbesserungsnachweis: endgültige Konfidenz übersteigt die anfängliche Konfidenz

Zwei hooks an unterschiedlichen Lebenszykluspunkten entsprechen der Art, wie Fehler tatsächlich auftreten: Manche sind sofort erkennbar (schlechter Score), andere schleichend (geringe Vielfalt, fehlende Dokumentation abweichender Meinungen).⁷

Warum Übereinstimmung gefährlich ist

Charlan Nemeth erforschte Minderheitendissens ab 1986 bis zu ihrem Buch In Defense of Troublemakers von 2018. Gruppen mit Andersdenkenden treffen bessere Entscheidungen als Gruppen, die schnell Einigkeit erzielen. Der Abweichler muss dabei nicht einmal recht haben. Allein der Akt des Widerspruchs zwingt die Mehrheit, Annahmen zu überprüfen, die sie sonst übergangen hätte.¹⁸

Wu et al. untersuchten, ob LLM-Agenten tatsächlich debattieren können, und stellten fest, dass Agenten ohne strukturelle Anreize für Widerspruch zur überzeugendsten klingenden Erstantwort konvergieren – unabhängig von deren Korrektheit.¹⁹ Liang et al. identifizierten die Ursache als „Degeneration-of-Thought”: Sobald ein LLM Vertrauen in eine Position aufgebaut hat, kann Selbstreflexion keine neuartigen Gegenargumente hervorbringen, was Multi-Agent-Bewertung strukturell notwendig macht.²⁰

Unabhängigkeit ist die entscheidende Designvorgabe. Zwei Agenten, die dieselbe Deployment-Strategie mit Einblick in die Ergebnisse des jeweils anderen bewerteten, erzielten Scores von 0,45 und 0,48. Dieselben Agenten ohne gegenseitigen Einblick: 0,45 und 0,72. Die Differenz zwischen 0,48 und 0,72 ist der Preis des Herdenverhaltens.⁷

Erkennung falscher Übereinstimmung

Ein Konformitätserkennungsmodul verfolgt Muster, die darauf hindeuten, dass Agenten zustimmen, ohne tatsächlich eigenständig bewertet zu haben:⁷

Score-Clustering: Wenn alle Agenten innerhalb von 0,3 Punkten auf einer 10-Punkte-Skala bewerten, deutet dies auf eine Kontamination durch geteilten Kontext hin statt auf unabhängige Bewertung. Als fünf Agenten bei der Bewertung eines Authentifizierungs-Refactorings das Sicherheitsrisiko zwischen 7,1 und 7,4 einordneten, ergab eine erneute Ausführung mit frischer Kontextisolierung eine Streuung von 5,8–8,9.

Schablonenhafter Dissens: Agenten, die die Bedenkenformulierungen des jeweils anderen kopieren, anstatt eigenständige Einwände zu formulieren.

Fehlende Minderheitenperspektiven: Einstimmige Zustimmung von Personas mit widersprüchlichen Prioritäten (ein Security Analyst und ein Performance Engineer sind selten in allem einer Meinung).

Der Konformitätsdetektor erkennt die offensichtlichen Fälle (etwa 10–15 % der Deliberationen, bei denen Agenten zu schnell konvergieren). Für die verbleibenden 85–90 % bieten die Konsens- und Pride-Check-Gates ausreichende Validierung.

Was bei der Deliberation nicht funktioniert hat

Freie Debattenrunden. Drei Runden textbasierter Diskussion über Datenbankindizierung erzeugten 7.500 Token Debatte. Runde 1: echte Meinungsverschiedenheit. Runde 2: Positionen wurden wiederholt. Runde 3: identische Argumente in anderen Worten. Strukturierte Dimensionsbewertung ersetzte die freie Debatte und senkte die Kosten um 60 % bei gleichzeitig verbesserter Ranking-Qualität.⁷

Ein einzelnes Validierungsgate. Die erste Implementierung verwendete einen einzigen Validierungs-Hook am Sitzungsende. Ein Agent schloss die Deliberation mit einem Konsenswert von 0,52 ab (unter dem Schwellenwert) und arbeitete dann 20 Minuten an anderen Aufgaben weiter, bevor der Session-End-Hook den Fehler meldete. Die Aufteilung in zwei Gates (eines bei Aufgabenabschluss, eines am Sitzungsende) fing dieselben Probleme an unterschiedlichen Lebenszykluspunkten ab.⁷

Kosten der Deliberation

Jeder Recherche-Agent verarbeitet etwa 5.000 Token Kontext und generiert 2.000–3.000 Token an Ergebnissen. Bei 3 Agenten sind das 15.000–24.000 zusätzliche Token pro Entscheidung. Bei 10 Agenten etwa 50.000–80.000 Token.⁷

Beim aktuellen Opus-Pricing kostet eine Deliberation mit 3 Agenten ungefähr 0,68–0,90 $. Eine Deliberation mit 10 Agenten kostet 2,25–3,00 $. Das System löst bei etwa 10 % der Entscheidungen eine Deliberation aus, sodass die amortisierten Kosten über alle Entscheidungen bei 0,23–0,30 $ pro Sitzung liegen. Ob sich das lohnt, hängt davon ab, was eine Fehlentscheidung kostet.

Wann deliberiert werden sollte

CLAUDE.md-Design

CLAUDE.md ist eine operative Richtlinie für einen KI-Agenten, kein README für Menschen.²¹ Der Agent muss nicht verstehen, warum Sie Conventional Commits verwenden. Er muss den exakten Befehl kennen und wissen, wie „fertig” aussieht.

Die Rangfolge-Hierarchie

Rules-Dateien werden automatisch geladen und liefern strukturierten Kontext, ohne die CLAUDE.md zu überfrachten.⁶

Was ignoriert wird

Diese Muster erzeugen zuverlässig keine beobachtbare Verhaltensänderung beim Agenten:²¹

Prosa-Absätze ohne Befehle. „Wir legen Wert auf sauberen, gut getesteten Code” ist Dokumentation, keine Anweisung. Der Agent liest es und schreibt anschließend Code ohne Tests, weil keine umsetzbare Anweisung vorliegt.

Mehrdeutige Direktiven. „Seien Sie vorsichtig bei Datenbankmigrationen” ist keine Einschränkung. „Führen Sie alembic check vor dem Anwenden von Migrationen aus. Abbruch, wenn der Downgrade-Pfad fehlt.” hingegen schon.

Widersprüchliche Prioritäten. „Schnell vorankommen und ausliefern” plus „Umfassende Testabdeckung sicherstellen” plus „Laufzeit unter 5 Minuten halten” plus „Vor jedem Commit vollständige Integrationstests ausführen.” Der Agent kann nicht alle vier gleichzeitig erfüllen und überspringt standardmäßig die Verifikation.²¹

Styleguides ohne Durchsetzung. „Dem Google Python Style Guide folgen” ohne ruff check --select D gibt dem Agenten keinen Mechanismus zur Überprüfung der Einhaltung.

Was funktioniert

Befehlsorientierte Anweisungen:

## Build and Test Commands
- Install: `pip install -r requirements.txt`
- Lint: `ruff check . --fix`
- Format: `ruff format .`
- Test: `pytest -v --tb=short`
- Type check: `mypy app/ --strict`
- Full verify: `ruff check . && ruff format --check . && pytest -v`

Abschlussdefinitionen:

## Definition of Done
Eine Aufgabe ist abgeschlossen, wenn ALLE folgenden Prüfungen bestanden sind:
1. `ruff check .` beendet mit Exit-Code 0
2. `pytest -v` beendet mit Exit-Code 0 ohne Fehler
3. `mypy app/ --strict` beendet mit Exit-Code 0
4. Geänderte Dateien wurden gestaged und committet
5. Die Commit-Nachricht folgt dem konventionellen Format: `type(scope): description`

Aufgabenorientierte Abschnitte:

## Beim Schreiben von Code
- Führen Sie `ruff check .` nach jeder Dateiänderung aus
- Fügen Sie Type Hints zu allen neuen Funktionen hinzu

## Beim Überprüfen von Code
- Prüfen Sie auf Sicherheitsprobleme: `bandit -r app/`
- Überprüfen Sie die Testabdeckung: `pytest --cov=app --cov-fail-under=80`

## Beim Veröffentlichen
- Aktualisieren Sie die Version in `pyproject.toml`
- Führen Sie die vollständige Testsuite aus: `pytest -v && ruff check . && mypy app/`

Eskalationsregeln:

## Bei Blockaden
- Falls Tests nach 3 Versuchen fehlschlagen: Stoppen und den fehlgeschlagenen Test mit vollständiger Ausgabe melden
- Falls eine Abhängigkeit fehlt: Zuerst `requirements.txt` prüfen, dann nachfragen
- Niemals: Dateien löschen um Fehler zu beheben, Force-Push durchführen oder Tests überspringen

Reihenfolge beim Erstellen

Wenn Sie bei Null anfangen, fügen Sie Abschnitte in dieser Prioritätsreihenfolge hinzu:²¹

1. Build- und Testbefehle (der Agent benötigt diese, bevor er irgendetwas Sinnvolles tun kann)
2. Definition of Done (verhindert falsche Abschlüsse)
3. Eskalationsregeln (verhindert destruktive Workarounds)
4. Aufgabenorientierte Abschnitte (reduziert das Parsen irrelevanter Anweisungen)
5. Verzeichnisbegrenzung (Monorepos: hält Service-Anweisungen isoliert)

Stilpräferenzen können warten, bis die ersten vier Punkte funktionieren.

Datei-Importe

Referenzieren Sie andere Dateien innerhalb von CLAUDE.md:

See @README.md for project overview
Coding standards: @docs/STYLE_GUIDE.md
API documentation: @docs/API.md
Personal preferences: @~/.claude/preferences.md

Import-Syntax: relativ (@docs/file.md), absolut (@/absolute/path.md) oder Home-Verzeichnis (@~/.claude/file.md). Maximale Tiefe: 5 Import-Ebenen.⁶

Kompatibilität mit anderen Tools

AGENTS.md ist ein offener Standard, der von über 60.000 Projekten genutzt und von jedem großen AI-Coding-Tool erkannt wird.²¹ Falls Ihr Team mehrere Tools verwendet, schreiben Sie AGENTS.md als kanonische Quelle und spiegeln Sie relevante Abschnitte in toolspezifische Dateien:

Die Muster in AGENTS.md (Befehl-zuerst, Closure-definiert, aufgabenorientiert) funktionieren in jeder Anweisungsdatei unabhängig vom Tool. Pflegen Sie keine parallelen Anweisungssätze, die auseinanderdriften. Schreiben Sie eine autoritative Quelle und spiegeln Sie diese.

Testen Ihrer Anweisungen

Überprüfen Sie, ob der Agent Ihre Anweisungen tatsächlich liest und befolgt:

# Check active instructions
claude --print "What instructions are you following for this project?"

# Verify specific rules are active
claude --print "What is your definition of done?"

Der Lackmustest: Bitten Sie den Agenten, Ihre Build-Befehle zu erklären. Kann er sie nicht wörtlich wiedergeben, sind die Anweisungen entweder zu ausführlich (Inhalte werden aus dem Kontext verdrängt), zu vage (der Agent kann keine umsetzbaren Anweisungen extrahieren) oder werden nicht gefunden. Die Analyse von GitHub über 2.500 Repositories ergab, dass Vagheit die häufigste Fehlerursache ist.²¹

Produktionsmuster

Der quality loop

Ein verbindlicher Überprüfungsprozess für alle nicht-trivialen Änderungen:

1. Implementieren – Schreiben Sie den Code
2. Überprüfen – Lesen Sie jede Zeile erneut. Finden Sie Tippfehler, Logikfehler und unklare Stellen
3. Bewerten – Führen Sie das evidence gate aus. Prüfen Sie Muster, Grenzfälle und Testabdeckung
4. Verfeinern – Beheben Sie jedes Problem. Niemals auf „später” verschieben
5. Zurücktreten – Prüfen Sie Integrationspunkte, Importe und angrenzenden Code auf Regressionen
6. Wiederholen – Falls ein Kriterium des evidence gate fehlschlägt, zurück zu Schritt 4
7. Berichten – Listen Sie auf, was geändert wurde, wie verifiziert, mit konkreten Belegen

Das evidence gate

„Ich glaube” und „es sollte” sind keine Belege. Nennen Sie Dateipfade, Testausgaben oder konkreten Code.

Können Sie für eine Zeile keinen Beleg erbringen, kehren Sie zur Verfeinerung zurück.²²

Fehlerbehandlungsmuster

Atomare Dateischreibvorgänge. Wenn mehrere Agenten gleichzeitig in dieselbe Zustandsdatei schreiben, wird JSON beschädigt. Schreiben Sie in .tmp-Dateien und verschieben Sie dann atomar mit mv. Das Betriebssystem garantiert, dass mv auf demselben Dateisystem atomar ist.¹⁷

# Atomic state update
jq --argjson d "$new_depth" '.depth = $d' "$STATE_FILE" > "${STATE_FILE}.tmp"
mv "${STATE_FILE}.tmp" "$STATE_FILE"

Wiederherstellung bei Zustandsbeschädigung. Bei beschädigtem Zustand stellt das Wiederherstellungsmuster sichere Standardwerte wieder her, anstatt abzustürzen:¹⁶

if ! jq -e '.depth' "$RECURSION_STATE_FILE" &>/dev/null; then
    # Corrupted state file, recreate with safe defaults
    echo '{"depth": 0, "agent_id": "root", "parent_id": null}' > "$RECURSION_STATE_FILE"
    echo "- Recursion state recovered (was corrupted)"
fi

Die ((VAR++)) Bash-Falle. ((VAR++)) gibt Exit-Code 1 zurück, wenn VAR gleich 0 ist, weil 0++ zu 0 ausgewertet wird – und Bash behandelt 0 als falsch. Mit aktiviertem set -e bricht dies das Skript ab. Verwenden Sie stattdessen VAR=$((VAR + 1)).¹⁶

Klassifikation des Wirkungsradius

Klassifizieren Sie jede Agenten-Aktion nach ihrem Wirkungsradius und sichern Sie entsprechend ab:²

Remote Control (Verbindung zum lokalen Claude Code von jedem Browser oder mobiler App) verwandelt die „Extern”-Absicherung von einer blockierenden Wartezeit in eine asynchrone Benachrichtigung. Der Agent arbeitet an der nächsten Aufgabe weiter, während Sie die vorherige von Ihrem Telefon aus überprüfen.²

Aufgabenspezifikation für autonome Durchläufe

Effektive autonome Aufgaben enthalten drei Elemente: Ziel, Abschlusskriterien und Kontextverweise:¹⁶

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

COMPLETION CRITERIA:
- All tests in tests/test_deliberation_lib.py pass (81 tests)
- post-deliberation.sh validates consensus above 70% threshold
- recursion-guard.sh enforces spawn budget (max 12 agents)
- No Python type errors (mypy clean)

CONTEXT:
- Follow patterns in lib/deliberation/state_machine.py
- Consensus thresholds in configs/deliberation-config.json
- Spawn budget model: agents inherit budget, not increment depth

Kriterien müssen maschinell überprüfbar sein: Test bestanden/fehlgeschlagen, Linter-Ausgabe, HTTP-Statuscodes, Dateiexistenzprüfungen. Eine frühe Aufgabe, die den Agenten bat „Tests zu schreiben, die bestehen”, produzierte assert True und assert 1 == 1. Technisch korrekt. Praktisch wertlos.¹⁶

Zu beobachtende Fehlermodi

Ein konkreter Sitzungsablauf

Ein Sitzungsablauf aus einem autonomen Durchlauf, der ein PRD mit 5 Stories verarbeitet:²

1. SessionStart wird ausgelöst. Der dispatcher injiziert: aktuelles Datum, Projekterkennung, Philosophie-Einschränkungen, Kostentracking-Initialisierung. Fünf hooks, insgesamt 180ms.

2. Der Agent liest das PRD und plant die erste Story. UserPromptSubmit wird ausgelöst. Der dispatcher injiziert: aktiven Projektkontext, Sitzungsdrift-Baseline.

3. Der Agent ruft Bash auf, um Tests auszuführen. PreToolUse:Bash wird ausgelöst. Anmeldedatenprüfung, Sandbox-Validierung, Projekterkennung. 90ms. Tests laufen. PostToolUse:Bash wird ausgelöst: Aktivitäts-Heartbeat protokolliert, Drift-Prüfung.

4. Der Agent ruft Write auf, um eine Datei zu erstellen. PreToolUse:Write wird ausgelöst: Dateiberechtigungsprüfung. PostToolUse:Write wird ausgelöst: Lint-Prüfung, Commit-Tracking.

5. Der Agent schließt die Story ab. Stop wird ausgelöst. Qualitätsprüfung: Hat der Agent Belege zitiert? Vage Formulierungen? TODO-Kommentare im Diff? Falls eine Prüfung fehlschlägt, Exit 2 und der Agent arbeitet weiter.

6. Unabhängige Verifizierung: Ein frischer Agent führt die Testsuite aus, ohne dem Selbstbericht des vorherigen Agenten zu vertrauen.

7. Drei Code-Review-Agenten werden parallel gestartet. Jeder überprüft den Diff unabhängig. Markiert ein Reviewer etwas als CRITICAL, wird die Story zurück in die Warteschlange gestellt.

8. Story bestanden. Nächste Story wird geladen. Der Zyklus wiederholt sich für alle 5 Stories.

Insgesamt ausgelöste hooks über 5 Stories: ~340. Gesamtzeit in hooks: ~12 Sekunden. Dieser Overhead verhinderte in einem einzigen nächtlichen Durchlauf drei Anmeldedaten-Lecks, einen destruktiven Befehl und zwei unvollständige Implementierungen.

Sicherheitsaspekte

Die Sandbox

Claude Code läuft in einer Sandbox, die den Netzwerkzugang und Dateisystemoperationen einschränkt. Die Sandbox verhindert, dass das Modell beliebige Netzwerkanfragen stellt oder auf Dateien außerhalb des Projektverzeichnisses zugreift.¹³

Berechtigungsgrenzen

Das Berechtigungssystem kontrolliert Operationen auf mehreren Ebenen:

Schutz vor Prompt Injection

Skills und hooks bieten gestaffelte Verteidigung gegen Prompt Injection:

Skills mit Tool-Einschränkungen verhindern, dass ein kompromittierter Prompt Schreibzugriff erlangt:

allowed-tools: Read, Grep, Glob

PreToolUse hooks validieren jeden Tool-Aufruf, unabhängig davon, wie das Modell angesprochen wurde:

# Block credential file access regardless of prompt
if echo "$FILE_PATH" | grep -qE "\.(env|pem|key|credentials)$"; then
    echo "BLOCKED: Sensitive file access" >&2
    exit 2
fi

Subagent-Isolation begrenzt den Wirkungsradius. Ein Subagent mit permissionMode: plan kann keine Änderungen vornehmen, selbst wenn sein Prompt kompromittiert wurde.

Hook-Sicherheit

HTTP hooks, die Umgebungsvariablen in Header interpolieren, erfordern eine explizite allowedEnvVars-Liste, um das willkürliche Auslesen von Umgebungsvariablen zu verhindern:¹³

{
  "type": "http",
  "url": "https://api.example.com/notify",
  "headers": {
    "Authorization": "Bearer $MY_TOKEN"
  },
  "allowedEnvVars": ["MY_TOKEN"]
}

Die Verantwortungsteilung zwischen Mensch und Agent

Sicherheit in Agentenarchitekturen erfordert eine klare Aufteilung der Verantwortlichkeiten zwischen Mensch und Agent:¹⁷

Das Muster: Menschen verantworten Entscheidungen, die organisatorischen Kontext, ethisches Urteilsvermögen oder strategische Ausrichtung erfordern. Agenten verantworten Entscheidungen, die rechnerische Suche über große Möglichkeitsräume erfordern. Hooks setzen die Grenze durch.

Rekursive Hook-Durchsetzung

Hooks werden auch für Subagent-Aktionen ausgelöst.¹³ Wenn Claude über das Agent tool einen Subagent startet, werden Ihre PreToolUse- und PostToolUse hooks für jedes Tool ausgeführt, das der Subagent verwendet. Ohne rekursive Hook-Durchsetzung könnte ein Subagent Ihre Sicherheitsschranken umgehen. Das SubagentStop-Event ermöglicht es Ihnen, Bereinigung oder Validierung durchzuführen, wenn ein Subagent abgeschlossen wird.

Das ist nicht optional. Ein Agent, der einen Subagent ohne Ihre Sicherheits-hooks startet, ist ein Agent, der auf main force-pushen, Anmeldedateien lesen oder destruktive Befehle ausführen kann, während Ihre Gates die Hauptkonversation tatenlos beobachten.

Kosten als Architektur

Kosten sind eine Architekturentscheidung, kein operativer Nachgedanke.² Drei Ebenen:

Token-Ebene. System-Prompt-Komprimierung. Entfernen Sie Tutorial-Codebeispiele (das Modell kennt die APIs), fassen Sie doppelte Regeln über Dateien hinweg zusammen und ersetzen Sie Erklärungen durch Constraints. „Tool-Aufrufe ablehnen, die sensible Pfade betreffen” leistet dasselbe wie eine 15-zeilige Erklärung, warum Anmeldedaten nicht gelesen werden sollten.

Agent-Ebene. Frische Starts statt langer Konversationen. Jede Story in einem autonomen Lauf erhält einen neuen Agenten mit sauberem Kontext. Der Kontext bläht sich nie auf, weil jeder Agent frisch beginnt. Briefing statt Gedächtnis: Modelle führen ein klares Briefing besser aus, als sich durch 30 angesammelte Kontextschritte zu navigieren.

Architekturebene. CLI-first statt MCP, wenn die Operation zustandslos ist. Ein claude --print-Aufruf für eine einmalige Auswertung kostet weniger und erzeugt keinen Verbindungsoverhead. MCP ist sinnvoll, wenn das Tool persistenten Zustand oder Streaming benötigt.

Entscheidungsrahmen

Wann welcher Mechanismus eingesetzt werden sollte:

Skills vs. Hooks vs. Subagents

FAQ

Wie viele hooks sind zu viele?

Nicht die Anzahl, sondern die Performance ist die Einschränkung. Jeder hook läuft synchron, daher addiert sich die gesamte Hook-Ausführungszeit zu jedem passenden Tool-Aufruf. 95 hooks über Benutzer- und Projektebene hinweg laufen ohne spürbare Latenz, wenn jeder hook in unter 200 ms abgeschlossen wird. Der Schwellenwert, den Sie beobachten sollten: Wenn ein PostToolUse hook mehr als 500 ms zu jeder Dateibearbeitung hinzufügt, fühlt sich die Sitzung träge an. Profilieren Sie Ihre hooks mit time, bevor Sie sie einsetzen.¹⁴

Können hooks Claude Code daran hindern, einen Befehl auszuführen?

Ja. PreToolUse hooks blockieren jede Tool-Aktion durch Beenden mit Exit-Code 2. Claude Code bricht die ausstehende Aktion ab und zeigt dem Modell die stderr-Ausgabe des hooks. Claude erkennt den Ablehnungsgrund und schlägt eine sicherere Alternative vor. Exit 1 ist eine nicht blockierende Warnung, bei der die Aktion trotzdem ausgeführt wird.³

Wo sollte ich Hook-Konfigurationsdateien ablegen?

Hook-Konfigurationen gehören in .claude/settings.json für Hooks auf Projektebene (in Ihr Repository eingecheckt, mit Ihrem Team geteilt) oder ~/.claude/settings.json für Hooks auf Benutzerebene (persönlich, auf jedes Projekt angewendet). Hooks auf Projektebene haben Vorrang, wenn beide existieren. Verwenden Sie absolute Pfade für Skriptdateien, um Probleme mit dem Arbeitsverzeichnis zu vermeiden.¹⁴

Braucht jede Entscheidung eine Deliberation?

Nein. Das Konfidenzmodul bewertet Entscheidungen anhand von vier Dimensionen (Mehrdeutigkeit, Komplexität, Tragweite, Kontextabhängigkeit). Nur Entscheidungen, die unter 0,70 Gesamtkonfidenz liegen, lösen eine Deliberation aus — das betrifft ungefähr 10 % aller Entscheidungen. Dokumentationskorrekturen, Variablenumbenennungen und Routinebearbeitungen überspringen die Deliberation vollständig. Sicherheitsarchitektur, Datenbankschemaänderungen und irreversible Deployments lösen sie dagegen zuverlässig aus.⁷

Wie testet man ein System, das auf produktiven Dissens ausgelegt ist?

Testen Sie sowohl Erfolgspfade als auch Fehlerpfade. Erfolg: Agenten sind produktiv unterschiedlicher Meinung und erreichen Konsens. Fehler: Agenten konvergieren zu schnell, konvergieren nie oder überschreiten Spawn-Budgets. End-to-End-Tests simulieren jedes Szenario mit deterministischen Agentenantworten und verifizieren, dass beide Validierungs-Gates jeden dokumentierten Fehlermodus erkennen. Ein produktives Deliberationssystem umfasst 141 Tests über drei Schichten: 48 Bash-Integrationstests, 81 Python-Unit-Tests und 12 End-to-End-Pipeline-Simulationen.⁷

Welche Latenzauswirkung hat die Deliberation?

Eine 3-Agenten-Deliberation fügt 30–60 Sekunden Echtzeit hinzu (Agenten laufen sequenziell über das Agent tool). Eine 10-Agenten-Deliberation fügt 2–4 Minuten hinzu. Die Konsens- und Pride-Check-hooks laufen jeweils in unter 200 ms. Der primäre Engpass ist die LLM-Inferenzzeit pro Agent, nicht der Orchestrierungsoverhead.⁷

Wie lang sollte eine CLAUDE.md-Datei sein?

Halten Sie jeden Abschnitt unter 50 Zeilen und die gesamte Datei unter 150 Zeilen. Lange Dateien werden durch Kontextfenster abgeschnitten, daher sollten die wichtigsten Anweisungen am Anfang stehen: Befehle und Closure-Definitionen vor Stilpräferenzen.²¹

Funktioniert das auch mit anderen Tools als Claude Code?

Die Architekturprinzipien (hooks als deterministische Gates, Skills als Domänenexpertise, Subagents als isolierte Kontexte, Dateisystem als Gedächtnis) lassen sich konzeptionell auf jedes agentische System übertragen. Die konkrete Implementierung nutzt die Lifecycle-Events, Matcher-Patterns und das Agent tool von Claude Code. AGENTS.md überträgt dieselben Muster auf Codex, Cursor, Copilot, Amp und Windsurf.²¹ Das harness-Muster ist toolunabhängig, auch wenn die Implementierungsdetails toolspezifisch sind.

Kurzreferenzkarte

Hook-Konfiguration

{
  "hooks": {
    "PreToolUse": [{"matcher": "Bash", "hooks": [{"type": "command", "command": "script.sh"}]}],
    "PostToolUse": [{"matcher": "Write|Edit", "hooks": [{"type": "command", "command": "format.sh"}]}],
    "Stop": [{"matcher": "", "hooks": [{"type": "agent", "prompt": "Verify tests pass. $ARGUMENTS"}]}],
    "SessionStart": [{"matcher": "", "hooks": [{"type": "command", "command": "setup.sh"}]}]
  }
}

Skill-Frontmatter

---
name: my-skill
description: What it does and when to use it. Include trigger phrases.
allowed-tools: Read, Grep, Glob
---

Subagent-Definition

---
name: my-agent
description: When to invoke. Include PROACTIVELY for auto-delegation.
tools: Read, Grep, Glob, Bash
model: opus
permissionMode: plan
---

Instructions for the subagent.

Exit-Codes

Wichtige Befehle

Dateispeicherorte

Änderungsprotokoll

Referenzen