Agentenarchitektur: Entwicklung KI-gestützter Entwicklungsumgebungen

TL;DR: Claude Code ist keine Chatbox mit Dateizugriff. Es ist eine programmierbare Runtime mit 29 dokumentierten Lifecycle-Events, die jeweils mit Shell-Skripten per Hook angebunden werden können und die das Modell nicht überspringen kann. Stapeln Sie hooks zu dispatchers, dispatchers zu skills, skills zu agents, agents zu workflows, und Sie erhalten ein autonomes Entwicklungsharness, das Constraints durchsetzt, Arbeit delegiert, memory sitzungsübergreifend persistiert und Multi-Agent-Deliberation orchestriert. Claude Code v2.1.147 hat das standardmäßig deaktivierte Workflow tool (CLAUDE_CODE_WORKFLOWS=1) hinzugefügt und deterministische Multi-Agent-Orchestrierung damit von reinen Userland-Skripten in Richtung eines First-Party-Runtime-Primitives verschoben; v2.1.149 bestätigt dieselbe Lehre von der Sicherheitsseite mit Fixes für PowerShell Permission-Bypasses und einem Fix für die git-worktree sandbox allowlist. Hooks und evidence gates bleiben für Korrektheit zuständig.⁵²⁵³ Dieser Leitfaden behandelt jede Ebene dieses Stacks: von einem einzelnen hook bis zu einem Konsenssystem mit 10 agents. Keine frameworks erforderlich. Nur bash und JSON.

Andrej Karpathy hat einen Begriff für das geprägt, was um einen LLM agent herum entsteht: claws. Die hooks, scripts und orchestration, mit denen der agent die Welt außerhalb seines context window greifen kann.¹ Die meisten Entwickler behandeln AI coding agents als interaktive Assistenten. Sie tippen einen Prompt, sehen zu, wie eine Datei bearbeitet wird, und machen weiter. Dieses Framing begrenzt die Produktivität auf das, was Sie persönlich überwachen können.

Das Infrastruktur-Mentalmodell ist anders: Ein AI coding agent ist eine programmierbare Runtime mit einem LLM kernel. Jede Aktion des Modells läuft durch hooks, die Sie kontrollieren. Sie definieren Policies, keine Prompts. Das Modell arbeitet innerhalb Ihrer Infrastruktur so, wie ein Webserver innerhalb von nginx-Regeln arbeitet. Sie sitzen nicht vor nginx und tippen Requests ein. Sie konfigurieren es, deployen es und überwachen es.

Der Unterschied ist wichtig, weil Infrastruktur kumuliert. Ein hook, der Zugangsdaten in bash-Befehlen blockiert, schützt jede Session, jeden agent, jeden autonomen Lauf. Ein skill, der Ihre Bewertungsrubrik kodifiziert, greift konsistent, egal ob Sie ihn aufrufen oder ein agent. Ein agent, der Code auf Sicherheit prüft, führt dieselben Checks aus, 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 jedes Mal unabhängig vom Modellverhalten laufen muss. Exit-Code 2 blockiert Aktionen. Exit-Code 1 warnt nur.³
• Skills kodifizieren Fachwissen, das automatisch aktiviert wird. Das Feld description entscheidet alles. Claude verwendet LLM reasoning (kein Keyword-Matching), um zu entscheiden, wann ein skill angewendet wird.⁴
• Subagents verhindern Kontextaufblähung. Isolierte context windows für Exploration und Analyse halten die Hauptsession schlank. Führen Sie unabhängige subagents parallel aus, und verwenden Sie agent teams, wenn workers dauerhafte Koordination benötigen.⁵
• Memory liegt im Dateisystem. Dateien bleiben über context windows hinweg bestehen. CLAUDE.md, MEMORY.md, rules-Verzeichnisse und Handoff-Dokumente bilden ein strukturiertes externes memory-System.⁶
• Multi-Agent-Deliberation findet blinde Flecken. Einzelne agents können ihre eigenen Annahmen nicht herausfordern. Zwei unabhängige agents mit unterschiedlichen Bewertungsschwerpunkten finden strukturelle Fehler, die quality gates nicht abdecken können.⁷
• Das harness pattern ist das System. CLAUDE.md, hooks, skills, agents und memory sind keine unabhängigen Funktionen. Sie verbinden sich zu einer deterministischen Ebene zwischen Ihnen und dem Modell, die mit der Automatisierung skaliert.

So verwenden Sie diesen Leitfaden

Jeder Abschnitt baut auf dem vorherigen auf. Das Decision Framework am Ende bietet eine Lookup-Tabelle, mit der Sie den richtigen Mechanismus für jeden Problemtyp auswählen können.

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 zusammensetzbare Sammlung von Dateien, Skripten und Konventionen, die einen AI-Coding-Agenten in deterministische Infrastruktur einbetten. 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 Verdichtung geladen. Dies ist das langfristige architektonische Gedächtnis des Agenten.

Extension Layer: Skills liefern Fachwissen, das sich kontextabhängig automatisch aktiviert. Hooks bieten deterministische Gates, die bei jedem passenden Tool-Aufruf ausgelöst werden. Memory-Dateien erhalten den Zustand ü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 unkontrollierte Rekursion. Konsens-Validierung sichert die Qualität.

Die zentrale Erkenntnis: Die meisten Benutzer arbeiten ausschließlich im Core Layer und sehen dabei zu, wie der Kontext aufbläht und die Kosten steigen. Power-User konfigurieren die Instruction- und Extension-Layer und nutzen den Core Layer dann nur noch für Orchestrierung und finale Entscheidungen.²

Verwaltete vs. selbst gehostete Harnesses (April 2026)

Während des frühen Jahres 2026 war der Weg „Bauen Sie Ihr eigenes Harness” die einzig realistische Option. Im April 2026 änderte sich das. Anthropic veröffentlichte Claude Managed Agents in einer öffentlichen Beta (8. April): Harness-Loop + Tool-Ausführung + Sandbox-Container + Zustandspersistenz als REST API, abgerechnet zu Standard-Tokens zuzüglich 0,08 $ pro Sitzungsstunde. Das Agents SDK-Update von OpenAI (16. April) formalisierte dieselbe Aufteilung — Harness und Compute als getrennte Schichten, mit nativen Sandbox-Anbietern (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) sowie Snapshot/Rehydrate, um Container-Verluste zu überstehen.²³²⁴

Die tiefere SDK-Oberfläche auf der OpenAI-Seite kam mit openai-agents Python v0.14.0 (veröffentlicht am 15. April 2026; angekündigt am 16. April): eine SandboxAgent-Unterklasse von Agent mit default_manifest, Sandbox-Anweisungen und Capabilities; ein Manifest, das den Vertrag für einen frischen Workspace beschreibt (Dateien, Verzeichnisse, lokale Dateien, Git-Repos, Env, Benutzer, Mounts); eine SandboxRunConfig für die Per-Run-Verdrahtung von Sandbox-Client, Live-Session-Injection, Manifest-Overrides, Snapshots und Materialisierungs-Concurrency-Limits. Die eingebauten Capabilities decken Shell-Zugriff, Filesystem-Editing, Image-Inspektion, Skills, Sandbox-Memory und Verdichtung ab. Sandbox-Memory bewahrt extrahierte Lessons über Runs hinweg und gibt sie progressiv frei; Workspaces unterstützen lokale Dateien, Git-Repo-Einträge und Remote-Mounts (S3, R2, GCS, Azure Blob, S3 Files); Snapshots sind anbieterübergreifend portierbar. Backends: UnixLocalSandboxClient, DockerSandboxClient sowie gehostete Clients für Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop und Vercel über optionale Extras.²⁴

Für Python-Projekte, die die Claude Code-Runtime als Bibliothek einbetten möchten — zwischen „Shell-Aufruf von claude” und „REST API zu Managed Agents” — ist claude-agent-sdk-python die dritte Option. Die Serie vom 28.–29. April (v0.1.69 → v0.1.71) hob das gebündelte CLI auf v2.1.123 an, setzte den Floor der mcp-Abhängigkeit auf >=1.19.0 (ältere Versionen verwarfen still CallToolResult-Rückgaben aus In-Process-MCP-Tools und ließen das Modell mit einem Validation-Error-Blob zurück) und brachte SandboxNetworkConfig zur Schema-Parität mit dem TypeScript-SDK (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰

Falls Ihr Harness eine Voice- oder Realtime-Schicht enthält, hat openai-agents-python v0.17.0 (8. Mai 2026) RealtimeAgent so aktualisiert, dass nun standardmäßig gpt-realtime-2 verwendet wird.⁴¹ Bestehende Realtime-Sessions übernehmen den neuen Default automatisch; pinnen Sie das vorherige Modell explizit, falls Sie das alte Verhalten zur Evaluation halten müssen.

Die architektonische Weggabelung ist nun real:

Wann was wählen: Selbst gehostet bleibt richtig für Teams, die bereits Infrastruktur-Muskeln aufgebaut haben, Skills/Hooks unter eigener Kontrolle wollen oder einen spezifischen Workflow tief optimieren. Managed ist richtig für Teams ohne dedizierte Plattform-Engineers, wenn Time-to-Value wichtiger ist als Customization, oder wenn Agent-Runs Laptop-Schließungen zuverlässig überstehen müssen, ohne dass Sie diese Persistenzschicht selbst bauen. Die beiden sind kompatibel — Sie können ein selbst gehostetes Harness betreiben, das spezifische langlaufende Aufgaben über dessen 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 via Git geteilt. Zusammen bilden sie das vollständige Harness.

Skills-System

Skills sind vom Modell aufgerufene Erweiterungen. Claude entdeckt und wendet sie automatisch anhand des Kontexts an, ohne dass Sie sie ausdrücklich aufrufen müssen.⁴ Sobald Sie merken, dass Sie denselben Kontext über mehrere Sitzungen hinweg erneut erklären, sollten Sie einen Skill erstellen.

Wann Sie einen Skill erstellen sollten

Skills sind für Wissen, das Claude immer verfügbar hat. Slash commands sind für Aktionen, die Sie ausdrücklich auslösen. Wenn Sie zwischen beiden entscheiden, fragen Sie: “Soll Claude dies automatisch anwenden, oder soll ich entscheiden, wann es ausgeführt wird?”

Einen Skill erstellen

Skills können an vier möglichen Orten liegen, vom breitesten bis zum engsten Scope:⁴

Jeder 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

## Security Checks
When reviewing code, verify:

### Input Validation
- All user input sanitized before database operations
- Parameterized queries (no string interpolation in SQL)
- Output encoding for rendered HTML content

### Authentication
- Session tokens validated on every protected endpoint
- Permission checks before data mutations
- No hardcoded credentials or API keys in source

Frontmatter-Referenz

Das Feld Description ist alles

Beim Sitzungsstart extrahiert Claude Code von jedem Skill name und description und fügt sie in den Kontext von Claude ein. Wenn Sie eine Nachricht senden, nutzt Claude Language-Model-Reasoning, um zu entscheiden, 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 verwendet normales 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 der Skill tut (Code auf bestimmte Problemtypen prüfen), wann er zu verwenden ist (beim Untersuchen von Änderungen, PRs, Qualitätsanalysen) und Trigger-Phrasen (review, audit, check), die Benutzer natürlicherweise eingeben.

Kontextbudget

Alle Skill-Beschreibungen teilen sich ein Kontextbudget, das dynamisch mit 1 % des Kontextfensters skaliert, mit einem Fallback von 8.000 Zeichen.⁴ Wenn Sie viele Skills haben, halten Sie jede Beschreibung knapp und stellen Sie den wichtigsten Anwendungsfall an den Anfang. 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 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 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 verschieben Sie detailliertes Referenzmaterial in unterstützende Dateien.¹²

Skills über Git teilen

Projekt-Skills (.claude/skills/ im Repo-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. Das ist der wirksamste Weg, Expertise in einem Team zu standardisieren.

Skills als Prompt-Bibliothek

Über einzelne 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 kontextabhängig 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 ihre eigenen hooks in der Frontmatter definieren, die nur aktiv werden, während der Skill läuft. Dadurch entsteht domänenspezifisches Verhalten, das andere Sitzungen nicht verschmutzt:²

---
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'"
---

Philosophy-Skills aktivieren sich automatisch über SessionStart-hooks und injizieren Qualitätsvorgaben in jede Sitzung, ohne ausdrücklichen Aufruf. Der Skill selbst ist Wissen. Der hook ist Durchsetzung. Zusammen bilden sie eine Policy-Schicht.

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 in 80 % der Sitzungen den Kontext. Die Lösung besteht darin, entweder die Beschreibung zu schärfen oder disable-model-invocation: true hinzuzufügen und einen ausdrücklichen Aufruf über /skill-name zu verlangen.⁴

Zu viele Skills konkurrieren um Budget. Mehr Skills bedeuten mehr Beschreibungen, die um das 1-%-Kontextbudget konkurrieren. Wenn Sie bemerken, dass Skills nicht aktiviert werden, prüfen Sie mit /context, welche ausgeschlossen wurden. Priorisieren 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 stehen, findet Claude sie möglicherweise nicht. Platzieren Sie wesentliche Informationen direkt in SKILL.md.⁴

SDK-Skill-Oberfläche (8. Mai 2026)

Self-hosted harnesses auf claude-agent-sdk-python v0.1.77+ sollten die Option skills in ClaudeAgentOptions verwenden, um verfügbare Skills zu deklarieren, nicht den veralteten "Skill"-Wert in allowed_tools.³⁷ Die "Skill"-Kurzform ist deprecated, und die dedizierte Option gibt Claude Code strukturiertere Informationen darüber, welche Skills verfügbar sind. Gebündeltes CLI in v0.1.77 ist v2.1.133.

Plugin- und Skill-Konvergenz in .claude/skills/ (29. Mai 2026)

Skills wurden schon immer aus dem .claude/skills/-Verzeichnis eines Projekts geladen. Claude Code v2.1.157 erweitert dieses Verzeichnis auf Plugins: Ein Plugin, das in .claude/skills/ liegt, wird jetzt automatisch ohne Marketplace-Registrierung geladen, und claude plugin init <name> erzeugt dort ein frisches Gerüst, bei dem Manifest und SKILL.md bereits verdrahtet sind.⁵⁸ Damit schließt sich die Lücke zwischen den beiden Formen von Projekt-Tooling, die früher an verschiedenen Orten lebten — ein nackter Skill, der direkt ins Repo committed wurde, gegenüber einem Plugin, das einen Skill plus hooks plus einen MCP-Server bündelt, zuvor aber zur Installation einen Marketplace benötigte. Der praktische Effekt für das harness-Design: Projektbezogenes Tooling braucht keinen Umweg über eine Registry mehr, um ausgeliefert zu werden — schreiben, committen, und Teammitglieder erhalten dieselbe Oberfläche mit git pull. Plugins behalten weiterhin den Anwendungsfall gebündelter Installierbarkeit (hooks + skills + MCP-Server + agents in einer ZIP); die Änderung ist, dass ein Projekt keinen Marketplace mehr aufsetzen muss, nur um eines aus seinem eigenen Baum zu laden.

Die gebündelte Oberfläche als Governance ausblenden (8. Juni 2026)

Skills sind Fähigkeit, und Fähigkeit ist Angriffsfläche. Claude Code v2.1.169 fügt eine disableBundledSkills-Einstellung hinzu (sowie die passende Umgebungsvariable CLAUDE_CODE_DISABLE_BUNDLED_SKILLS), die die gebündelten Skills, Workflows und eingebauten slash commands vollständig vor dem Modell verbirgt.⁶⁰ Für einen gehärteten oder regulierten harness ist das eine bewusste Reduktion der Angriffsfläche: Ein Operator, der eine bestimmte Menge an Projekt- und persönlichen Skills auditiert und freigegeben hat, kann alles unterdrücken, was Anthropic mitliefert, sodass das Modell nur über die Oberfläche reasoning betreibt, die der Operator geprüft hat. Behandeln Sie es genauso wie eine Tool-Allowlist — der Standard ist breite Fähigkeit, und diesen Standard abzuschalten ist eine Governance-Entscheidung, kein Komfortschalter.

Verschachtelte .claude/skills und Closest-Wins-Auflösung (16. Juni 2026)

Claude Code v2.1.178 machte Projekt-Tooling ortsabhängig. Skills in verschachtelten .claude/skills-Verzeichnissen werden jetzt geladen, wenn Sie an Dateien unterhalb dieses Verzeichnisses arbeiten, nicht nur aus dem Repo-Root; bei einem Namenskonflikt erscheint der verschachtelte Skill als <dir>:<name>, sodass beide erreichbar bleiben.⁶³ Dieselbe Version ließ den Rest der Projektoberfläche nach der Nähe zum Arbeitsverzeichnis auflösen: Wenn ein agent-, workflow- oder output-style-Name in verschachtelten .claude/-Verzeichnissen kollidiert, gewinnt der Eintrag, der dem Arbeitsverzeichnis am nächsten liegt, und ein projektbezogenes Speichern eines Workflows zielt auf das nächstgelegene vorhandene .claude/workflows/ statt immer auf den Root.⁶³ Für ein Monorepo oder Repo-of-Repos ist das der Unterschied zwischen einer flachen globalen Oberfläche und Paket-Tooling, das im Kontext aktiviert wird — ein services/api/.claude/skills/ kann API-spezifische Skills enthalten, die nur beim Arbeiten in diesem Baum erscheinen, ohne mit einem gleichnamigen Skill in services/web/ zu kollidieren.

Hook-Architektur

Hooks sind Shell-Befehle, die durch Lebenszyklusereignisse 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 Blocklist und lehnt ihn ab, bevor die Shell ihn überhaupt sieht. Der Hook wird ausgelöst, ob das Modell das will oder nicht.

Verfügbare Ereignisse

Claude Code stellt zum Zeitpunkt dieser Guide-Aktualisierung 29 dokumentierte Lebenszyklusereignisse in acht Kategorien bereit. Die Ereignisliste wächst mit Releases, behandeln Sie daher die Referenzdokumentation als Quelle der Wahrheit und prüfen Sie das Cheat Sheet auf die aktuelle vollständige Tabelle, bevor Sie Produktions-Hooks verdrahten:¹³

Semantik von Exit-Codes

Exit-Codes bestimmen, 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. Das 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 filtert einen ereignisspezifischen Wert. Bei Tool-Ereignissen stimmt es mit tool_name-Werten wie Bash, Edit, Write, Read, Glob, Grep, MCP-Toolnamen wie mcp__server__tool oder * für alle Tools überein. Einfache Namen und mit | getrennte Listen sind exakte Treffer; Werte mit anderen Zeichen sind reguläre JavaScript-Ausdrücke. Einige Ereignisse unterstützen keine Matcher und werden immer ausgelöst, wenn sie konfiguriert sind.¹³

Hook-Eingabe-/Ausgabeprotokoll

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 Steuerung können PreToolUse-Hooks JSON ausgeben, um Tool-Eingaben zu ändern, Kontext einzuspeisen oder Berechtigungsentscheidungen zu treffen. Verwenden Sie den Wrapper hookSpecificOutput — 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: Welche Art von Garantie brauche ich?¹⁴

Formatierungsgarantien stellen nachträglich Konsistenz 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'"
          }
        ]
      }
    ]
  }
}

Sicherheitsgarantien 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ätsgarantien validieren den Zustand an Entscheidungspunkten. PreToolUse-Hooks auf git commit-Befehle führen Ihren Linter oder Ihre Test-Suite 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 fünf Hook-Typen:¹³

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

MCP-Tool-Hooks (type: "mcp_tool") rufen ein Tool auf einem bereits verbundenen MCP-Server auf. Nutzen Sie sie, wenn die Validierungslogik bereits hinter einer MCP-Grenze liegt und kein separates Shell-Skript benötigt.

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. Nutzen Sie sie für nuancierte Bewertungen, die Regex nicht ausdrücken kann.

Agent-Hooks (type: "agent") starten einen subagent mit Tool-Zugriff (Read, Grep, Glob) für Multi-Turn-Verifikation. Sie sind experimentell; bevorzugen Sie Command-Hooks für Produktions-Gates und reservieren Sie Agent-Hooks für Prüfungen, die tatsächlich echte Dateien oder Testausgaben inspizieren müssen:

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

Seit Claude Code v2.1.140 enthält die Eingabe von Agent-Hooks subagent_type, wodurch ein gemeinsam genutzter Hook einen security-reviewer-Lauf von einem explorer oder generischen worker unterscheiden kann, ohne aus Prompt-Text raten zu müssen.⁴⁹

HTTP-Hooks (type: "http") senden die JSON-Eingabe des Ereignisses als POST-Anfrage an eine URL und erhalten JSON zurück. Nutzen Sie sie für Webhooks, externe Benachrichtigungsdienste oder API-basierte Validierung (v2.1.63+). Für SessionStart-Ereignisse nicht unterstützt:

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

Async-Hooks

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

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

Nutzen Sie async für Benachrichtigungen, Telemetrie und Backups. Verwenden Sie async niemals für Formatierung, Validierung oder irgendetwas, das vor der nächsten Aktion abgeschlossen sein muss.

Dispatcher statt unabhängiger Hooks

Wenn sieben Hooks beim selben Ereignis ausgelöst werden und jeweils unabhängig stdin lesen, entstehen Race Conditions. Zwei Hooks, die gleichzeitig in dieselbe JSON-Statusdatei schreiben, kürzen die JSON ab. 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 still fehlschlagen:¹⁴

1. Skripte unabhängig testen. Leiten Sie Beispiel-JSON per Pipe weiter: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Stderr für Debug-Ausgaben verwenden. Bei Exit-Code 2 wird stderr als Fehlermeldung an Claude zurückgegeben. Nicht blockierendes stderr (Exit 1, 3, etc.) erscheint nur im ausführlichen Modus (Ctrl+O).
3. Auf jq-Fehler achten. Falsche JSON-Pfade geben still null zurück. Testen Sie jq-Ausdrücke gegen echte Tool-Eingaben.
4. Exit-Codes verifizieren. Ein PreToolUse-Hook, der exit 1 verwendet, erzwingt nichts, obwohl er zu funktionieren scheint.
5. Hooks schnell halten. Hooks laufen synchron. Halten Sie alle Hooks unter 2 Sekunden, idealerweise unter 500 ms.

SDK-seitiges Hook-Ereignisstreaming

Self-hosted harnesses, die auf claude-agent-sdk-python (v0.1.74+, 6. Mai 2026) basieren, können Hook-Ereignisse direkt aus dem Nachrichtenstream abonnieren, statt über Shell-Skript-Callbacks zu gehen.³⁶ Setzen Sie include_hook_events=True in ClaudeAgentOptions, und HookEventMessage-Objekte (PreToolUse, PostToolUse, Stop und andere) werden aus demselben Iterator geliefert wie Assistant-Nachrichten und Tool-Ergebnisse. Das spiegelt die Option includeHookEvents des TypeScript SDK wider; das gebündelte CLI wurde im selben Release auf v2.1.129 angehoben.

Das Ereignisstream-Muster passt, wenn Ihr harness bereits in Python lebt und Sie Hook-Signale im selben Kontrollfluss wie die Modellausgabe haben möchten. Der Shell-Skript-Hook-Vertrag (Exit-Codes, stdin-JSON, Dispatcher) bleibt die richtige Antwort für harnesses, die mehrere Tools kombinieren, Hooks über Claude Code und Codex hinweg teilen oder Exit-Code-Semantik zum Blockieren benötigen.

Effort und Session-Herkunft (7.-8. Mai 2026)

Zwei Ergänzungen in Claude Code v2.1.132 und v2.1.133 geben Hooks und Subprozessen bessere Signale über ihren Ausführungskontext:³⁸³⁹

• effort.level in der Hook-Eingabe. Hooks erhalten jetzt ein JSON-Feld effort.level in derselben Eingabe, die tool_input und session_id trägt. Derselbe Wert wird als Env-Var $CLAUDE_EFFORT exportiert, sodass Bash-Befehle ihn lesen können, ohne JSON zu parsen. Nutzen Sie dies, um Hook-Kosten nach Effort-Stufe zu skalieren: teure Validierung bei low überspringen, das vollständige Security-Gate bei xhigh oder max ausführen.
• Env-Var CLAUDE_CODE_SESSION_ID in Bash-Subprozessen. Bash-Tool-Subprozesse sehen jetzt denselben session_id-Wert wie die Hooks, offengelegt als CLAUDE_CODE_SESSION_ID. Das schließt die Herkunftslücke für Tools, die zustandsbezogen pro Session loggen und zuvor Subprozessereignisse nicht mit Hook-Ereignissen korrelieren konnten.

Beide Signale sind ohne Codeänderungen verfügbar; vorhandene Hooks, die die neuen Felder ignorieren, funktionieren weiter.

autoMode.hard_deny und Hook-/Plugin-Fixes in v2.1.136 (8. Mai 2026)

Claude Code v2.1.136 ergänzte Auto Mode um eine neue Hard-Deny-Stufe und behob eine Gruppe von Plugin- und MCP-Problemen, die lang laufende harnesses betrafen:⁴⁰

• settings.autoMode.hard_deny. Auto-Mode-Classifier-Regeln, die bedingungslos blockieren, unabhängig von Benutzerabsicht oder Allow-Ausnahmen. Dies steht über den bestehenden Allow/Deny-Matchern als nicht verhandelbarer Governance-Hebel. Nutzen Sie es für Regeln, die niemals überschrieben werden dürfen (Force-Push auf main, Dateien mit Secrets, Zugriff auf Produktionsdatenbanken), selbst wenn ein Operator die breitere Kategorie in seinen persönlichen Einstellungen genehmigt hat.
• MCP-Server verschwinden nach /clear nicht mehr. Server, die in .mcp.json, Plugins und claude.ai-Connectors konfiguriert waren, fielen nach einem /clear in der VS Code-Erweiterung, im JetBrains-Plugin und im Agent SDK still aus der aktiven Menge heraus. Der Fix landet in v2.1.136. Wenn Sie „MCP server X went missing mid-session“ gesehen haben, war das die Ursache.
• Verlust von MCP-OAuth-Refresh-Tokens bei gleichzeitiger Aktualisierung. Benutzer mit mehreren Remote-MCP-Servern sollten keine tägliche erneute Authentifizierung mehr benötigen. Gleichzeitige Refresh-Schreibvorgänge überschrieben einander.
• Plan Mode blockiert Dateischreibvorgänge jetzt korrekt. Eine passende Edit(...)-Allow-Regel umging den Schreibschutz des Plan Mode. Plan Mode wird jetzt unabhängig von Allow-Regeln erzwungen.
• Plugin-Hooks Stop und UserPromptSubmit schlagen nicht mehr mitten in der Session fehl. Die Cache-Bereinigung löschte Plugin-Versionsdateien, die von der laufenden Session noch genutzt wurden, wodurch speziell diese beiden Hook-Ereignisse brachen. Der Fix hält verwendete Versionen gepinnt.
• skills-Eintrag in plugin.json. Das Setzen von skills blendete das standardmäßige skills/-Verzeichnis des Plugins aus. Jetzt wird der Eintrag korrekt kombiniert, und ein Verweis auf einen Dateipfad löst einen expliziten Fehler aus, statt still fehlzuschlagen.
• Env-Vars von CLAUDE_ENV_FILE-SessionStart-Hooks wurden stale. Variablen, die von SessionStart-Hooks über CLAUDE_ENV_FILE exportiert wurden, wurden nach /resume oder /clear stale. In v2.1.136 behoben. Sessions sourcen die Env-Datei jetzt bei diesen Ereignissen erneut.

Für Governance-harnesses sind die operativ interessanten Punkte autoMode.hard_deny (neuer Hebel) und der Fix für verschwindende MCP-Server (stiller Fehler, der lange Sessions brach). Alles andere ist eine Quality-of-Life-Bereinigung.

Strukturierte Hook-Argumente und Block-Fortsetzung (11. Mai 2026)

Claude Code v2.1.139 ergänzte zwei Hook-Details, die für Produktions-harnesses wichtig sind: eine Exec-Form args: string[] für Command-Hooks und continueOnBlock für PostToolUse-Hooks.⁴²⁴⁴ Bevorzugen Sie args, wenn ein Hook dynamische Werte oder Pfad-Platzhalter benötigt. Der Befehl wird direkt ohne Shell gestartet, wodurch eine ganze Klasse von Quoting- und Injection-Fehlern entfällt.

Nutzen Sie continueOnBlock, wenn ein PostToolUse-Hook seinen Ablehnungsgrund an Claude zurückgeben und den Turn fortsetzen soll, statt den Ablauf zu beenden. Behandeln Sie es als Operator-Experience-Funktion, nicht als Security-Bypass. Ein blockierendes Gate sollte das unsichere Ergebnis weiterhin blockieren.

Dasselbe Release übergibt CLAUDE_PROJECT_DIR an MCP-stdio-Server und erlaubt Plugin-Konfigurationen, ${CLAUDE_PROJECT_DIR} in Befehlen zu referenzieren.⁴² MCP-Tools sollten projektrelative Pfade aus diesem Wert auflösen, nicht aus dem zufälligen Arbeitsverzeichnis des Prozesses, der den Server gestartet hat.

Claude Code v2.1.140 ist vor allem ein Reliability-Release für harness-Operatoren: Es behebt, dass ConfigChange-Hooks bei Einstellungsänderungen nicht ausgelöst wurden, schließt Edge Cases, in denen disableAllHooks und allowManagedHooksOnly über Einstellungsebenen hinweg nicht korrekt zusammenspielten, und verhindert, dass Berechtigungsdialoge unbeabsichtigte Umgebungsvariablen anzeigen, die von Hook-Ergebnissen zurückgegeben wurden.⁴⁹ Dadurch werden die bestehenden Governance-Muster in diesem Abschnitt verlässlicher; eine neue Hook-Architektur ist nicht erforderlich.

Claude Code v2.1.141 ergänzt ein Hook-Ausgabefeld terminalSequence für Desktop-Benachrichtigungen, Fenstertitel und Bells ohne steuerndes Terminal.⁵⁰ Behandeln Sie das als Operator-Signal, nicht als Durchsetzung. Security- und Qualitäts-Gates sollten Fehler weiterhin über den normalen Blockierungsvertrag kommunizieren: strukturierte Hook-Ausgabe plus Exit-Verhalten, das die unsichere Aktion verhindert. Dasselbe Release ergänzt claude agents --cwd <path> zur Eingrenzung von Agent View auf ein Verzeichnis, CLAUDE_CODE_PLUGIN_PREFER_HTTPS für Plugin-Installationen in Umgebungen ohne GitHub-SSH-Schlüssel und ANTHROPIC_WORKSPACE_ID für Workload-Identity-Federation-Regeln, die mehr als einen Workspace abdecken.⁵⁰ Das sind Architekturdetails für Team-harnesses: engere operative Ansichten, weniger Annahmen bei Plugin-Installationen und explizites Enterprise-Token-Scoping.

Claude Code v2.1.142 ist wichtiger für die Orchestrierung von Hintergrund-Sessions als für Hook-Semantik.⁵¹ claude agents kann Hintergrund-Sessions jetzt mit expliziten Flags für Verzeichnis, Einstellungen, MCP, Plugin, Berechtigung, Modell und Effort dispatchen, statt vom Wrapper-Zustand abzuhängen. Fast Mode verwendet jetzt standardmäßig Opus 4.7; pinnen Sie CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 nur, wenn ein harness eine gemessene Abhängigkeit vom Verhalten von Opus 4.6 hat. Root-Level-Plugin-SKILL.md-Discovery und Plugin-bereitgestellte LSP-Sichtbarkeit reduzieren Packaging-Mehrdeutigkeit. Fixes für MCP_TOOL_TIMEOUT, bereits vorhandene Hintergrund-Session-Worktrees, Daemon-Sleep/Wake und Post-Upgrade-Bereinigung sowie Plugin-Cache-Bereinigung schließen Reliability-Lücken, die sonst wie Orchestrierungsfehler aussehen.

Stop-Hook-Steuerung, sitzungsübergreifende Autorität und Multi-Agent v2 (Juni 2026)

Vier Änderungen von Anfang Juni sind für harness- und Multi-Agent-Design wichtig.⁵⁹

Stop/SubagentStop-Hooks erhielten einen Steuerungskanal. Seit Claude Code v2.1.163 kann ein Stop- oder SubagentStop-Hook hookSpecificOutput.additionalContext zurückgeben, um Claude Feedback zu geben und den Turn fortzusetzen, ohne dass die Antwort als Hook-Fehler markiert wird. Zuvor war der einzige echte Hebel eines Stop-Hooks der Exit-2-Block, der wie ein Fehler wirkt und auf das Limit für aufeinanderfolgende Blocks zählt. Für ein Quality-Gate-harness ist das die sauberere Primitive: Ein Stop-Hook, der erkennt „Sie sagen fertig, aber die Tests sind rot“, kann jetzt „das schlägt noch fehl, machen Sie weiter“ einspeisen, statt hart zu blockieren. Nutzen Sie den Block für echte Stop-Bedingungen und additionalContext für „noch nicht fertig, hier ist der Grund“.

Sitzungsübergreifendes Messaging trägt keine geliehene Autorität mehr. v2.1.166 hat den Multi-Session-Fall gehärtet: Nachrichten, die per SendMessage aus einer anderen Claude-Session weitergeleitet werden, tragen nicht mehr die Autorität des ursprünglichen Benutzers, sodass eine empfangende Session weitergeleitete Berechtigungsanfragen ablehnt und Auto Mode sie blockiert. Wenn Ihre Orchestrierung Agents einander Nachrichten senden lässt, behandeln Sie eine eingehende Nachricht als nicht vertrauenswürdige Daten, nicht als authentifizierte Anweisung. Das ist dasselbe Prinzip, das der Security-Abschnitt auf Tool-Ausgaben anwendet, erweitert auf Inter-Agent-Messaging.

Modellresilienz wurde zu einer First-Class-Einstellung. Die Einstellung fallbackModel verkettet jetzt bis zu drei Backup-Modelle, die der Reihe nach ausprobiert werden, wenn das Primärmodell überlastet oder nicht verfügbar ist, und ein Turn wird bei unerwarteten, nicht wiederholbaren API-Fehlern einmal automatisch mit dem Fallback erneut versucht. Für ein lang laufendes autonomes harness wird aus einem vorübergehenden Ausfall des Primärmodells eine geordnete Degradation statt eines abgebrochenen Laufs. claude agents --json ergänzte außerdem ein Feld waitingFor (v2.1.162), das sichtbar macht, worauf eine blockierte Hintergrund-Session wartet, etwa auf einen Berechtigungs-Prompt — ein Observability-Gewinn für jeden Coordinator, der eine Agent-Flotte pollt.

Safe Mode für Clean-Room-Governance und Troubleshooting. Claude Code v2.1.169 ergänzt ein Flag --safe-mode (und die passende Umgebungsvariable CLAUDE_CODE_SAFE_MODE), das eine Session startet, bei der alle Anpassungen auf einmal deaktiviert sind: CLAUDE.md, Plugins, skills, hooks und MCP-Server.⁶⁰ Das ist das Gegenteil des harness — ein bewusster Clean Room. Nutzen Sie es, um die Frage zu beantworten, die jeder Operator irgendwann stellt: „Kommt dieses Verhalten vom Modell oder von etwas, das ich konfiguriert habe?“ Wenn ein Hook falsch auslöst, ein skill aktiviert wird, obwohl er es nicht sollte, oder ein MCP-Server den Kontext vergiftet, gibt Ihnen --safe-mode eine bekannte leere Baseline zum Vergleich. Es ist auch eine Governance-Primitive: eine Möglichkeit, das reine Modell ohne die persistente Autorität auszuführen, die Ihr harness normalerweise gewährt. Das ist wichtig, wenn Sie ein Ergebnis reproduzieren müssen, ohne dass operator-definiertes Scaffolding es beeinflusst.

Ein Hinweis zu Modellstufen. Dieser Guide behandelt Opus 4.8 als agentic Default von Claude Code — das Modell, das autonome harnesses ausführt, sofern Sie nichts anderes auswählen. Am 9. Juni 2026 veröffentlichte Anthropic Claude Fable 5 (claude-fable-5), eine neue Stufe über Opus, beschrieben als das leistungsstärkste Modell — ein „Mythos-class“-System, das für die allgemeine Nutzung sicher gemacht wurde — auswählbar in Claude Code v2.1.170 über /model claude-fable-5.⁶⁰ Opus 4.8 bleibt der agentic Default; greifen Sie bewusst zur höheren Stufe, bei Entscheidungen, bei denen rohe Reasoning-Tiefe die Kosten rechtfertigt, nicht als pauschale Einstellung für eine Flotte.

Codex hat Multi-Agent v2 ausgeliefert. Codex CLI v0.137.0 belässt die Runtime-Wahl bei jedem Thread, stellt sauberere Follow-up- und Metadata-Defaults für gestartete Agents bereit (hide_spawn_agent_metadata ist jetzt standardmäßig true) und propagiert rohe Parent-Ereignisse an Child-Listener. Sein subagent-Modell bleibt explizit: eingebaute Agent-Typen default/worker/explorer, TOML-definierte Custom Agents und Concurrency-Steuerungen (agents.max_threads Standard 6, agents.max_depth Standard 1). Dasselbe Release ergänzt eine v1-skills-Erweiterung mit skill-catalog-Auflösung pro Turn und neuen Lifecycle-Contributor-Ereignissen thread-start/turn-error, wodurch die Lücke zur Hook-/skill-Oberfläche von Claude Code kleiner wird, während die Kernel-Sandbox-Haltung als Standardgrenze erhalten bleibt. Codex v0.138.0-v0.139.0 härtete Multi-Agent v2 anschließend für die Produktion: Inter-Agent-Message-Payloads sind jetzt verschlüsselt, ein v2-Agent-Config-Katalog plus eine Agent-Residency-LRU verwalten, welche Agents resident bleiben, und Concurrency wird nach aktiver Ausführung statt nach gestarteten Threads gezählt, sodass idle Agents keinen Slot mehr verbrauchen.⁶¹ Auch der Lifecycle-API ist gereift — close_agent wurde in interrupt_agent (v0.139.0) umbenannt, um klarzustellen, dass ein laufender Agent unterbrochen und nicht nur ein Handle geschlossen wird — und MCP-Startwarnungen, die von einem subagent ausgelöst werden, bleiben jetzt auf den zugehörigen Thread beschränkt, statt nach oben in das Transcript des Parents dupliziert zu werden.⁶¹ Für alle, die Codex-seitige Orchestrierung bauen, ist das der Unterschied zwischen Demo und Flotte: verschlüsselter Nachrichtentransport, begrenzte Residency, ausführungsgezählte Concurrency und Warnungen, die nicht über die Thread-Grenze lecken. Codex v0.140.0 öffnete dann eine Cross-Tool-Schnittstelle: /import zieht Setup, Projektkonfiguration und aktuelle Chats selektiv aus Claude Code in Codex, und Sessions wurden dauerhaft löschbar (codex delete / /delete, mit Bestätigungs-Safeguards).⁶⁴ /import ist die erste offizielle Anerkennung, dass Operatoren zwischen harnesses wechseln — die Konfiguration, die Sie für eines bauen, ist nicht mehr dort eingeschlossen.

Speicher und Kontext

Jede AI-Konversation läuft innerhalb eines begrenzten Kontextfensters. Wenn die Konversation wächst, komprimiert das System frühere Turns, um Platz für neue Inhalte zu schaffen. Diese Komprimierung ist verlustbehaftet. Architekturentscheidungen, die in Turn 3 dokumentiert wurden, überstehen Turn 15 möglicherweise nicht.⁹

Die drei Mechanismen des Multi-Turn-Zusammenbruchs

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

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

~/.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 hält Fehler, Entscheidungen und Muster über Sitzungen hinweg fest. 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 Ihnen in Python ein ähnlicher Integer-Grenzfall begegnet, macht der Eintrag in MEMORY.md dieses Muster wieder sichtbar.¹⁵

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

Speicherpflege statt Speichervolumen (Mai 2026): Ein aktuelles arXiv-Preprint zu LLM-Agent-Kooperation beschreibt erweiterte Erinnerung als möglichen Fehlermodus: In den Experimenten der Autoren verschlechterte eine längere sichtbare Historie die Kooperation in 18 von 28 Modell-Spiel-Settings.⁴⁸ Behandeln Sie das als Designwarnung, nicht als abschließendes Gesetz. Die Produktionsregel ist bereits klar genug: Halten Sie MEMORY.md kurz, verlinken Sie Details und schreiben Sie entscheidungsreife Zusammenfassungen in Handoffs. Rohdaten aus Transkripten, Tool-Logs und lange Recall-Feeds gehören in durchsuchbaren Speicher, nicht automatisch in den aktiven Prompt.

Strategie 2: Proaktive Kompaktierung

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

Wann Sie kompaktieren sollten: - Nach Abschluss einer klar abgegrenzten Teilaufgabe (Funktion implementiert, Bug behoben) - Bevor Sie in einem neuen Bereich der Codebasis beginnen - Wenn Claude anfängt, sich zu wiederholen oder früheren Kontext zu vergessen - Etwa alle 25-30 Minuten während intensiver Sitzungen

Benutzerdefinierte Kompaktierungsanweisungen in CLAUDE.md:

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

Kompaktierung schützt die Konversation; der /cd-Befehl (Claude Code v2.1.169) schützt den Prompt-Cache. Er verschiebt eine Sitzung mitten im Verlauf in ein neues Arbeitsverzeichnis, ohne den Cache zu brechen, der sich über den Turn aufgebaut hat.⁶⁰ Zuvor bedeutete ein Verzeichniswechsel eine neue Sitzung und einen kalten Cache. Für eine lange laufende Sitzung, die von einem Repository zu einem benachbarten Repository wechselt, was bei Monorepo- und Multi-Service-Arbeit häufig vorkommt, hält /cd das teure gecachte Präfix intakt und richtet zugleich den Dateisystemkontext neu aus.

Strategie 3: Sitzungs-Handoffs

Für Aufgaben, die sich über mehrere Sitzungen erstrecken, erstellen Sie Handoff-Dokumente, die den vollständigen Zustand festhalten:

## 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 gibt der Folgesitzung vollständigen Kontext bei minimalen Tokenkosten. Eine neue Sitzung mit claude -c (continue) zu starten oder das Handoff-Dokument zu lesen, führt direkt in die Implementierung.¹⁵

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

Für Sitzungen, die länger als 60-90 Minuten dauern, starten Sie pro Iteration eine frische Claude-Instanz. Der Zustand bleibt über das Dateisystem bestehen, nicht über die Konversationserinnerung. 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

Vergleich 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 Orientierungsschritt (Zustandsdateien lesen, Git-Historie scannen) gegen volle kognitive Ressourcen pro Iteration.¹⁶ Die Kosten-Nutzen-Rechnung: Für Sitzungen unter 60 Minuten ist eine einzelne Konversation effizienter. Ab 90 Minuten liefert frischer Kontext trotz Overhead höherwertige Ergebnisse.

Strategie 5: Verwaltete Speicherpflege (Dreaming)

Die Claude Managed Agents von Anthropic haben am 6. Mai 2026 Dreaming als Research Preview hinzugefügt.³⁵ Laut Anthropic: “Dreaming is a scheduled process that reviews your agent sessions and memory stores, extracts patterns, and curates memories so your agents improve over time.”³⁵

Dreaming läuft zwischen Sitzungen im Hintergrund, nicht auf dem kritischen Pfad. Es ergänzt das Muster Dateisystem-als-Speicher, statt es zu ersetzen: Ihre Datei MEMORY.md bleibt die tragende Oberfläche; Dreaming schreibt kuratierte Speichereinträge in den Speicher der Managed Agents, den der Agent beim Sitzungsstart liest. Beide Muster können in harnesses koexistieren, die selbst gehosteten Dateisystemzustand mit verwalteter Kuratierung kombinieren.

Dreaming ist in Research Preview, daher kann sich das Verhalten ändern. Die oben dokumentierten Muster für Sitzungs-Handoffs und CLAUDE.md bleiben der maßgebliche Speichermechanismus für selbst gehostete harnesses.

Die Anti-Patterns

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

Ausführliche Fehlerausgaben im Kontext behalten. Nach dem Debugging eines Bugs enthält Ihr Kontext 40+ Stacktraces aus fehlgeschlagenen Iterationen. Ein einzelnes /compact nach der Fehlerbehebung entfernt 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 100.000+ Tokens unnötigen Vorab-Ladens.¹⁵

Subagent-Muster

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

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 dabei eine vollständig isolierte Kopie des Repository:⁵

---
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 für experimentelle Arbeiten unerlässlich, die die Codebase beschädigen könnten.

Parallele Subagents

Verwenden Sie parallele subagents für unabhängige Rechercheaufgaben, die sich nicht miteinander abstimmen müssen:⁵

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

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

Der Rekursionsschutz

Ohne Spawn-Limits delegieren Agents an Agents, die wiederum an Agents delegieren, wobei jeder Kontext verliert und Tokens verbrennt. Das Muster für Rekursionsschutz setzt Budgets durch:¹⁶

#!/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"

Kritische 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 Parent, begrenzt durch ein konfigurierbares Maximum. Das Budgetmodell bildet den tatsächlichen Fehlermodus ab (zu viele Agents insgesamt) statt einer Ersatzmetrik (zu viele Verschachtelungsebenen).⁷

Rekursive Delegierung ist jetzt eine First-Party-Tiefe. Seit Claude Code v2.1.172 (10. Juni 2026) können sub-agents ihre eigenen sub-agents spawnen, verschachtelt bis zu 5 Ebenen tief — zuvor war Delegierung praktisch auf eine Ebene begrenzt.⁶² Dadurch wird der obige Rekursionsschutz wichtiger, nicht weniger wichtig: Die Plattform erlaubt nun genau jene Agent-an-Agent-Delegierungsketten, die Kontext und Tokens verbrennen. Deshalb sind Spawn-Budget und Tiefenlimit das, was einen Baum mit 5 Ebenen daran hindert, sich zu Hunderten aktiver Agents aufzufächern. Behandeln Sie 5 Ebenen als von der Plattform erlaubte Obergrenze, nicht als Standardziel.

Auto-Modus prüft Spawns jetzt vor dem Start. Claude Code v2.1.178 hat die Governance-Lücke beim Matching geschlossen: Im Auto-Modus werden subagent-Spawns vom Berechtigungsklassifizierer vor dem Start des subagent bewertet, nicht erst, sobald er Aktionen ausführt.⁶³ Zuvor konnte ein subagent gespawnt werden, um eine Aktion anzufordern, die der Parent-Sitzung untersagt gewesen wäre — der Spawn selbst war die Umgehung. Die Prüfung zum Spawn-Zeitpunkt bedeutet, dass Rekursionsschutz und Berechtigungsmodell endlich zusammenlaufen: Ein Child kann nicht als Verschleierungsschritt für eine Aktion verwendet werden, die die Richtlinie verbietet.

Agent Teams (Research Preview)

Agent Teams koordinieren mehrere Claude Code-Instanzen, die unabhängig arbeiten, über eine gemeinsame Mailbox und Aufgabenliste kommunizieren und die Ergebnisse der jeweils anderen infrage stellen können:⁵

Aktivieren mit: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Wann Sie Agent Teams statt subagents verwenden sollten:

Agent View und Goal Loops (Mai 2026)

Claude Code v2.1.139 fügte Agent View hinzu, eine Research-Preview-Oberfläche, die mit claude agents gestartet wird und laufende, blockierte und abgeschlossene Claude Code-Sitzungen auf einem Bildschirm zeigt.⁴²⁴³ Die offiziellen Dokumente beschreiben sie als Möglichkeit, viele Sitzungen zu dispatchen und zu verwalten, zu sehen, was jede Sitzung tut, und zu erkennen, welche Sitzungen Eingaben durch einen Operator benötigen.⁴³ Damit erhält Multi-Agent-Arbeit eine Betriebsansicht, die abschließende Zusammenfassungen nicht liefern können.

Verwenden Sie Agent View, wenn Sie ein subagent- oder Team-Muster hochstufen: Prüfen Sie, welche Sitzungen blockiert sind, welche noch laufen und ob die Arbeitsverteilung zur beabsichtigten Architektur passt. Behandeln Sie sie nicht als Qualitätsnachweis. Sie ist Observability; Tests, Review-Gates und Evidence-Reports entscheiden weiterhin, ob die Arbeit solide ist.

Dieselbe Version fügte /goal hinzu, das eine Abschlussbedingung setzt und Claude über Turns hinweg weiterlaufen lässt, bis die Bedingung erfüllt ist, einschließlich interaktiver Nutzung, -p und Remote Control.⁴² Behandeln Sie /goal als sitzungsbezogene Completion-Loop, nicht als Ersatz für deterministische Gates. Es ist nützlich, um einen Agent auf ein Ziel fokussiert zu halten, aber Tests, Zitationsprüfungen, Deployment-Prüfungen und Security-hooks sollten dort befehls- oder skriptgestützt bleiben, wo ein Fehlschlag blockieren muss.

Workflow-Tool (v2.1.147+)

Claude Code v2.1.147 ergänzt ein standardmäßig deaktiviertes Workflow-Tool für deterministische Multi-Agent-Orchestrierung. Aktivieren Sie es mit CLAUDE_CODE_WORKFLOWS=1.⁵² Architektonisch ist das wichtig, weil Claude Code damit ein First-Party-Orchestrierungsprimitiv für Abläufe erhält, die zuvor eigene dispatcher-Skripte, Mailbox-State und subagent-Koordinationskonventionen erforderten.

Löschen Sie nicht den harness darum herum. Ein Workflow kann die Ausführung strukturieren, ersetzt aber nicht Ihr Sicherheitsmodell. Behalten Sie PreToolUse- und PostToolUse-hooks als blockierende Ebene bei, behalten Sie Spawn-Budgets oder Workflow-Schrittbudgets bei, um ausufernde Breite zu verhindern, halten Sie den Dateisystemzustand auditierbar und führen Sie abschließende Evidence-Reports außerhalb der Selbsteinschätzung des Modells. In der Praxis: Verwenden Sie Workflow für die Orchestrierungsform; verwenden Sie hooks, Tests und Review-Gates für die Wahrheit.

Multi-Agent-Orchestrierung

Single-Agent-KI-Systeme 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 festgeschrieben 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 ausführt, jeder mit isoliertem Container, Git-Worktree und eigenen Credentials. Läuft lokal, im Hub oder auf Kubernetes. Explizite Philosophie: „Isolation statt Beschränkungen” — Agenten laufen mit hoher Autonomie innerhalb von Grenzen, die auf der Infrastrukturebene durchgesetzt werden, nicht im Prompt.²⁵ Dies erweitert das Argument der Subagent-Isolation direkt auf verschiedene Tool-Anbieter. Wenn Ihr Workflow Claude und OpenAI-Modelle umfasst, ist Scion die erste echte Referenzimplementierung für tool-übergreifende Subagenten mit Worktree- und Credential-Isolation pro Agent.

Debatte ist keine Wunderwaffe: Der Forschungscluster M3MAD-Bench (Anfang 2026) hat festgestellt, dass Multi-Agent-Debatten ein Plateau erreichen und durch irreführenden Konsens unterlaufen werden können — gültige Argumente verlieren, wenn andere Agenten selbstbewusst die falsche Antwort behaupten.²⁶ Tool-MAD verbessert dies, indem jedem Agenten heterogener Tool-Zugriff gewährt wird und in der Judge-Phase Faithfulness-/Relevance-Scores verwendet werden. Wenn Sie debattenartige Orchestrierung aufbauen, investieren Sie in (a) Tool-Heterogenität pro Agent und (b) quantitatives Judge-Scoring, anstatt anzunehmen, dass mehr Agenten = bessere Antworten bedeutet.

Managed Multiagent Orchestration und Outcomes (Public Beta)

Wenn Sie die unten beschriebene Deliberations-Infrastruktur nicht selbst aufbauen möchten, ist Multiagent Orchestration am 6. Mai 2026 in Claude Managed Agents in die Public Beta gegangen.³⁵ Laut Anthropic: „Wenn die Arbeit für einen einzelnen Agenten zu umfangreich ist, um sie gut zu erledigen, ermöglicht Multiagent Orchestration einem Lead-Agenten, die Aufgabe in Teile aufzubrechen und jedes davon an einen Spezialisten mit eigenem Modell, Prompt und eigenen Tools zu delegieren.”³⁵ Spezialisten „arbeiten parallel auf einem gemeinsamen Dateisystem und tragen zum Gesamtkontext des Lead-Agenten bei.”³⁵

Tracing ist sofort einsatzbereit. Laut Anthropic: „Sie können außerdem jeden Schritt in der Claude-Konsole nachverfolgen: welcher Agent was wann und warum getan hat — was Ihnen vollständige Transparenz darüber gibt, wie Ihre Aufgabe delegiert und ausgeführt wurde.”³⁵

Die ergänzende Public-Beta-Funktion ist Outcomes. Laut Anthropic: „Sie schreiben eine Rubric, die beschreibt, wie Erfolg aussieht, und der Agent arbeitet darauf hin. Ein separater Grader bewertet die Ausgabe in seinem eigenen Kontextfenster anhand Ihrer Kriterien, sodass er nicht durch das Reasoning des Agenten beeinflusst wird.”³⁵ Dies ist die Managed-Service-Variante des Two-Gate-Validierungsmusters, das später in diesem Abschnitt dokumentiert wird: Die Rubric ersetzt das handgeschriebene Gate, der separate Grader ersetzt den Konsens-Validator.

Selbstgehostete Deliberation bleibt die richtige Antwort, wenn die Validierung in Ihre eigene Hook-Oberfläche integriert werden muss (PreToolUse-Blocking, Exit-Code-Semantik, eigene Dispatcher) oder wenn die Harness ohne externe Abhängigkeiten laufen muss. Managed Multiagent ist die richtige Antwort, wenn Standard-Delegation plus Rubric-Grading der Vertrag ist, den Sie tatsächlich benötigen.

Minimal tragfähige 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 inkrementelle Verbesserungen.

Der Confidence-Trigger

Nicht jede Aufgabe braucht Deliberation. Ein Modul für Konfidenz-Scoring bewertet vier Dimensionen:¹⁷

1. Mehrdeutigkeit – Hat die Anfrage mehrere gültige Interpretationen?
2. Domänenkomplexität – Erfordert sie spezialisiertes Wissen?
3. Tragweite – Ist die Entscheidung umkehrbar?
4. Kontextabhängigkeit – Erfordert sie ein Verständnis des breiteren Systems?

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. Damit wird Over-Engineering bei einfachen Aufgaben verhindert, während riskante Entscheidungen geprüft werden.⁷

Die State Machine

Sieben Phasen, jede vom Abschluss der vorherigen abhängig:⁷

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). Kontextisolation stellt sicher, dass Agenten während der Recherche die Erkenntnisse der anderen nicht sehen können.

DELIBERATION: 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 Two-Gate-Validierungsarchitektur

Zwei Validierungs-Gates fangen Probleme in unterschiedlichen Phasen ab:⁷

Gate 1: Consensus-Validierung (PostToolUse-Hook). Läuft unmittelbar nach Abschluss jedes Deliberations-Agenten: 1. Die Phase muss mindestens RANKING erreicht haben 2. Mindestens 2 Agenten abgeschlossen (konfigurierbar) 3. Der Consensus-Score erreicht den aufgaben-adaptiven Schwellenwert 4. Wenn ein Agent abweichender Meinung war, müssen die Bedenken dokumentiert sein

Gate 2: Pride Check (Stop-Hook). Läuft, bevor die Sitzung geschlossen werden kann: 1. Vielfältige Methoden: mehrere einzigartige Personas vertreten 2. Widerspruchstransparenz: Abweichungen haben dokumentierte Gründe 3. Komplexitätsbehandlung: mindestens 2 Alternativen generiert 4. Consensus-Konfidenz: klassifiziert als stark (über 0,85) oder moderat (0,70–0,84) 5. Verbesserungsnachweis: Die Endkonfidenz übersteigt die Anfangskonfidenz

Zwei Hooks an unterschiedlichen Lifecycle-Punkten passen dazu, wie Fehler tatsächlich auftreten: Manche sind sofort sichtbar (schlechter Score), andere schleichend (geringe Vielfalt, fehlende Dokumentation von Abweichungen).⁷

Warum Übereinstimmung gefährlich ist

Charlan Nemeth erforschte den Minderheits-Widerspruch von 1986 bis zu ihrem Buch In Defense of Troublemakers aus dem Jahr 2018. Gruppen mit Andersdenkenden treffen bessere Entscheidungen als Gruppen, die schnell zu einer Einigung gelangen. Der Andersdenkende muss nicht recht haben. Allein der Akt des Widerspruchs zwingt die Mehrheit, Annahmen zu prüfen, die sie sonst übergehen würde.¹⁸

Wu et al. testeten, ob LLM-Agenten wirklich debattieren können, und stellten fest, dass Agenten ohne strukturelle Anreize für Widerspruch unabhängig von der Korrektheit zu der initial selbstbewusstesten Antwort konvergieren.¹⁹ Liang et al. identifizierten als Grundursache die „Degeneration-of-Thought”: Sobald ein LLM Vertrauen in eine Position aufgebaut hat, kann Selbstreflexion keine neuen Gegenargumente mehr erzeugen, weshalb Multi-Agent-Bewertung strukturell notwendig ist.²⁰

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

Vorgetäuschte Übereinstimmung erkennen

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

Score-Clustering: Wenn jeder Agent auf einer 10-Punkte-Skala innerhalb von 0,3 Punkten bewertet, deutet dies auf gemeinsame Kontextkontamination statt auf unabhängige Bewertung hin. Als fünf Agenten, die ein Authentifizierungs-Refactoring bewerteten, das Sicherheitsrisiko durchgängig zwischen 7,1 und 7,4 einstuften, streuten die Scores nach erneutem Durchlauf mit frischer Kontextisolation auf 5,8–8,9.

Boilerplate-Widerspruch: Agenten, die die Bedenken-Sprache der anderen kopieren, anstatt unabhängige Einwände zu formulieren.

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

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 Consensus- und Pride-Check-Gates eine ausreichende Validierung.

Was bei der Deliberation nicht funktioniert hat

Freie Debattenrunden. Drei Runden Hin-und-Her-Text zu einer Diskussion über Datenbankindizierung erzeugten 7.500 Tokens an Debatte. Runde 1: echter Widerspruch. Runde 2: erneut formulierte Positionen. Runde 3: identische Argumente in anderen Worten. Strukturiertes Dimensions-Scoring ersetzte die freie Debatte, senkte die Kosten um 60 % und verbesserte gleichzeitig die Ranking-Qualität.⁷

Einzelnes Validierungs-Gate. Die erste Implementierung führte einen einzigen Validierungs-Hook am Sitzungsende aus. Ein Agent schloss die Deliberation mit einem Consensus-Score von 0,52 ab (unter dem Schwellenwert), arbeitete dann 20 Minuten an unabhängigen Aufgaben weiter, bevor der Sitzungsende-Hook das Versagen meldete. Die Aufteilung in zwei Gates (eines bei Aufgabenabschluss, eines am Sitzungsende) fing dieselben Probleme an unterschiedlichen Lifecycle-Punkten ab.⁷

Kosten der Deliberation

Jeder Recherche-Agent verarbeitet etwa 5.000 Tokens Kontext und erzeugt 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 aktuellen Opus-Preisen kostet eine 3-Agenten-Deliberation ungefähr 0,68–0,90 USD. Eine 10-Agenten-Deliberation 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 0,23–0,30 USD pro Sitzung betragen. 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 AI agent, kein 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 „done“ aussieht.

Die Precedence-Hierarchie

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

Was ignoriert wird

Diese Muster erzeugen zuverlässig keine beobachtbare Änderung im Agent-Verhalten:²¹

Prosabsätze ohne Befehle. „Wir legen Wert auf sauberen, gut getesteten Code“ ist Dokumentation, keine operative Anweisung. Der Agent liest es und schreibt anschließend Code ohne Tests, weil es keine umsetzbare Anweisung gibt.

Mehrdeutige Anweisungen. „Seien Sie vorsichtig mit Datenbankmigrationen“ ist keine Einschränkung. „Führen Sie alembic check aus, bevor Sie Migrationen anwenden. Brechen Sie ab, wenn der Downgrade-Pfad fehlt.“ ist eine.

Widersprüchliche Prioritäten. „Schnell vorankommen und zügig 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. „Befolgen Sie den Google Python Style Guide“ ohne ruff check --select D gibt dem Agent keinen Mechanismus, die Einhaltung zu überprüfen.

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`

Aufgabenorientierte 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

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

1. Build- und Testbefehle (der Agent braucht diese, bevor er etwas Nützliches tun kann)
2. Definition of done (verhindert falsche Abschlussmeldungen)
3. Eskalationsregeln (verhindert destruktive Workarounds)
4. Aufgabenorientierte Abschnitte (reduziert das Parsen irrelevanter Anweisungen)
5. Verzeichnis-Scoping (Monorepos: hält Service-Anweisungen isoliert)

Überspringen Sie Stilpräferenzen, bis die ersten vier Punkte 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 Importebenen.⁶

Toolübergreifende Anweisungskompatibilität

AGENTS.md ist ein offener Standard, der von allen wichtigen AI-Coding-Tools erkannt 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, aufgabenorientiert) funktionieren in jeder Anweisungsdatei unabhängig vom Tool. Pflegen Sie keine parallelen Anweisungssätze, die auseinanderdriften. Schreiben Sie eine maßgebliche Quelle und spiegeln Sie sie.

Codex-Paritätshinweise

Codex verfügt inzwischen über erstklassige Entsprechungen für die wichtigsten harness-Schichten, aber die Migration ist eine Musterübersetzung, keine Dateikopie. Codex liest AGENTS.md, bevor die Arbeit beginnt, und schichtet globale Vorgaben aus ~/.codex mit Projekt- und verschachtelten Repository-Anweisungen.³¹ Codex skills verwenden dasselbe SKILL.md-Denkmodell mit progressive disclosure: Codex beginnt mit Skill-Name, Beschreibung und Dateipfad und lädt den vollständigen Skill erst, wenn es entscheidet, ihn zu verwenden.³² Codex hat außerdem native hooks, plugin-gebündelte hooks, managed hooks, MCP-Unterstützung und explizite subagent-Workflows.³³³⁴

Codex v0.138.0–v0.139.0 hat diese AGENTS.md-Erkennung für nicht triviale Workspaces gehärtet: Das Laden läuft jetzt über die Dateisystemabstraktion der Umgebung und bewahrt logische Pfade während des Discovery-Walks, sodass die richtige Datei ausgewählt wird, selbst wenn der Workspace ein Remote-Dateisystem oder ein symlinkter Baum ist.⁶¹ Das ist immer dann wichtig, wenn Ihr kanonisches AGENTS.md die maßgebliche Quelle ist und der Agent über einen gemounteten, container-materialisierten oder symlinkten Checkout arbeitet — also genau in den Fällen, in denen ein naiver Pfad-Walk stillschweigend die falsche Anweisungsdatei oder gar keine auswählt. Wenn Sie ein maßgebliches AGENTS.md über Services hinweg spiegeln, behandeln Sie dies als Mindestniveau, um darauf zu vertrauen, dass die vom Agent tatsächlich geladene Datei die ist, die Sie geschrieben haben.

Codex v0.141.0 hat anschließend den Remote-Execution-Pfad selbst gehärtet: Remote-Executors verbinden sich jetzt über authentifizierte, Ende-zu-Ende-verschlüsselte Noise-relay channels (Control Plane und Executor vertrauen dem Relay zwischen ihnen nicht mehr), plattformübergreifende Remote Execution bewahrt das native Arbeitsverzeichnis und die Shell des Executors, und TLS akzeptiert P-521-Zertifikatsignaturen für Enterprise-Proxys.⁶⁵ Wenn Ihre Orchestrierung Codex-Executors über eine Netzwerkgrenze hinweg steuert, ist das der Unterschied zwischen einer Trusted-Relay-Annahme und einer Ende-zu-Ende-verschlüsselten Annahme — behandeln Sie es als Basis für jede Remote-Executor-Topologie.

Die praktische Zuordnung:

Der wichtige Unterschied: Claude subagents können anhand von Beschreibungen automatisch ausgewählt werden, während Codex subagent-Workflows derzeit als explizit dokumentiert. Deshalb sind skills und hooks in Codex die richtige Voreinstellung für dauerhaft aktives harness-Verhalten; subagents eignen sich für bewusst angestoßene parallele Arbeit, Reviews und Exploration.

Ihre Anweisungen testen

Prü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 Härtetest: Bitten Sie den Agent, Ihre Build-Befehle zu erklären. Wenn er sie nicht wortgetreu wiedergeben kann, sind die Anweisungen entweder zu ausführlich (Inhalt wurde aus dem Kontext gedrängt), zu vage (der Agent kann keine umsetzbaren Anweisungen extrahieren) oder werden nicht gefunden. Die Analyse von GitHub über 2.500 Repositories ergab, dass Unschärfe die meisten Fehler verursacht.²¹

Production Patterns

Opus 4.7 Long-Horizon Patterns (April 2026)

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

• Tool-failure Resilience: Opus 4.7 arbeitet auch nach Tool-Fehlern weiter, die Opus-4.6-Sitzungen angehalten hätten. Sie können defensive Retry-Wrapper im subagent-Code reduzieren, aber nicht vollständig entfernen. Behalten Sie die Guards auf hook-Ebene bei; kürzen Sie das In-Prompt-Gerüst nach dem Muster „wenn das Tool fehlschlägt, versuchen Sie es dreimal erneut“.
• xhigh Effort-Tier (nur Opus-4.7): Liegt zwischen high und max. Empfohlener Standard für Coding- und agentische Workloads. Bei lang laufenden subagents übertrifft xhigh high deutlich, bei unterproportionalen Token-Kosten. max bleibt die richtige Wahl für schwieriges Single-Shot-Reasoning; xhigh eignet sich besser für ausdauernde Aufgaben.
• Token-Budget-Obergrenze: Pro Agent-Lauf über output_config.task_budget konfigurierbar (Beta-Header task-budgets-2026-03-13). Das Modell sieht einen laufenden Countdown und grenzt die Arbeit elegant auf das Budget ein, statt unerwartet auszulaufen. Nutzen Sie dies für agentische Schleifen, wenn Sie vorhersehbare Token-Ausgaben möchten, ohne bei kurzen Prompts Qualität zu opfern.
• Bewusstsein für implizite Bedürfnisse: Erstes Claude-Modell, das „implicit-need“-Tests besteht, also erkennt, wenn die wörtliche Anfrage des Benutzers nicht vollständig beschreibt, was tatsächlich gebraucht wird. Dadurch wird der Abschnitt „Clarifying Rules“ in CLAUDE.md weniger notwendig. Wenn Ihre CLAUDE.md aus 200 Zeilen „auch X berücksichtigen, wenn der Benutzer nach Y fragt“-Guardrails besteht, kürzen Sie die Regeln, die nun nativ abgedeckt sind.

Worktree Base, Sandbox-Pfade und Admin-Einstellungen (7. Mai 2026)

Claude Code v2.1.133 ergänzt vier Admin-Tier-Einstellungen, die für Produktions-Harnesses wichtig sind:³⁹

Die Rücknahme bei worktree.baseRef sollten Sie Benutzern besonders markieren: Agents, die sich auf das Verhalten von v2.1.128 bis v2.1.132 verlassen haben (Worktrees verzweigen von lokalem HEAD), verlieren in frischen Worktrees Zugriff auf nicht gepushte Arbeit, sofern sie nicht explizit zurückwechseln.

OTel-Feedbackumfrage für Enterprise Observability (8. Mai 2026)

Claude Code v2.1.136 fügte CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL hinzu, um die Qualitätumfrage innerhalb der Sitzung für Unternehmen wieder zu aktivieren, die die Antworten über OpenTelemetry erfassen.⁴⁰ Wenn Ihre Organisation OTel-Events in einen zentralen Observability-Stack leitet, bringt diese Umgebungsvariable die Umfrage zurück in den Datenpfad, sodass Qualitätssignale durch dieselbe Pipeline fließen wie Latenz- und Fehlermetriken. Behandeln Sie sie als Opt-in: Standardmäßig bleibt die Umfrage unterdrückt, was für Nicht-OTel-Deployments korrekt ist.

Der Quality Loop

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

1. Implementieren - Schreiben Sie den Code
2. Reviewen - Lesen Sie jede Zeile erneut. Finden Sie Tippfehler, Logikfehler und unklare Abschnitte
3. Evaluieren - Führen Sie das evidence gate aus. Prüfen Sie Muster, Edge Cases und Testabdeckung
4. Verfeinern - Beheben Sie jedes Problem. Verschieben Sie nichts auf „später“
5. Herauszoomen - Prüfen Sie Integrationspunkte, Imports und angrenzenden Code auf Regressionen
6. Wiederholen - Wenn ein Kriterium des evidence gate fehlschlägt, kehren Sie zu Schritt 4 zurück
7. Berichten - Listen Sie auf, was geändert wurde, wie es verifiziert wurde, und zitieren Sie konkrete Evidenz

Das Evidence Gate

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

Wenn Sie für eine Zeile keine Evidenz liefern können, kehren Sie zu Verfeinern zurück.²²

Menschliche Merge-Autorität

Eine arXiv-Studie vom Mai 2026 zu 29.585 Pull-Request-Lebenszyklen von AI agents trennt operative Agency von Merge-Governance.⁴⁷ Die nützliche Architekturlektion ist einfach: Agents können Arbeit beginnen, Branches vorantreiben, PRs öffnen, Arbeit reviewen und Risiken zusammenfassen, während Merge-Autorität eine separate Governance-Grenze bleibt.

Machen Sie diese Grenze im Harness explizit. Lassen Sie Agents PRs vorbereiten und Evidenz sammeln; verlangen Sie menschliche Freigabe für Merges, Releases und destruktive Repository-Operationen, sofern die Organisation keine separat auditierte Automatisierungsrichtlinie hat. Wo Automatisierung einen Merge ausführt, bewahren Sie Logs auf, die den Executor von der Person oder Richtlinie unterscheiden, die ihn autorisiert hat.

Error-Handling-Patterns

Atomare Dateischreibvorgänge. Wenn mehrere Agents gleichzeitig in dieselbe State-Datei schreiben, wird JSON beschädigt. Schreiben Sie in .tmp-Dateien und verwenden Sie anschließend atomar 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 nach State-Beschädigung. Wenn State beschädigt wird, erstellt das Recovery-Pattern ihn aus sicheren Standardwerten neu, statt 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 0 ist, weil 0++ zu 0 ausgewertet wird, was bash als false behandelt. Mit aktiviertem set -e beendet das das Skript. Verwenden Sie stattdessen VAR=$((VAR + 1)).¹⁶

Blast-Radius-Klassifizierung

Klassifizieren Sie jede Agent-Aktion nach Blast Radius und gaten Sie entsprechend:²

Remote Control (Verbindung zu lokalem Claude Code aus jedem Browser oder jeder mobilen App) macht aus dem blockierenden Warten am „Extern“-Gate eine asynchrone Benachrichtigung. Der Agent arbeitet an der nächsten Aufgabe weiter, während Sie die vorherige vom Smartphone aus prüfen.²

Aufgabenspezifikation für autonome Läufe

Wirksame 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 verifizierbar sein: Test bestanden/fehlgeschlagen, Linter-Ausgabe, HTTP-Statuscodes, Prüfungen auf Dateiexistenz. Eine frühe Aufgabe, die den Agent bat, „Tests zu schreiben, die bestehen“, erzeugte assert True und assert 1 == 1. Technisch korrekt. Praktisch wertlos.¹⁶

Failure Modes, 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. Dispatcher injiziert: aktuelles Datum, Projekterkennung, philosophische Constraints, Initialisierung der Kostenerfassung. Fünf hooks, insgesamt 180 ms.

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

3. Agent ruft Bash auf, um Tests auszuführen. PreToolUse:Bash feuert. Credential-Prüfung, Sandbox-Validierung, Projekterkennung. 90 ms. Tests laufen. PostToolUse:Bash feuert: Aktivitäts-Heartbeat protokolliert, Drift-Prüfung.

4. Agent ruft Write auf, um eine Datei zu erstellen. PreToolUse:Write feuert: Prüfung des Dateiscopes. PostToolUse:Write feuert: Lint-Prüfung, Commit-Tracking.

5. Agent schließt die Story ab. Stop feuert. Quality Gate prüft: Hat der Agent Evidenz zitiert? Hedging-Sprache? TODO-Kommentare im Diff? Wenn eine Prüfung fehlschlägt, Exit 2, und der Agent fährt fort.

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

7. Drei Code-Review-Agents starten parallel. Jeder reviewt den Diff unabhängig. Wenn ein Reviewer CRITICAL meldet, geht die Story zurück in die Queue.

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

Über 5 Stories hinweg ausgelöste hooks insgesamt: ~340. Gesamtzeit in hooks: ~12 Sekunden. Dieser Overhead verhinderte in einem einzigen Overnight-Run drei Credential-Leaks, einen destruktiven Befehl und zwei unvollständige Implementierungen.

Fallstudie: Overnight-PRD-Verarbeitung

Ein Produktions-Harness verarbeitete 12 PRDs (47 Stories) über 8 Overnight-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 machten das Rotieren von API-Schlüsseln und Audits nachgelagerter Dienste erforderlich: ungefähr 4 Stunden Incident Response. Der Harness-Overhead, der das Äquivalent verhinderte, betrug 2,4 Sekunden bash pro Story. Die False-Completion-Rate sank von 35 % auf 4 %, weil der Stop hook unabhängig Tests ausführte, bevor der Agent „fertig“ melden durfte.

Sicherheitsüberlegungen

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

Anthropic veröffentlichte am 9. April 2026 ein formales Framework für die Vertrauenswürdigkeit von Agents.²⁷ Die fünf Prinzipien entsprechen dem Evidence-Gate-Denken in diesem Leitfaden und erweitern es:

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

Skill-Sandbox-Tooling: Für Teams, die skills als Angriffsfläche behandeln, führt Permisos SandyClaw (gestartet am 2. April 2026) skills in einer dedizierten Sandbox aus und liefert evidenzgestützte Bewertungen aus Sigma-/YARA-/Nova-/Snort-Erkennung. Erstes Produkt in der Skill-Sandbox-Kategorie.²⁸

Die Sandbox

Claude Code unterstützt einen optionalen Sandbox-Modus (aktiviert über settings.json oder den Befehl /sandbox), der Netzwerkzugriff und Dateisystemoperationen über Isolation auf Betriebssystemebene einschränkt (seatbelt unter macOS, bubblewrap unter Linux). Ist die Sandbox aktiviert, hindert sie das Modell daran, beliebige Netzwerkanfragen zu stellen oder auf Dateien außerhalb des Projektverzeichnisses zuzugreifen. Ohne Sandbox nutzt Claude Code ein berechtigungsbasiertes Modell, bei dem Sie einzelne Tool-Aufrufe genehmigen oder ablehnen.¹³

Security-Mindeststand Mai 2026. Claude Code v2.1.149 behob einen PowerShell-Working-Directory-Permission-Bypass, mehrere Lücken in PowerShell-Allow-Regeln und der Permission-Analyse mit veralteten Variablen sowie einen git-worktree-Sandbox-Write-Allowlist-Bug, der den gesamten Root des Hauptrepositorys statt nur gemeinsam genutzter git-Interna abdeckte.⁵³ Wenn Ihr harness PowerShell oder worktree-isolierte Agents zulässt, behandeln Sie v2.1.149+ als Mindeststand und halten Sie Shell-Regeln eng. Breite PowerShell(*)-Regeln und Schreibausnahmen für das gesamte Repository sind Orchestrierungsabkürzungen, keine Sicherheitsgrenzen.

OpenAI Agents SDK Sandbox-Lockdown (v0.17.0, 8. Mai 2026). Auf OpenAI-Seite verschärfte openai-agents-python v0.17.0 eine parallele Grenze: LocalFile.src und LocalDir.src sind jetzt auf die Materialisierungs-base_dir beschränkt (das aktuelle Arbeitsverzeichnis des SDK-Prozesses, wenn das Manifest angewendet wird), es sei denn, die Quelle wird explizit über Manifest.extra_path_grants mit SandboxPathGrant freigegeben.⁴¹ Relative lokale Quellen werden von base_dir aus aufgelöst; absolute Pfade müssen bereits darin liegen oder eine Freigabe besitzen. Das schließt ein Problem an der Grenze lokaler Artefakte: Frühere Versionen erlaubten Manifesten, beliebige Host-Pfade in einen Sandbox-Workspace zu ziehen. Migration: Deklarieren Sie vertrauenswürdige Host-Roots auf Manifestebene mit SandboxPathGrant(path=..., read_only=True) für Read-only-Mounts. Behandeln Sie extra_path_grants als vertrauenswürdige Anwendungskonfiguration; befüllen Sie Grants niemals aus Modellausgaben oder nicht vertrauenswürdigen Manifest-Eingaben.

OpenAI Agents SDK Follow-up-Mindeststand (v0.17.3). Die Linie 0.17.1-0.17.3 ergänzte weitere Sandbox- und Session-Härtung: Limits für Archive-Extraktion, GitRepo-Subpath-Validierung, klarere Sandbox-Provider-Fehler, Mountpoint-Anmeldeinformationen außerhalb von Sandbox-Befehlen, Ablehnung relativer Sandbox-Workspace-Roots und Terminal-State-Handling für Vercel-Sandboxen.⁵⁴ Wenn Sie OpenAI-gehostete oder provider-gestützte Sandboxen statt nur Claude Code hooks verwenden, behandeln Sie 0.17.3 als aktuellen Mindeststand für die Muster in diesem Abschnitt.

Berechtigungsgrenzen

Das Berechtigungssystem steuert Operationen auf mehreren Ebenen:

Berechtigungsregeln auf Parameterebene (Juni 2026)

Claude Code v2.1.178 erweiterte Berechtigungsregeln von der Tool-Ebene hinunter auf die Parameterebene: Tool(param:value) wird gegen die Eingabeparameter eines Tools abgeglichen, wobei * als Wildcard dient. Das kanonische Beispiel ist Agent(model:opus), eine Regel, die verhindert, dass subagents auf einer bestimmten Modellstufe gestartet werden.⁶³ Architektonisch schließt das eine Lücke, die die obige Tabelle mit vier Ebenen nicht ausdrücken konnte: Zuvor konnten Sie ein Tool pauschal erlauben oder verweigern, aber nicht einschränken, wie es aufgerufen wurde. Eine Governance-Policy kann jetzt deterministisch festlegen: „subagents dürfen gestartet werden, aber nicht auf der Fable-5-Stufe” oder „Bash ist erlaubt, aber nicht mit diesem Flag”, statt dies nur als Prompt-Anweisung zu formulieren.

Eine begleitende Managed Setting, enforceAvailableModels (v2.1.175), beschränkt die Modellauswahl von oben herab: Sie pinnt das Default-Modell und verhindert, dass Benutzer- oder Projekteinstellungen die verwaltete availableModels-Allowlist erweitern.⁶³ Beide greifen ineinander: Die Allowlist definiert, welche Stufen für die Session überhaupt existieren, und Regeln auf Parameterebene begrenzen, wie subagents daraus auswählen.

Auto-Mode-Guardrails für destruktive Befehle (Juni 2026)

Claude Code v2.1.183 verringerte den Schadensradius von Auto Mode für Operationen, die stillschweigend Arbeit verlieren lassen oder Umgebungen abbauen. Auto Mode blockiert jetzt hart, sofern Sie nicht in der Session ausdrücklich danach gefragt haben: destruktive git-Operationen (git reset --hard, git checkout -- ., git clean -fd, git stash drop); git commit --amend, wenn der Commit nicht vom Agent in dieser Session erstellt wurde; und Infrastrukturabbau (terraform destroy, pulumi destroy, cdk destroy), sofern Sie nicht den konkreten Stack benannt haben.⁶⁵ Architektonisch ergänzt das die Spawn-Prüfung und die Regeln auf Parameterebene oben: Statt zu steuern, welches Tool verwendet oder wie es gestartet wird, werden einige wenige konkrete irreversible Befehle nach Absicht gesteuert. Der Agent kann sie weiterhin ausführen, aber nur auf ausdrückliche Anweisung, nicht aus eigener Initiative. Für ein autonomes harness sollten Sie dasselbe Prinzip in Ihren eigenen PreToolUse hooks kodieren: Befehle, die Zustand zerstören, verdienen eine Deny-by-default-Regel, die nur durch ein explizites Operator-Signal aufgehoben wird.

Abwehr von Prompt Injection

Skills und hooks bieten Defense-in-Depth gegen Prompt Injection:

Skills mit Tool-Beschränkungen verhindern, dass ein kompromittierter Prompt Schreibzugriff erhält:

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 Schadensradius. Ein subagent mit permissionMode: plan kann keine Änderungen vornehmen, selbst wenn sein Prompt kompromittiert ist.

Agent-Logs und Guardrails sind Sicherheitsflächen

Zwei Advisories vom Mai 2026 untermauern ein Muster: Agent-Infrastruktur schafft neue Orte, an denen sensible Inhalte und ausführbare Policies leaken oder ausbrechen können. GitHub Advisory GHSA-f3jg-756w-gm35 behandelt ein Payload-Filter-Problem in Gryph Agents, bei dem sensible Tool-Payload-Inhalte unter dem Standard-Logging-Verhalten in lokalen SQLite-Logs verbleiben konnten.⁴⁵ OSV GHSA-wxxx-gvqv-xp7p behandelt einen Sandbox-Ausbruch bei LiteLLM custom-code guardrail in einem admin-geschützten Proxy-Endpunkt.⁴⁶

Die Produktionsregel: Behandeln Sie Agent-Transkripte, Tool-Payloads, SQLite-Logs und Guardrail-Ausführung als sensible Infrastruktur. Redigieren Sie vor der Persistierung, setzen Sie Aufbewahrungslimits, und halten Sie Custom-Guardrail-Code sandboxed und reviewbar. Eine Prompt-Regel wie „keine Secrets loggen” reicht nicht; der Logging- und Guardrail-Pfad braucht deterministische Tests.

Hook-Security

HTTP-hooks, die Umgebungsvariablen in Header interpolieren, benötigen eine explizite allowedEnvVars-Liste, um Exfiltration beliebiger Umgebungsvariablen zu verhindern:¹³

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

Die Verantwortungsaufteilung zwischen Mensch und Agent

Security in Agent-Architekturen erfordert eine klare Aufteilung zwischen menschlichen und Agent-Verantwortlichkeiten:¹⁷

Das Muster: Menschen verantworten Entscheidungen, die organisatorischen Kontext, ethisches Urteil oder strategische Richtung erfordern. Agents 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 Sicherheitsprüfungen umgehen. Das SubagentStop-Event ermöglicht Cleanup oder Validierung, wenn ein subagent abgeschlossen ist.

Das ist nicht optional. Ein Agent, der einen subagent ohne Ihre Security-hooks startet, ist ein Agent, der force-pushes auf main ausführen, Anmeldeinformationen-Dateien lesen oder destruktive Befehle ausführen kann, während Ihre Gates zusehen, wie die Hauptkonversation nichts tut.

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 sensiblen Pfaden entsprechen” leistet dasselbe wie eine 15-zeilige Erklärung, warum Anmeldeinformationen nicht gelesen werden sollten.

Agent-Ebene. Frische Spawns statt langer Konversationen. Jede Story in einem autonomen Lauf bekommt einen neuen Agent mit sauberem Kontext. Der Kontext bläht sich nie auf, weil jeder Agent frisch startet. Briefing statt Memory: Modelle führen ein klares Briefing besser aus, als sich durch 30 Schritte angesammelten Kontext zu navigieren.

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

Entscheidungsframework

Wann welcher Mechanismus verwendet werden sollte:

Skills vs Hooks vs Subagents

FAQ

Wie viele hooks sind zu viele?

Die Einschränkung ist Performance, nicht die Anzahl. Jeder hook läuft synchron, daher addiert sich die gesamte hook-Ausführungszeit zu jedem passenden Toolaufruf. 95 hooks über Einstellungen auf Benutzer- und Projektebene hinweg laufen ohne spürbare Latenz, wenn jeder hook in unter 200 ms abgeschlossen ist. Der Schwellenwert, den Sie beobachten sollten: Wenn ein PostToolUse hook jede Dateibearbeitung um mehr als 500 ms verlängert, fühlt sich die Sitzung träge an. Profilen Sie Ihre hooks vor dem Deployment mit time.¹⁴

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

Ja. PreToolUse hooks blockieren jede Toolaktion, indem sie mit Code 2 beenden. Claude Code bricht die ausstehende Aktion ab und zeigt dem Modell die stderr-Ausgabe des hooks. Claude sieht den Ablehnungsgrund und schlägt eine sicherere Alternative vor. Exit 1 ist eine nicht blockierende Warnung, bei der die Aktion trotzdem fortgesetzt wird.³

Wo sollte ich hook-Konfigurationsdateien ablegen?

Hook-Konfigurationen gehören in .claude/settings.json für hooks auf Projektebene (in Ihr Repository committed, 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.¹⁴

Braucht jede Entscheidung deliberation?

Nein. Das Confidence-Modul bewertet Entscheidungen über vier Dimensionen hinweg (Mehrdeutigkeit, Komplexität, Tragweite, Kontextabhängigkeit). Nur Entscheidungen mit einer Gesamt-Confidence unter 0,70 lösen deliberation aus, ungefähr 10 % aller Entscheidungen. Dokumentationskorrekturen, Variablenumbenennungen und routinemäßige Bearbeitungen überspringen deliberation vollständig. Security-Architektur, Datenbankschemaänderungen und irreversible Deployments lösen sie zuverlässig aus.⁷

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

Testen Sie sowohl Erfolgspfade als auch Fehlerpfade. Erfolg: Agents widersprechen einander produktiv und erreichen Konsens. Fehler: Agents konvergieren zu schnell, konvergieren nie oder überschreiten Spawn-Budgets. End-to-End-Tests simulieren jedes Szenario mit deterministischen Agent-Antworten und verifizieren, dass beide Validierungsgates jeden dokumentierten Fehlermodus abfangen. Ein produktives deliberation-System führt 141 Tests über drei Ebenen aus: 48 Bash-Integrationstests, 81 Python Unit-Tests und 12 End-to-End-Pipeline-Simulationen.⁷

Welche Latenzauswirkung hat deliberation?

Eine 3-Agent-deliberation fügt 30-60 Sekunden Wall-Clock-Zeit hinzu (Agents laufen sequenziell über das Agent tool). Eine 10-Agent-deliberation fügt 2-4 Minuten hinzu. Die Consensus- und Pride-Check-hooks laufen jeweils in unter 200 ms. Der primäre Engpass 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 gesamte Datei unter 150 Zeilen. Lange Dateien werden durch Kontextfenster gekürzt, deshalb sollten die wichtigsten Anweisungen am Anfang stehen: Befehle und Abschlussdefinitionen 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 Memory) lassen sich konzeptionell auf jedes agentische System übertragen. Die konkrete Implementierung nutzt die Lifecycle-Events, Matcher-Muster und das Agent tool von Claude Code. AGENTS.md überträgt dieselben Muster auf Codex, Cursor, Copilot, Amp und Windsurf.²¹ Das harness-Muster ist Tool-agnostisch, auch wenn die Implementierungsdetails Tool-spezifisch 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