Agent Harness Architektur 2026: Diagramm-Referenz

TL;DR: Claude Code ist keine Chatbox mit Dateizugriff. Es ist eine programmierbare Laufzeitumgebung mit 22 Lifecycle-Events, die jeweils über Shell-Skripte hookbar sind, welche das Modell nicht überspringen kann. Schichten Sie hooks zu Dispatchern, Dispatcher zu skills, skills zu Agenten und Agenten zu Workflows – so entsteht ein autonomes Entwicklungs-harness, das Einschränkungen durchsetzt, Arbeit delegiert, Speicher über Sitzungen hinweg persistiert und Multi-Agenten-Deliberation orchestriert. Dieser Leitfaden behandelt jede Schicht dieses Stacks: von einem einzelnen hook bis hin 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: Klauen. 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 geben einen Prompt ein, beobachten die Dateibearbeitung und machen weiter. Dieses Verständnis begrenzt die Produktivität auf das, was Sie persönlich beaufsichtigen können.

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

Der Unterschied ist entscheidend, weil Infrastruktur kumuliert. Ein hook, der Zugangsdaten in Bash-Befehlen blockiert, schützt jede Sitzung, jeden Agenten, jeden autonomen Lauf. Ein skill, der Ihr Bewertungsschema kodiert, wird konsistent angewendet – unabhängig davon, ob Sie oder ein Agent ihn aufrufen. Ein Agent, der Code auf Sicherheit prüft, führt dieselben Checks durch, ob Sie zusehen oder nicht.²

Wichtigste Erkenntnisse

• Hooks garantieren Ausführung; Prompts nicht. Verwenden Sie hooks für Linting, Formatierung, Sicherheitsprüfungen und alles, was unabhängig vom Modellverhalten jedes Mal 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.⁵
• Speicher lebt im Dateisystem. Dateien persistieren über Kontextfenster hinweg. CLAUDE.md, MEMORY.md, Rules-Verzeichnisse und Übergabedokumente bilden ein strukturiertes externes Speichersystem.⁶
• 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-Muster ist das System. CLAUDE.md, hooks, skills, Agenten und Speicher sind keine voneinander unabhängigen Funktionen. Sie fügen sich zu einer deterministischen Schicht zwischen Ihnen und dem Modell zusammen, die mit der Automatisierung skaliert.

Verwendung dieses Leitfadens

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

Der Fünf-Minuten-Goldpfad

Vor dem tiefen Einstieg hier der kürzeste Weg von null zu einem funktionierenden Harness. Ein Hook, ein Skill, ein Subagent, ein Ergebnis.

Schritt 1: Einen Security-Hook erstellen (2 Minuten)

Erstellen Sie .claude/hooks/block-secrets.sh:

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if echo "$CMD" | grep -qEi '(AKIA|sk-|ghp_|password=)'; then
    echo "BLOCKED: Potential secret in command" >&2
    exit 2
fi

Verdrahten Sie ihn in .claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": ".claude/hooks/block-secrets.sh" }]
      }
    ]
  }
}

Ergebnis: Jeder Bash-Befehl, den Claude ausführt, wird nun auf durchgesickerte Anmeldeinformationen geprüft. Das Modell kann diese Prüfung nicht umgehen.

Schritt 2: Einen Code-Review-Skill erstellen (1 Minute)

Erstellen Sie .claude/skills/reviewer/SKILL.md mit Frontmatter (name: reviewer, description: Review code for security issues, bugs, and quality problems. Use when examining changes, reviewing PRs, or auditing code., allowed-tools: Read, Grep, Glob) und einer Checkliste: SQL-Injection, XSS, fest codierte Secrets, fehlende Fehlerbehandlung, Funktionen mit mehr als 50 Zeilen.

Ergebnis: Claude aktiviert diese Expertise automatisch, sobald Sie Review, Check oder Audit erwähnen.

Schritt 3: Einen Subagenten starten (30 Sekunden)

Bitten Sie Claude in einer beliebigen Claude Code-Sitzung, die letzten drei Commits mithilfe eines separaten Agenten auf Sicherheitsprobleme zu überprüfen. Claude startet einen Explore-Agenten, der das Diff liest, Ihren Review-Skill anwendet und eine Zusammenfassung zurückgibt. Ihr Hauptkontext bleibt sauber.

Was Sie jetzt haben

Ein dreischichtiges Harness: ein deterministisches Security-Gate (Hook), Domänenexpertise, die sich automatisch aktiviert (Skill), und isolierte Analyse, die Ihren Kontext schützt (Subagent). Jeder folgende Abschnitt vertieft eine dieser drei Schichten.

Warum Agentenarchitektur wichtig ist

Simon Willison bringt den aktuellen Moment auf eine einzige Beobachtung: Code zu schreiben ist jetzt billig.⁸ Stimmt. Die Folge ist jedoch, dass die Verifikation nun den teuren Teil ausmacht. Billiger Code ohne Verifikationsinfrastruktur produziert Bugs in großem Maßstab. Die Investition, die sich auszahlt, ist nicht ein besserer Prompt. Es ist das System um das Modell herum, das einfängt, was das Modell übersieht.

Drei Kräfte machen Agentenarchitektur notwendig:

Kontextfenster sind endlich und verlustbehaftet. Jeder Dateilesezugriff, jede Tool-Ausgabe und jede Gesprächsrunde verbraucht Tokens. Microsoft Research und Salesforce haben 15 LLMs in über 200.000 simulierten Konversationen getestet und fanden einen durchschnittlichen Leistungsabfall von 39 % vom Einzelturn zur Mehrfachturn-Interaktion.⁹ Die Verschlechterung beginnt bereits nach zwei Runden und folgt einer vorhersagbaren Kurve: Präzise Multi-Datei-Bearbeitungen in den ersten 30 Minuten verkommen bis zur 90. Minute zu Tunnelblick auf eine einzelne Datei. Längere Kontextfenster beheben das nicht. Die Bedingung „Concat” derselben Studie (vollständige Konversation als einzelner Prompt) erreichte 95,1 % der Einzelturn-Leistung bei identischem Inhalt. Die Verschlechterung stammt von den Turn-Grenzen, nicht von Token-Limits.

Modellverhalten ist probabilistisch, nicht deterministisch. Claude anzuweisen „Führe Prettier nach jedem Dateibearbeiten aus” funktioniert in etwa 80 % der Fälle.³ Das Modell könnte es vergessen, Geschwindigkeit priorisieren oder entscheiden, dass die Änderung „zu klein” ist. Für Compliance, Sicherheit und Team-Standards sind 80 % nicht akzeptabel. Hooks garantieren die Ausführung: jedes Edit oder Write löst Ihren Formatter aus, jedes Mal, ohne Ausnahmen. Deterministisch schlägt probabilistisch.

Einzelperspektiven übersehen mehrdimensionale Probleme. Ein einzelner Agent, der einen API-Endpoint überprüfte, kontrollierte Authentifizierung, validierte die Eingabesanitierung und verifizierte CORS-Header. Sauberer Gesundheitsbefund. Ein zweiter Agent, separat als Penetration Tester instruiert, entdeckte, dass der Endpoint unbegrenzte Query-Parameter akzeptierte, die einen Denial-of-Service durch Datenbankabfrage-Amplifikation auslösen konnten.⁷ Der erste Agent hatte nie geprüft, weil nichts in seinem Bewertungsrahmen Query-Komplexität als Sicherheitsfläche behandelte. Diese Lücke ist strukturell. Keine Menge an Prompt-Engineering behebt das.

Agentenarchitektur adressiert alle drei Punkte: Hooks erzwingen deterministische Einschränkungen, Subagenten verwalten die Kontextisolation, und Multi-Agent-Orchestrierung liefert unabhängige Perspektiven. Zusammen bilden sie das Harness.

Das Harness-Muster

Das Harness ist kein Framework. Es ist ein Muster: eine kombinierbare Sammlung aus Dateien, Skripten und Konventionen, die 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 architektonische Langzeitgedächtnis des Agenten.

Extension Layer: Skills liefern Fachwissen, das kontextbasiert automatisch aktiviert wird. Hooks bieten deterministische Gates, die bei jedem passenden Tool-Aufruf auslösen. Memory-Dateien erhalten Zustände über Sitzungen hinweg. Custom Agents stellen spezialisierte Subagent-Konfigurationen bereit.

Orchestration Layer: Multi-Agent-Muster koordinieren unabhängige Agenten für Recherche, Review und Deliberation. Spawn-Budgets verhindern außer Kontrolle geratene Rekursionen. Consensus-Validation sichert die Qualität.

Die zentrale Erkenntnis: Die meisten Benutzer arbeiten ausschließlich im Core Layer und beobachten, wie Kontext und Kosten in die Höhe schnellen. Power-User konfigurieren die Instruction- und Extension-Layer und nutzen den Core Layer nur noch für Orchestrierung und finale Entscheidungen.²

Managed- vs. Self-Hosted-Harnesses (April 2026)

Während des gesamten ersten Quartals 2026 war der Weg „eigenes Harness bauen” die einzige realistische Option. Im April 2026 hat sich das geändert. Anthropic veröffentlichte Claude Managed Agents in der öffentlichen Beta (8. April): Harness-Loop + Tool-Ausführung + Sandbox-Container + State-Persistenz als REST API, abgerechnet zu Standard-Token-Preisen plus 0,08 $/Sitzungsstunde. Das Agents SDK-Update von OpenAI (16. April) formalisierte dieselbe Trennung — Harness und Compute als separate Schichten, mit nativen Sandbox-Anbietern (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) sowie Snapshot/Rehydrate zum Überleben von Container-Verlusten.²³²⁴

Die architektonische Weggabelung ist jetzt real:

Wann wählen Sie was: Self-Hosted bleibt die richtige Wahl für Teams, die bereits Infrastruktur-Know-how mitbringen, die Skills/Hooks unter eigener Kontrolle wollen oder die einen spezifischen Workflow tiefgreifend optimieren. Managed ist richtig für Teams ohne dedizierte Platform-Engineers, wenn Time-to-Value wichtiger ist als Anpassbarkeit, oder wenn Agent-Läufe zuverlässig das Zuklappen des Laptops überstehen müssen, ohne dass Sie diese Persistenzschicht selbst bauen. Die beiden Ansätze sind kompatibel — Sie können ein Self-Hosted-Harness betreiben, das spezifische langlaufende Aufgaben über die REST API an Managed Agents delegiert.

Wie das 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 das vollständige Harness.

Skills-System

Skills sind modellinvozierte Erweiterungen. Claude entdeckt und wendet sie automatisch basierend auf dem Kontext an, ohne dass Sie sie explizit aufrufen.⁴ In dem Moment, in dem Sie sich dabei ertappen, denselben Kontext sitzungsübergreifend erneut zu erklären, sollten Sie ein Skill bauen.

Wann Sie ein Skill bauen sollten

Skills sind für Wissen, das Claude immer 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?”

Ein Skill erstellen

Skills leben an vier möglichen Orten, vom breitesten bis zum engsten Geltungsbereich:⁴

Jedes Skill benötigt 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
Bei der Code-Überprüfung ist zu verifizieren:

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

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

Frontmatter-Referenz

Das Description-Feld ist alles

Beim Start der Sitzung extrahiert Claude Code name und description jedes Skills und injiziert sie in den Kontext von Claude. 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 injiziert, und das Modell verwendet standardmäßiges Sprachverständnis, um relevante Skills auszuwählen.¹⁰

Schlechte Beschreibung:

description: Helps with code

Wirksame 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 wirksame Beschreibung enthält: was sie tut (Code auf bestimmte Problemtypen überprüfen), wann sie zu verwenden ist (bei Prüfung von Änderungen, PRs, Qualitätsanalyse) und Auslöser-Phrasen (review, audit, check), die Benutzer natürlicherweise eingeben.

Kontextbudget

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

Unterstützende Dateien und Organisation

Skills können auf zusätzliche Dateien im selben Verzeichnis 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, wenn der Skill aktiviert wird. Halten Sie SKILL.md unter 500 Zeilen und verlagern Sie detailliertes Referenzmaterial in unterstützende Dateien.¹²

Skills über Git teilen

Projekt-Skills (.claude/skills/ im Repository-Root) 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 die effektivste Methode, um Fachwissen teamweit zu standardisieren.

Skills als Prompt-Bibliothek

Über Single-Purpose-Skills hinaus funktioniert die Verzeichnisstruktur 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 basierend auf dem Kontext automatisch schöpft. Ein Junior-Entwickler erhält Senior-Level-Anleitung, ohne danach fragen zu müssen.

Skills lassen sich mit Hooks kombinieren

Skills können eigene Hooks im Frontmatter definieren, die nur während der Ausführung des Skills aktiv werden. Dies erzeugt domänenspezifisches Verhalten, das andere Sitzungen nicht belastet:²

---
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 injizieren Qualitätsvorgaben in jede Sitzung ohne explizite Aufrufung. Der Skill selbst ist Wissen. Der Hook ist Durchsetzung. Zusammen bilden sie eine Richtlinienebene.

Häufige Fehler bei Skills

Zu weit gefasste 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 ist entweder eine präzisere Beschreibung oder das Hinzufügen von disable-model-invocation: true und die Anforderung einer expliziten /skill-name-Aufrufung.⁴

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

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

Hook-Architektur

Hooks sind Shell-Befehle, die durch Lebenszyklus-Ereignisse von Claude Code 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 überhaupt sieht. Der Hook feuert, ob das Modell es will oder nicht.

Verfügbare Ereignisse

Claude Code stellt über 26 Lebenszyklus-Ereignisse in sieben Kategorien bereit (die Ereignisliste wächst mit jedem Release — die aktuelle vollständige Tabelle finden Sie im Cheat Sheet):¹³

Semantik der Exit-Codes

Exit-Codes entscheiden darüber, ob Hooks Aktionen blockieren:³

Kritisch: Jeder Security-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 liegen in Einstellungsdateien. Auf Projektebene (.claude/settings.json) für gemeinsam genutzte Hooks. Auf 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 Feld matcher ist eine Regex, die Tool-Namen abgleicht: Bash, Write, Edit, Read, Glob, Grep, Agent oder * für alle Tools. Verwenden Sie "" (leerer String) für Ereignisse ohne Tools wie UserPromptSubmit.

Hook-Ein-/Ausgabe-Protokoll

Hooks erhalten 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 Kontrolle können PreToolUse-Hooks JSON ausgeben, um Tool-Eingaben zu verändern, Kontext einzuspeisen oder Berechtigungsentscheidungen zu treffen. Verwenden Sie den hookSpecificOutput-Wrapper — das ältere Top-Level-Format decision/reason ist für PreToolUse veraltet:

{
  "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 benötige ich?¹⁴

Formatierungs-Garantien 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, weil 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'"
          }
        ]
      }
    ]
  }
}

Sicherheits-Garantien verhindern gefährliche Aktionen, bevor sie ausgeführt werden. PreToolUse-Hooks auf Bash prüfen 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äts-Garantien 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 vier 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 } zurück, um zu erlauben, oder { "ok": false, "reason": "..." }, um zu blockieren. Verwenden Sie dies für differenzierte Bewertungen, die sich nicht in Regex ausdrücken lassen.

Agent-Hooks (type: "agent") starten einen Subagenten mit Tool-Zugriff (Read, Grep, Glob) für mehrstufige Verifikation. Verwenden Sie dies, wenn die Prüfung die 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
          }
        ]
      }
    ]
  }
}

HTTP-Hooks (type: "http") senden die Ereignis-Eingabe JSON als POST-Request an eine URL und empfangen JSON zurück. Verwenden Sie dies für Webhooks, externe Benachrichtigungsdienste oder API-basierte Validierung (v2.1.63+). Nicht unterstützt für SessionStart-Ereignisse:

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "https://your-webhook.example.com/hook",
            "headers": { "Authorization": "Bearer $WEBHOOK_TOKEN" },
            "allowedEnvVars": ["WEBHOOK_TOKEN"],
            "timeout": 10
          }
        ]
      }
    ]
  }
}

Asynchrone Hooks

Hooks können im Hintergrund laufen, ohne die Ausführung zu blockieren. Fügen Sie async: true für nicht kritische 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. Niemals für Formatierung, Validierung oder irgendetwas, das vor der nächsten Aktion abgeschlossen sein muss.

Dispatcher statt unabhängiger Hooks

Sieben Hooks, die alle auf dasselbe Ereignis reagieren und jeweils unabhängig stdin lesen, erzeugen Race Conditions. Zwei Hooks, die gleichzeitig in dieselbe JSON-Zustandsdatei schreiben, werden die JSON abschneiden. Jeder nachgelagerte Hook, der diese Datei parst, bricht.²

Die Lösung: ein Dispatcher pro Ereignis, der Hooks sequenziell aus zwischengespeichertem 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 zum Debuggen von Hooks, die stillschweigend fehlschlagen:¹⁴

1. Skripte unabhängig testen. Leiten Sie beispielhaftes JSON durch: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Stderr für Debug-Ausgaben verwenden. Stderr bei Exit-Code 2 wird als Fehlermeldung an Claude zurückgegeben. Nicht blockierendes Stderr (Exit 1, 3 usw.) erscheint nur im Verbose-Modus (Ctrl+O).
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 verifizieren. Ein PreToolUse-Hook, der exit 1 verwendet, bietet keinerlei Durchsetzung, obwohl er zu funktionieren scheint.
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 Turns, um Platz für neue Inhalte zu schaffen. Die Komprimierung ist verlustbehaftet. Architekturentscheidungen, die in Turn 3 dokumentiert wurden, überleben möglicherweise nicht bis Turn 15.⁹

Die drei Mechanismen des Multi-Turn-Kollapses

Die MSR/Salesforce-Studie identifizierte drei unabhängige Mechanismen, die jeweils eine andere Intervention erfordern:⁹

Strategie 1: Das Dateisystem als Speicher

Der zuverlässigste Speicher über Kontextgrenzen hinweg lebt im Dateisystem. Claude Code liest CLAUDE.md und Memory-Dateien 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 MEMORY.md-Datei erfasst Fehler, Entscheidungen und Muster über Sitzungen hinweg. Wenn Sie entdecken, dass ((VAR++)) mit set -e in Bash fehlschlägt, wenn VAR 0 ist, halten Sie das fest. Drei Sitzungen später, wenn Sie in Python auf einen ähnlichen Integer-Randfall stoßen, bringt der MEMORY.md-Eintrag das Muster wieder an die Oberfläche.¹⁵

Auto Memory (v2.1.32+): Claude Code erfasst und ruft Projektkontext automatisch 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 es prägnant und verlinken Sie für detaillierte Notizen auf separate Themendateien.⁶

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 Task-State erhalten bleiben.¹⁵

Wann komprimieren: - Nach Abschluss einer abgegrenzten Teilaufgabe (Feature implementiert, Bug behoben) - Bevor Sie einen neuen Bereich der Codebasis in Angriff nehmen - Wenn Claude beginnt, sich zu wiederholen oder früheren Kontext zu vergessen - Etwa 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: Session Handoffs

Erstellen Sie für Aufgaben, die sich über mehrere Sitzungen erstrecken, Handoff-Dokumente, 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 Status/Files/Decision/Blocked/Next liefert der Nachfolgesitzung den vollständigen Kontext bei minimalen Token-Kosten. Starten Sie eine neue Sitzung mit claude -c (continue) oder lesen Sie das Handoff-Dokument, und Sie gehen direkt zur Implementierung über.¹⁵

Strategie 4: Fresh-Context-Iteration (Der Ralph Loop)

Bei Sitzungen, die 60–90 Minuten überschreiten, starten Sie pro Iteration eine frische Claude-Instanz. Zustand bleibt über das Dateisystem bestehen, nicht über das konversationelle Gedächtnis. 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

Vergleichen Sie dies mit einer einzelnen langen 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 Orient-Schritt (Lesen der State-Dateien, Durchsuchen der Git-Historie) 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 Fresh-Context trotz des Overheads qualitativ hochwertigere Ergebnisse.

Die Anti-Patterns

Ganze Dateien lesen, wenn Sie nur 10 Zeilen brauchen. Ein einzelnes Einlesen einer 2.000-zeiligen Datei verbraucht 15.000–20.000 Tokens. Verwenden Sie Zeilen-Offsets: Read file.py offset=100 limit=20 spart den größten Teil dieser Kosten.¹⁵

Ausführliche Fehlerausgaben im Kontext belassen. Nach dem Debugging eines Bugs enthält Ihr Kontext mehr als 40 Stack Traces aus fehlgeschlagenen Iterationen. Ein einziges /compact nach der Behebung des Bugs befreit diesen Ballast.

Jede Sitzung damit beginnen, jede Datei zu lesen. Lassen Sie die Glob- und Grep-Tools von Claude Code relevante Dateien bei Bedarf finden — das spart mehr als 100.000 Tokens an unnötigem Vorab-Laden.¹⁵

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 geben Ergebnisse als Zusammenfassungen zurück. Die Ergebnisse der Exploration blähen Ihre Hauptkonversation nicht auf; nur die Schlussfolgerungen kehren zurück.⁵

Integrierte Subagent-Typen

Benutzerdefinierte 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.

Subagent-Konfigurationsfelder

Worktree-Isolation

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

---
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 unerlässlich 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 unabhängige Recherche-Aufgaben:

> 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 Rekursions-Schutz

Ohne Spawn-Limits delegieren Agents an Agents, die wiederum an Agents delegieren, wobei jeder einzelne Kontext verliert und Tokens verbrennt. Das Rekursions-Schutz-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 Lektion: Verwenden Sie Spawn-Budgets, nicht nur Tiefenlimits. Tiefenbasierte Limits verfolgen Eltern-Kind-Ketten (blockiert bei Tiefe 3), übersehen aber die Breite: 23 Agents auf Tiefe 1 sind immer noch „Tiefe 1”. Ein Spawn-Budget verfolgt die Gesamtzahl aktiver Kinder pro Elternteil, begrenzt auf ein konfigurierbares Maximum. Das Budget-Modell bildet den tatsächlichen Fehlermodus (zu viele Agents insgesamt) ab und nicht eine Ersatzmetrik (zu viele Verschachtelungsebenen).⁷

Agent Teams (Research Preview)

Agent Teams koordinieren mehrere Claude Code-Instanzen, die unabhängig voneinander arbeiten, über eine gemeinsame Mailbox und 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 infrage stellen.⁷ Multi-Agent-Deliberation erzwingt eine unabhängige Bewertung aus mehreren Perspektiven, bevor eine Entscheidung endgültig getroffen wird.

Tool-übergreifende Orchestrierung (April 2026): Google hat am 7. April Scion als Open Source veröffentlicht — einen Multi-Agent-Hypervisor, der Claude Code, Gemini CLI und andere „Deep Agents” als nebenläufige Prozesse betreibt, jeweils mit isoliertem Container, git worktree und eigenen Credentials. Lauffähig lokal, im Hub oder auf Kubernetes. Die explizite Philosophie lautet: „Isolation statt Einschränkungen” — Agenten arbeiten mit hoher Autonomie innerhalb von Grenzen, die auf der Infrastrukturebene durchgesetzt werden, nicht im Prompt.²⁵ Damit wird das Argument der Subagent-Isolation direkt auf unterschiedliche Tool-Anbieter ausgeweitet. Wenn Ihr Workflow Claude und OpenAI-Modelle umfasst, ist Scion die erste echte Referenzimplementierung für tool-übergreifende Subagenten mit pro-Agent worktree- und Credential-Isolation.

Debatten sind kein Allheilmittel: Der Forschungscluster M3MAD-Bench (Anfang 2026) hat festgestellt, dass Multi-Agent-Debatten ein Plateau erreichen und durch irreführenden Konsens unterwandert werden können — valide Argumente verlieren, wenn andere Agenten selbstbewusst die falsche Antwort behaupten.²⁶ Tool-MAD verbessert dies, indem jeder Agent heterogenen Tool-Zugriff erhält und in der Judge-Phase Faithfulness/Relevance-Scores verwendet werden. Wenn Sie eine debattenbasierte Orchestrierung aufbauen, investieren Sie in (a) Tool-Heterogenität pro Agent und (b) quantitative Judge-Bewertung, anstatt anzunehmen, dass mehr Agenten = bessere Antworten bedeuten.

Minimum Viable Deliberation

Beginnen Sie mit 2 Agenten und 1 Regel: Agenten müssen unabhängig bewerten, bevor sie die Arbeit 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 noch inkrementelle Verbesserungen.

Der Confidence-Trigger

Nicht jede Aufgabe braucht Deliberation. Ein Confidence-Scoring-Modul bewertet vier Dimensionen:¹⁷

1. Mehrdeutigkeit – Hat die Anfrage mehrere valide Interpretationen?
2. Domänenkomplexität – Erfordert sie Spezialwissen?
3. Tragweite – Ist die Entscheidung umkehrbar?
4. Kontextabhängigkeit – Erfordert sie ein Verständnis des umfassenderen Systems?

Der Score wird auf drei Stufen abgebildet:

Die Schwelle passt sich nach Aufgabentyp an. Sicherheitsentscheidungen erfordern einen Konsens von 0,85. Dokumentationsänderungen benötigen lediglich 0,50. Damit wird verhindert, dass einfache Aufgaben überentwickelt werden, während riskante Entscheidungen sorgfältig geprüft werden.⁷

Die State Machine

Sieben Phasen, jede durch die vorhergehende abgesichert:⁷

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

RESEARCH: Unabhängige Agenten untersuchen das Thema. Jeder Agent erhält eine andere Persona (Technical Architect, Security Analyst, Performance Engineer und weitere). Die Kontextisolation stellt sicher, dass die Agenten die Erkenntnisse der anderen während der Recherche nicht einsehen können.

DELIBERATION: Die Agenten sehen alle Forschungsergebnisse 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 Architektur mit zwei Validierungs-Gates

Zwei Validierungs-Gates erfassen Probleme in unterschiedlichen Phasen:⁷

Gate 1: Konsens-Validierung (PostToolUse hook). Läuft unmittelbar nach Abschluss jedes Deliberation-Agents: 1. Die Phase muss mindestens RANKING erreicht haben 2. Mindestens 2 Agenten abgeschlossen (konfigurierbar) 3. Der Konsens-Score erreicht die aufgabenadaptive Schwelle 4. Wenn ein Agent abgewichen ist, müssen die Bedenken dokumentiert sein

Gate 2: Pride Check (Stop hook). Läuft, bevor die Sitzung geschlossen werden kann: 1. Diverse Methoden: mehrere einzigartige Personas vertreten 2. Transparenz bei Widersprüchen: Abweichungen sind mit dokumentierten Gründen versehen 3. Komplexitätsbewältigung: mindestens 2 Alternativen generiert 4. Konsens-Vertrauen: klassifiziert als stark (über 0,85) oder moderat (0,70–0,84) 5. Verbesserungsnachweis: das endgültige Vertrauen übersteigt das anfängliche Vertrauen

Zwei Hooks an unterschiedlichen Lifecycle-Punkten entsprechen dem tatsächlichen Auftreten von Fehlern: Manche sind sofort sichtbar (schlechter Score), andere entstehen schleichend (geringe Diversität, fehlende Dokumentation von Abweichungen).⁷

Warum Einigkeit gefährlich ist

Charlan Nemeth hat Minderheiten-Dissens von 1986 bis zu ihrem 2018 erschienenen Buch In Defense of Troublemakers untersucht. Gruppen mit Andersdenkenden treffen bessere Entscheidungen als Gruppen, die schnell zu einer Einigung gelangen. Der Andersdenkende muss dabei nicht recht haben. Bereits der Akt der Meinungsverschiedenheit zwingt die Mehrheit, Annahmen zu prüfen, die sie sonst übergehen würde.¹⁸

Wu et al. haben getestet, ob LLM-Agenten wirklich debattieren können, und festgestellt, dass Agenten ohne strukturelle Anreize zur Meinungsverschiedenheit unabhängig von der Korrektheit zu der am selbstbewusstesten klingenden ersten Antwort konvergieren.¹⁹ Liang et al. haben die Grundursache als „Degeneration-of-Thought” identifiziert: Sobald ein LLM Vertrauen in eine Position aufgebaut hat, kann Selbstreflexion keine neuartigen Gegenargumente mehr hervorbringen, weshalb eine Multi-Agent-Bewertung strukturell notwendig wird.²⁰

Unabhängigkeit ist die entscheidende Designanforderung. Zwei Agenten, die dieselbe Deployment-Strategie mit Einsicht in die Erkenntnisse des jeweils anderen bewerteten, ergaben Scores von 0,45 und 0,48. Dieselben Agenten ohne Einsicht: 0,45 und 0,72. Die Differenz zwischen 0,48 und 0,72 ist der Preis des Herding-Effekts.⁷

Vorgetäuschte Einigkeit erkennen

Ein Modul zur Konformitätserkennung verfolgt Muster, die darauf hindeuten, dass Agenten ohne tatsächliche Bewertung zustimmen:⁷

Score-Clustering: Wenn jeder Agent auf einer 10-Punkte-Skala innerhalb von 0,3 Punkten liegt, deutet das auf eine Kontamination des geteilten Kontexts hin und nicht auf eine unabhängige Bewertung. Als fünf Agenten ein Authentication-Refactor bewerteten und das Sicherheitsrisiko alle zwischen 7,1 und 7,4 einstuften, ergab eine Wiederholung mit frischer Kontextisolation eine Spreizung der Werte auf 5,8–8,9.

Boilerplate-Dissens: Agenten kopieren die Bedenken-Formulierungen der anderen, anstatt eigenständige Einwände zu generieren.

Fehlende Minderheitsperspektiven: Einstimmige Zustimmung von Personas mit gegensätzlichen Prioritäten (ein Security Analyst und ein Performance Engineer sind sich selten in allem einig).

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

Was bei der Deliberation nicht funktioniert hat

Freiform-Debattenrunden. Drei Runden hin und her in Textform für eine Diskussion über Datenbank-Indexierung erzeugten 7.500 Tokens an Debatte. Runde 1: echte Meinungsverschiedenheit. Runde 2: erneut formulierte Positionen. Runde 3: identische Argumente in anderen Worten. Strukturiertes Dimensionen-Scoring ersetzte die Freiform-Debatte und senkte die Kosten um 60 %, während die Ranking-Qualität verbessert wurde.⁷

Einzelnes Validierungs-Gate. Die erste Implementierung ließ einen Validierungs-Hook am Sitzungsende laufen. Ein Agent schloss die Deliberation mit einem Konsens-Score von 0,52 (unterhalb der Schwelle) ab und arbeitete dann 20 Minuten lang an unverwandten Aufgaben weiter, bevor der Session-End-Hook den Fehler markierte. Die Aufteilung in zwei Gates (eines bei Aufgabenabschluss, eines am Sitzungsende) erfasste dieselben Probleme an unterschiedlichen Lifecycle-Punkten.⁷

Kosten der Deliberation

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

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

Wann zu deliberieren ist

CLAUDE.md-Design

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

Die Präzedenzhierarchie

Regeldateien werden automatisch geladen und liefern strukturierten Kontext, ohne CLAUDE.md zu überfrachten.⁶

Was ignoriert wird

Diese Muster führen zuverlässig zu keiner beobachtbaren Änderung im Verhalten des Agenten:²¹

Prosaabsätze ohne Befehle. „Wir legen Wert auf sauberen, gut getesteten Code” ist Dokumentation, keine Anweisung. Der Agent liest das und schreibt dennoch Code ohne Tests, weil keine umsetzbare Instruktion vorhanden ist.

Mehrdeutige Direktiven. „Seien Sie vorsichtig mit Datenbankmigrationen” ist keine Einschränkung. „Führen Sie alembic check aus, bevor Sie Migrationen anwenden. Abbrechen, wenn der Downgrade-Pfad fehlt.” hingegen schon.

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

Styleguides ohne Durchsetzung. „Befolgen Sie den Google Python Style Guide” 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
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

Aufgabenorganisierte Abschnitte:

## When Writing Code
- Run `ruff check .` after every file change
- Add type hints to all new functions

## When Reviewing Code
- Check for security issues: `bandit -r app/`
- Verify test coverage: `pytest --cov=app --cov-fail-under=80`

## When Releasing
- Update version in `pyproject.toml`
- Run full suite: `pytest -v && ruff check . && mypy app/`

Eskalationsregeln:

## When Blocked
- If tests fail after 3 attempts: stop and report the failing test with full output
- If a dependency is missing: check `requirements.txt` first, then ask
- Never: delete files to resolve errors, force push, or skip tests

Schreibreihenfolge

Beginnen Sie von Grund auf, fügen Sie Abschnitte in dieser Prioritätsreihenfolge hinzu:²¹

1. Build- und Test-Befehle (der Agent benötigt diese, bevor er etwas Sinnvolles tun kann)
2. Definition of Done (verhindert falsche Abschlussmeldungen)
3. Eskalationsregeln (verhindert destruktive Workarounds)
4. Aufgabenorganisierte Abschnitte (reduziert die Verarbeitung irrelevanter Anweisungen)
5. Verzeichnis-Scoping (Monorepos: hält Service-Anweisungen isoliert)

Überspringen Sie Stilpräferenzen, bis die ersten vier funktionieren.

Datei-Imports

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.⁶

Werkzeugübergreifende Anweisungskompatibilität

AGENTS.md ist ein offener Standard, der von jedem großen KI-Coding-Tool anerkannt wird.²¹ Wenn 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 (befehlsorientiert, abschlussdefiniert, aufgabenorganisiert) funktionieren in jeder Anweisungsdatei, unabhängig vom Tool. Pflegen Sie keine parallelen Anweisungssätze, die auseinanderdriften. Schreiben Sie eine autoritative Quelle und spiegeln Sie sie.

Ihre Anweisungen testen

Ü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 wortgetreu wiedergeben, sind die Anweisungen entweder zu ausführlich (Inhalt aus dem Kontext gedrängt), zu vage (Agent kann keine umsetzbaren Anweisungen extrahieren) oder werden nicht entdeckt. Die Analyse von 2.500 Repositories durch GitHub ergab, dass Vagheit die meisten Fehler verursacht.²¹

Produktionsmuster

Opus 4.7 Langzeit-Muster (April 2026)

Claude Opus 4.7 (16. April 2026) wurde mit spezifischen Fähigkeiten ausgeliefert, die verändern, wogegen sich ein Harness verteidigen muss:²⁹

• Resilienz bei Tool-Fehlern: Opus 4.7 arbeitet bei Tool-Fehlern weiter, die Opus 4.6-Sitzungen zum Stillstand brachten. Sie können defensive Retry-Wrapper im Subagent-Code reduzieren — aber nicht vollständig eliminieren. Behalten Sie die Hook-Level-Guards bei; kürzen Sie das In-Prompt-Gerüst „wenn das Tool fehlschlägt, versuche es dreimal erneut”.
• xhigh Effort-Stufe (nur Opus-4.7): Liegt zwischen high und max. Empfohlene Voreinstellung für Coding- und Agenten-Workloads. Bei langlaufenden Subagenten übertrifft xhigh high deutlich bei unterproportionalen Token-Kosten. max bleibt die richtige Wahl für einmaliges hartes Reasoning; xhigh ist besser für anhaltende Aufgaben.
• Token-Budget-Obergrenze: Pro Agent-Run konfigurierbar über output_config.task_budget (Beta-Header task-budgets-2026-03-13). Das Modell sieht einen laufenden Countdown und passt die Arbeit elegant an das Budget an, anstatt unerwartet auszulaufen. Verwenden Sie dies für agentische Schleifen, bei denen Sie vorhersagbare Token-Ausgaben ohne Qualitätseinbußen bei kurzen Prompts wünschen.
• Bewusstsein für implizite Bedürfnisse: Erstes Claude-Modell, das „Implicit-Need”-Tests besteht — erkennt, wenn die wörtliche Anfrage des Benutzers das, was er tatsächlich benötigt, zu wenig spezifiziert. Dadurch wird der Abschnitt „Klärungsregeln” in CLAUDE.md weniger notwendig. Wenn Ihre CLAUDE.md 200 Zeilen an Leitplanken im Stil „berücksichtige auch X, wenn der Benutzer nach Y fragt” enthält, entfernen Sie jene, die nun nativ abgedeckt sind.

Die Quality Loop

Ein obligatorischer Review-Prozess für alle nicht-trivialen Änderungen:

1. Implement - Code schreiben
2. Review - Jede Zeile erneut lesen. Tippfehler, Logikfehler, unklare Abschnitte aufspüren
3. Evaluate - Die evidence gate durchlaufen. Patterns, Edge Cases, Testabdeckung prüfen
4. Refine - Jedes Problem beheben. Niemals auf „später” verschieben
5. Zoom Out - Integrationspunkte, Imports, angrenzenden Code auf Regressionen prüfen
6. Repeat - Wenn ein Kriterium der evidence gate fehlschlägt, zurück zu Schritt 4
7. Report - Auflisten, was sich geändert hat, wie verifiziert wurde, konkrete Belege zitieren

Die Evidence Gate

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

Wenn Sie für eine Zeile keinen Beleg liefern können, kehren Sie zu Refine zurück.²²

Muster für Fehlerbehandlung

Atomare Dateischreibvorgänge. Wenn mehrere Agenten gleichzeitig in dieselbe State-Datei schreiben, beschädigt dies JSON. 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 State-Korruption. Wenn der State beschädigt wird, erstellt das Recovery-Pattern ihn aus sicheren Standardwerten neu, 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, was bash als false behandelt. Mit aktiviertem set -e beendet dies das Skript. Verwenden Sie stattdessen VAR=$((VAR + 1)).¹⁶

Klassifizierung des Blast Radius

Klassifizieren Sie jede Agent-Aktion nach Blast Radius und schalten Sie entsprechend Gates davor:²

Remote Control (Verbindung zu lokalem Claude Code von einem beliebigen Browser oder einer mobilen App aus) verwandelt das „External”-Gate von einem blockierenden Warten in eine asynchrone Benachrichtigung. Der Agent arbeitet an der nächsten Aufgabe weiter, während Sie die vorherige vom Telefon aus überprüfen.²

Task-Spezifikation für autonome Läufe

Effektive autonome Tasks enthalten drei Elemente: Objective, Completion Criteria und Context Pointers:¹⁶

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 verifizierbar sein: Test bestanden/fehlgeschlagen, Linter-Ausgabe, HTTP-Statuscodes, Prüfungen auf Existenz von Dateien. Eine frühe Aufgabe, die den Agenten aufforderte, „Tests zu schreiben, die bestehen”, produzierte assert True und assert 1 == 1. Technisch korrekt. Praktisch wertlos.¹⁶

Fehlermuster, auf die Sie achten sollten

Ein konkreter Session-Trace

Ein Session-Trace aus einem autonomen Lauf, der ein PRD mit 5 Stories verarbeitet:²

1. SessionStart feuert. Der Dispatcher injiziert: aktuelles Datum, Projekterkennung, Philosophie-Constraints, Initialisierung des Cost Trackings. Fünf Hooks, insgesamt 180 ms.

2. Der Agent liest das PRD und plant die erste Story. UserPromptSubmit feuert. Der Dispatcher injiziert: aktiven Projektkontext, Session-Drift-Baseline.

3. Der Agent ruft Bash auf, um Tests auszuführen. PreToolUse:Bash feuert. Credential-Prüfung, Sandbox-Validierung, Projekterkennung. 90 ms. Tests laufen. PostToolUse:Bash feuert: Activity Heartbeat geloggt, Drift-Check.

4. Der Agent ruft Write auf, um eine Datei zu erstellen. PreToolUse:Write feuert: File-Scope-Prüfung. PostToolUse:Write feuert: Lint-Check, Commit-Tracking.

5. Der Agent beendet die Story. Stop feuert. Quality Gate prüft: Hat der Agent Belege zitiert? Hedging-Sprache? TODO-Kommentare im Diff? Wenn eine Prüfung fehlschlägt, Exit 2 und der Agent arbeitet weiter.

6. Unabhängige Verifikation: Ein frischer Agent führt die Test-Suite aus, ohne dem Selbstbericht des vorherigen Agenten zu vertrauen.

7. Drei Code-Review-Agenten werden parallel gestartet. Jeder überprüft das Diff unabhängig. Wenn einer der Reviewer CRITICAL markiert, kehrt die Story in die Queue zurück.

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

Insgesamt gefeuerte Hooks über 5 Stories: ~340. Gesamtzeit in Hooks: ~12 Sekunden. Dieser Overhead verhinderte in einem einzigen nächtlichen Lauf drei Credential-Leaks, einen destruktiven Befehl und zwei unvollständige Implementierungen.

Fallstudie: Nächtliche PRD-Verarbeitung

Ein Produktions-Harness verarbeitete 12 PRDs (47 Stories) über 8 nächtliche Sessions. Die Metriken vergleichen die ersten 4 PRDs (minimaler Harness: nur CLAUDE.md) mit den letzten 8 (voller Harness: Hooks, Skills, Quality Gates, Multi-Agent-Review).

Die beiden Credential-Leaks erforderten das Rotieren von API-Keys und das Auditieren nachgelagerter Dienste: etwa 4 Stunden Incident Response. Der Harness-Overhead, der das Äquivalent verhinderte, betrug 2,4 Sekunden Bash pro Story. Die Rate falscher Abschlüsse sank von 35 % auf 4 %, weil der Stop-Hook unabhängig Tests ausführte, bevor dem Agenten erlaubt wurde, „fertig” zu melden.

Sicherheitsüberlegungen

Die fünf Prinzipien vertrauenswürdiger Agenten (Anthropic, April 2026)

Anthropic veröffentlichte am 9. April 2026 ein formales Rahmenwerk für die Vertrauenswürdigkeit von Agenten.²⁷ Die fünf Prinzipien ergänzen — und erweitern — das Evidence-Gate-Denken in diesem Leitfaden:

Anthropic spendete zudem MCP an die Agentic AI Foundation der Linux Foundation und schloss sich damit AGENTS.md an (nun gemeinsam verwaltet mit OpenAI, Google, Cursor, Factory, Sourcegraph). Standards für Agent-Interoperabilität sind jetzt anbieterneutral.²⁷

Skill-Sandbox-Tooling: Für Teams, die Skills als Angriffsfläche betrachten, führt Permisos SandyClaw (veröffentlicht am 2. April 2026) Skills in einer dedizierten Sandbox aus und liefert evidenzbasierte Urteile aus Sigma/YARA/Nova/Snort-Erkennung. Erstes Produkt in der Skill-Sandbox-Kategorie.²⁸

Die Sandbox

Claude Code unterstützt einen optionalen Sandbox-Modus (aktivierbar über settings.json oder den Befehl /sandbox), der Netzwerkzugriff und Dateisystemoperationen mithilfe von Isolation auf Betriebssystemebene einschränkt (seatbelt unter macOS, bubblewrap unter Linux). Wenn aktiviert, verhindert die Sandbox, dass das Modell beliebige Netzwerkanfragen stellt oder auf Dateien außerhalb des Projektverzeichnisses zugreift. Ohne Sandboxing verwendet Claude Code ein berechtigungsbasiertes Modell, bei dem Sie einzelne Tool-Aufrufe genehmigen oder ablehnen.¹³

Berechtigungsgrenzen

Das Berechtigungssystem gatiert Operationen auf mehreren Ebenen:

Abwehr von Prompt Injection

Skills und Hooks bieten Defense-in-Depth 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 gepromptet 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 ist.

Hook-Sicherheit

HTTP-Hooks, die Umgebungsvariablen in Header interpolieren, erfordern eine explizite allowedEnvVars-Liste, um das willkürliche Exfiltrieren 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 Agent-Architekturen erfordert eine klare Aufteilung zwischen menschlichen und agentenseitigen Verantwortlichkeiten:¹⁷

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 einen Subagent über das Agent-Tool spawnt, 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 Sicherheits-Gates umgehen. Das Ereignis SubagentStop erlaubt Ihnen, Bereinigung oder Validierung auszuführen, wenn ein Subagent abschließt.

Dies ist nicht optional. Ein Agent, der einen Subagent ohne Ihre Sicherheits-Hooks spawnt, ist ein Agent, der force-push auf main ausführen, Credential-Dateien lesen oder destruktive Befehle ausführen kann, während Ihre Gates dabei zusehen, wie die Hauptkonversation nichts tut.

Kosten als Architektur

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

Token-Ebene. Komprimierung des System-Prompts. 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 sensiblen Pfaden entsprechen” leistet dieselbe Arbeit wie eine 15-zeilige Erklärung, warum Credentials nicht gelesen werden sollten.

Agent-Ebene. Frische Spawns 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 startet. Briefing statt Gedächtnis: Modelle führen ein klares Briefing besser aus, als dass sie durch 30 Schritte angesammelten Kontexts navigieren.

Architekturebene. CLI-first statt MCP, wenn die Operation zustandslos ist. Ein claude --print-Aufruf für eine einmalige Auswertung kostet weniger und fügt keinen Verbindungsoverhead hinzu. 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?

Die Einschränkung ist die Performance, nicht die Anzahl. Jeder Hook läuft synchron, sodass sich die gesamte Hook-Ausführungszeit bei jedem übereinstimmenden Tool-Aufruf aufsummiert. 95 Hooks, verteilt auf Einstellungen auf Benutzer- und Projektebene, laufen ohne spürbare Latenz, wenn jeder Hook in weniger als 200 ms abgeschlossen wird. Der Schwellenwert, den Sie beobachten sollten: Wenn ein PostToolUse-Hook mehr als 500 ms zu jeder Dateibearbeitung hinzufügt, wirkt die Sitzung träge. 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, indem sie mit Code 2 beendet werden. Claude Code bricht die ausstehende Aktion ab und zeigt die stderr-Ausgabe des Hooks dem Modell an. Claude sieht den Ablehnungsgrund und schlägt eine sicherere Alternative vor. Exit 1 ist eine nicht blockierende Warnung, bei der die Aktion dennoch 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 in ~/.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.¹⁴

Muss jede Entscheidung deliberiert werden?

Nein. Das Confidence-Modul bewertet Entscheidungen über vier Dimensionen (Mehrdeutigkeit, Komplexität, Tragweite, Kontextabhängigkeit). Nur Entscheidungen mit einem Gesamtkonfidenzwert unter 0,70 lösen eine Deliberation aus, etwa 10 % aller Entscheidungen. Dokumentationskorrekturen, Variablenumbenennungen und Routinebearbeitungen überspringen die Deliberation vollständig. Sicherheitsarchitektur, Änderungen am Datenbankschema und irreversible Deployments lösen sie konsistent aus.⁷

Wie teste ich ein System, das darauf ausgelegt ist, Meinungsverschiedenheiten zu erzeugen?

Testen Sie sowohl Erfolgs- als auch Fehlerpfade. Erfolg: Agenten widersprechen einander produktiv und erreichen einen 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 abfangen. Ein produktives Deliberationssystem führt 141 Tests über drei Ebenen aus: 48 Bash-Integrationstests, 81 Python-Unit-Tests und 12 End-to-End-Pipeline-Simulationen.⁷

Welche Auswirkungen hat die Deliberation auf die Latenz?

Eine Deliberation mit 3 Agenten fügt 30-60 Sekunden Wall-Clock-Zeit hinzu (Agenten laufen sequenziell über das Agent tool). Eine Deliberation mit 10 Agenten fügt 2-4 Minuten hinzu. Die Consensus- und Pride-Check-Hooks laufen jeweils in weniger als 200 ms. Der primäre Flaschenhals ist die LLM-Inferenzzeit pro Agent, nicht der Orchestrierungs-Overhead.⁷

Wie lang sollte eine CLAUDE.md-Datei sein?

Halten Sie jeden Abschnitt unter 50 Zeilen und die Gesamtdatei unter 150 Zeilen. Lange Dateien werden von Kontextfenstern abgeschnitten, stellen Sie daher die wichtigsten Anweisungen voran: Befehle und Abschlussdefinitionen vor Stilpräferenzen.²¹

Kann dies mit anderen Tools als Claude Code funktionieren?

Die architektonischen Prinzipien (Hooks als deterministische Gates, Skills als Domänenexpertise, Subagents als isolierte Kontexte, Dateisystem als Speicher) gelten konzeptionell für jedes agentische System. 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-Pattern ist tool-agnostisch, auch wenn die Implementierungsdetails tool-spezifisch sind.

Schnellreferenz-Karte

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