Agentenarchitektur: Entwicklung KI-gestützter Entwicklungssysteme

TL;DR: Claude Code ist kein Chatfenster mit Dateizugriff. Es ist eine programmierbare Laufzeitumgebung mit 31 dokumentierten Lebenszyklusereignissen, die jeweils mit Shell-Skripts verknüpft werden können, welche das Modell nicht überspringen kann. Stapeln Sie hooks zu dispatchers, dispatchers zu skills, skills zu agents und agents zu workflows, erhalten Sie einen autonomen Entwicklungsharness, der Einschränkungen durchsetzt, Arbeit delegiert, Memory sitzungsübergreifend speichert und Multi-Agent-Deliberation orchestriert. Die dynamischen workflows von Claude Code (v2.1.154+) machten deterministische Multi-Agent-Orchestrierung zu einem First-Party-Primitiv — Dutzende bis Hunderte Hintergrundagents über /workflows — und die Plattform führt subagents inzwischen standardmäßig im Hintergrund aus (20 gleichzeitig, Verschachtelungstiefe 3), ermöglicht Ihren Sitzungen, als Peers miteinander Nachrichten auszutauschen (v2.1.224), und führt Cloud-Sitzungen auf selbstgehosteten Runners aus. Hooks und evidence gates bleiben für die Korrektheit verantwortlich.⁵²⁵³⁸⁷ Dieser Leitfaden behandelt jede Schicht dieses Stacks: von einem einzelnen hook bis zu einem Konsenssystem mit 10 agents. Keine Frameworks erforderlich. Alles Bash und JSON.

Andrej Karpathy prägte einen Begriff für das, was um einen LLM agent herum wächst: claws. Die hooks, Skripts und Orchestrierung, die dem agent ermöglichen, nach der Welt außerhalb seines Kontextfensters zu greifen.¹ Die meisten Entwickler behandeln KI-Coding-Agents als interaktive Assistenten. Sie geben einen Prompt ein, beobachten, wie dieser eine Datei bearbeitet, und machen weiter. Diese Denkweise begrenzt die Produktivität auf das, was Sie persönlich überwachen können.

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

Der Unterschied ist wichtig, weil Infrastruktur sich potenziert. Ein hook, der Zugangsdaten in Bash-Befehlen blockiert, schützt jede Sitzung, jeden agent und jeden autonomen Durchlauf. Ein skill, der Ihre Bewertungsrubrik kodiert, wird konsistent angewandt — unabhängig davon, ob Sie ihn aufrufen oder ein agent es tut. Ein agent, der Code auf Sicherheit prüft, führt dieselben Checks aus, unabhängig davon, ob Sie zusehen oder nicht.²

Wichtigste Erkenntnisse

• Hooks garantieren die Ausführung; Prompts nicht. Verwenden Sie hooks für Linting, Formatierung, Sicherheitsprüfungen und alles, was unabhängig vom Modellverhalten jedes Mal ausgeführt werden muss. Exit-Code 2 blockiert Aktionen. Exit-Code 1 warnt nur.³
• Skills kodieren Domänenwissen, das automatisch aktiviert wird. Das Feld description entscheidet über alles. Claude nutzt LLM reasoning (kein Keyword-Matching), um zu entscheiden, wann ein skill angewendet wird.⁴
• Subagents verhindern Context Bloat. Isolierte Kontextfenster für Exploration und Analyse halten die Hauptsitzung schlank. Führen Sie unabhängige subagents parallel aus und verwenden Sie agent teams, wenn workers dauerhafte Koordination benötigen.⁵
• Memory lebt im Dateisystem. Dateien bleiben über Kontextfenster hinweg erhalten. CLAUDE.md, MEMORY.md, Regelordner und Übergabedokumente bilden ein strukturiertes externes Memory-System.⁶
• Multi-Agent-Deliberation deckt blinde Flecken auf. Einzelne agents können ihre eigenen Annahmen nicht hinterfragen. Zwei unabhängige agents mit unterschiedlichen Bewertungsprioritäten erkennen strukturelle Fehler, die quality gates nicht adressieren können.⁷
• Das Harness-Muster ist das System. CLAUDE.md, hooks, skills, agents und memory sind keine unabhängigen Funktionen. Sie fügen sich zu einer deterministischen Schicht zwischen Ihnen und dem Modell zusammen, die mit der Automatisierung skaliert.

So verwenden Sie diesen Leitfaden

Jeder Abschnitt baut auf dem vorherigen auf. Der Entscheidungsrahmen am Ende bietet eine Nachschlagetabelle, mit der Sie für jeden Problemtyp den passenden Mechanismus 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 Pattern

Das harness ist kein Framework. Es ist ein Muster: eine kombinierbare Sammlung aus Dateien, Skripten und Konventionen, die einen KI-Coding-Agenten mit deterministischer Infrastruktur umgibt. 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        │
└──────────────────────────────────────────────────────────────┘

Instruktionsebene: CLAUDE.md-Dateien und Regelordner definieren, was der Agent über Ihr Projekt weiß. Sie werden automatisch beim Sitzungsstart und nach jeder Komprimierung geladen. Das ist das langfristige Architekturgedächtnis des Agenten.

Erweiterungsebene: Skills liefern Fachwissen, das sich abhängig vom Kontext automatisch aktiviert. Hooks stellen deterministische Sperren bereit, die bei jedem passenden Tool-Aufruf ausgelöst werden. Memory-Dateien speichern den Zustand sitzungsübergreifend. Custom Agents stellen spezialisierte subagent-Konfigurationen bereit.

Orchestrierungsebene: Multi-Agent-Muster koordinieren unabhängige Agents für Recherche, Überprüfung und Abwägung. Spawn-Budgets verhindern außer Kontrolle geratene Rekursion. Konsensvalidierung sichert die Qualität.

Die zentrale Erkenntnis: Die meisten Benutzer arbeiten vollständig in der Core Layer und beobachten, wie der Kontext anschwillt und die Kosten steigen. Erfahrene Benutzer konfigurieren die Instruktions- und Erweiterungsebene und nutzen die Core Layer anschließend nur für Orchestrierung und endgültige Entscheidungen.²

Verwaltete vs. selbstgehostete Harnesses (April 2026)

Bis Anfang 2026 war der Weg „eigenes harness bauen“ die einzige echte Option. Im April 2026 änderte sich das. Anthropic veröffentlichte Claude Managed Agents als öffentliche Beta (8. April): harness loop + Tool-Ausführung + Sandbox-Container + Zustands-Persistenz als REST-API, abgerechnet zu Standard-Tokenpreisen plus 0,08 $ pro Sitzungsstunde. Das Update Agents SDK von OpenAI (16. April) formalisierte dieselbe Trennung — harness und Compute als getrennte Ebenen, mit nativen Sandbox-Anbietern (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) sowie Snapshot/Rehydrate zum Überstehen eines Containerverlusts.²³²⁴

Die tiefergehende 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-Instruktionen und Fähigkeiten; ein Manifest, das den Vertrag für frische Workspaces beschreibt (Dateien, Verzeichnisse, lokale Dateien, Git-Repositories, Umgebungsvariablen, Benutzer, Mounts); eine SandboxRunConfig für die Konfiguration pro Ausführung von Sandbox-Client, Einbindung einer Live-Sitzung, Manifest-Überschreibungen, Snapshots und Parallelitätslimits für die Materialisierung. Integrierte Fähigkeiten umfassen Shell-Zugriff, Bearbeitung des Dateisystems, Bildinspektion, skills, Sandbox Memory und Komprimierung. Sandbox Memory speichert extrahierte Erkenntnisse laufübergreifend und legt sie schrittweise offen; Workspaces unterstützen lokale Dateien, Git-Repository-Einträge und Remote-Mounts (S3, R2, GCS, Azure Blob, S3 Files); Snapshots sind anbieterübergreifend portabel. 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 „claude über die Shell ausführen“ und „REST-API an Managed Agents“ — ist claude-agent-sdk-python die dritte Option. Die Serie vom 28.–29. April (v0.1.69 → v0.1.71) aktualisierte die gebündelte CLI auf v2.1.123, erhöhte die Mindestversion der Abhängigkeit mcp auf >=1.19.0 (ältere Versionen verwarfen stillschweigend CallToolResult-Rückgaben von prozessinternen MCP-Tools, sodass dem Modell ein Blob mit Validierungsfehlern blieb) und brachte SandboxNetworkConfig auf Schema-Parität mit der TypeScript SDK (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰ Stand 12.08.2026 liegt das Paket auf PyPI bei v0.2.137 und die TypeScript SDK bei v0.3.229 (beide anhand der Live-Register verifiziert); die 0.2.x-Linie ergänzt inkrementell die hier beschriebene 0.1.x-Oberfläche — die folgenden Optionen include_hook_events, skills und Sandbox-Konfigurationen sind weiterhin aktuell — während sich jüngere Releases auf die Zuverlässigkeit von Subprozess-Bereinigung und NDJSON-Streams konzentrieren.⁹⁰⁸⁶

Wenn Ihr harness eine Sprach- oder Realtime-Ebene umfasst, aktualisierte openai-agents-python v0.17.0 (8. Mai 2026) RealtimeAgent so, dass standardmäßig gpt-realtime-2 verwendet wird.⁴¹ Bestehende Realtime-Sitzungen übernehmen den neuen Standard automatisch; pinnen Sie das vorherige Modell explizit, wenn Sie das bisherige Verhalten für eine Evaluierung beibehalten müssen.

Im Juli 2026 erhielt die verwaltete Spalte auch auf der OpenAI-Seite eine Multi-Agent-Geschichte: openai-agents-python v0.18.2 (11. Juli) und openai-agents-js v0.13.2 (10. Juli) ergänzen gehostete Multi-Agent-Unterstützung als Beta — von OpenAI verwaltete Orchestrierung mehrerer Agents als gehosteten Dienst, das direkte Gegenstück zur öffentlichen Beta von Managed Multiagent Orchestration von Anthropic, die im Abschnitt Multi-Agent-Orchestrierung behandelt wird.⁷³ Beide Anbieter bieten nun auf der Multi-Agent-Ebene denselben Tausch an, den die folgende Tabelle für einzelne Agents beschreibt: Der Anbieter betreibt die Delegationsschleife, Sie geben die Hook-Oberfläche auf.

Die architektonische Verzweigung ist jetzt real:

Wann Sie welche Variante wählen sollten: Selbsthosting bleibt richtig für Teams, die bereits über Infrastrukturkompetenz verfügen, skills/hooks unter eigener Kontrolle wünschen oder einen bestimmten Workflow tiefgehend optimieren. Managed eignet sich für Teams ohne dedizierte Platform Engineers, wenn die Zeit bis zum Nutzen wichtiger ist als Anpassbarkeit oder wenn Agent-Läufe Laptop-Schließungen zuverlässig überstehen müssen, ohne dass Sie diese Persistenzebene selbst bauen. Beide Ansätze sind kompatibel — Sie können ein selbstgehostetes harness betreiben, das bestimmte lang laufende Aufgaben per REST-API an Managed Agents delegiert.

So sieht das Harness auf dem Datenträger aus

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

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

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

Skills-System

Skills sind vom Modell aufgerufene Erweiterungen. Claude erkennt und wendet sie anhand des Kontexts automatisch an, ohne dass Sie sie ausdrücklich aufrufen müssen.⁴ Sobald Sie sich dabei ertappen, denselben Kontext über Sitzungen hinweg erneut zu 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-Befehle sind für Aktionen, die Sie ausdrücklich auslösen. Wenn Sie zwischen beiden abwägen, fragen Sie sich: „Soll Claude dies automatisch anwenden, oder möchte ich entscheiden, wann es ausgeführt wird?“

Einen Skill erstellen

Skills können an vier möglichen Orten liegen – vom weitesten bis zum engsten Geltungsbereich:⁴

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 Description-Feld ist entscheidend

Beim Sitzungsstart extrahiert Claude Code den name und die description jedes Skills und fügt sie in den Kontext von Claude ein. Wenn Sie eine Nachricht senden, verwendet Claude Sprachmodell-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 nutzt sein gewöhnliches Sprachverständnis, um relevante Skills auszuwählen.¹⁰

Schlechte Beschreibung:

description: Helps with code

Wirksame Beschreibung:

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

Die wirksame Beschreibung enthält: was sie tut (Code auf konkrete Problemtypen prüfen), wann sie zu verwenden ist (beim Untersuchen von Änderungen, PRs und der Qualitätsanalyse) sowie Auslösephrasen (review, audit, check), die Benutzer auf natürliche Weise eingeben.

Beachten Sie, dass die automatische Aktivierung ein Regler und kein Gesetz ist: Seit v2.1.215 ruft Claude die gebündelten Skills /verify und /code-review nicht mehr selbst auf – sie werden nur noch ausdrücklich ausgelöst. Das ist eine bewusste Rücknahme der beschreibungsbasierten Aktivierung für aufwendige Review-Skills, deren unaufgeforderte Ausführungen mehr kosteten, als sie einbrachten.⁷⁴

Kontextbudget

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

Unterstützende Dateien und Organisation

Skills können auf zusätzliche Dateien im selben 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 in 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 ausführliches Referenzmaterial in unterstützende Dateien.¹²

Skills über Git teilen

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

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

Wenn Teammitglieder pullen, erhalten sie den Skill automatisch. Keine Installation, keine Konfiguration. Dies ist der wirkungsvollste Weg, Fachwissen in einem Team zu standardisieren.

Skills als Prompt-Bibliothek

Über Skills mit nur einem Zweck 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 einen anderen Aspekt Ihres Fachwissens. Zusammen bilden sie eine Wissensbasis, aus der Claude abhängig vom Kontext automatisch schöpft. Ein Junior-Entwickler erhält Senior-Level-Anleitung, ohne danach fragen zu müssen.

Skills lassen sich mit Hooks kombinieren

Skills können im Frontmatter eigene Hooks definieren, die nur aktiv sind, während der Skill ausgeführt wird. Dadurch entsteht domänenspezifisches Verhalten, das andere Sitzungen nicht belastet:²

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

Philosophie-Skills aktivieren sich über SessionStart-Hooks automatisch und injizieren Qualitätsvorgaben in jede Sitzung, ohne ausdrücklich aufgerufen zu werden. Der Skill selbst ist Wissen. Der Hook ist Durchsetzung. Gemeinsam bilden sie eine Richtlinienebene.

Häufige Skill-Fehler

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

Zu viele Skills konkurrieren um das Budget. Mehr Skills bedeuten mehr Beschreibungen, die um das 1-%-Kontextbudget konkurrieren. Wenn Sie feststellen, dass Skills nicht aktiviert werden, prüfen Sie /context auf ausgeschlossene Skills. Bevorzugen Sie wenige, gut beschriebene Skills gegenüber vielen vagen.

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

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

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

Konvergenz von Plugin und Skill 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 in .claude/skills/ abgelegtes Plugin wird nun automatisch geladen, ohne Marketplace-Registrierung, und claude plugin init <name> erstellt dort ein neues Plugin, bei dem Manifest und SKILL.md bereits verbunden sind.⁵⁸ Damit schließt sich die Lücke zwischen den beiden Formen von Projekt-Tooling, die früher an unterschiedlichen Orten lagen – einem direkt im Repository versionierten eigenständigen Skill und einem Plugin, das einen Skill zusammen mit Hooks und einem MCP-Server bündelt, zuvor jedoch zur Installation einen Marketplace benötigte. Der praktische Effekt für das Harness-Design: Projektbezogenes Tooling benötigt keinen Umweg über eine Registry mehr, um ausgeliefert zu werden – schreiben Sie es, committen Sie es, und Teammitglieder erhalten dieselbe Oberfläche mit git pull. Plugins bleiben für den gebündelt installierbaren Anwendungsfall zuständig (Hooks + Skills + MCP-Server + Agents in einer ZIP-Datei); die Änderung besteht darin, dass ein Projekt keinen Marketplace mehr aufsetzen muss, nur um eines aus seinem eigenen Verzeichnis zu laden. Diese Konvergenz hat nun eine herstellerübergreifende Grundlage: Agent Plugins 1.0.0 (veröffentlicht am 6. August 2026) standardisiert dieselbe Paketform – ein plugin.json-Manifest, skills/-Verzeichnisse mit SKILL.md-Ordnern und optional mcp.json – als „das portable Paketformat für AI agents“, das zum Start von VS Code, Cursor, GitHub Copilot, ChatGPT & Codex und Kiro übernommen wurde. Es handelt sich ausdrücklich um eine Verpackungsschicht für Agent Skills und MCP, nicht um einen Ersatz; beachten Sie, dass Anthropic, Autor der Agent-Skills-Spezifikation, noch nicht Teil der Koalition ist – behandeln Sie daher die von Claude-Code ausgehende Portabilität als Kompatibilität auf Formatebene, nicht als offiziellen bidirektionalen Vertrag.⁸⁹

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

Skills sind Fähigkeiten, und Fähigkeiten sind Angriffsfläche. Claude Code v2.1.169 ergänzt die Einstellung disableBundledSkills (und die entsprechende Umgebungsvariable CLAUDE_CODE_DISABLE_BUNDLED_SKILLS), die gebündelte Skills, Workflows und integrierte Slash-Befehle vollständig vor dem Modell verbirgt.⁶⁰ Für ein gehärtetes oder reguliertes Harness ist dies eine bewusste Verringerung der Angriffsfläche: Ein Betreiber, der einen konkreten Satz von Projekt- und persönlichen Skills geprüft und genehmigt hat, kann alles unterdrücken, was Anthropic mitliefert, sodass das Modell nur über die vom Betreiber geprüfte Oberfläche nachdenkt. Behandeln Sie dies genauso wie eine Tool-Allowlist – standardmäßig stehen umfassende Fähigkeiten zur Verfügung, und das Abschalten dieses Standards 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 standortbewusst. Skills in verschachtelten .claude/skills-Verzeichnissen werden nun geladen, wenn Sie an Dateien unter diesem Verzeichnis arbeiten, nicht nur aus dem Repository-Stammverzeichnis; bei einem Namenskonflikt erscheint der verschachtelte Skill als <dir>:<name>, sodass beide erreichbar bleiben.⁶³ Dieselbe Version ließ den Rest der Projektoberfläche relativ zum Arbeitsverzeichnis auflösen: Wenn ein Agent-, Workflow- oder Output-Style-Name in verschachtelten .claude/-Verzeichnissen kollidiert, gewinnt derjenige, der dem Arbeitsverzeichnis am nächsten liegt, und ein Workflow-Speichervorgang im Projektbereich zielt auf das nächstgelegene vorhandene .claude/workflows/, statt immer auf das Stammverzeichnis.⁶³ Für ein Monorepo oder ein Repository-von-Repositories ist dies der Unterschied zwischen einer flachen globalen Oberfläche und paketbezogenem Tooling, das im Kontext aktiviert wird – ein services/api/.claude/skills/ kann API-spezifische Skills enthalten, die nur erscheinen, während Sie in diesem Verzeichnis arbeiten, ohne mit einem services/web/-Skill gleichen Namens zu kollidieren.

Hook-Architektur

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

Verfügbare Events

Claude Code stellt zum Zeitpunkt dieser Aktualisierung des Leitfadens 31 dokumentierte Lifecycle-Events in acht Kategorien bereit. Die Event-Liste wächst mit neuen Releases; behandeln Sie daher die Referenzdokumentation als maßgebliche Quelle und prüfen Sie vor dem Einrichten produktiver Hooks das Cheat Sheet auf die aktuell vollständige Tabelle:¹³

DirectoryAdded (v2.1.219) schließt die Workspace-Lücke während einer Sitzung. Die Event-Liste war stabil, seit MessageDisplay in v2.1.152 hinzugekommen ist; DirectoryAdded ist seither das erste neue Lifecycle-Event und wird ausgelöst, nachdem /add-dir — oder die register_repo_root-Control-Anfrage von SDK — während einer Sitzung ein neues Arbeitsverzeichnis registriert.⁸⁴ Die dadurch geschlossene Lücke ist real: Bisher konnte ein harness einen Workspace bei SessionStart umfassend validieren und anschließend zusehen, wie ein zweites Repository hinzugefügt wurde, ohne dass überhaupt ein Hook ausgelöst wurde. Alles, was Sie beim Start über den Workspace zusichern — Vertrauensprüfungen, Secret-Scans, aus dem Verzeichnisbaum abgeleitete Pfadbereichsregeln, das Laden repositoryspezifischer Richtlinien — muss hier erneut ausgeführt werden, weil die Verzeichnismenge einer Sitzung beim Start nicht mehr festgelegt ist. Das Event dient der Information und blockiert nicht. Behandeln Sie es daher als Trigger, um den Zustand erneut abzuleiten und die Herkunft zu protokollieren, nicht als Gate; wenn ein Verzeichnis niemals hinzugefügt werden darf, verweigern Sie es in den Einstellungen, statt zu versuchen, es über einen Hook abzulehnen. Die SDK-Seite wurde im selben Release ergänzt (TypeScript v0.3.219 fügt DirectoryAdded zu den Lifecycle-Events des Control-Protokolls hinzu), sodass SDK-gehostete harnesses es gleichwertig mit CLI-basierten sehen.⁸⁵

Semantik der Exit-Codes

Exit-Codes bestimmen, ob Hooks Aktionen blockieren:³

Hook-Konfiguration

Hooks befinden sich in Einstellungsdateien. Auf Projektebene (.claude/settings.json) für gemeinsame 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 eventspezifischen Wert. Bei Tool-Events gleicht es tool_name-Werte ab, etwa Bash, Edit, Write, Read, Glob, Grep, MCP-Tool-Namen wie mcp__server__tool oder * für alle Tools. Einfache Namen und mit | getrennte Listen sind exakte Übereinstimmungen; Werte mit anderen Zeichen sind JavaScript-reguläre Ausdrücke. Einige Events unterstützen keine Matcher und werden bei Konfiguration immer ausgelöst.¹³ Seit Claude Code v2.1.195 werden Matcher mit Bindestrich-Identifiern (code-reviewer, mcp__brave-search) exakt abgeglichen, statt versehentlich Teilzeichenketten zuzuordnen — ein Hook für einen bestimmten Agent oder Server wird nicht mehr für jeden Namen ausgelöst, der die Zeichenkette lediglich enthält; um alle Tools eines MCP-Servers mit Bindestrich abzudecken, schreiben Sie das explizite Muster mcp__brave-search__.*.⁶⁶ v2.1.214 wandte dieselbe Disziplin auf Pfad-Muster an: Eine Hook-Bedingung if: mit einem einsegmentigen Muster dir/** entspricht nun nur <cwd>/dir, nicht jedem Verzeichnis namens dir irgendwo im Baum — verwenden Sie **/dir/**, wenn Sie tatsächlich jede Tiefe meinen.⁷⁴ Wie bei der Änderung in v2.1.195 ersetzt die Korrektur versehentliche Breite durch deklarierte Absicht; prüfen Sie alle Hook-Bedingungen, die sich stillschweigend auf das frühere Verhalten für beliebige Tiefe verlassen haben.

Hook-Ein-/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 einzufügen oder Berechtigungsentscheidungen zu treffen. Verwenden Sie den Wrapper hookSpecificOutput — das ältere Format mit decision/reason auf oberster Ebene 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

Fragen Sie sich vor dem Schreiben eines Hooks: Welche Art von Garantie benötige ich?¹⁴

Formatierungsgarantien sorgen nachträglich für Konsistenz. PostToolUse-Hooks für 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 für 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 für git commit-Befehle führen Ihren Linter oder Ihre Testsuite aus und blockieren den Commit, wenn Qualitätsprüfungen fehlschlagen:

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

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

Hook-Typen jenseits von Shell-Befehlen

Claude Code unterstützt fünf Hook-Typen:¹³ Command hooks (type: "command") führen Shell-Skripte aus. Schnell, deterministisch, ohne Tokenkosten.

MCP tool hooks (type: "mcp_tool") rufen ein Tool auf einem bereits verbundenen MCP-Server auf. Verwenden 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 zum Zulassen { "ok": true } oder zum Blockieren { "ok": false, "reason": "..." } zurück. Verwenden Sie sie für differenzierte Bewertungen, die sich nicht mit Regex ausdrücken lassen.

Agent hooks (type: "agent") starten einen subagent mit Toolzugriff (Read, Grep, Glob) für mehrstufige Verifizierung. Sie sind experimentell; bevorzugen Sie command hooks für Produktions-Gates und reservieren Sie agent hooks für Prüfungen, die tatsächlich die Untersuchung realer Dateien oder Testausgaben erfordern:

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

Ab Claude Code v2.1.140 enthält die Eingabe für agent hooks subagent_type, wodurch ein gemeinsamer Hook einen Durchlauf mit security-reviewer von einem explorer oder generischen worker unterscheiden kann, ohne anhand des Prompt-Texts 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. Verwenden Sie sie für Webhooks, externe Benachrichtigungsdienste oder API-basierte Validierung (v2.1.63+). Für SessionStart-Ereignisse werden sie 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
          }
        ]
      }
    ]
  }
}

Asynchrone Hooks

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

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

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

Dispatcher statt unabhängiger Hooks

Wenn sieben Hooks alle 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. Jeder nachgelagerte Hook, der diese Datei parst, fällt aus.²

Die Lösung: ein dispatcher pro Ereignis, der Hooks sequenziell aus zwischengespeichertem stdin ausführt:

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

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

Hooks debuggen

Fünf Techniken zum Debuggen von Hooks, die stillschweigend fehlschlagen:¹⁴

1. Testen Sie Skripte unabhängig. Leiten Sie beispielhaftes JSON weiter: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Verwenden Sie stderr für Debugausgaben. stderr mit Exit-Code 2 wird Claude als Fehlermeldung zurückgegeben. Nicht blockierendes stderr (Exit 1, 3 usw.) erscheint nur im ausführlichen Modus (Ctrl+O).
3. Achten Sie auf jq-Fehler. Falsche JSON-Pfade geben stillschweigend null zurück. Testen Sie jq-Ausdrücke mit echten Tooleingaben.
4. Verifizieren Sie Exit-Codes. Ein PreToolUse hook, der exit 1 verwendet, erzwingt nichts, obwohl er scheinbar funktioniert.
5. Halten Sie Hooks schnell. Hooks laufen synchron. Halten Sie alle Hooks unter 2 Sekunden, idealerweise unter 500 ms.

SDK-seitiges Hook-Ereignisstreaming

Selbstgehostete harnesses, die auf claude-agent-sdk-python (v0.1.74+, 6. Mai 2026) basieren, können Hook-Ereignisse direkt aus dem Nachrichtenstream abonnieren, statt Shell-Skript-Callbacks zu verwenden.³⁶ Setzen Sie include_hook_events=True bei ClaudeAgentOptions; HookEventMessage-Objekte (PreToolUse, PostToolUse, Stop und andere) werden über denselben Iterator wie Assistant-Nachrichten und Toolergebnisse ausgegeben. Dies entspricht der includeHookEvents-Option des TypeScript SDK; das gebündelte CLI wurde in derselben Version 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 benötigen. Der Shell-Skript-Hook-Vertrag (Exit-Codes, stdin JSON, dispatcher) bleibt die richtige Wahl für harnesses, die mehrere Tools kombinieren, Hooks zwischen Claude Code und Codex teilen oder Exit-Code-Semantik zum Blockieren benötigen.

Die Serie des TypeScript SDK vom Juli 2026 (v0.3.205–v0.3.208) machte auch das gestreamte Protokoll selbst verbindlicher.⁷⁰ Interrupts liefern nun typisierte Empfangsbestätigungen zurück: Ein Interrupt bestätigt über still_queued UUIDs, welche Nachrichten in der Warteschlange noch ausstehen, und Sitzungen kündigen die Fähigkeit interrupt_receipt_v1 in system/init an. So kann ein Koordinator unterscheiden, ob ein „Interrupt angekommen“ ist oder ob er eine bereits laufende Nachricht überholt hat. command_lifecycle-Frames melden pro Nachricht queued/started/completed/cancelled/discarded — die erste First-Party-Antwort auf „Was ist mit der von mir gesendeten Nachricht passiert?“, ohne Rückschlüsse aus dem Transkript ziehen zu müssen. Auch kleinere Oberflächen kamen hinzu: ein AgentToolCompletedOutput-Typ für subagent-Abschluss-Payloads, und canUseTool-Callbacks können jetzt {behavior: 'allow'} ohne ein updatedInput-Feld zurückgeben.

Eine Zeile dieser Serie ist eine Sicherheitsuntergrenze, keine Funktion: v0.3.208 behebt, dass ein während eines ausstehenden Hooks eintreffender Abbruch durch den Aufrufer in Hook-Erfolg umgewandelt wurde — wodurch ein durch einen PreToolUse hook geschütztes Tool nach dem Abbruch durch den Aufrufer ausgeführt werden konnte.⁷⁰ Falls Ihr harness SDK-seitige Hooks als Berechtigungsgate verwendet und sich darauf verlässt, dass ein Abbruch laufende Arbeit beendet, behandeln Sie v0.3.208 als Mindestversion; darunter bedeutete „abgebrochen“ nicht zuverlässig „blockiert“. Python v0.2.127 (24. Juli 2026) ist der zweite Bypass dieser Art innerhalb eines Monats — query() schloss stdin beim ersten result-Frame, während subagents im Hintergrund noch liefen, sodass ihre SDK-MCP-Toolaufrufe mit "Stream closed" fehlschlugen und PreToolUse hooks vollständig umgingen.⁸⁵ Benennen Sie das Muster und achten Sie darauf: SDK-seitige Hook-Erzwingung schlägt an Lebenszyklusgrenzen offen fehl — Abbruch, Teardown, Stream-Schließung — wenn der Transport stirbt, bevor das Hook-Urteil eingeholt wird; und sie schlägt stillschweigend fehl, weil ein umgangener Hook genauso aussieht wie ein Hook, der zugestimmt hat. Pinnen Sie beide SDK-Mindestversionen und behalten Sie die Shell-Hook-Schicht als Erzwingung bei, die Sie nachweisen können.

Aufwand und Sitzungsprovenienz (7.–8. Mai 2026)

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

• effort.level in Hook-Eingaben. Hooks erhalten nun ein JSON-Feld effort.level in derselben Eingabe, die tool_input und session_id enthält. Derselbe Wert wird als Umgebungsvariable $CLAUDE_EFFORT exportiert, sodass Bash-Befehle ihn ohne Parsen von JSON lesen können. Verwenden Sie dies, um die Hook-Kosten mit der Aufwandsstufe zu skalieren: Überspringen Sie aufwendige Validierung bei low, führen Sie das vollständige Sicherheits-Gate bei xhigh oder max aus.
• Umgebungsvariable CLAUDE_CODE_SESSION_ID für Bash-Subprozesse. Bash-Tool-Subprozesse sehen nun denselben session_id-Wert wie Hooks, verfügbar als CLAUDE_CODE_SESSION_ID. Das schließt die Provenienzlücke für Tools, die Status pro Sitzung protokollieren und zuvor Subprozessereignisse nicht mit Hook-Ereignissen korrelieren konnten.

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

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

Claude Code v2.1.136 fügte dem Auto-Modus eine neue Hard-Deny-Stufe hinzu und behob eine Reihe von Plugin- und MCP-Problemen, die lang laufende harnesses betrafen:⁴⁰ - settings.autoMode.hard_deny. Regeln des Auto-Mode-Classifiers, die unabhängig von Benutzerabsicht oder allow-Ausnahmen unbedingt blockieren. Dies steht als nicht verhandelbarer Governance-Hebel über den bestehenden allow/deny-Matchern. Nutzen Sie ihn für Regeln, die niemals überschrieben werden dürfen (force-push auf main, Dateien mit Secrets, Zugriff auf Produktionsdatenbanken), selbst wenn ein Operator die übergeordnete Kategorie in seinen persönlichen Einstellungen genehmigt hat. - autoMode.classifyAllShell (v2.1.193). Standardmäßig prüft der Auto-Mode-Classifier nur Shell-Befehle, die Mustern für die Ausführung beliebigen Codes entsprechen. Diese Einstellung leitet jeden Bash/PowerShell-Befehl durch den Classifier — die Haltung maximaler Abdeckung für einen gesteuerten harness — und dieselbe Version zeigt Ablehnungsgründe im Transkript, im Toast und in /permissions an, wodurch stille Blockierungen zu auditierbaren Entscheidungen werden. Codex hat die entsprechende Oberfläche in v0.142.2 verschärft: PowerShell-Befehle mit ausführbaren AST-Bereichen, die sein Sicherheits-Classifier nicht prüfen kann, benötigen nun eine Genehmigung, anstatt stillschweigend durchgelassen zu werden.⁶⁶ - Hook ask setzt dem Classifier eine Untergrenze (v2.1.211). Die Frage zur Priorität von Hook gegenüber Auto Mode ist nun geklärt: Ein PreToolUse-Hook, der eine ask-Berechtigungsentscheidung zurückgibt, setzt das endgültige Ergebnis mindestens auf eine Aufforderung — Auto Mode kann dies für unsandboxed Bash-Befehle nicht wieder zu allow hochstufen.⁶⁹ Für einen gesteuerten harness ist dies die fehlende Garantieschicht: Das ask eines Hooks ist ein deterministischer Human-in-the-Loop-Stopp, der selbst vollständig automatische Berechtigungshaltungen übersteht. Verwenden Sie ask (nicht nur Exit-2-Blockierungen) für Vorgänge, bei denen Sie eine menschliche Entscheidung statt einer Ablehnung wünschen. - Das Classifier-Modell wird pro Sitzung festgelegt (v2.1.210). Der Auto-Mode-Classifier verwendet standardmäßig Sonnet 5 und wird für die Sitzung festgelegt, sodass Modellwechsel während der Sitzung nicht mehr ändern, welches Modell Berechtigungsklassifizierungen vornimmt.⁶⁹ Klassifizierungskonsistenz ist eine Governance-Eigenschaft; dadurch wird eine stille Quelle für Drift beseitigt. - 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, dem JetBrains-Plugin und Agent SDK stillschweigend aus der aktiven Menge. Die Korrektur ist in v2.1.136 enthalten. Wenn Sie erlebt haben, dass „MCP server X went missing mid-session“, war dies die Ursache. - Verlust von MCP-OAuth-Refresh-Tokens bei gleichzeitigem Refresh. Benutzer mit mehreren Remote-MCP-Servern sollten sich nicht länger täglich erneut authentifizieren müssen. Gleichzeitige Refresh-Schreibvorgänge überschriebene einander. - Plan Mode blockiert Dateischreibvorgänge nun korrekt. Eine passende Edit(...)-allow-Regel umging den Schreibschutz von Plan Mode. Plan Mode wird nun unabhängig von allow-Regeln durchgesetzt. - Plugin-Stop- und -UserPromptSubmit-Hooks schlagen während einer Sitzung nicht mehr fehl. Die Cache-Bereinigung löschte Plugin-Version-Dateien, die von der laufenden Sitzung noch verwendet wurden, wodurch speziell diese beiden Hook-Events fehlschlugen. Die Korrektur hält verwendete Versionen fest. - skills-Eintrag in plugin.json. Das Setzen von skills blendete den standardmäßigen skills/-Ordner des Plugins aus. Nun wird der Eintrag korrekt zusammengesetzt, und ein Verweis auf einen Dateipfad erzeugt einen expliziten Fehler, statt stillschweigend fehlzuschlagen. - CLAUDE_ENV_FILE-SessionStart-Hook-Umgebungsvariablen wurden veraltet. Variablen, die von SessionStart-Hooks über CLAUDE_ENV_FILE exportiert wurden, veralteten nach /resume oder /clear. Behoben in v2.1.136. Sitzungen lesen die env-Datei bei diesen Events nun erneut ein.

Für Governance-harnesses sind die operativ interessanten Punkte autoMode.hard_deny (neuer Hebel) und die Korrektur für verschwindende MCP-Server (stiller Fehler, der lange Sitzungen beeinträchtigte). Alles andere ist eine Bereinigung der Benutzerfreundlichkeit.

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

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

Verwenden Sie continueOnBlock, wenn ein PostToolUse-Hook seinen Ablehnungsgrund an Claude zurückgeben und den Turn fortsetzen soll, anstatt den Ablauf zu beenden. Behandeln Sie es als Funktion für die Operator-Erfahrung, nicht als Sicherheitsumgehung. Ein blockierendes Gate sollte das unsichere Ergebnis weiterhin blockieren.

Dieselbe Version übergibt CLAUDE_PROJECT_DIR an MCP-stdio-Server und ermöglicht Plugin-Konfigurationen, in Befehlen auf ${CLAUDE_PROJECT_DIR} zu verweisen.⁴² MCP-Tools sollten projektbezogene Pfade anhand dieses Werts auflösen, statt anhand des Arbeitsverzeichnisses des Prozesses, der den Server zufällig gestartet hat. Die Versionen von Anfang Juli 2026 (v2.1.203–v2.1.206) erweiterten dasselbe Prinzip auf die Protokollebene: MCP roots/list enthält nun die zusätzlichen Arbeitsverzeichnisse der Sitzung, mit roots/list_changed-Benachrichtigungen bei Änderungen — sodass ein Server, der MCP roots respektiert, die tatsächliche Form eines Arbeitsbereichs mit mehreren Verzeichnissen nachverfolgt, anstatt von einem einzelnen Projektverzeichnis auszugehen.⁶⁸

Claude Code v2.1.140 ist überwiegend eine Zuverlässigkeitsversion für harness-Operatoren: Sie behebt, dass ConfigChange-Hooks bei Einstellungsänderungen nicht ausgelöst wurden, schließt Randfälle, in denen disableAllHooks und allowManagedHooksOnly sich über Einstellungsebenen hinweg nicht korrekt zusammensetzten, und verhindert, dass Berechtigungsdialoge unbeabsichtigte Umgebungsvariablen offenlegen, die von Hook-Ergebnissen zurückgegeben wurden.⁴⁹ Dadurch werden die bestehenden Governance-Muster in diesem Abschnitt zuverlässiger; eine neue Hook-Architektur ist nicht erforderlich.

Claude Code v2.1.141 fügt ein Hook-Output-Feld terminalSequence für Desktop-Benachrichtigungen, Fenstertitel und Signaltöne ohne steuerndes Terminal hinzu.⁵⁰ Behandeln Sie dies als Operator-Signalisierung, nicht als Durchsetzung. Sicherheits- und Qualitäts-Gates sollten Fehler weiterhin über den normalen Blockierungsvertrag kommunizieren: strukturierten Hook-Output plus das Exit-Verhalten, das die unsichere Aktion verhindert. Dieselbe Version fügt claude agents --cwd <path> hinzu, um Agent View auf ein Verzeichnis zu beschränken, CLAUDE_CODE_PLUGIN_PREFER_HTTPS für Plugin-Installationen in Umgebungen ohne GitHub SSH keys sowie ANTHROPIC_WORKSPACE_ID für Regeln zur Workload-Identity-Federation, die mehr als einen Workspace abdecken.⁵⁰ Das sind Architekturdetails für Team-harnesses: engere operative Ansichten, weniger Annahmen bei Plugin-Installationen und explizites Scoping von Enterprise-Tokens.

Claude Code v2.1.142 ist für die Orchestrierung von Hintergrundsitzungen wichtiger als für die Hook-Semantik.⁵¹ claude agents kann Hintergrundsitzungen nun mit expliziten Flags für Verzeichnis, Einstellungen, MCP, Plugin, Berechtigungen, Modell und Aufwand starten, statt von Wrapper-Zustand abhängig zu sein. Fast Mode verwendete in dieser Version standardmäßig Opus 4.7, mit CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 als Festlegung für einen harness, der nachweislich vom Verhalten von Opus 4.6 abhängt — ab v2.1.219 ist Opus 4.7 vollständig aus Fast Mode entfernt und /fast gilt für Opus 5 und Opus 4.8.⁸⁴ Die Erkennung von SKILL.md im Root-Level von Plugins und die Sichtbarkeit von durch Plugins bereitgestellten LSP reduzieren Unklarheiten bei der Paketierung. Korrekturen für MCP_TOOL_TIMEOUT, bereits vorhandene Worktrees für Hintergrundsitzungen, Daemon-Sleep/Wake und Bereinigung nach Upgrades sowie die Plugin-Cache-Bereinigung schließen Zuverlässigkeitslücken, die andernfalls 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. Ab Claude Code v2.1.163 kann ein Stop- oder SubagentStop-Hook hookSpecificOutput.additionalContext zurückgeben, um Claude Feedback zu übermitteln und den Turn fortzusetzen, ohne dass die Antwort als Hook-Fehler gekennzeichnet wird. Zuvor war der einzige echte Hebel eines Stop-Hooks die Exit-2-Blockierung, die als Fehler erscheint und auf die Obergrenze aufeinanderfolgender Blockierungen angerechnet wird. Für einen Quality-Gate-harness ist dies das sauberere Primitiv: Ein Stop-Hook, der erkennt: „Sie haben done gesagt, aber die Tests sind rot“, kann nun „Folgendes schlägt weiterhin fehl, fahren Sie fort“ einschleusen, statt hart zu blockieren. Verwenden Sie die Blockierung für echte Stoppbedingungen und additionalContext für „noch nicht fertig, aus diesem Grund“.

Sitzungsübergreifende Nachrichten übertragen keine geliehene Autorität mehr. v2.1.166 hat den Multi-Session-Fall gehärtet: Nachrichten, die über SendMessage aus einer anderen Claude-Sitzung weitergeleitet werden, übertragen nicht mehr die Autorität des ursprünglichen Benutzers, sodass eine empfangende Sitzung weitergeleitete Berechtigungsanfragen ablehnt und Auto Mode sie blockiert. Wenn Ihre Orchestrierung Agents Nachrichten senden lässt, behandeln Sie eine eingehende Nachricht als nicht vertrauenswürdige Daten, nicht als authentifizierte Anweisung. Dies ist dasselbe Prinzip, das der Sicherheitsabschnitt auf Tool-Output anwendet, erweitert auf die Kommunikation zwischen Agents. Ab v2.1.199 erkennt und warnt Claude Code außerdem, wenn ein SendMessage fehlgeleitet wird, weil zwei Agents denselben Namen haben — eine Zuverlässigkeitsergänzung zu dieser Autoritätsgrenze, da eine Nachricht, die den falschen gleichnamigen Agent erreicht, eine eigene Klasse von Orchestrierungsfehlern darstellt. Sessions sind jetzt gleichberechtigte Einheiten erster Klasse (v2.1.224+). Cross-Session-Messaging wurde von einer Relay-Härtung zu einer vollständigen Oberfläche weiterentwickelt: SendMessage/ListAgents ermöglichen Ihren Sessions, sich über Ihre Rechner hinweg (macOS/Linux) zu erkennen und miteinander zu kommunizieren; auf der Empfängerseite stehen dafür crossSessionInbound-Steuerelemente zum Akzeptieren, Zurückhalten oder Ablehnen bereit — und self-hosted runners ermöglichen es Claude Code, Web- und Mobile-Sessions auf Hardware auszuführen, die Sie kontrollieren. Für die harness-Architektur wird „eine Session“ damit zu einem adressierbaren Knoten: Erkennung, Inbound-Richtlinien und die oben beschriebene Autoritätsgrenze sind nun Plattformprimitive und keine Mailbox-Skripte mehr (der Claude Code guide dokumentiert den vollständigen Vertrag).⁸⁷ Gleichzeitig ändert sich eine Sicherheitsposition: Der Auto-Modus wird am 14. August 2026 zum Standardberechtigungsmodus für Pro-, Max- und Team-Pläne — ein harness, der sich bei menschlicher Kontrolle auf Aufforderungen im Manual-Modus stützt, sollte defaultMode ausdrücklich festlegen, statt dies vorauszusetzen.⁸⁷

Modellresilienz wurde zu einer Einstellung erster Klasse. Die Einstellung fallbackModel verkettet nun bis zu drei Backup-Modelle, die der Reihe nach ausprobiert werden, wenn das primäre Modell überlastet oder nicht verfügbar ist; bei unerwarteten, nicht wiederholbaren API-Fehlern wird ein Turn einmal automatisch mit dem Fallback wiederholt. Für ein langfristig laufendes autonomes harness wird aus einem vorübergehenden Ausfall des Primärmodells damit eine kontrollierte Degradierung statt eines abgebrochenen Durchlaufs. claude agents --json erhielt außerdem ein Feld waitingFor (v2.1.162), das anzeigt, worauf eine blockierte Hintergrund-Session wartet, etwa auf eine Berechtigungsabfrage — ein Gewinn an Beobachtbarkeit für jeden Koordinator, der eine Flotte von Agents abfragt.

Safe Mode für Clean-Room-Governance und Fehlerbehebung. Claude Code v2.1.169 fügt ein Flag --safe-mode hinzu (sowie die passende Umgebungsvariable CLAUDE_CODE_SAFE_MODE), das eine Session startet, in der sämtliche Anpassungen zugleich deaktiviert sind: CLAUDE.md, Plugins, skills, hooks und MCP-Server.⁶⁰ Das ist das Gegenteil des harness — ein bewusst eingerichteter Clean Room. Damit beantworten Sie die Frage, die sich jeder Operator irgendwann stellt: „Kommt dieses Verhalten vom Modell oder von etwas, das ich konfiguriert habe?“ Wenn ein hook fehlausgelöst wird, sich ein skill aktiviert, obwohl er es nicht sollte, oder ein MCP-Server den Kontext vergiftet, liefert --safe-mode eine bekanntermaßen leere Baseline zum Vergleich. Es ist auch ein Governance-Primitiv: 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-definierte Gerüste es beeinflussen.

Ein Hinweis zu Modellstufen. Mit Claude Code v2.1.197 (30. Juni 2026) ist Claude Sonnet 5 das ausgelieferte Standardmodell für neue Sessions — mit nativem 1M-Kontext und einem Aktionspreis von $2/$10 pro MTok bis zum 31. August — und ersetzt Opus 4.8 als sofort verfügbare Standardwahl. Dieser Leitfaden behandelt Opus 5 (claude-opus-5) als empfohlenen agentischen Standard: als das Modell, auf dem autonome harnesses laufen sollten, sofern Sie nicht bewusst etwas anderes wählen. Gerade bei Agent-Loops mit langem Horizont und hohem Risiko rechtfertigt die Tiefe von Opus’ Schlussfolgerungen seine Kosten. Opus 5 wurde am 24. Juli 2026 als neues Standard-Opus in Claude Code v2.1.219 ausgeliefert — mit 1M Kontext, $5/$25 pro MTok (demselben Preis wie beim abgelösten Opus 4.8), Fast Mode zu $10/$50 bei ungefähr 2,5× der Standardgeschwindigkeit — und Anthropic zufolge erreicht es auf Frontier-Bench v0.1 mehr als die doppelte Leistung von Opus 4.8, während sein CursorBench-3.2-Ergebnis höchstens 0,5 % hinter Fable 5 liegt, bei halben Kosten.⁸⁴⁹¹ Gleicher Preis, mehr Fähigkeiten und ein Modell, das Anthropic als „wesentlich stärker beim Überprüfen seiner Arbeit und beim sorgfältigen Iterieren“ beschreibt, machen dieses Upgrade für harness-Arbeit zu einer seltenen Verbesserung, die kein Kostenargument braucht; die Migration von 4.8 ist eine ID-Änderung. Wechseln Sie für kostensensitive oder hochvolumige Arbeit zu Sonnet 5, wenn dessen Verhältnis von Geschwindigkeit zu Intelligenz überzeugt. Über Opus steht Claude Fable 5 (claude-fable-5), das am 9. Juni 2026 eingeführt wurde — eine neue Stufe, die als leistungsstärkstes Modell von Anthropic beschrieben wird, ein „Mythos-class“-System, das für den allgemeinen Einsatz sicher gemacht wurde und in Claude Code v2.1.170 über /model claude-fable-5 auswählbar ist.⁶⁰ Greifen Sie bewusst zur höheren Stufe, bei Entscheidungen, bei denen rohe Tiefe des Schlussfolgerns die Kosten rechtfertigt, nicht als Pauschaleinstellung für eine Flotte. Der Wechsel zu Opus 5 hat zwei weitere Folgen: Opus 4.7 ist nicht mehr im Fast Mode (/fast gilt nun für Opus 5 und Opus 4.8), und der Fable-5-Fallback des Auto-Mode-Klassifizierers — seit v2.1.176 „das beste verfügbare Opus-Modell“ — wird nun zu Opus 5 aufgelöst.⁸⁴

Codex lieferte Multi-Agent v2 aus. Codex CLI v0.137.0 behält die Runtime-Auswahl bei jedem Thread, bietet sauberere Standardwerte für Follow-ups und Metadaten bei gestarteten Agents (hide_spawn_agent_metadata ist jetzt standardmäßig true) und propagiert rohe Parent-Events an Child-Listener. Sein subagent-Modell bleibt explizit: integrierte Agent-Typen default/worker/explorer, TOML-definierte benutzerdefinierte Agents und Parallelitätssteuerungen (agents.max_threads standardmäßig 6, agents.max_depth standardmäßig 1). Dieselbe Version fügt eine skills-Erweiterung v1 mit einer Skill-Katalogauflösung pro Turn sowie neue Lifecycle-Contributor-Events für Thread-Start und Turn-Fehler hinzu und verringert damit den Abstand zu Claude Code’s hook/skill-Oberfläche, 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-Nachrichten-Payloads sind nun verschlüsselt, ein v2-Agent-Konfigurationskatalog sowie ein Agent-Residency-LRU verwalten, welche Agents resident bleiben, und Parallelität wird anhand der aktiven Ausführung statt anhand gestarteter Threads gezählt, sodass inaktive Agents keinen Slot mehr belegen.⁶¹ Auch der Lifecycle API reifte weiter — close_agent wurde in interrupt_agent (v0.139.0) umbenannt, um widerzuspiegeln, dass ein laufender Agent unterbrochen wird, statt lediglich einen Handle zu schließen — und MCP-Startwarnungen eines subagent bleiben nun auf den zugehörigen Thread beschränkt, statt im Transkript des Parents dupliziert zu werden.⁶¹ Für alle, die Codex-seitige Orchestrierung entwickeln, ist dies der Unterschied zwischen einer Demo und einer Flotte: verschlüsselter Nachrichtentransport, begrenzte Residency, nach Ausführungen gezählte Parallelität und Warnungen, die nicht über die Thread-Grenze hinweg durchsickern. Codex v0.140.0 öffnete anschließend eine Schnittstelle zwischen Tools: /import übernimmt selektiv Setup, Projektkonfiguration und jüngste Chats aus Claude Code in Codex, und Sessions wurden dauerhaft löschbar (codex delete / /delete, mit Bestätigungsschutz).[^^92] /import ist die erste offizielle Anerkennung, dass Operators zwischen harnesses wechseln — die Konfiguration, die Sie für eines erstellen, ist nicht länger darin gefangen.

Speicher und Kontext

Jede AI-Unterhaltung findet innerhalb eines begrenzten Kontextfensters statt. Mit zunehmender Länge der Unterhaltung 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, überleben Turn 15 möglicherweise nicht.⁹

Die drei Mechanismen des Multi-Turn-Kollapses

Die MSR/Salesforce-Studie identifizierte drei unabhängige Mechanismen, die jeweils einen anderen Eingriff erfordern:⁹

Strategie 1: Das Dateisystem als Speicher

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

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

Die Datei MEMORY.md hält Fehler, Entscheidungen und Muster sitzungsübergreifend fest. Wenn Sie feststellen, dass ((VAR++)) mit set -e in bash fehlschlägt, wenn VAR 0 ist, halten Sie dies fest. Wenn Sie drei Sitzungen später in Python auf einen ähnlichen Ganzzahl-Sonderfall stoßen, macht der Eintrag in MEMORY.md dieses Muster sichtbar.¹⁵

Auto Memory (v2.1.32+): Claude Code erfasst und ruft Projektkontext automatisch ab. Während Sie arbeiten, schreibt Claude Beobachtungen in ~/.claude/projects/{project-path}/memory/MEMORY.md. Auto Memory lädt zu Beginn einer Sitzung die ersten 200 Zeilen in Ihren System-Prompt. Halten Sie die Datei knapp und verlinken Sie für detaillierte Notizen auf separate Themendateien.⁶ Seit v2.1.210 führt ein Schreibvorgang in MEMORY.md, der die Größenbegrenzung überschreitet, zu einem Fehler, statt die Datei stillschweigend zu kürzen⁶⁹ — der Fehler wird beim Schreiben sichtbar, statt dass Speichereinträge unbemerkt verschwinden. Wenn Ihr harness Speicherschreibvorgänge automatisiert, behandeln Sie diesen Fehler; die Plattform signalisiert damit, dass die Datei kuratiert werden muss, nicht dass ein erneuter Versuch nötig ist.

Speicherkuratierung statt Speichervolumen (Mai 2026): Ein aktueller arXiv-Preprint zur Zusammenarbeit von LLM-Agenten beschreibt erweiterten Abruf als möglichen Fehlermodus: In den Experimenten der Autoren verschlechterte ein längerer sichtbarer Verlauf die Zusammenarbeit in 18 von 28 Modellspiel-Konfigurationen.⁴⁸ Betrachten Sie dies als Designwarnung, nicht als abschließendes Gesetz. Die Produktionsregel ist bereits klar genug: Halten Sie MEMORY.md kurz, verlinken Sie auf Details und platzieren Sie entscheidungsreife Zusammenfassungen in Übergaben. Rohe Transkript-Dumps, Tool-Logs und lange Abruf-Feeds gehören in durchsuchbaren Speicher, nicht automatisch in den aktiven Prompt.

Strategie 2: Proaktive Komprimierung

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

Wann komprimiert werden sollte: - Nach Abschluss einer klar abgegrenzten Teilaufgabe (Funktion implementiert, Fehler behoben) - Bevor Sie einen neuen Bereich der Codebasis beginnen - Wenn Claude beginnt, früheren Kontext zu wiederholen oder zu vergessen - Ungefähr alle 25–30 Minuten während intensiver Sitzungen

Benutzerdefinierte Komprimierungsanweisungen in CLAUDE.md:

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

Die Komprimierung schützt die Unterhaltung; der Befehl /cd (Claude Code v2.1.169) schützt den Prompt-Cache. Er verschiebt eine Sitzung während des laufenden Vorgangs in ein neues Arbeitsverzeichnis, ohne den über den Turn hinweg aufgebauten Cache zu unterbrechen.⁶⁰ Zuvor bedeutete ein Verzeichniswechsel eine neue Sitzung und einen kalten Cache. Bei einer lang laufenden Sitzung, die von einem Repository zu einem benachbarten wechselt — üblich bei Monorepo- und Multi-Service-Arbeit — bewahrt /cd das teure gecachte Präfix, während der Dateisystemkontext neu ausgerichtet wird.

Strategie 3: Sitzungsübergaben

Erstellen Sie für Aufgaben, die mehrere Sitzungen umfassen, Übergabedokumente, welche 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 liefert der nachfolgenden Sitzung vollständigen Kontext bei minimalem Tokenverbrauch. Eine neue Sitzung mit claude -c (fortsetzen) zu starten oder das Übergabedokument zu lesen, führt direkt zur Implementierung.¹⁵

Strategie 4: Iteration mit frischem Kontext (die Ralph Loop)

Für Sitzungen, die 60–90 Minuten überschreiten, starten Sie pro Iteration eine frische Claude-Instanz. Der Zustand bleibt über das Dateisystem erhalten, nicht über den Gesprächsspeicher. Jede Iteration erhält das vollständige Kontextbudget:¹⁶

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

Vergleich mit einer einzelnen langen Sitzung:

Minute 0:   [fresh context]        -> productive
Minute 30:  [context filling]      -> somewhat productive
Minute 60:  [mostly consumed]      -> degraded
Minute 90:  [compaction pending]   -> significantly degraded
Minute 120: [compressed, lossy]    -> errors accumulate

Der Ansatz mit frischem Kontext pro Iteration tauscht einen Overhead von 15–20 % für den Orientierungsschritt (Zustandsdateien lesen, Git-Historie prüfen) gegen vollständige kognitive Ressourcen pro Iteration.¹⁶ Die Kosten-Nutzen-Abwägung: Für Sitzungen unter 60 Minuten ist eine einzelne Unterhaltung effizienter. Über 90 Minuten hinaus liefert frischer Kontext trotz des Overheads qualitativ bessere Ergebnisse.

Strategie 5: Verwaltete Speicherkuratierung (Dreaming)

Die Managed Agents von Anthropic Claude führten Dreaming am 6. Mai 2026 als Research Preview ein.³⁵ Laut Anthropic: „Dreaming ist ein geplanter Prozess, der Ihre Agentensitzungen und Speicherablagen überprüft, Muster extrahiert und Speicher kuratiert, damit sich Ihre Agenten im Laufe der Zeit verbessern.“³⁵

Dreaming läuft zwischen Sitzungen im Hintergrund und nicht auf dem kritischen Pfad. Es ergänzt das Muster „Dateisystem als Speicher“, statt es zu ersetzen: Ihre Datei MEMORY.md bleibt die tragende Grundlage; Dreaming schreibt kuratierte Speichereinträge in den Speicher von Managed Agents, den der Agent zu Beginn einer Sitzung liest. Die beiden Muster bestehen für harnesses nebeneinander, die selbst gehosteten Dateisystemzustand mit verwalteter Kuratierung kombinieren.

Dreaming befindet sich in Research Preview, sein Verhalten kann sich also ändern. Die oben dokumentierten Muster für Sitzungsübergaben und CLAUDE.md bleiben der maßgebliche Speichermechanismus für selbst gehostete harnesses.

Die Anti-Patterns

Gesamte Dateien lesen, wenn Sie 10 Zeilen benötigen. Das Lesen einer einzelnen Datei mit 2.000 Zeilen verbraucht 15.000–20.000 Tokens. Verwenden Sie Zeilen-Offsets: Read file.py offset=100 limit=20 spart den überwiegenden Teil dieser Kosten.¹⁵

Ausführliche Fehlerausgaben im Kontext behalten. Nach dem Debugging eines Fehlers enthält Ihr Kontext mehr als 40 Stacktraces fehlgeschlagener Iterationen. Ein einzelnes /compact nach der Fehlerbehebung beseitigt diesen Ballast.

Jede Sitzung beginnen, indem jede Datei gelesen wird. Lassen Sie die Glob- und Grep-Tools von Claude Code relevante Dateien bei Bedarf finden und sparen Sie so über 100.000 Tokens unnötigen Vorladens.¹⁵

Subagent-Muster

Subagents sind spezialisierte Claude-Instanzen, die komplexe Aufgaben selbstständig bearbeiten. Die meisten starten mit einem bereinigten Kontext (ohne Inhalte aus der Hauptkonversation) — eine Ausnahme bildet der nachfolgende Typ fork, der bewusst alles übernimmt —, arbeiten mit festgelegten Tools und geben ihre Ergebnisse als Zusammenfassungen zurück. Die Erkundungsergebnisse blähen Ihre Hauptkonversation nicht auf; nur die Schlussfolgerungen werden zurückgegeben.⁵

Integrierte Subagent-Typen

Benutzerdefinierte Subagents erstellen

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

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

You are a senior security engineer reviewing code for vulnerabilities.

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

Focus on actionable security findings, not style issues.

Konfigurationsfelder für Subagents

Worktree-Isolation

Subagents können in temporären Git-Worktrees arbeiten, die eine vollständige isolierte Kopie des Repositorys bereitstellen:⁵

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

Die Worktree-Isolation ist für experimentelle Arbeiten unerlässlich, durch die die Codebasis beschädigt werden könnte.

Isolation ist nur dann Isolation, wenn die Grenze hält. In Claude Code v2.1.210 wurde ein Fehler behoben, durch den Worktree-isolierte Subagents den Haupt-Checkout verändern konnten — genau der Ausfall, den dieser Mechanismus verhindern soll.⁶⁹ Wenn Sie isolation: worktree als Sicherheitsgrenze und nicht nur als Komfortfunktion einsetzen, sollten Sie v2.1.210 als Mindestversion betrachten. Die begleitende Berechtigungsänderung wirkt in die andere Richtung: Seit v2.1.211 bleiben „always allow“-Regeln am Repository-Stamm über Worktrees hinweg bestehen. Eine in einem Worktree akzeptierte Regel gilt also auch für gleichgeordnete Worktrees desselben Repositorys.⁶⁹ Das ist für parallele Worktree-Agenten ergonomisch sinnvoll, bedeutet jedoch, dass eine während eines kurzlebigen Experiments erteilte Freigabe das Experiment überdauert — erteilen Sie Freigaben daher mit Blick auf das gesamte Repository und nicht nur auf den gerade sichtbaren Worktree.

v2.1.216 brachte diese Arbeit zum Abschluss und machte die Worktree-Isolation von einer Fehlerbehebung zu einer belastbar durchgesetzten Schutzmaßnahme.⁷⁴ Die Korrektur in v2.1.210 verhinderte, dass Worktree-Subagents den Haupt-Checkout durch gewöhnliche Git-Aufrufe veränderten. Git selbst bietet jedoch explizite Umleitungen — git -C <path>, --git-dir sowie die Umgebungsvariablen GIT_DIR/GIT_WORK_TREE —, und ein Worktree-isolierter Subagent konnte damit weiterhin gezielt auf den gemeinsamen Checkout zugreifen. All diese Auswege sind nun geschlossen. Dieselbe Version behob außerdem, dass Worktree-Sitzungen gelegentlich im verbliebenen Worktree eines anderen Projekts landeten, verhinderte, dass Schreibvorgänge von Workflows und geplanten Aufgaben einem unter .claude platzierten Symlink zu einem Ziel außerhalb des Projekts folgten, und sorgte dafür, dass /rewind Symlinks und Hardlinks nicht mehr durchläuft. Das Muster hinter allen vier Korrekturen ist gleich: Eine Isolationsgrenze muss gezielten Umleitungen standhalten — Git-Umgebungsüberschreibungen ebenso wie platzierten Symlinks — und nicht nur dem Standardverhalten. Wenn isolation: worktree in Ihrem harness eine Sicherheitsgrenze und nicht bloß eine Komfortfunktion darstellt, ist v2.1.216 die neue Mindestversion.

Parallele Subagents

Verwenden Sie parallele Subagents für unabhängige Rechercheaufgaben, die keine Abstimmung untereinander erfordern:⁵

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

Jeder Agent arbeitet in einem eigenen Kontextfenster, findet relevanten Code und gibt eine Zusammenfassung zurück. Der Hauptkontext bleibt übersichtlich.

Der Rekursionsschutz

Ohne Begrenzung beim Erzeugen delegieren Agenten an Agenten, die wiederum an Agenten delegieren. Dabei geht auf jeder Ebene Kontext verloren und es werden Tokens verbraucht. Das Muster des Rekursionsschutzes 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"

Entscheidende Erkenntnis: Verwenden Sie Erzeugungsbudgets und nicht nur Tiefenbegrenzungen. Tiefenbasierte Begrenzungen verfolgen Eltern-Kind-Ketten (beispielsweise eine Sperre ab Tiefe 3), übersehen aber die Breite: 23 Agenten auf Tiefe 1 sind weiterhin nur „Tiefe 1“. Ein Erzeugungsbudget erfasst die Gesamtzahl aktiver Kindinstanzen pro Elterninstanz und begrenzt sie auf einen konfigurierbaren Höchstwert. Das Budgetmodell bildet den tatsächlichen Fehlermodus ab — zu viele Agenten insgesamt — statt einer Ersatzmetrik — zu viele Verschachtelungsebenen.⁷

Der Standardwert für die Verschachtelungstiefe wurde dreimal geändert; bauen Sie nicht darauf auf. Claude Code v2.1.172 (10. Juni 2026) erlaubte Subagents, eigene Subagents zu erzeugen, und unterstützte eine Verschachtelung von bis zu 5 Ebenen — zuvor war die Delegation faktisch auf eine Ebene beschränkt.⁶² Das galt von v2.1.172 bis einschließlich v2.1.216. v2.1.217 (21. Juli 2026) reduzierte den Wert auf 1 und deaktivierte damit die verschachtelte Erzeugung standardmäßig. v2.1.219 (24. Juli 2026) fand schließlich einen Mittelweg: „Subagents can now spawn nested subagents up to depth 3 by default (was 1); set CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 to disable nesting.“⁸⁴ Erst fünf, dann eins, dann drei — wobei die letzten beiden Änderungen innerhalb von drei Tagen erfolgten.

Die hilfreiche Erkenntnis lautet nicht, dass eine dieser Zahlen richtig ist. Vielmehr sucht die Plattform noch nach einem geeigneten Standardwert, weshalb ein harness nicht einfach „das jeweils Ausgelieferte“ übernehmen sollte. Behandeln Sie die Verschachtelungstiefe als explizite Budgetposition: Setzen Sie CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH auf die Tiefe, die Ihre Architektur tatsächlich benötigt — für die meisten Orchestrierungen ist das 1 oder 2 —, damit ein Upgrade nicht unbemerkt verändert, wie tief Ihre Agentenflotte delegiert. Das grundlegende Argument bleibt trotz all dieser Änderungen bestehen: Ketten aus Agenten, die an weitere Agenten delegieren, verbrauchen Kontext und Tokens schneller, als sie Ergebnisse liefern. Tiefe ist ein Risiko, das Sie budgetieren sollten, und keine Fähigkeit, die Sie möglichst weit ausreizen müssen. Der oben beschriebene recursion guard verhindert, dass sich ein tiefer Baum zu Hunderten aktiver Agenten auffächert, unabhängig davon, wohin sich der Standardwert als Nächstes bewegt. Nur eine selbst festgelegte Begrenzung behält nach der nächsten Version noch die Bedeutung, die Sie ihr zugeschrieben haben.

Auto mode prüft Erzeugungsvorgänge jetzt vor dem Start. Claude Code v2.1.178 schloss die entsprechende Governance-Lücke: Im auto mode bewertet der Berechtigungsklassifikator die Erzeugung von Subagents bevor der Subagent startet, statt erst dann, wenn dieser mit seinen Aktionen beginnt.⁶³ Zuvor konnte ein Subagent erzeugt werden, um eine Aktion anzufordern, die der übergeordneten Sitzung untersagt worden wäre — das Erzeugen selbst stellte die Umgehung dar. Durch die Prüfung beim Erzeugen greifen recursion guard und Berechtigungsmodell endlich ineinander: Eine Kindinstanz kann nicht mehr dazu dienen, eine von der Richtlinie untersagte Aktion zu verschleiern.

Die Plattform bietet jetzt ein natives Erzeugungsbudget. Claude Code v2.1.212 (Juli 2026) führte integrierte Schutzmechanismen gegen außer Kontrolle geratene Schleifen ein: Sitzungen sind standardmäßig auf 200 erzeugte Subagents begrenzt (CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION zur Anpassung, /clear setzt den Zähler zurück), und WebSearch ist auf 200 Aufrufe pro Sitzung beschränkt (CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION).⁶⁹ Das Erzeugungsbudget-Muster, das dieser Abschnitt seit v1.0 als benutzerseitiges Skripting dokumentiert, wird nun von der Plattform bereitgestellt — eine Bestätigung des Budgetmodells gegenüber dem Tiefenmodell. Beachten Sie jedoch die Kalibrierung: 200 erzeugte Instanzen liegen um eine Größenordnung über dem Budget von 12 Agenten in der obigen Konfiguration. Die nativen Obergrenzen sind Sicherungen gegen eine tatsächlich außer Kontrolle geratene Schleife und keine auf Ihre Architektur abgestimmten Budgets. Behalten Sie den benutzerseitigen guard für Budgets pro Elterninstanz, die Tiefenverfolgung und Begrenzungen bei, die dem tatsächlichen Verhalten Ihrer Orchestrierung entsprechen; die Plattformbegrenzung fängt dann auf, was dennoch entwischt.

Die integrierten Schutzmechanismen decken jetzt vier Achsen ab. Drei davon sichern genau das ab, was der benutzerseitige guard in diesem Abschnitt verfolgt: die Gesamtzahl erzeugter Instanzen pro Sitzung (v2.1.212, Obergrenze 200, CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION), die Verschachtelungstiefe (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, derzeitiger und nachweislich instabiler Standardwert 3) sowie die gleichzeitige Ausführung (v2.1.217, Standardwert 20, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS — eine einzelne Nachricht kann nicht mehr unbegrenzt viele Hintergrundagenten auffächern).⁷⁸⁸⁴ v2.1.219 fügt eine vierte Achse hinzu, über die benutzerseitige guards im Allgemeinen nicht verfügten: die Orchestrierungsbreite, also die Anzahl der Agenten, die ein einzelner geplanter Workflow enthalten darf. Sie wird als Standardrichtlinie „aim for fewer than 15 agents“ ausgeliefert und kann über workflowSizeGuideline in jeder Einstellungsdatei festgelegt werden (siehe den nachfolgenden Abschnitt zum Workflow Tool). Damit wird das Erzeugungsbudget-Muster nun auf jeder Achse abgesichert, für die es konzipiert wurde — und zusätzlich auf einer weiteren.

Der Hinweis zur Kalibrierung gilt weiterhin, allerdings nicht gleichmäßig. 200 Erzeugungsvorgänge und 20 gleichzeitig aktive Agenten sind Sicherungen — eine Größenordnung über dem Deliberationsbudget von 12 Agenten in der obigen Konfiguration — und sollen außer Kontrolle geratene Schleifen abfangen, nicht eine Architektur formen. Die Breitenrichtlinie ist die erste native Zahl, die sich in derselben Größenordnung wie ein echtes Budget bewegt: 15 Agenten pro Workflow liegen direkt neben den 12 dieses Leitfadens. Die Übernahme des Plattformstandards kostet Sie daher nichts; wenn Sie davon abweichen, sollten Sie einen konkreten Grund haben. Setzen Sie die drei Sicherungen auf Werte, die Sie begründen können, und die Breitenrichtlinie entsprechend der Struktur der Orchestrierung, die Sie tatsächlich entwickeln wollten.

Agent Teams (Research Preview)

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

Aktivieren mit: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Wann Agent Teams und wann Subagents verwendet werden sollten:

Agent View und Zielschleifen (Mai 2026)

Claude Code v2.1.139 führte Agent View ein, eine Research-Preview-Oberfläche, die mit claude agents gestartet wird und laufende, blockierte sowie abgeschlossene Claude Code-Sitzungen auf einem Bildschirm anzeigt.⁴²⁴³ Die offizielle Dokumentation beschreibt sie als Möglichkeit, zahlreiche Sitzungen zu starten und zu verwalten, die aktuelle Tätigkeit jeder Sitzung einzusehen und zu erkennen, welche Sitzungen Eingaben eines Bedieners benötigen.⁴³ Dadurch erhält die Arbeit mit mehreren Agenten eine operative Übersicht, die Abschlusszusammenfassungen nicht bieten können.

Verwenden Sie Agent View, wenn Sie ein Subagent- oder Team-Muster in den produktiven Einsatz überführen: Prüfen Sie, welche Sitzungen blockiert sind, welche noch laufen und ob die Arbeitsverteilung der vorgesehenen Architektur entspricht. Betrachten Sie die Ansicht nicht als Qualitätsnachweis. Sie schafft Beobachtbarkeit; Tests, Review Gates und Evidenzberichte entscheiden weiterhin darüber, ob die Arbeit belastbar ist.

Dieselbe Version führte /goal ein. Damit wird eine Abschlussbedingung festgelegt, und Claude kann über mehrere Durchläufe hinweg weiterarbeiten, bis diese Bedingung erfüllt ist — auch bei interaktiver Verwendung, mit -p und über Remote Control.⁴² Behandeln Sie /goal als sitzungsbezogene Abschlussschleife und nicht als Ersatz für deterministische Gates. Die Funktion hilft dabei, einen Agenten auf ein Ziel auszurichten; Tests, Zitationsprüfungen, Bereitstellungsprüfungen und Security-hooks sollten jedoch weiterhin auf Befehlen oder Skripten beruhen, wenn ein Fehler den Ablauf blockieren muss.

Workflow Tool (v2.1.147+)

Die dynamischen Workflows von Claude Code sind eine ausgelieferte und standardmäßig verfügbare Oberfläche: Seit v2.1.154 orchestrieren sie Dutzende bis Hunderte Agenten im Hintergrund, werden über /workflows überwacht und bieten eine /config-Steuerung namens „Dynamic workflow size“ (v2.1.202) sowie den Einstellungsschlüssel workflowSizeGuideline, dessen Standardrichtlinie „medium“ lautet — sofern nicht anders angewiesen, sollten weniger als 15 Agenten angestrebt werden (v2.1.219). Die Oberfläche erschien eine Version zuvor erstmals als das standardmäßig deaktivierte Workflow-Tool aus v2.1.147 hinter CLAUDE_CODE_WORKFLOWS=1. Diese Phase mit einem Flag ist inzwischen Geschichte, doch die damals verdeutlichte architektonische Aussage bleibt bestehen.⁵² Damit erhält Claude Code ein integriertes Orchestrierungsprimitiv für Abläufe, die zuvor benutzerdefinierte Dispatcher-Skripte, Mailbox-Zustände und Konventionen zur Koordination von Subagents erforderten.

Entfernen Sie deshalb nicht den umgebenden harness. Ein Workflow kann die Ausführung strukturieren, ersetzt jedoch nicht Ihr Sicherheitsmodell. Behalten Sie PreToolUse- und PostToolUse-hooks als blockierende Ebene bei, verwenden Sie weiterhin Erzeugungsbudgets oder Budgets für Workflow-Schritte, um unkontrollierte Breite zu verhindern, halten Sie den Dateisystemzustand auditierbar und erstellen Sie abschließende Evidenzberichte außerhalb der Selbsteinschätzung des Modells. In der Praxis gilt: Nutzen Sie Workflow für die Form der Orchestrierung und hooks, Tests sowie Review Gates für die Wahrheit.

Dynamische Workflows bringen jetzt eine eigene Vorstellung von Breite mit (v2.1.219). Dynamische Workflows verwenden standardmäßig die Größenrichtlinie „medium“ — „aim for fewer than 15 agents“. Weitere Größen und eine unbeschränkte Option sind unter „Dynamic workflow size“ in /config verfügbar; außerdem zeigt die Statuszeile des laufenden Workflows die aktuelle Richtlinie an.⁸⁴ Die Zahl ist eine Empfehlung und wird nicht erzwungen; sie lenkt den Planer, statt einen zu breiten Plan zu blockieren. Konfigurationswürdig ist sie vor allem wegen ihres Bereitstellungsmechanismus: Der neue Einstellungsschlüssel workflowSizeGuideline kann in jeder Einstellungsdatei gesetzt werden — einschließlich verwalteter Einstellungen und Projekteinstellungen — und ist seit v0.3.219 in den Einstellungstypen des TypeScript SDK enthalten. Dadurch kann ein Team oder eine Organisation die Orchestrierungsbreite standardisieren, statt jeden Bediener sie neu bestimmen zu lassen.⁸⁵ Legen Sie den Wert auf Projektebene fest, um abzubilden, in welche Arbeitseinheiten sich die Aufgaben Ihrer Codebasis tatsächlich zerlegen lassen. Zwei Hinweise für Bediener: Wird der Wert durch eine Einstellungsdatei bestimmt, blendet sich die entsprechende Zeile in /config aus. Das ist das richtige Verhalten, wirkt jedoch wie eine fehlende Einstellung, wenn Sie den Grund nicht kennen. Da die Richtlinie außerdem den Planer lenkt, statt die Ausführung zu sperren, gehört sie in die Spalte Form und nicht in die Spalte Sicherheit. Für außer Kontrolle geratene Breite ist weiterhin die Erzeugungsobergrenze zuständig.

Die wesentliche Einordnung lautet, dass dies eine vierte Achse integrierter Schutzmechanismen darstellt — die Orchestrierungsbreite neben der Anzahl erzeugter Instanzen, der Verschachtelungstiefe und der gleichzeitigen Ausführung — und die erste ist, die Anthropic auf eine plausible Arbeitsgröße statt auf eine Sicherung gegen außer Kontrolle geratene Abläufe kalibriert hat. 15 Agenten pro Workflow liegen in derselben Größenordnung wie das Deliberationsbudget von 12 Agenten, das dieser Leitfaden seit v1.0 verwendet. Wenn der Plattformstandard und Ihr eigenes Budget aus unterschiedlichen Richtungen zum selben Ergebnis gelangen, kommt das einer unabhängigen Bestätigung dieser Zahlen so nahe, wie es in diesem Bereich möglich ist.

Sitzungs-Forking und automatisch in den Hintergrund verschobenes MCP (Juli 2026)

Claude Code v2.1.212 gestaltete zwei Orchestrierungsprimitive neu.⁶⁹ /fork erstellt jetzt aus dem aktuellen Konversationszustand eine neue Hintergrundsitzung — der abgespaltene Verlauf arbeitet unabhängig weiter, während die ursprüngliche Sitzung ihre Arbeit fortsetzt —, und das bisherige sitzungsinterne Verhalten wurde in /subtask umbenannt. Diese Unterscheidung ist für das Orchestrierungsdesign relevant: /subtask ist ein begrenzter Abstecher innerhalb des Lebenszyklus einer Sitzung; /fork bietet eine kostengünstige Möglichkeit, eine parallele Hintergrundsitzung mit vollständig übernommenem Kontext zu erzeugen, und ähnelt damit eher der Instanzerzeugung einer Ralph-Schleife als einem Subagent. Wenn Ihre harness-Skripte davon ausgingen, dass /fork innerhalb der Sitzung bleibt, verteilen sie nun Hintergrundarbeit.

Dieselbe Version verschiebt langsame MCP-Aufrufe automatisch in den Hintergrund: Ein Aufruf eines MCP-Tools, der länger als zwei Minuten dauert, wird automatisch als Hintergrundausführung fortgesetzt (der Schwellenwert lässt sich mit CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS anpassen).⁶⁹ Ein langsamer MCP-Server hält die agentische Schleife dadurch nicht mehr an — allerdings sind „das Tool hat ein Ergebnis zurückgegeben“ und „der Durchlauf wurde fortgesetzt“ nun nicht mehr dasselbe Ereignis. hooks oder Skripte, die von einem synchronen Abschluss von MCP ausgingen, sollten daher an das Tool-Ergebnis und nicht an die Grenze des Durchlaufs anknüpfen.

Für die Headless-Orchestrierung führte v2.1.211 --forward-subagent-text (Umgebungsvariable: CLAUDE_CODE_FORWARD_SUBAGENT_TEXT) ein, wodurch Assistententext von Subagents an die stream-json-Ausgabe weitergeleitet wird.⁶⁹ Ein Koordinatorprozess, der den Stream der übergeordneten Instanz verarbeitet, kann den Fortschritt von Subagents nun direkt beobachten, statt Transkripte abzufragen oder auf die abschließende Zusammenfassung zu warten — die Beobachtbarkeitsergänzung zu standardmäßig im Hintergrund ausgeführten Subagents. v2.1.219 erweiterte dies über die erste Ebene hinaus: Subagents, die auf Tiefe 2 oder tiefer erzeugt werden, erscheinen nun ebenfalls im weitergeleiteten Stream und werden über die tool_use-ID des erzeugenden Agent indiziert.⁸⁴ Auf diesem Schlüssel sollten Sie aufbauen. Da die Verschachtelung wieder standardmäßig aktiviert ist, wäre ein flacher Stream aus Subagent-Text mehrdeutig — die ID zeigt einem Koordinator, welche Elterninstanz welche Kindinstanz erzeugt hat. Dadurch lässt sich der Delegationsbaum aus dem Stream rekonstruieren, statt nur erschlossen zu werden. Wurde Ihr Stream-Verbraucher für lediglich eine Subagent-Ebene entwickelt, sieht er nun Text von Agenten, deren Existenz ihm bislang unbekannt war; gruppieren Sie nach der tool_use-ID des erzeugenden Agent, statt anzunehmen, jede weitergeleitete Zeile gehöre zu einer direkten Kindinstanz.

Multi-Agent-Orchestrierung

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

Toolübergreifende Orchestrierung (April 2026): Google veröffentlichte Scion am 7. April als Open Source — einen Multi-Agent-Hypervisor, der Claude Code, Gemini CLI und andere „deep agents“ als parallele Prozesse ausführt, jeweils mit isoliertem Container, git worktree und Zugangsdaten. Läuft lokal, über einen Hub oder in Kubernetes. Explizite Philosophie: „isolation over constraints“ — Agenten arbeiten mit hoher Autonomie innerhalb von Grenzen, die auf Infrastrukturebene und nicht im Prompt durchgesetzt werden.²⁵ Dies erweitert das Argument der Subagent-Isolation unmittelbar auf verschiedene Tool-Anbieter. Wenn Ihr Workflow Claude und OpenAI-Modelle umfasst, ist Scion die erste echte Referenzimplementierung für toolübergreifende subagents mit Worktree- und Zugangsdatenisolation pro Agent.

Debatten sind kein Allheilmittel: Der Forschungscluster M3MAD-Bench (Anfang 2026) stellte fest, dass Multi-Agent-Debatten ein Plateau erreichen und durch irreführenden Konsens unterlaufen werden können — valide Argumente verlieren, wenn andere Agenten selbstsicher die falsche Antwort behaupten.²⁶ Tool-MAD verbessert dies, indem jedem Agenten heterogener Tool-Zugriff gegeben und in der Bewertungsphase Faithfulness-/Relevance-Scores verwendet werden. Wenn Sie eine debatttenähnliche Orchestrierung entwickeln, investieren Sie in (a) Tool-Heterogenität pro Agent und (b) quantitative Bewertungs-Scores, statt anzunehmen, dass mehr Agenten = bessere Antworten bedeutet.

Verwaltete Multiagent-Orchestrierung und Outcomes (Public Beta)

Wenn Sie die unten beschriebene Deliberation-Infrastruktur nicht selbst entwickeln möchten, ging Multiagent Orchestration am 6. Mai 2026 in Claude Managed Agents in die Public Beta.³⁵ Laut Anthropic: „When there is too much work for a single agent to do well, multiagent orchestration lets a lead agent break the job into pieces and delegate each one to a specialist with its own model, prompt, and tools.“³⁵ Spezialisten „work in parallel on a shared filesystem and contribute to the lead agent’s overall context.“³⁵

Tracing ist direkt enthalten. Laut Anthropic: „you can also trace every step in the Claude Console: which agent did what, in what order, and why, giving you full visibility into how your task was delegated and executed.“³⁵

Die begleitende Public-Beta-Funktion ist Outcomes. Laut Anthropic: „you write a rubric describing what success looks like and the agent works toward it. A separate grader evaluates the output against your criteria in its own context window, so it isn’t influenced by the agent’s reasoning.“³⁵ Dies ist die Managed-Service-Version des weiter unten in diesem Abschnitt dokumentierten Zwei-Gate-Validierungsmusters: Die Rubric ersetzt das handgeschriebene Gate, der separate Grader ersetzt den Konsensvalidator.

Selbstgehostete Deliberation bleibt die richtige Wahl, wenn die Validierung in Ihre eigene Hook-Oberfläche integriert werden muss (PreToolUse-Blockierung, Exit-Code-Semantik, benutzerdefinierte dispatcher) oder wenn der harness ohne externe Abhängigkeiten laufen muss. Managed Multiagent ist die richtige Wahl, wenn Standarddelegation plus Rubric-Bewertung genau den Vertrag darstellt, den Sie benötigen.

Minimal umsetzbare Deliberation

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

Der Confidence-Trigger

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

1. Mehrdeutigkeit - Hat die Anfrage mehrere gültige Interpretationen?
2. Domänenkomplexität - Erfordert sie Fachwissen?
3. Tragweite - Ist die Entscheidung reversibel?
4. Kontextabhängigkeit - Erfordert sie ein Verständnis des übergeordneten Systems?

Der Score wird drei Stufen zugeordnet:

Der Schwellenwert passt sich an den Aufgabentyp an. Sicherheitsentscheidungen erfordern einen Konsens von 0.85. Dokumentationsänderungen benötigen nur 0.50. So wird verhindert, dass einfache Aufgaben überentwickelt werden, während risikoreiche Entscheidungen die nötige Prüfung erhalten.⁷

Die Zustandsmaschine

Sieben Phasen, die jeweils durch die vorherige abgesichert sind:⁷

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

DELIBERATION: Agenten sehen alle Rechercheergebnisse und entwickeln Alternativen. Der Debate-Agent identifiziert Konflikte. Der Synthesis-Agent kombiniert widerspruchsfreie Erkenntnisse.

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

Die Zwei-Gate-Validierungsarchitektur

Zwei Validierungs-Gates erkennen Probleme in unterschiedlichen Phasen:⁷

Gate 1: Konsensvalidierung (PostToolUse hook). Wird unmittelbar nach Abschluss jedes Deliberation-Agenten ausgeführt: 1. Die Phase muss mindestens RANKING erreicht haben 2. Mindestens 2 Agenten müssen abgeschlossen sein (konfigurierbar) 3. Der Konsensscore erfüllt den aufgabenadaptiven Schwellenwert 4. Falls ein Agent abgewichen ist, müssen die Bedenken dokumentiert sein

Gate 2: Pride Check (Stop hook). Wird ausgeführt, bevor die Sitzung geschlossen werden kann: 1. Vielfältige Methoden: mehrere unterschiedliche Personas sind vertreten 2. Transparenz bei Widersprüchen: abweichende Meinungen haben dokumentierte Gründe 3. Umgang mit Komplexität: mindestens 2 Alternativen wurden entwickelt 4. Konsens-Confidence: als stark (über 0.85) oder moderat (0.70-0.84) eingestuft 5. Verbesserungsnachweis: Die finale Confidence übersteigt die anfängliche Confidence

Zwei hooks an unterschiedlichen Punkten des Lebenszyklus entsprechen dem tatsächlichen Auftreten von Fehlern: Manche sind sofort erkennbar (schlechter Score), andere entwickeln sich schrittweise (geringe Vielfalt, fehlende Dokumentation abweichender Meinungen).⁷

Warum Zustimmung gefährlich ist

Charlan Nemeth untersuchte Minderheitsdissens von 1986 bis zu ihrem Buch In Defense of Troublemakers aus dem Jahr 2018. Gruppen mit Andersdenkenden treffen bessere Entscheidungen als Gruppen, die schnell Übereinstimmung erzielen. Die abweichende Person muss nicht recht haben. Der Akt des Widerspruchs zwingt die Mehrheit dazu, Annahmen zu prüfen, die sie sonst übersprungen hätte.¹⁸

Wu et al. testeten, ob LLM-Agenten tatsächlich debattieren können, und stellten fest, dass Agenten ohne strukturelle Anreize zum Widerspruch unabhängig von der Richtigkeit zur selbstsichersten anfänglichen Antwort konvergieren.¹⁹ Liang et al. identifizierten die Ursache als „Degeneration-of-Thought“: Sobald ein LLM Vertrauen in eine Position aufgebaut hat, kann Selbstreflexion keine neuen Gegenargumente erzeugen, weshalb Multi-Agent-Bewertung strukturell notwendig ist.²⁰

Unabhängigkeit ist die entscheidende Designvorgabe. Zwei Agenten, die dieselbe Deployment-Strategie bewerteten und Einblick in die Erkenntnisse des jeweils anderen hatten, erzielten Scores von 0.45 und 0.48. Dieselben Agenten ohne Einblick: 0.45 und 0.72. Die Differenz zwischen 0.48 und 0.72 sind die Kosten von Herding.⁷

Scheinbare Zustimmung erkennen

Ein Konformitätserkennungsmodul 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 eher auf Kontamination durch gemeinsamen Kontext als auf unabhängige Beurteilung hin. Als fünf Agenten, die ein Authentication-Refactoring bewerteten, das Sicherheitsrisiko alle zwischen 7.1 und 7.4 einstuften, führte eine erneute Ausführung mit frischer Kontextisolation zu einer Streuung der Scores von 5.8 bis 8.9.

Textbaustein-Dissens: Agenten kopieren die Formulierungen der Bedenken anderer, statt unabhängige Einwände zu generieren.

Fehlende Minderheitsperspektiven: Einstimmige Zustimmung von Personas mit widersprüchlichen Prioritäten (ein Security Analyst und ein Performance Engineer stimmen selten in allem überein).

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

Was bei Deliberation nicht funktioniert hat

Freiform-Debattenrunden. Drei Runden wechselseitiger Texte zu einer Datenbankindexierungsdiskussion erzeugten 7,500 Token an Debatte. Runde 1: echte Meinungsverschiedenheit. Runde 2: wiederholte Positionen. Runde 3: identische Argumente mit anderen Worten. Strukturiertes Dimensions-Scoring ersetzte die Freiform-Debatte, senkte die Kosten um 60 % und verbesserte zugleich die Ranking-Qualität.⁷

Ein einziges Validierungs-Gate. Die erste Implementierung führte einen Validierungs-hook am Sitzungsende aus. Ein Agent schloss die Deliberation mit einem Konsensscore von 0.52 (unter dem Schwellenwert) ab und setzte anschließend 20 Minuten lang die Arbeit an nicht zusammenhängenden Aufgaben fort, bevor der Hook am Sitzungsende den Fehler meldete. Die Aufteilung in zwei Gates (eines nach Abschluss der Aufgabe, eines am Sitzungsende) erkannte dieselben Probleme an unterschiedlichen Punkten des Lebenszyklus.⁷

Kosten der Deliberation

Jeder Recherche-Agent verarbeitet ungefähr 5,000 Token Kontext und generiert 2,000-3,000 Token an Erkenntnissen. Bei 3 Agenten sind das 15,000-24,000 zusätzliche Token pro Entscheidung. Bei 10 Agenten etwa 50,000-80,000 Token.⁷

Bei den aktuellen Opus-5-Preisen ($5/$25 pro MTok) kostet eine Deliberation mit 3 Agenten ungefähr $0.23-0.30. Eine Deliberation mit 10 Agenten kostet $0.75-1.00. Das System löst Deliberation bei ungefähr 10 % der Entscheidungen aus, sodass die amortisierten Kosten über alle Entscheidungen hinweg $0.08-0.10 pro Sitzung betragen. (Frühere Ausgaben nannten das Dreifache dieser Werte, berechnet mit den bisherigen Preisen von $15/$75 für Opus 4.x.) Ob sich das lohnt, hängt davon ab, was eine schlechte Entscheidung kostet.

Wann Sie deliberieren sollten

CLAUDE.md-Design

CLAUDE.md ist eine Betriebsrichtlinie für einen AI-Agenten, keine README für Menschen.²¹ Der Agent muss nicht verstehen, warum Sie Conventional Commits verwenden. Er muss den exakten auszuführenden Befehl kennen und wissen, wann eine Aufgabe als „erledigt“ gilt.

Die Rangfolge

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

Was ignoriert wird

Diese Muster führen nachweislich zu keiner beobachtbaren Änderung des Agentenverhaltens:²¹

Prosaabsätze ohne Befehle. „Wir legen Wert auf sauberen, gut getesteten Code“ ist Dokumentation, keine Betriebsanweisung. Der Agent liest dies und schreibt anschließend Code ohne Tests, weil eine konkrete Handlungsanweisung fehlt.

Mehrdeutige Anweisungen. „Seien Sie bei Datenbankmigrationen vorsichtig“ ist keine Einschränkung. „Führen Sie vor dem Anwenden von Migrationen alembic check aus. Brechen Sie ab, wenn der Downgrade-Pfad fehlt.“ ist eine.

Widersprüchliche Prioritäten. „Arbeiten Sie schnell und liefern Sie zügig aus“ plus „Stellen Sie eine umfassende Testabdeckung sicher“ plus „Halten Sie die Laufzeit unter 5 Minuten“ plus „Führen Sie vor jedem Commit vollständige Integrationstests aus.“ Der Agent kann nicht alle vier Vorgaben gleichzeitig erfüllen und überspringt deshalb standardmäßig die Überprüfung.²¹

Styleguides ohne Durchsetzungsmechanismus. „Befolgen Sie den Google Python Style Guide“ gibt dem Agenten ohne ruff check --select D keine Möglichkeit, 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

Reihenfolge beim Verfassen

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

1. Build- und Testbefehle (der Agent benötigt diese, bevor er etwas Nützliches tun kann)
2. Definition of Done (verhindert fälschlich als abgeschlossen gemeldete Aufgaben)
3. Eskalationsregeln (verhindert destruktive Umgehungslösungen)
4. Aufgabenorientierte Abschnitte (reduziert die Verarbeitung irrelevanter Anweisungen)
5. Verzeichnisbezogene Geltungsbereiche (bei Monorepos: hält dienstspezifische Anweisungen voneinander getrennt)

Lassen Sie Stilpräferenzen zunächst aus, bis die ersten vier Punkte funktionieren.

Die Plattform prüft Ihre CLAUDE.md jetzt für Sie. Seit den Releases von Anfang Juli 2026 (v2.1.203–v2.1.206) analysiert /doctor CLAUDE.md und schlägt vor, Inhalte zu kürzen, die das Modell selbst aus der Codebasis ableiten kann – erneut aufgeführte Verzeichnisstrukturen, bereits im Code erkennbare Framework-Konventionen und Befehlslisten, die Package-Skripte duplizieren.⁶⁸ Dies bestätigt aus erster Hand die These dieses Abschnitts: Anweisungen rechtfertigen ihren Token-Verbrauch, indem sie festhalten, was der Agent nicht ableiten kann (Richtlinien, Schwellenwerte, Abschlussdefinitionen), statt Informationen zu wiederholen, die er von der Festplatte lesen kann. Führen Sie /doctor aus, nachdem CLAUDE.md erheblich gewachsen ist, und betrachten Sie die Kürzungsvorschläge als Ausgangspunkt. Behalten Sie jedoch Betriebsregeln bei, die möglicherweise als „ableitbar“ markiert werden, wenn es sich um tragende Einschränkungen statt um Beschreibungen handelt.

Dateiimporte

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

Importsyntax: relativ (@docs/file.md), absolut (@/absolute/path.md) oder aus dem Home-Verzeichnis (@~/.claude/file.md). Maximale Tiefe: 5 Importebenen.⁶

Werkzeugübergreifende Kompatibilität von Anweisungen

AGENTS.md ist ein offener Standard, den alle wichtigen AI-Coding-Tools unterstützen.²¹ Wenn Ihr Team mehrere Tools verwendet, schreiben Sie AGENTS.md als kanonische Quelle und spiegeln Sie die relevanten Abschnitte in werkzeugspezifische Dateien:

Die Muster aus AGENTS.md – befehlsorientiert, mit definiertem Abschluss und aufgabenorientiert – funktionieren unabhängig vom Tool in jeder Anweisungsdatei. Pflegen Sie keine parallelen Anweisungssätze, die mit der Zeit auseinanderdriften. Schreiben Sie eine maßgebliche Quelle und spiegeln Sie deren Inhalte.

Hinweise zur Codex-Parität

Codex verfügt inzwischen über vollwertige Entsprechungen für die wichtigsten harness-Ebenen, doch die Migration ist eine Übertragung von Mustern, keine bloße Dateikopie. Codex liest vor Arbeitsbeginn AGENTS.md und kombiniert dabei globale Vorgaben aus ~/.codex mit Projektanweisungen und verschachtelten Repository-Anweisungen.³¹ Codex skills verwenden dasselbe SKILL.md-Grundmodell mit schrittweiser Offenlegung: Codex beginnt mit dem Namen, der Beschreibung und dem Dateipfad des skill und lädt ihn erst vollständig, wenn es sich für dessen Verwendung entscheidet.³² Codex bietet außerdem native hooks, in Plugins gebündelte hooks, verwaltete hooks, Unterstützung für MCP und explizite subagent-Workflows.³³³⁴

Codex v0.138.0–v0.139.0 hat diese AGENTS.md-Erkennung für nicht triviale Arbeitsbereiche robuster gemacht: Das Laden erfolgt nun über die Dateisystemabstraktion der Umgebung und bewahrt während der Erkennungssuche logische Pfade, sodass selbst bei einem Remote-Dateisystem oder einer durch symbolische Links strukturierten Verzeichnisstruktur die richtige Datei ausgewählt wird.⁶¹ Dies ist immer dann relevant, wenn Ihre kanonische AGENTS.md die maßgebliche Quelle ist und der Agent mit einem eingebundenen, in einem Container materialisierten oder über symbolische Links bereitgestellten Checkout arbeitet – also genau in den Fällen, in denen eine naive Pfadsuche unbemerkt die falsche oder gar keine Anweisungsdatei auswählt. Wenn Sie eine maßgebliche AGENTS.md über mehrere Dienste hinweg spiegeln, sollten Sie diese Version als Mindestvoraussetzung dafür betrachten, darauf zu vertrauen, dass der Agent tatsächlich die von Ihnen verfasste Datei geladen hat.

Codex v0.141.0 hat anschließend den Remote-Ausführungspfad selbst robuster gemacht: Remote-Executors stellen nun Verbindungen über authentifizierte, Ende-zu-Ende-verschlüsselte Noise-relay-Kanäle her (Control Plane und Executor müssen dem Relay zwischen ihnen nicht mehr vertrauen), plattformübergreifende Remote-Ausführungen bewahren das native Arbeitsverzeichnis und die Shell des Executors, und TLS akzeptiert P-521-Zertifikatsignaturen für Unternehmens-Proxys.⁶⁵ Wenn Ihre Orchestrierung Codex-Executors über eine Netzwerkgrenze hinweg steuert, markiert dies den Unterschied zwischen der Annahme eines vertrauenswürdigen Relays und einer Ende-zu-Ende-verschlüsselten Verbindung – behandeln Sie es als Mindeststandard für jede Remote-Executor-Topologie.

Die Release-Reihe vom Juli 2026 zeigt, wie sich beide Laufzeitumgebungen aus entgegengesetzten Richtungen denselben Grundbausteinen annähern.⁷² In Codex v0.143.0 werden MCP-Tools standardmäßig über Toolsuche geladen – Toolschemas werden zurückgestellt und bei Bedarf abgerufen, statt vorab in den Kontext geladen zu werden. Dies entspricht demselben Muster zum verzögerten Laden von Tools, das Claude Code über seine ToolSearch-Oberfläche bereitstellt, und ist in beiden Laufzeitumgebungen die richtige Antwort auf einen aufgeblähten Kontext bei einer hohen Anzahl von MCP-Tools. Codex v0.144.0 fügt einen writes-App-Genehmigungsmodus hinzu: Schreibgeschützte Aktionen werden ohne Nachfrage ausgeführt, während Schreibvorgänge eine Genehmigung erfordern. Dabei handelt es sich um einen tatsächlich neuen Berechtigungsmodus zwischen „read-only“ und „auto-approve“, für den die Modusliste von Claude Code keine direkte Entsprechung bietet (am nächsten kommt der plan-Modus, der Schreibvorgänge vollständig blockiert, statt für jeden Schreibvorgang einzeln nachzufragen). Mit demselben Release erreicht die interaktive MCP-Authentifizierung die allgemeine Verfügbarkeit. Und v0.144.5 erweitert die Erkennung gefährlicher Befehle, entsprechend den Schutzmechanismen gegen destruktive Befehle, die Claude Code mit v2.1.183 und v2.1.208 eingeführt hat. Für das Laufzeitumgebungen übergreifende harness-Design ist diese Annäherung entscheidend: Verzögertes Laden von Tools, abgestufte Schreibgenehmigungen und die Erkennung gefährlicher Befehle auf Absichtsebene werden zu Grundvoraussetzungen statt zu Unterscheidungsmerkmalen einzelner Anbieter.

Codex v0.145.0 treibt diese Annäherung an zwei Fronten weiter voran.⁷⁶ Die optionale multi-agent V2-Oberfläche wurde stabilisiert: Modelle, Reasoning-Stufen und Parallelität von subagents sind nun konfigurierbar, und die zuvor entfernten Agentenrollen wurden wiederhergestellt – die Codex-Entsprechung zur Konfiguration von Modell und Aufwand pro subagent im Frontmatter von .claude/agents/. Zudem wurde /import zu einer vollständigen harness-übergreifenden Migration ausgebaut: Über den mit v0.140.0 eingeführten Import von Claude Code-Einstellungen hinaus migriert der Befehl nun Einstellungen aus Claude Code und Cursor – einschließlich MCP-Servern, Plugins, Sitzungen, Befehlen und projektspezifischen Erinnerungen. Für Teams, die beide Laufzeitumgebungen einsetzen, sinken die Migrationskosten zwischen ihnen in einer Richtung immer weiter. Die auf Claude Code aufgebauten harness-Ebenen – Server, skills als Befehle und memory – werden zunehmend zu portablem Zustand statt zu Anbieterbindung.

Die praktische Zuordnung:

Der entscheidende Unterschied: Claude subagents können anhand ihrer Beschreibungen automatisch ausgewählt werden, während Codex subagent-Workflows derzeit als explizit dokumentiert. Daher sind skills und hooks in Codex die richtige Standardeinstellung für dauerhaft aktives harness-Verhalten; subagents eignen sich für gezielte parallele Arbeit, Reviews und Erkundungen.

Ihre Anweisungen testen

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

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

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

Der Härtetest: Bitten Sie den Agenten, Ihre Build-Befehle zu erläutern. Kann er sie nicht wortgetreu wiedergeben, sind die Anweisungen entweder zu ausführlich (Inhalte wurden aus dem Kontext verdrängt), zu vage (der Agent kann keine konkreten Handlungsanweisungen extrahieren) oder werden nicht erkannt. Die Analyse von GitHub mit 2.500 Repositorys ergab, dass unpräzise Formulierungen die meisten Fehler verursachen.²¹

Produktionsmuster

Opus 4.7-Muster für Langzeitaufgaben (April 2026)

Claude Opus 4.7 (16. April 2026) wurde mit spezifischen Funktionen veröffentlicht, die verändern, wogegen sich ein harness schützen muss:²⁹

• Resilienz bei Tool-Fehlern: Opus 4.7 arbeitet trotz Tool-Fehlern weiter, die Sitzungen mit Opus 4.6 zum Stillstand brachten. Sie können defensive Wiederholungs-Wrapper im subagents-Code reduzieren — aber nicht vollständig entfernen. Behalten Sie die Guards auf Hook-Ebene bei; straffen Sie das In-Prompt-Gerüst „Wenn das Tool fehlschlägt, versuche es dreimal erneut“.
• xhigh-Aufwandsstufe: Zusammen mit Opus 4.7 eingeführt und inzwischen auf aktuellen Opus-Modellen unterstützt (Opus 4.8 wurde damit als /effort xhigh in v2.1.154 veröffentlicht; Opus 5 übernimmt sie). Sie liegt zwischen high und max. Empfohlene Standardeinstellung für Coding- und agentische Workloads. Bei lang laufenden subagents übertrifft xhigh high deutlich bei unterproportionalen Tokenkosten. max bleibt die richtige Wahl für einmaliges, schwieriges Reasoning; für anhaltende Aufgaben ist xhigh besser geeignet.
• Obergrenze für das Tokenbudget: Pro Agent-Ausführung über output_config.task_budget konfigurierbar (Beta-Header task-budgets-2026-03-13). Das Modell sieht einen laufenden Countdown und passt den Arbeitsumfang dem Budget elegant an, statt unerwartet an die Grenze zu stoßen. Nutzen Sie dies für agentische Loops, in denen Sie vorhersehbare Tokenkosten wünschen, ohne bei kurzen Prompts Qualität einzubüßen.
• Bewusstsein für implizite Bedürfnisse: Erstes Claude Modell, das „implicit-need“-Tests besteht — es erkennt also, wenn die wörtliche Anfrage des Benutzers unzureichend beschreibt, was tatsächlich benötigt wird. Dadurch ist der Abschnitt „clarifying rules“ in CLAUDE.md weniger nötig. Falls Ihre CLAUDE.md aus 200 Zeilen mit Guardrails wie „Berücksichtige auch X, wenn der Benutzer nach Y fragt“ besteht, streichen Sie die Punkte, die nun nativ abgedeckt sind.

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

Claude Code v2.1.133 fügt vier Einstellungen auf Admin-Ebene hinzu, die für Production-harnesses wichtig sind:³⁹

Die Rücknahme von worktree.baseRef sollten Sie Benutzern besonders deutlich machen: Agents, die sich auf das Verhalten von v2.1.128–v2.1.132 verlassen haben (Worktrees verzweigen von lokalem HEAD), verlieren in frischen Worktrees den Zugriff auf nicht gepushte Arbeit, sofern sie sich nicht wieder dafür entscheiden.

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ätsumfrage innerhalb der Session für Enterprises wieder zu aktivieren, die die Antworten über OpenTelemetry erfassen.⁴⁰ Wenn Ihre Organisation OTel-Ereignisse in einen zentralen Observability-Stack leitet, bringt diese Umgebungsvariable die Umfrage zurück in den Datenpfad, sodass Qualitätssignale durch dieselbe Pipeline wie Latenz- und Fehlermetriken fließen. Behandeln Sie dies als Opt-in: Standardmäßig bleibt die Umfrage unterdrückt, was für Nicht-OTel-Deployments richtig ist.

Unternehmens-Launcher und Performance im MCP-Umfang (Juli 2026)

Zwei Änderungen in v2.1.207 sind für Production-Deployments relevant.⁶⁸ CLAUDE_CODE_PROCESS_WRAPPER ermöglicht es verwalteten Umgebungen, den Claude Code-Prozess über eine Unternehmens-Wrapper-Binärdatei zu starten — der Integrationspunkt für Endpoint-Agents, Richtlinienprüfungen beim Start und Umgebungen, in denen jeder Prozess unter einem vorgeschriebenen Supervisor laufen muss. Falls Ihr Enterprise dies bisher mit Shell-Aliasen oder geforkten Launcher-Skripten nachgebildet hat, ist dies die unterstützte Schnittstelle.

Dieselbe Version senkte den Runtime-Overhead dort, wo harnesses ihn am stärksten spüren: bis zu 7× schnellere Tool-Use-Runden in Sessions mit hohen MCP-Tool-Anzahlen und 79× kleinere Session-Transkripte.⁶⁸ Das relativiert — ohne sie aufzuheben — die Hinweise unter Kosten als Architektur: CLI-first gewinnt weiterhin bei zustandslosen Einmaloperationen, aber ein harness mit Dutzenden MCP Tools zahlt nicht mehr die Penalty pro Runde wie im Frühjahr, und die Speicherung von Transkripten ist kein versteckter Kostenfaktor langer autonomer Läufe mehr.

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 - Falls ein Kriterium des evidence gate fehlschlägt, kehren Sie zu Schritt 4 zurück.
7. Berichten - Listen Sie auf, was sich geändert hat, wie es verifiziert wurde, und führen Sie konkrete Evidenz an.

Das Evidence Gate

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

Falls Sie für eine Zeile keine Evidenz vorlegen 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 Handlungsfähigkeit von Merge-Governance.⁴⁷ Die nützliche Architekturlehre ist einfach: Agents können Arbeit beginnen, Branches weiterführen, PRs öffnen, Arbeit reviewen und Risiken zusammenfassen, während die 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 Genehmigung für Merges, Releases und destruktive Repository-Operationen, sofern die Organisation nicht über eine separat auditierte Automatisierungsrichtlinie verfügt. Wenn Automatisierung einen Merge ausführt, bewahren Sie Logs auf, die zwischen dem Ausführenden und dem Menschen oder der Richtlinie unterscheiden, die ihn autorisiert hat.

Muster zur Fehlerbehandlung

Atomare Dateischreibvorgänge. Wenn mehrere Agents gleichzeitig in dieselbe Zustandsdatei schreiben, wird JSON beschädigt. Schreiben Sie in .tmp-Dateien und verwenden Sie anschließend atomar mv. Das Betriebssystem garantiert, dass mv im selben 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 Zustandsbeschädigung. Wenn der Zustand beschädigt wird, erstellt das Wiederherstellungsmuster 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 Bash-Falle ((VAR++)). ((VAR++)) gibt Exit-Code 1 zurück, wenn VAR 0 ist, weil 0++ zu 0 ausgewertet wird, was Bash als false behandelt. Ist set -e aktiviert, beendet dies das Skript. Verwenden Sie stattdessen VAR=$((VAR + 1)).¹⁶

Blast-Radius-Klassifizierung

Klassifizieren Sie jede Agent-Aktion nach Blast Radius und schalten Sie sie entsprechend frei:²

Remote Control (Verbindung mit lokalem Claude Code aus jedem Browser oder jeder mobilen App) verwandelt das „External“-Gate von einer blockierenden Wartezeit in eine asynchrone Benachrichtigung. Der Agent arbeitet an der nächsten Aufgabe weiter, während Sie die vorherige auf Ihrem Smartphone 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

Die Kriterien müssen maschinell überprüfbar sein: Test bestanden/nicht bestanden, Linter-Ausgabe, HTTP-Statuscodes, Prüfungen auf vorhandene Dateien. Eine frühe Aufgabe, in der der Agent „Tests schreiben sollte, die bestehen“, erzeugte assert True und assert 1 == 1. Technisch korrekt. Praktisch wertlos.¹⁶

Zu beobachtende Fehlermodi

Ein konkreter Session-Trace

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

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

2. Der Agent liest das PRD und plant die erste Story. UserPromptSubmit wird ausgelöst. Der dispatcher injiziert: aktiven Projektkontext, Baseline für Session Drift.

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

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

5. Der Agent beendet die Story. Stop wird ausgelöst. Das Quality Gate prüft: Hat der Agent Evidenz angeführt? Unverbindliche Sprache verwendet? TODO-Kommentare im Diff? Falls eine Prüfung fehlschlägt, Exit 2 und der Agent arbeitet weiter.

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

7. Drei Code-Review-Agents starten parallel. Jeder reviewed den Diff unabhängig. Falls ein Reviewer CRITICAL markiert, kommt die Story zurück in die Queue.

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

Insgesamt ausgelöste hooks über 5 Stories: ~340. Gesamte Zeit in hooks: ~12 Sekunden. Dieser Overhead verhinderte in einem einzigen Lauf über Nacht drei Credential-Leaks, einen destruktiven Befehl und zwei unvollständige Implementierungen.

Fallstudie: Verarbeitung von PRDs über Nacht

Ein Production-harness verarbeitete 12 PRDs (47 Stories) über 8 Sessions hinweg über Nacht. Die Metriken vergleichen die ersten 4 PRDs (minimaler harness: nur CLAUDE.md) mit den letzten 8 (vollständiger harness: hooks, skills, Quality Gates, Multi-Agent-Review).

Die zwei Credential-Leaks erforderten das Rotieren von API-Schlüsseln und die Prüfung nachgelagerter Services: ungefähr 4 Stunden Incident Response. Der harness-Overhead, der das Äquivalent verhinderte, betrug 2,4 Sekunden Bash pro Story. Die Rate falscher Abschlüsse sank von 35 % auf 4 %, weil der Stop hook unabhängig Tests ausführte, bevor der Agent den Abschluss 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 dieses Leitfadens — und gehen darüber hinaus:

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

Der zustandslose Turn und die selbstgemeldete Identität von MCP. Die MCP-Spezifikation schloss mit der Revision vom 28. Juli 2026, nun die Current spec, ihren Übergang zu einem zustandslosen Kern (SEP-2575) ab. Damit entfällt der zustandsbehaftete initialize-Handshake, der zuvor die Serveridentität übermittelte. Eine Änderung der Draft-Spec, die am 16. Juli (PR #3002) gemergt wurde, stellt die Identität als optionale Oberfläche wieder her: Server können ein Objekt io.modelcontextprotocol/serverInfo in Antwort-_meta einschließen, und clientInfo wird bei Anfragen optional.⁷¹ Der sicherheitsrelevante Teil ist, was die Spezifikation über Vertrauen sagt: Diese Identität ist selbstgemeldet und nicht verifiziert — nur für Anzeige und Protokollierung — und SHOULD NOT für Sicherheitsentscheidungen verwendet werden. Wenn Ihr harness Allowlist-, Berechtigungsregeln oder protokollbasierte Audits an den deklarierten Namen eines MCP-Servers bindet, ist dieser Name eine Behauptung, keine Credential; verankern Sie Vertrauen im Transport und in der Konfiguration (welchen Server Sie an welchem Endpunkt konfiguriert haben), niemals darin, was der Server über sich selbst sagt. Die zustandslose Revision wurde planmäßig am 28. Juli 2026 ausgeliefert (obligatorisches server/discover, Protokollversionsverhandlung über _meta, Streamable-HTTP-Header) — die obige Vertrauensrichtlinie beschreibt das ausgelieferte Verhalten.

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 mittels Isolierung auf Betriebssystemebene einschränkt (seatbelt unter macOS, bubblewrap unter Linux). Wenn sie aktiviert ist, verhindert die Sandbox, dass das Modell beliebige Netzwerkanfragen stellt oder auf Dateien außerhalb des Projektverzeichnisses zugreift. Ohne Sandboxing verwendet Claude Code ein berechtigungsbasiertes Modell, bei dem Sie einzelne Tool-Aufrufe genehmigen oder ablehnen.¹³

Sicherheitsminimum vom Mai 2026. Claude Code v2.1.149 behob einen Berechtigungsumgehung für das PowerShell-Arbeitsverzeichnis, mehrere Lücken bei PowerShell-Allow-Regeln und der Berechtigungsanalyse veralteter Variablen sowie einen Fehler in der Sandbox-Schreib-Allowlist für git-worktree, der das vollständige Haupt-Repository-Root statt nur gemeinsam genutzter git-Interna abdeckte.⁵³ Wenn Ihr harness PowerShell oder über Worktrees isolierte Agents zulässt, behandeln Sie v2.1.149+ als Mindestversion und halten Sie Shell-Regeln eng gefasst. Breite PowerShell(*)- und repositoryweite Schreibausnahmen sind Orchestrierungsabkürzungen, keine Sicherheitsgrenzen.

OpenAI Agents SDK Sandbox-Lockdown (v0.17.0, 8. Mai 2026). Auf der OpenAI-Seite verschärfte openai-agents-python v0.17.0 eine parallele Grenze: LocalFile.src und LocalDir.src sind nun auf die Materialisierungs-base_dir beschränkt (das aktuelle Arbeitsverzeichnis des SDK-Prozesses, wenn das Manifest angewendet wird), sofern die Quelle nicht explizit über Manifest.extra_path_grants mit SandboxPathGrant gewährt wird.⁴¹ Relative lokale Quellen werden ausgehend von base_dir aufgelöst; absolute Pfade müssen sich bereits darin befinden oder eine Gewährung enthalten. Dies schließt ein lokales Artefaktgrenzenproblem: Frühere Versionen erlaubten Manifesten, beliebige Host-Pfade in einen Sandbox-Workspace zu übernehmen. Migration: Deklarieren Sie vertrauenswürdige Host-Roots auf Manifestebene mit SandboxPathGrant(path=..., read_only=True) für schreibgeschützte Mounts. Behandeln Sie extra_path_grants als vertrauenswürdige Anwendungskonfiguration; befüllen Sie Gewährungen niemals aus Modellausgaben oder nicht vertrauenswürdigen Manifest-Eingaben.

OpenAI Agents SDK Folge-Mindestversion (v0.17.3). Die Reihe 0.17.1–0.17.3 fügte weitere Sandbox- und Sitzungsverhärtungen hinzu: Limits für Archivextraktion, GitRepo-Subpfadvalidierung, klarere Fehler von Sandbox-Providern, aus Sandbox-Befehlen herausgehaltene Mountpoint-Credentials, die Ablehnung relativer Sandbox-Workspace-Roots und die Behandlung von Terminalzuständen der Vercel-Sandbox.⁵⁴ Wenn Sie OpenAI-gehostete oder provider-gestützte Sandboxes statt ausschließlich Claude Code-Hooks verwenden, behandeln Sie 0.17.3 als aktuelle Mindestversion für die Muster dieses Abschnitts.

Drei Containment-Muster produktübergreifend (Anthropic, Mai 2026)

Der Engineering-Beitrag von Anthropic „How we contain Claude across products“ (25. Mai 2026) ist die eigene Darlegung des Herstellers zu den Prinzipien, die dieser Abschnitt schrittweise vermittelt — die Sandbox auf Einstellungsebene oben, das Minimum für Worktree-Isolation, die Haltung, alles als nicht vertrauenswürdig zu behandeln.⁸¹ Der Kern besteht darin, die Stärke der Containment-Maßnahmen der Produktoberfläche zuzuordnen; diese Zuordnung selbst ist die Lektion: Es gibt kein einzig richtiges Isolierungsdesign, sondern nur Isolierung, die dazu passt, wer überwacht und was schiefgehen kann.

• Ephemere gVisor-Container (claude.ai). Serverseitige Ausführung erfolgt in gVisor-Containern auf isolierter Infrastruktur mit einem ephemeren Dateisystem pro Sitzung. Das Bedrohungsmodell betrifft Infrastruktur- und Tenant-Isolation — der Rechner des Benutzers ist niemals erreichbar, daher muss nichts Lokales verteidigt werden.
• OS-Sandboxing mit Human-in-the-loop (Claude Code). Das im Sandbox-Absatz oben beschriebene Muster, als Richtlinie formuliert: Seatbelt unter macOS und bubblewrap unter Linux, mit erlaubten Lesezugriffen, auf den Workspace beschränkten Schreibzugriffen und standardmäßig verweigertem Netzwerk — der Mensch genehmigt, was die Grenze nicht abdeckt. Anthropic veröffentlichte die Runtime (sandbox-runtime) als Open Source, damit die Grenze prüfbar ist. Der Beitrag benennt das schwache Glied offen: Rund 93 % der Berechtigungsaufforderungen werden genehmigt, und der Auto-Mode-Klassifikator — der ungefähr 83 % übereifriger Verhaltensweisen vor der Ausführung erkennt und Berechtigungsaufforderungen um 84 % reduziert — existiert genau deshalb, weil Genehmigungsmüdigkeit eine Sicherheitseigenschaft und keine UX-Beschwerde ist. Das ist die Check-Layer-Haltung, die dieser Leitfaden seit v2.1.193 verfolgt.
• Versiegelte VMs (Claude Cowork). Vollständige virtuelle Maschinen auf Plattform-Hypervisoren — Apple Virtualization framework unter macOS, HCS unter Windows — wobei nur der ausgewählte Workspace und der Ordner .claude eingebunden werden; nichts anderes auf dem Host ist sichtbar. Credentials gelangen niemals in die VM: Sie verbleiben im Host-Keychain, und jede Sitzung erhält ein begrenztes, unabhängig widerrufbares Token. Ein defensiver MITM-Proxy innerhalb der VM erzwingt dies und leitet nur Anfragen weiter, die das eigene bereitgestellte Sitzungstoken der VM tragen — ein von einem Angreifer eingebetteter Schlüssel wird an der Grenze abgewiesen, weil nur die VM die Herkunft kennt.

Die den Kategorien zugrunde liegenden Designprinzipien sind der übertragbare Teil. Containment zuerst auf Umgebungsebene, Steuerung danach auf Modellebene: Jede probabilistische Verteidigung hat eine Missrate ungleich null, daher müssen deterministische Grenzen abfangen, was die Steuerung auf Prompt-Ebene verfehlt — das Argument dieses Leitfadens, dass Hooks die Ausführung garantieren, vom Hersteller erneut formuliert. Passen Sie die Isolierungsstärke an die Fähigkeit des Benutzers zur Überwachung an: Ein Entwickler kann einen Bash-Befehl vor seiner Genehmigung bewerten; ein Knowledge Worker kann das nicht — deshalb erhält Code einen Berechtigungsdialog und Cowork eine versiegelte VM. Bevorzugen Sie kampferprobte Primitive gegenüber benutzerdefiniertem Isolierungscode: Hypervisoren, seccomp und Container-Runtimes haben gegnerischer Prüfung besser standgehalten als die eigenen benutzerdefinierten Allowlist-Proxys und Konfigurationsparser von Anthropic. Behandeln Sie projektlokale Konfiguration und Tool-Ausgaben als nicht vertrauenswürdig: Die Anweisung des Beitrags lautet, das Öffnen eines Projekts und das Laden von Konfiguration wie jede eingehende Anfrage aus dem Internet zu behandeln sowie Tool-Ausgaben als Angriffsfläche, selbst wenn das Tool vertrauenswürdig ist — dieselbe Haltung, die dieser Leitfaden auf Inter-Agent-Nachrichten, von Subagents gelesene Inhalte und selbstgemeldete MCP-Identität anwendet. Halten Sie Credentials außerhalb der Sandbox: begrenzte, widerrufbare Tokens pro Sitzung statt allgegenwärtiger Schlüssel, die der Agent preisgeben könnte.

Die Einstellungsoberfläche holt beim ersten Prinzip auf (v2.1.219). „Containment zuerst auf Umgebungsebene“ ist leicht zu befürworten und war schwer tatsächlich zu konfigurieren, weil die Sandbox von Claude Code bei nicht abgedeckten Regeln durch Nachfragen entschied — und eine Berechtigungsaufforderung eine probabilistische Verteidigung im Gewand einer deterministischen ist, wie die obige 93-%-Genehmigungsquote einräumt. sandbox.network.strictAllowlist entfernt die Frage für ausgehenden Netzwerkverkehr: Ist diese Einstellung gesetzt, wird die Anfrage eines sandboxed Befehls an einen nicht allowgelisteten Host direkt verweigert, statt eine Aufforderung auszulösen.⁸⁴ Kombinieren Sie dies mit sandbox.filesystem.disabled aus v2.1.216, und die beiden Einstellungen ergeben eine Haltung statt eines Haufens von Umschaltern — Dateisystem- und Netzwerk-Containment sind unabhängig auswählbar, und Netzwerk-Containment kann nun deterministisch gestaltet werden. Für einen unbeaufsichtigten harness ist dies die wichtigere der beiden Optionen, weil ausgehender Verkehr der Punkt ist, an dem eine injizierte Anweisung zur Exfiltration wird, und der Endzustand von Genehmigungsmüdigkeit darin besteht, dass niemand an der Tastatur sitzt, der müde werden könnte. Die Kosten entsprechen den üblichen Kosten einer deterministischen Grenze: Die Allowlist muss korrekt sein, und ein vergessener Host schlägt als undurchsichtige Verweigerung statt als Frage fehl. Listen Sie die Hosts auf, die Ihre Agents legitim benötigen, und entfernen Sie dann die Aufforderung.

Nichts davon ersetzt die Hook-Ebene; es liegt unter ihr. Die Containment-Muster sind das deterministische Fundament, und die Geschichte der Worktree-Durchsetzung in diesem Leitfaden ist dieselbe Lektion im Kleinen: Eine Grenze zählt nur, wenn sie bewusster Umleitung standhält, und die Primitive, die am ehesten standhalten, sind diejenigen, die nicht für den Anlass geschrieben wurden.

Berechtigungsgrenzen

Das Berechtigungssystem kontrolliert Operationen auf mehreren Ebenen:

Berechtigungsregeln auf Parameterebene (Juni 2026)

Claude Code v2.1.178 erweiterte Berechtigungsregeln von der Tool-Ebene bis hinunter auf die Parameter-Ebene: Tool(param:value) wird mit den Eingabeparametern eines Tools abgeglichen, wobei * als Wildcard dient. Das kanonische Beispiel lautet Agent(model:opus) — eine Regel, die verhindert, dass Subagents auf einem bestimmten Modell-Tier gestartet werden.⁶³ Architektonisch schließt dies eine Lücke, die die obige Tabelle mit vier Ebenen nicht ausdrücken konnte: Zuvor erlaubten oder verweigerten Sie ein Tool vollständig, konnten aber nicht einschränken, wie es aufgerufen wurde. Eine Governance-Richtlinie kann nun sagen: „Subagents dürfen starten, aber nicht auf dem Fable-5-Tier“ oder „Bash ist erlaubt, aber nicht mit diesem Flag“ — als deterministische Regel statt als Anfrage auf Prompt-Ebene.

Eine begleitende verwaltete Einstellung, enforceAvailableModels (v2.1.175), beschränkt die Modellauswahl von oben nach unten: Sie fixiert das Default-Modell und verhindert, dass benutzer- oder projektbezogene Einstellungen die verwaltete Allowlist availableModels erweitern.⁶³ Die beiden greifen ineinander — die Allowlist definiert, welche Tiers für die Sitzung überhaupt existieren, und Regeln auf Parameterebene beschränken, wie Subagents daraus wählen. Ab v2.1.196 können Administratoren außerdem über die Org-Konsole ein organisationsweites Default-Modell festlegen, das in /model als „Org default“ angezeigt wird, sodass eine Flotte einen geregelten Standard erbt, ohne dass jeder Operator einen festlegen muss — ein Fundament als Ergänzung zur Obergrenze der Allowlist.

Pfadbezogene Allow-Regeln verankern sich im Arbeitsverzeichnis (Juli 2026)

Claude Code v2.1.214 schloss einen unauffälligen Überabgleich in pfadbezogenen Berechtigungsregeln: Eine Allow-Regel mit einem dir/**-Muster mit einem einzigen Segment — etwa Edit(src/**) — genehmigte Bearbeitungen in jedem Verzeichnis namens src in jeder Tiefe automatisch, einschließlich vendor/some-package/src/ und jedem anderen verschachtelten src/, das der Autor der Regel niemals freigeben wollte. Solche Regeln verankern sich nun nur noch bei <cwd>/dir; falls Sie tatsächlich Abgleich in jeder Tiefe wünschen, deklarieren Sie ihn mit **/dir/**.⁷⁴ Deny- und Ask-Regeln behalten bewusst den bisherigen Abgleich in jeder Tiefe bei. Diese Asymmetrie ist das korrekte Fail-safe-Design: Eine zu eng passende Allow-Regel schlägt sicher fehl (Sie erhalten eine Aufforderung), während eine zu eng passende Deny-Regel offen fehlschlägt (ein blockierter Pfad rutscht durch) — daher wurden Allows strenger und Denys blieben breit. Wenn Ihre Einstellungen auf Allow-Mustern mit einem einzelnen Segment beruhen, um verschachtelte Pfade abzudecken, erfüllen sie dies ab v2.1.214 stillschweigend nicht mehr; das ist die beabsichtigte Wirkung des Fixes, aber Ihre Allowlists sollten Sie daraufhin überprüfen, die Breite zu deklarieren, die Sie tatsächlich wünschen.

Schutzmechanismen für destruktive Befehle im Auto Mode (Juni 2026)

Claude Code v2.1.183 begrenzte den Schadensradius des Auto Mode für Operationen, die stillschweigend Arbeit verlieren lassen oder Umgebungen abbauen. Auto Mode blockiert nun standardmäßig, sofern Sie sie nicht ausdrücklich in der Sitzung angefordert haben: destruktive git-Operationen (git reset --hard, git checkout -- ., git clean -fd, git stash drop); git commit --amend, wenn der Commit nicht in dieser Sitzung vom Agent erstellt wurde; sowie Infrastrukturabbau (terraform destroy, pulumi destroy, cdk destroy), sofern Sie nicht den konkreten Stack genannt haben.⁶⁵ Architektonisch ergänzt dies die Spawn-Prüfung und die Parameteregeln oben: Anstatt zu kontrollieren, welches Tool oder wie es gestartet wird, kontrolliert es eine kleine Menge konkreter irreversibler Befehle nach Absicht — der Agent kann sie weiterhin ausführen, aber nur auf explizite Anweisung, nicht aus eigener Initiative. Kodieren Sie für einen autonomen harness dasselbe Prinzip in Ihren eigenen PreToolUse-Hooks: Befehle, die Zustand zerstören, verdienen eine Deny-by-default-Regel, die nur ein explizites Operatorsignal aufhebt.

Juli 2026: Auto Mode wird enterprise-tauglich, und eine Aufforderung kann nicht abgewählt werden. Auto Mode erreichte in v2.1.207 auf Amazon Bedrock, Google Vertex AI und Microsoft Foundry GA, mit der verwalteten Einstellung disableAutoMode als Enterprise-Opt-out — die Klassifikator-als-Check-Layer-Haltung ist nun auf jeder First-Party-Enterprise-Plattform verfügbar, und ihre Deaktivierung ist eine explizite Governance-Entscheidung statt einer Plattformlücke.⁶⁸ v2.1.208 machte dann den Schutz vor katastrophalen Löschungen absolut: Bestätigungsaufforderungen für katastrophale Löschungen durchbrechen sowohl --dangerously-skip-permissions als auch Auto Mode.⁶⁸ Das ist ein bemerkenswerter Präzedenzfall — die erste Bestätigung in Claude Code, die durch keine Berechtigungshaltung, einschließlich des expliziten Bypass-Flags, aufgehoben werden kann. Entwürfe autonomer harnesses, die davon ausgingen, dass --dangerously-skip-permissions buchstäblich null Aufforderungen bedeutet, sollten diese eine Ausnahme berücksichtigen; sie greift genau dort, wo eine unbeaufsichtigte Schleife den größten irreparablen Schaden anrichten kann.

Schutzmechanismen gegen Fabrikation (Juli 2026)

Die Releases v2.1.203–v2.1.206 schlossen zwei Wege, über die ein Agent seine eigene Audit-Spur fabrizieren konnte.⁶⁸ Erstens blockiert eine Auto-Mode-Regel nun die Manipulation von Transkriptdateien — der Sitzungsdatensatz ist nicht länger etwas, das die eigenen Tool-Aufrufe der Sitzung umschreiben können. Zweitens geben Benachrichtigungen über Hintergrundaufgaben nun explizit an, dass keine menschliche Eingabe erfolgte, während die Aufgabe lief. Die zweite Änderung richtet sich gegen einen subtilen Fehler: Ein Modell, das eine Hintergrundaufgabe zusammenfasste, konnte zuvor eine „Genehmigung“ im Transkript darstellen (oder erfinden), die nie erfolgte, und nichts in der Benachrichtigung widersprach dem. Nun ist die Benachrichtigung selbst die Gegen-Evidenz.

Die Architekturerkenntnis lässt sich auf das Evidence Gate übertragen: Transkripte, Benachrichtigungen und Logs sind Audit-Oberflächen, und Audit-Oberflächen dürfen nicht durch dasjenige beschreibbar sein, das sie auditieren. Die Plattform erzwingt dies nun für ihr eigenes Transkript; wenden Sie dieselbe Regel auf Ihren harness an — Evidenzberichte, Testergebnisse und Deliberation-Aufzeichnungen gehören außerhalb des beschreibbaren Pfads des Modells.

Verteidigung gegen Prompt Injection

Skills und Hooks ermöglichen Defense-in-depth gegen Prompt Injection:

Skills mit Tool-Einschrä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 aufgefordert 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 wurde.

Das Plattformminimum stieg im Juli 2026. Claude Code v2.1.210 härtete das Agent tool gegen indirekte Prompt Injection, die in von einem Subagent gelesenen Inhalten enthalten ist — eine vergiftete Datei, Webseite oder ein von einem Subagent abgerufenes Tool-Ergebnis kann die Delegierungsoberfläche selbst weniger gut steuern.⁶⁹ Und v2.1.211 härtete das menschliche Glied in der Kette: Berechtigungsvorschauen neutralisieren nun bidirektionale Override-, Zero-Width- und ähnlich aussehende Unicode-Zeichen, sodass ein Befehl nicht mehr so gestaltet werden kann, dass er im Genehmigungsdialog harmlos angezeigt wird, während er etwas anderes ausführt.⁶⁹ Der zweite Fix ist besonders wichtig für harnesses, bei denen ein Mensch gerenderte Vorschauen unter Zeitdruck genehmigt — auch die Anzeige war eine Injektionsfläche. Keine der beiden Änderungen ersetzt die Hook-Level-Verteidigungen oben; sie erhöhen das Sicherheitsminimum darunter.

Agent-Logs und Guardrails sind Sicherheitsoberflächen

Zwei Advisories vom Mai 2026 verstärken ein Muster: Agent-Infrastruktur schafft neue Orte, an denen sensible Inhalte und ausführbare Richtlinien auslaufen oder entkommen können. GitHub Advisory GHSA-f3jg-756w-gm35 behandelt ein Payload-Filterproblem von Gryph Agents, bei dem sensible Tool-Payload-Inhalte unter dem Standard-Protokollierungsverhalten in lokalen SQLite-Logs verbleiben konnten.⁴⁵ OSV GHSA-wxxx-gvqv-xp7p behandelt einen LiteLLM-Sandbox-Escape für Custom-Code-Guardrails in einem durch Administratoren geschützten Proxy-Endpunkt.⁴⁶

Die Produktionsregel: Behandeln Sie Agent-Transkripte, Tool-Payloads, SQLite-Logs und die Ausführung von Guardrails als sensible Infrastruktur. Redigieren Sie vor der Persistierung, wenden Sie Aufbewahrungslimits an und halten Sie benutzerdefinierten Guardrail-Code sandboxed und überprüfbar. Eine Regel auf Prompt-Ebene wie „keine Secrets protokollieren“ reicht nicht aus; der Logging- und Guardrail-Pfad benötigt deterministische Tests.

Hook-Sicherheit

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

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

Die Aufteilung der Verantwortung zwischen Mensch und Agent

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

Das Muster: Menschen verantworten Entscheidungen, die Organisationskontext, ethisches Urteilsvermögen oder strategische Ausrichtung erfordern. Agents verantworten Entscheidungen, die rechnerische Suche über große Möglichkeitsräume erfordern. Hooks erzwingen die Grenze.

Rekursive Hook-Durchsetzung

Hooks werden auch für Aktionen von Subagents 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 Sicherheits-Gates umgehen. Das Ereignis SubagentStop ermöglicht es Ihnen, Bereinigung oder Validierung auszuführen, wenn ein Subagent abgeschlossen ist.

Das ist nicht optional. Ein Agent, der einen Subagent ohne Ihre Sicherheits-Hooks startet, ist ein Agent, der einen Force-Push nach main durchführen, Credential-Dateien lesen oder destruktive Befehle ausführen kann, während Ihre Gates dem Hauptgespräch zusehen und nichts tun.

Kosten als Architektur

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

Token-Ebene. Komprimierung des System-Prompts. Entfernen Sie Tutorial-Codebeispiele (das Modell kennt die APIs), reduzieren Sie doppelte Regeln über Dateien hinweg, und ersetzen Sie Erklärungen durch Einschränkungen. „Reject tool calls matching sensitive paths“ leistet dasselbe wie eine 15-zeilige Erklärung dafür, warum Credentials nicht gelesen werden sollten.

Agent-Ebene. Frische Spawns statt langer Gespräche. Jede Story in einem autonomen Lauf erhält einen neuen Agent mit sauberem Kontext. Der Kontext wächst nie unkontrolliert, weil jeder Agent neu beginnt. Briefing statt Memory: Modelle führen ein klares Briefing besser aus, als dass sie 30 Schritte angesammelten Kontexts navigieren.

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

Entscheidungsrahmen

Wann Sie welchen Mechanismus einsetzen sollten:

Skills vs Hooks vs Subagents

FAQ

Wie viele Hooks sind zu viele?

Nicht die Anzahl, sondern die Performance ist der begrenzende Faktor. Jeder Hook wird synchron ausgeführt, daher summiert sich die gesamte Hook-Ausführungszeit bei jedem passenden Tool-Aufruf. 95 Hooks in Einstellungen auf Benutzer- und Projektebene laufen ohne merkliche Latenz, wenn jeder Hook in unter 200 ms abgeschlossen ist. Der relevante Schwellenwert: Wenn ein PostToolUse hook zu jeder Dateibearbeitung mehr als 500 ms hinzufügt, fühlt sich die Sitzung träge an. Profilieren Sie Ihre Hooks mit time, bevor Sie sie bereitstellen.¹⁴

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

Ja. PreToolUse hooks blockieren jede Tool-Aktion, indem sie mit Code 2 beendet werden. Claude Code bricht die ausstehende Aktion ab und zeigt dem Modell die stderr-Ausgabe des Hooks. Claude sieht den Grund für die Ablehnung und schlägt eine sicherere Alternative vor. Exit 1 ist eine nicht blockierende Warnung, bei der die Aktion dennoch fortgesetzt wird.³

Wo sollte ich Hook-Konfigurationsdateien ablegen?

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

Braucht jede Entscheidung deliberation?

Nein. Das Confidence-Modul bewertet Entscheidungen anhand von vier Dimensionen (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, Umbenennungen von Variablen und Routinebearbeitungen überspringen deliberation vollständig. Sicherheitsarchitektur, Änderungen am Datenbankschema und irreversible Deployments lösen sie konsistent aus.⁷

Wie teste ich ein System, das Uneinigkeit erzeugen soll?

Testen Sie sowohl Erfolgs- als auch Fehlerpfade. Erfolg: Agents sind produktiv uneinig und erreichen einen Konsens. Fehler: Agents konvergieren zu schnell, konvergieren nie oder überschreiten Spawn-Budgets. Ende-zu-Ende-Tests simulieren jedes Szenario mit deterministischen Agent-Antworten und prüfen, dass beide Validierungsgates jeden dokumentierten Fehlermodus erkennen. Ein Produktionssystem für deliberation führt 141 Tests über drei Ebenen aus: 48 Bash-Integrationstests, 81 Python-Unit-Tests und 12 Ende-zu-Ende-Pipeline-Simulationen.⁷

Welche Latenzauswirkung hat deliberation?

Eine deliberation mit 3 Agents fügt 30–60 Sekunden Echtzeit hinzu (dieses deliberation-Design führt seine Agents nacheinander über das Agent tool aus; die Plattform selbst führt subagents seit v2.1.198 parallel im Hintergrund aus). Eine deliberation mit 10 Agents fügt 2–4 Minuten hinzu. Die Konsens- und Pride-Check-Hooks laufen jeweils in unter 200 ms. Der primäre Engpass ist die LLM-Inferenzzeit pro Agent, nicht der Orchestrierungsaufwand.⁷

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 von Kontextfenstern abgeschnitten; stellen Sie daher die kritischsten Anweisungen an den Anfang: Befehle und Abschlussdefinitionen vor Stilpräferenzen.²¹

Kann dies mit anderen Tools als Claude Code funktionieren?

Die Architekturprinzipien (Hooks als deterministische Gates, Skills als Domänenwissen, Subagents als isolierte Kontexte, Dateisystem als Speicher) gelten konzeptionell für jedes agentische System. Die konkrete Implementierung verwendet 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 toolspezifisch sind.

Schnellreferenzkarte

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

Dateipfade

Änderungsprotokoll

Quellenangaben