Agentenarchitektur: Entwicklung KI-gestützter Entwicklungssysteme

Kurzfassung: Claude Code ist keine Chatbox mit Dateizugriff. Es handelt sich um eine programmierbare Laufzeitumgebung mit 30 dokumentierten Lebenszyklusereignissen, die sich jeweils mit Shell-Skripten verknüpfen lassen, welche das Modell nicht überspringen kann. Kombinieren Sie hooks zu dispatchers, dispatchers zu skills, skills zu agents und agents zu Workflows, erhalten Sie ein autonomes Entwicklungsharness, das Einschränkungen durchsetzt, Arbeit delegiert, Speicher sitzungsübergreifend erhält und Multi-Agent-Deliberation orchestriert. Mit Claude Code v2.1.147 kam das standardmäßig deaktivierte Workflow-Tool (CLAUDE_CODE_WORKFLOWS=1) hinzu. Dadurch entwickelt sich die deterministische Multi-Agent-Orchestrierung von reinen Userland-Skripten hin zu einem Laufzeitprimitiv aus erster Hand; v2.1.149 unterstreicht dieselbe Erkenntnis aus Sicherheitsperspektive durch Korrekturen für die Umgehung von PowerShell-Berechtigungen und die Allowlist der git-worktree-Sandbox. Für die Korrektheit sind weiterhin hooks und evidence gates zuständig.⁵²⁵³ Dieser Leitfaden behandelt jede Ebene dieses Stacks: von einem einzelnen hook bis zu einem Konsenssystem mit 10 agents. Keine Frameworks erforderlich. Ausschließlich bash und JSON.

Andrej Karpathy prägte einen Begriff für das, was um einen LLM agent herum entsteht: claws. Gemeint sind die hooks, Skripte und die Orchestrierung, mit denen der agent die Welt außerhalb seines Kontextfensters greifen kann.¹ Die meisten Entwickler betrachten KI-Coding-agents als interaktive Assistenten. Sie geben einen Prompt ein, beobachten, wie eine Datei bearbeitet wird, und machen weiter. Diese Sichtweise begrenzt die Produktivität auf das, was Sie persönlich beaufsichtigen können.

Das Infrastruktur-Denkmodell ist ein anderes: Ein KI-Coding-agent ist eine programmierbare Laufzeitumgebung mit einem LLM-Kernel. Jede Aktion des Modells durchläuft hooks, die Sie kontrollieren. Sie definieren Richtlinien, keine Prompts. Das Modell arbeitet innerhalb Ihrer Infrastruktur so, wie ein Webserver innerhalb von nginx-Regeln arbeitet. Sie sitzen nicht vor nginx und geben Anfragen ein. Sie konfigurieren und deployen es und überwachen seinen Betrieb.

Dieser Unterschied ist entscheidend, weil sich Infrastrukturvorteile mit der Zeit verstärken. Ein hook, der Zugangsdaten in bash-Befehlen blockiert, schützt jede Sitzung, jeden agent und jeden autonomen Durchlauf. Ein skill, der Ihre Bewertungsrubrik abbildet, wird konsistent angewendet – unabhängig davon, ob Sie oder ein agent ihn aufrufen. Ein agent, der Code auf Sicherheitsprobleme prüft, führt dieselben Kontrollen aus, ob Sie ihn dabei beobachten 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 gibt lediglich eine Warnung aus.³
• Skills bilden automatisch aktiviertes Fachwissen ab. Das Feld description ist für die gesamte Aktivierungsentscheidung ausschlaggebend. Claude entscheidet mittels LLM-Reasoning und nicht anhand von Schlüsselwortübereinstimmungen, wann ein skill angewendet wird.⁴
• Subagents verhindern eine Überlastung des Kontexts. 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 die Beteiligten dauerhaft koordiniert werden müssen.⁵
• Der Speicher befindet sich im Dateisystem. Dateien bleiben über Kontextfenster hinweg erhalten. CLAUDE.md, MEMORY.md, Regelverzeichnisse und Übergabedokumente bilden ein strukturiertes externes Speichersystem.⁶
• Multi-Agent-Deliberation deckt blinde Flecken auf. Einzelne agents können ihre eigenen Annahmen nicht infrage stellen. Zwei unabhängige agents mit unterschiedlichen Bewertungsprioritäten erkennen strukturelle Fehler, die quality gates nicht erfassen können.⁷
• Das harness-Muster ist das System. CLAUDE.md, hooks, skills, agents und Speicher sind keine unabhängigen Funktionen. Gemeinsam bilden sie eine deterministische Ebene zwischen Ihnen und dem Modell, die mit zunehmender Automatisierung skaliert.

So verwenden Sie diesen Leitfaden

Jeder Abschnitt baut auf dem vorherigen auf. Der Entscheidungsrahmen am Ende enthält eine Nachschlagetabelle, mit der Sie für jeden Problemtyp den richtigen 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-Muster

Das harness ist kein Framework. Es ist ein Muster: ein kombinierbarer Satz aus Dateien, Skripten und Konventionen, der 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        │
└──────────────────────────────────────────────────────────────┘

Anweisungsebene: CLAUDE.md-Dateien und Regelverzeichnisse legen fest, was der Agent über Ihr Projekt weiß. Sie werden zu Beginn jeder Sitzung und nach jeder Komprimierung automatisch geladen. Dies ist das langfristige Architekturgedächtnis des Agenten.

Erweiterungsebene: skills stellen Fachwissen bereit, das kontextabhängig automatisch aktiviert wird. hooks bilden deterministische Schranken, die bei jedem passenden Tool-Aufruf ausgelöst werden. Speicherdateien bewahren den Zustand sitzungsübergreifend. Benutzerdefinierte Agenten ermöglichen spezialisierte subagents-Konfigurationen.

Orchestrierungsebene: Multi-Agent-Muster koordinieren unabhängige Agenten für Recherche, Prüfung und Abwägung. Spawn-Budgets verhindern unkontrollierte Rekursion. Konsensvalidierung sichert die Qualität.

Die zentrale Erkenntnis: Die meisten Benutzer arbeiten ausschließlich auf der Kernebene und sehen dabei zu, wie der Kontext immer weiter anwächst und die Kosten steigen. Erfahrene Benutzer konfigurieren die Anweisungs- und Erweiterungsebenen und verwenden die Kernebene anschließend nur noch für die Orchestrierung und abschließende Entscheidungen.²

Verwaltete und selbst gehostete Harnesses (April 2026)

Anfang 2026 war „ein eigenes harness entwickeln“ die einzige echte Möglichkeit. Im April 2026 änderte sich das. Anthropic veröffentlichte Claude Managed Agents als öffentliche Beta-Version (8. April): harness-Schleife + Tool-Ausführung + Sandbox-Container + Zustandspersistenz als REST API, abgerechnet nach Standardtokens zuzüglich 0,08 $ pro Sitzungsstunde. Das Update von OpenAIs Agents SDK (16. April) formalisierte dieselbe Trennung – harness und Rechenleistung als separate Ebenen, mit nativen Sandbox-Anbietern (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) sowie Snapshot/Wiederherstellung, um Containerverluste zu überstehen.²³²⁴

Die umfassendere SDK-Oberfläche auf OpenAI-Seite erschien in openai-agents Python v0.14.0 (veröffentlicht am 15. April 2026; angekündigt am 16. April): eine SandboxAgent-Unterklasse von Agent mit default_manifest, Sandbox-Anweisungen und Funktionen; ein Manifest, das den Vertrag für einen neuen Arbeitsbereich beschreibt (Dateien, Verzeichnisse, lokale Dateien, Git-Repositorys, Umgebungsvariablen, Benutzer, Einbindungen); eine SandboxRunConfig für die laufbezogene Verknüpfung von Sandbox-Client, Einbindung einer aktiven Sitzung, Manifest-Überschreibungen, Snapshots und Parallelitätsgrenzen bei der Materialisierung. Die integrierten Funktionen umfassen Shell-Zugriff, Dateisystembearbeitung, Bildprüfung, skills, Sandbox-Speicher und Komprimierung. Der Sandbox-Speicher bewahrt extrahierte Erkenntnisse laufübergreifend auf und legt sie schrittweise offen; Arbeitsbereiche unterstützen lokale Dateien, Git-Repository-Einträge und Remote-Einbindungen (S3, R2, GCS, Azure Blob, S3 Files); Snapshots sind anbieterübergreifend portierbar. Backends: UnixLocalSandboxClient, DockerSandboxClient sowie über optionale Extras verfügbare gehostete Clients für Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop und Vercel.²⁴

Für Python-Projekte, die die Claude Code-Laufzeit als Bibliothek einbetten möchten – zwischen „claude als externen Prozess aufrufen“ und „REST API für Managed Agents verwenden“ –, ist claude-agent-sdk-python die dritte Option. Mit der Veröffentlichungsreihe vom 28. bis 29. April (v0.1.69 → v0.1.71) wurde die mitgelieferte CLI auf v2.1.123 aktualisiert, die Mindestversion der mcp-Abhängigkeit auf >=1.19.0 angehoben (ältere Versionen verwarfen CallToolResult-Rückgaben prozessinterner MCP-Tools unbemerkt, sodass das Modell lediglich einen Validierungsfehlerblock erhielt) und SandboxNetworkConfig an das Schema der TypeScript SDK angeglichen (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰ Zum Stand vom 2026-08-01 liegt das Paket auf PyPI bei v0.2.128 (mit der gebündelten Claude CLI v2.1.220 und einer inzwischen auf >=1.23.0 angehobenen mcp-Mindestversion), die TypeScript SDK bei v0.3.220; die 0.2.x-Reihe baut schrittweise auf der hier beschriebenen 0.1.x-Oberfläche auf – die nachfolgenden Optionen include_hook_events, skills und zur Sandbox-Konfiguration sind weiterhin aktuell –, wobei sich neuere Versionen vor allem auf die Bereinigung von Unterprozessen und die Zuverlässigkeit von NDJSON-Streams konzentrieren.⁸⁶

Wenn Ihr harness eine Sprach- oder Echtzeitebene umfasst, wurde RealtimeAgent mit openai-agents-python v0.17.0 (8. Mai 2026) so aktualisiert, dass standardmäßig gpt-realtime-2 verwendet wird.⁴¹ Bestehende Echtzeitsitzungen übernehmen den neuen Standard automatisch; legen Sie das vorherige Modell ausdrücklich fest, wenn Sie das bisherige Verhalten für Auswertungen beibehalten müssen.

Im Juli 2026 erhielt auch die verwaltete Variante auf OpenAI-Seite eine Multi-Agent-Lösung: openai-agents-python v0.18.2 (11. Juli) und openai-agents-js v0.13.2 (10. Juli) ergänzen als Beta-Version gehostete Multi-Agent-Unterstützung – eine von OpenAI verwaltete Orchestrierung mehrerer Agenten als gehosteter Dienst und damit das direkte Gegenstück zur öffentlichen Beta-Version von Anthropics Managed Multiagent Orchestration, die im Abschnitt Multi-Agent-Orchestrierung behandelt wird.⁷³ Beide Anbieter bieten auf der Multi-Agent-Ebene nun dieselbe Abwägung, die die nachfolgende Tabelle für einzelne Agenten beschreibt: Der Anbieter führt die Delegationsschleife aus, dafür verzichten Sie auf die hook-Oberfläche.

Die architektonische Weggabelung ist inzwischen Realität:

Wann eignet sich welche Variante: Selbsthosting bleibt die richtige Wahl für Teams, die bereits über starke Infrastrukturkompetenz verfügen, selbst kontrollierte skills/hooks benötigen oder einen bestimmten Arbeitsablauf umfassend optimieren möchten. Eine verwaltete Lösung eignet sich für Teams ohne eigene Plattformtechniker, wenn eine schnelle Wertschöpfung wichtiger als Anpassbarkeit ist oder Agentenläufe das Zuklappen eines Laptops zuverlässig überstehen müssen, ohne dass Sie diese Persistenzebene selbst entwickeln. Beide Varianten sind kompatibel – Sie können ein selbst gehostetes harness betreiben, das bestimmte lang laufende Aufgaben über dessen 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/-Verzeichnisbaum bildet Ihre persönliche Infrastruktur, die für alle Projekte gilt. Der .claude/-Verzeichnisbaum jedes Repositorys ist projektspezifisch und wird über Git geteilt. Zusammen bilden sie das vollständige harness.

Skills-System

Skills sind vom Modell aufgerufene Erweiterungen. Claude erkennt sie anhand des Kontexts und wendet sie automatisch an, ohne dass Sie sie explizit aufrufen müssen.⁴ Sobald Sie feststellen, dass Sie in mehreren Sitzungen immer wieder denselben Kontext erklären, sollten Sie einen Skill erstellen.

Wann Sie einen Skill erstellen sollten

Skills sind für Wissen gedacht, das Claude jederzeit zur Verfügung steht. Slash commands dienen Aktionen, die Sie explizit auslösen. Wenn Sie zwischen beiden wählen müssen, fragen Sie sich: „Soll Claude dies automatisch anwenden oder möchte ich selbst entscheiden, wann es ausgeführt wird?“

Einen Skill erstellen

Skills können sich an vier Orten befinden, geordnet 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 Beschreibungsfeld ist entscheidend

Beim Sitzungsstart extrahiert Claude Code die Werte name und description jedes Skills und fügt sie in den Kontext von Claude ein. Wenn Sie eine Nachricht senden, entscheidet Claude mithilfe der Schlussfolgerungsfähigkeit des Sprachmodells, ob ein Skill relevant ist. Eine unabhängige Analyse des Quellcodes von Claude Code bestätigt diesen Mechanismus: Skill-Beschreibungen werden in einen available_skills-Abschnitt des System-Prompts eingefügt, und das Modell wählt anhand seines allgemeinen Sprachverständnisses die passenden Skills aus.¹⁰

Schlechte Beschreibung:

description: Helps with code

Wirksame Beschreibung:

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

Die wirksame Beschreibung enthält: was der Skill tut (Code auf bestimmte Arten von Problemen prüfen), wann er verwendet werden soll (bei der Untersuchung von Änderungen, PRs und der Codequalität) sowie Auslösebegriffe (review, audit, check), die Benutzer üblicherweise eingeben.

Beachten Sie, dass die automatische Aktivierung eine Stellschraube und kein unumstößliches Gesetz ist: Seit v2.1.215 ruft Claude die mitgelieferten Skills /verify und /code-review nicht mehr selbst auf – sie werden nur noch explizit gestartet. Damit wurde die beschreibungsgesteuerte Aktivierung bewusst für umfangreiche Review-Skills zurückgenommen, deren unaufgeforderte Ausführung mehr kostete, als sie einbrachte.⁷⁴

Kontextbudget

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

Unterstützende Dateien und Organisation

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

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

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

Skills über Git teilen

Projekt-Skills (.claude/skills/ im Repository-Stammverzeichnis) werden über die Versionsverwaltung 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 die Änderungen abrufen, erhalten sie den Skill automatisch. Keine Installation, keine Konfiguration. Dies ist die wirksamste Methode, Fachwissen innerhalb eines Teams zu vereinheitlichen.

Skills als Prompt-Bibliothek

Über einzelne, zweckgebundene Skills hinaus eignet sich 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 bildet einen anderen Aspekt Ihres Fachwissens ab. Zusammen ergeben sie eine Wissensbasis, aus der Claude abhängig vom Kontext automatisch schöpft. So erhalten Nachwuchsentwickler Anleitung auf Senior-Niveau, ohne danach fragen zu müssen.

Skills lassen sich mit hooks kombinieren

Skills können in ihrem Frontmatter eigene hooks definieren, die nur während der Ausführung des Skills aktiviert sind. Dadurch entsteht domänenspezifisches Verhalten, ohne andere Sitzungen zu belasten:²

---
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 werden über SessionStart-hooks automatisch aktiviert und binden Qualitätsvorgaben ohne expliziten Aufruf in jede Sitzung ein. Der Skill selbst liefert das Wissen. Der hook setzt es durch. Zusammen bilden sie eine Richtlinienebene.

Häufige Fehler bei Skills

Zu weit gefasste Beschreibungen. Ein git-rebase-helper-Skill, der bei jeder Git-bezogenen Anfrage aktiviert wird (Rebases, Merges, Cherry-Picks und sogar git status), belastet den Kontext in 80 % der Sitzungen. Abhilfe schafft entweder eine präzisere Beschreibung oder disable-model-invocation: true, sodass ein expliziter Aufruf über /skill-name erforderlich ist.⁴

Zu viele Skills konkurrieren um das Budget. Mehr Skills bedeuten, dass mehr Beschreibungen um das 1-prozentige Kontextbudget konkurrieren. Wenn Skills nicht aktiviert werden, prüfen Sie mit /context, ob sie ausgeschlossen wurden. Bevorzugen Sie wenige, gut beschriebene Skills gegenüber vielen vagen Skills.

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

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

Selbst gehostete harnesses auf Basis von claude-agent-sdk-python v0.1.77+ sollten die Option skills in ClaudeAgentOptions verwenden, um verfügbare Skills zu deklarieren, und nicht mehr den veralteten Wert "Skill" in allowed_tools.³⁷ Die Kurzform "Skill" ist veraltet; die dedizierte Option liefert Claude Code strukturiertere Informationen darüber, welche Skills verfügbar sind. Das in v0.1.77 enthaltene CLI liegt in Version v2.1.133 vor.

Zusammenführung von Plugins und Skills 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 nun auf Plugins: Ein in .claude/skills/ abgelegtes Plugin wird jetzt ohne Marketplace-Registrierung automatisch geladen, und claude plugin init <name> legt dort ein neues Gerüst an, in dem das Manifest und SKILL.md bereits eingebunden sind.⁵⁸ Damit schließt sich die Lücke zwischen den beiden Formen von Projektwerkzeugen, die zuvor an unterschiedlichen Orten angesiedelt waren – einem einfachen, direkt in das Repository übernommenen Skill und einem Plugin, das einen Skill sowie hooks und einen MCP-Server bündelt, für die Installation zuvor jedoch einen Marketplace benötigte. Die praktische Auswirkung auf das harness-Design: Projektbezogene Werkzeuge benötigen für die Bereitstellung keinen Umweg über eine Registry mehr – schreiben Sie sie, committen Sie sie, und Ihre Teammitglieder erhalten mit git pull dieselbe Oberfläche. Plugins bleiben die richtige Lösung für gebündelte, installierbare Pakete (hooks + skills + MCP-Server + agents in einer ZIP-Datei); neu ist, dass ein Projekt keinen Marketplace mehr einrichten muss, nur um ein Plugin aus dem eigenen Verzeichnisbaum zu laden.

Ausblenden der mitgelieferten Oberfläche als Governance-Maßnahme (8. Juni 2026)

Skills stellen Fähigkeiten bereit, und jede Fähigkeit vergrößert die Angriffsfläche. Claude Code v2.1.169 ergänzt die Einstellung disableBundledSkills sowie die entsprechende Umgebungsvariable CLAUDE_CODE_DISABLE_BUNDLED_SKILLS, durch die mitgelieferte Skills, workflows und integrierte Slash commands vollständig vor dem Modell verborgen werden.⁶⁰ Für ein gehärtetes oder reguliertes harness bedeutet dies eine bewusste Verkleinerung der Angriffsfläche: Ein Betreiber, der eine bestimmte Gruppe von Projekt- und persönlichen Skills geprüft und freigegeben hat, kann alles unterdrücken, was Anthropic standardmäßig mitliefert. Das Modell berücksichtigt dann ausschließlich die vom Betreiber geprüfte Oberfläche. Behandeln Sie diese Option wie eine Tool-Allowlist – standardmäßig steht ein breites Fähigkeitsspektrum bereit; diese Vorgabe zu deaktivieren ist eine Governance-Entscheidung und kein bloßer Komfortschalter.

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

Mit Claude Code v2.1.178 wurden Projektwerkzeuge ortsabhängig. Skills in verschachtelten .claude/skills-Verzeichnissen werden nun geladen, wenn Sie an Dateien unterhalb des jeweiligen Verzeichnisses arbeiten, statt ausschließlich aus dem Repository-Stammverzeichnis. Bei einem Namenskonflikt erscheint der verschachtelte Skill als <dir>:<name>, sodass beide erreichbar bleiben.⁶³ Mit derselben Version wurde auch die übrige Projektoberfläche nach dem Prinzip der größten Nähe zum Arbeitsverzeichnis aufgelöst: Wenn der Name eines agents, workflows oder output-style in mehreren verschachtelten .claude/-Verzeichnissen vorkommt, gewinnt die Variante, die dem Arbeitsverzeichnis am nächsten liegt. Beim Speichern eines workflows im Projekt-Geltungsbereich wird außerdem das nächstgelegene vorhandene .claude/workflows/ verwendet, statt immer das Stammverzeichnis als Ziel zu wählen.⁶³ Für ein Monorepository oder ein Repository aus mehreren Unter-Repositorys macht dies den Unterschied zwischen einer einzigen flachen, globalen Oberfläche und paketbezogenen Werkzeugen aus, die kontextabhängig aktiviert werden – ein Verzeichnis services/api/.claude/skills/ kann API-spezifische Skills enthalten, die nur bei der Arbeit in diesem Verzeichnisbaum erscheinen, ohne mit einem gleichnamigen Skill unter services/web/ zu kollidieren.

Hook-Architektur

Hooks sind Shell-Befehle, die durch Lebenszyklusereignisse von Claude Code ausgelöst werden.³ Sie werden außerhalb des LLM als einfache Skripte ausgeführt und nicht als Prompts vom Modell interpretiert. Das Modell möchte rm -rf / ausführen? Ein zehnzeiliges Bash-Skript gleicht den Befehl mit einer Sperrliste ab und lehnt ihn ab, bevor die Shell ihn überhaupt verarbeitet. Der Hook wird ausgelöst, ob das Modell dies möchte oder nicht.

Verfügbare Ereignisse

Zum Zeitpunkt dieser Aktualisierung des Leitfadens stellt Claude Code 30 dokumentierte Lebenszyklusereignisse in acht Kategorien bereit. Die Ereignisliste wächst mit neuen Versionen. Betrachten Sie daher die Referenzdokumentation als maßgebliche Quelle und prüfen Sie vor der Einrichtung von Produktions-Hooks die Kurzübersicht mit der aktuellen vollständigen Tabelle:¹³

DirectoryAdded (v2.1.219) schließt die Lücke bei Arbeitsbereichsänderungen während einer Sitzung. Seit der Einführung von MessageDisplay in v2.1.152 war die Ereignisliste unverändert; DirectoryAdded ist das erste neue Lebenszyklusereignis seitdem. Es wird ausgelöst, nachdem /add-dir – oder die Steuerungsanfrage register_repo_root des SDK – während einer laufenden Sitzung ein neues Arbeitsverzeichnis registriert hat.⁸⁴ Damit wird eine echte Lücke geschlossen: Bisher konnte ein harness bei SessionStart einen Arbeitsbereich umfassend validieren, während anschließend ein zweites Repository ohne jegliche Hook-Auslösung hinzugefügt werden konnte. Alles, was Sie beim Start über den Arbeitsbereich sicherstellen – Vertrauensprüfungen, Geheimnisscans, aus der Verzeichnisstruktur abgeleitete Regeln für den Pfadumfang oder das Laden Repository-spezifischer Richtlinien –, muss hier erneut ausgeführt werden, da die Verzeichnismenge einer Sitzung nicht mehr ab dem Start unveränderlich ist. Das Ereignis dient der Information und blockiert nicht. Verwenden Sie es daher als Auslöser, um den Zustand neu abzuleiten und die Herkunft zu protokollieren, nicht als gate. Wenn ein Verzeichnis niemals hinzugefügt werden darf, verweigern Sie dies in den Einstellungen, anstatt es über einen Hook verhindern zu wollen. Die Unterstützung aufseiten von SDK erschien mit derselben Version (TypeScript v0.3.219 ergänzt die Lebenszyklusereignisse des Steuerungsprotokolls um DirectoryAdded), sodass von SDK gehostete harnesses das Ereignis gleichwertig zu CLI-basierten harnesses verarbeiten.⁸⁵

Semantik der Exit-Codes

Exit-Codes bestimmen, ob Hooks Aktionen blockieren:³

Hook-Konfiguration

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

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

Das Feld matcher filtert einen ereignisspezifischen Wert. Bei Tool-Ereignissen gleicht es tool_name-Werte wie Bash, Edit, Write, Read, Glob, Grep, Namen von MCP-Tools wie mcp__server__tool oder * für alle Tools ab. Einfache Namen und durch | getrennte Listen werden exakt abgeglichen; Werte mit anderen Zeichen gelten als reguläre Ausdrücke von JavaScript. Einige Ereignisse unterstützen keine Matcher und werden bei entsprechender Konfiguration immer ausgelöst.¹³ Seit Claude Code v2.1.195 werden Matcher mit Bezeichnern, die Bindestriche enthalten (code-reviewer, mcp__brave-search), exakt abgeglichen, anstatt versehentlich Teilzeichenfolgen zu finden. Ein Hook für einen bestimmten Agenten oder Server wird somit nicht mehr für jeden Namen ausgelöst, der lediglich diese Zeichenfolge enthält. Um alle Tools eines MCP-Servers mit Bindestrich abzudecken, verwenden Sie das explizite Muster mcp__brave-search__.*.⁶⁶ Mit v2.1.214 wurde dieselbe Präzision auf Pfadmuster übertragen: Eine if:-Bedingung eines Hooks, die das einsegmentige Muster dir/** verwendet, entspricht nun ausschließlich <cwd>/dir und nicht mehr jedem Verzeichnis namens dir an beliebiger Stelle der Verzeichnisstruktur. Verwenden Sie **/dir/**, wenn Sie tatsächlich jede Tiefe meinen.⁷⁴ Wie bei der Änderung in v2.1.195 ersetzt diese Korrektur unbeabsichtigte Reichweite durch ausdrücklich erklärte Absicht. Prüfen Sie daher alle Hook-Bedingungen, die stillschweigend vom früheren Verhalten für beliebige Verzeichnistiefen abhingen.

Ein-/Ausgabeprotokoll für Hooks

Hooks empfangen JSON mit dem vollständigen Kontext über stdin:

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

Für eine erweiterte Steuerung können PreToolUse-Hooks JSON ausgeben, um Tool-Eingaben zu ändern, Kontext einzuschleusen 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 gewährleisten nachträglich Konsistenz. PostToolUse-Hooks für Write/Edit führen nach jeder Dateiänderung Ihr Formatierungsprogramm aus. Die Ausgabe des Modells spielt keine Rolle, da das Formatierungsprogramm 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 diese 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 die 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 und ohne Token-Kosten. 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 { "ok": true } zurück, um die Ausführung zuzulassen, oder { "ok": false, "reason": "..." }, um sie zu blockieren. Verwenden Sie sie für differenzierte Auswertungen, die sich nicht mit regulären Ausdrücken abbilden lassen.

Agent-hooks (type: "agent") starten einen subagent mit Tool-Zugriff (Read, Grep, Glob) für mehrstufige Überprüfungen. Sie sind experimentell; bevorzugen Sie command hooks für Produktionsprüfungen und setzen Sie agent hooks nur für Prüfungen ein, bei denen tatsächlich Dateien oder Testausgaben untersucht werden müssen:

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

Seit Claude Code v2.1.140 enthält die Eingabe für agent hooks subagent_type. Dadurch kann ein gemeinsam genutzter hook einen security-reviewer-Lauf von einem explorer oder generischen worker unterscheiden, ohne dies aus dem Prompt-Text ableiten zu müssen.⁴⁹

HTTP-hooks (type: "http") senden die JSON-Eingabe des Ereignisses als POST-Anfrage an eine URL und empfangen JSON als Antwort. Verwenden Sie sie für webhooks, externe Benachrichtigungsdienste oder API-basierte Validierung (ab 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 ausgeführt werden, ohne die Ausführung zu blockieren. Fügen Sie für nicht kritische Vorgänge wie Benachrichtigungen und Protokollierung async: true hinzu:¹³

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

Verwenden Sie async für Benachrichtigungen, Telemetrie und Sicherungen. Verwenden Sie async niemals für Formatierung, Validierung oder Vorgänge, die vor der nächsten Aktion abgeschlossen sein müssen.

Dispatcher statt unabhängiger hooks

Wenn sieben hooks beim selben Ereignis ausgelöst werden und jeweils unabhängig stdin lesen, entstehen Race Conditions. Schreiben zwei hooks gleichzeitig in dieselbe JSON-Statusdatei, wird JSON abgeschnitten. Jeder nachgelagerte hook, der diese Datei parst, schlägt daraufhin fehl.²

Die Lösung: ein dispatcher pro Ereignis, der hooks nacheinander mit 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 Methoden zum Debuggen von hooks, die ohne sichtbare Fehlermeldung scheitern:¹⁴

1. Testen Sie Skripte unabhängig voneinander. Leiten Sie eine JSON-Beispieleingabe weiter: echo '{"tool_input":{"command":"git commit -m test"}}' | bash your-hook.sh
2. Verwenden Sie stderr für Debug-Ausgaben. stderr bei Exit-Code 2 wird als Fehlermeldung an Claude zurückgegeben. Nicht blockierendes stderr (Exit-Code 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 Tool-Eingaben.
4. Überprüfen Sie Exit-Codes. Ein PreToolUse-hook, der exit 1 verwendet, setzt keinerlei Regeln durch, obwohl er zu funktionieren scheint.
5. Halten Sie hooks schnell. Hooks werden synchron ausgeführt. Alle hooks sollten weniger als 2 Sekunden benötigen, idealerweise weniger als 500 ms.

SDK-seitiges Streaming von hook-Ereignissen

Selbst gehostete harnesses auf Basis von claude-agent-sdk-python (ab v0.1.74, 6. Mai 2026) können hook-Ereignisse direkt aus dem Nachrichtenstream abonnieren, statt Shell-Skript-Callbacks zu verwenden.³⁶ Setzen Sie include_hook_events=True in ClaudeAgentOptions; anschließend liefert derselbe Iterator, der Assistentennachrichten und Tool-Ergebnisse ausgibt, auch HookEventMessage-Objekte (PreToolUse, PostToolUse, Stop und weitere). Dies entspricht der Option includeHookEvents im TypeScript SDK; die gebündelte CLI-Version wurde im selben Release auf v2.1.129 aktualisiert.

Das Event-Stream-Muster eignet sich, wenn Ihr harness bereits in Python ausgeführt wird und Sie hook-Signale im selben Kontrollfluss wie die Modellausgabe verarbeiten möchten. Der Shell-Skript-hook-Vertrag (Exit-Codes, stdin-JSON, dispatcher) bleibt die richtige Lösung für harnesses, die mehrere Tools kombinieren, hooks gemeinsam für Claude Code und Codex verwenden oder zum Blockieren eine Exit-Code-Semantik benötigen.

Mit der Serie vom Juli 2026 (v0.3.205–v0.3.208) machte der TypeScript SDK auch das gestreamte Protokoll selbst verbindlicher.⁷⁰ Unterbrechungen geben nun typisierte Bestätigungen zurück: Eine Unterbrechung bestätigt anhand von still_queued-UUIDs, welche Nachrichten noch in der Warteschlange stehen. Zudem geben Sitzungen in system/init die Fähigkeit interrupt_receipt_v1 bekannt, sodass ein Koordinator unterscheiden kann, ob eine Unterbrechung angekommen ist oder eine bereits laufende Nachricht knapp verfehlt hat. command_lifecycle-Frames melden für jede Nachricht queued/started/completed/cancelled/discarded – die erste offizielle Antwort auf die Frage „Was ist mit meiner gesendeten Nachricht passiert?“, ohne dies aus dem Transkript ableiten zu müssen. Hinzu kamen kleinere Schnittstellen: ein AgentToolCompletedOutput-Typ für Abschlussdaten von subagents sowie die Möglichkeit, dass canUseTool-Callbacks nun {behavior: 'allow'} ohne ein updatedInput-Feld zurückgeben.

Eine Zeile dieser Serie bildet eine Sicherheitsuntergrenze und ist keine Funktion: v0.3.208 behob einen Fehler, bei dem ein Abbruch durch den Aufrufer während eines ausstehenden hooks als hook-Erfolg gewertet wurde – dadurch konnte ein von einem PreToolUse-hook kontrolliertes Tool ausgeführt werden, nachdem der Aufrufer bereits abgebrochen hatte.⁷⁰ Wenn Ihr harness SDK-seitige hooks als Berechtigungsschranke verwendet und sich zum Abbrechen laufender Vorgänge auf abort verlässt, sollten Sie v0.3.208 als Mindestversion festlegen; in früheren Versionen bedeutete „abgebrochen“ nicht zuverlässig „blockiert“. Python v0.2.127 (24. Juli 2026) ist innerhalb eines Monats die zweite Umgehung dieser Art: query() schloss stdin beim ersten result-Frame, während subagents im Hintergrund noch liefen. Dadurch schlugen deren SDK-MCP-Tool-Aufrufe mit "Stream closed" fehl und umgingen PreToolUse-hooks vollständig.⁸⁵ Benennen Sie dieses Muster und achten Sie darauf: Die SDK-seitige Durchsetzung durch hooks fällt an den Rändern des Lebenszyklus offen aus – bei abort, teardown und stream close –, wenn die Übertragung endet, bevor das hook-Urteil eingeholt wurde. Zudem geschieht dies lautlos, weil ein umgangener hook genauso aussieht wie ein hook, der seine Zustimmung erteilt hat. Fixieren Sie für beide SDK-Versionen diese Mindeststände und behalten Sie die Shell-hook-Ebene als nachweisbare Durchsetzungsinstanz bei.

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

Zwei Ergänzungen in Claude Code v2.1.132 und v2.1.133 liefern hooks und Unterprozessen bessere Informationen über ihren Ausführungskontext:³⁸³⁹

• effort.level in der hook-Eingabe. Hooks erhalten nun ein JSON-Feld namens effort.level in derselben Eingabe, die auch tool_input und session_id enthält. Derselbe Wert wird als Umgebungsvariable $CLAUDE_EFFORT exportiert, sodass Bash-Befehle ihn lesen können, ohne JSON zu parsen. Nutzen Sie dies, um den Aufwand eines hooks an die Aufwandsstufe anzupassen: Überspringen Sie kostspielige Validierungen bei low und führen Sie bei xhigh oder max das vollständige Sicherheits-gate aus.
• Umgebungsvariable CLAUDE_CODE_SESSION_ID in Bash-Unterprozessen. Unterprozesse des Bash-Tools sehen nun denselben session_id-Wert wie die hooks, bereitgestellt als CLAUDE_CODE_SESSION_ID. Damit wird die Herkunftslücke für Tools geschlossen, die einen sitzungsbezogenen Status protokollieren und zuvor Unterprozessereignisse nicht mit hook-Ereignissen verknüpfen konnten.

Beide Signale stehen ohne Codeänderungen zur Verfügung; vorhandene 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 ergänzte den Automatikmodus um eine neue hard-deny-Stufe und behob mehrere Plugin- und MCP-Probleme, die sich auf langlebige harnesses auswirkten:⁴⁰ - settings.autoMode.hard_deny. Regeln für den Auto-mode-Classifier, die bedingungslos blockieren – unabhängig von der Benutzerabsicht oder Ausnahmen durch allow-Regeln. Diese Ebene steht über den vorhandenen allow/deny-Matchern und dient als nicht verhandelbarer Governance-Mechanismus. Verwenden Sie sie für Regeln, die niemals außer Kraft gesetzt werden dürfen (Force-Push auf main, Dateien mit Geheimnissen, Zugriff auf Produktionsdatenbanken), selbst wenn ein Operator die übergeordnete Kategorie in seinen persönlichen Einstellungen freigegeben 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. Mit dieser Einstellung wird jeder Bash-/PowerShell-Befehl durch den Classifier geleitet – die Haltung mit maximaler Abdeckung für einen kontrollierten harness. Dieselbe Version zeigt zudem die Gründe für Ablehnungen im Transkript, in der Benachrichtigung und unter /permissions an, wodurch aus stillen Blockierungen überprüfbare Entscheidungen werden. Codex verschärfte die entsprechende Schutzfunktion in v0.142.2: PowerShell-Befehle mit ausführbaren AST-Bereichen, die der Sicherheits-Classifier nicht untersuchen kann, erfordern nun eine Genehmigung, anstatt stillschweigend ausgeführt zu werden.⁶⁶ - Hook-ask setzt die Untergrenze für den Classifier (v2.1.211). Die Rangfolge zwischen hooks und Auto mode ist nun geklärt: Gibt ein PreToolUse hook die Berechtigungsentscheidung ask zurück, kann das Endergebnis nicht unter eine Rückfrage fallen – Auto mode kann es bei Bash-Befehlen außerhalb der Sandbox nicht wieder zu allow hochstufen.⁶⁹ Für einen kontrollierten harness ist dies die bislang fehlende Garantiestufe: Das ask eines hooks ist ein deterministischer Human-in-the-Loop-Haltepunkt, der selbst bei vollständig automatischen Berechtigungskonfigurationen bestehen bleibt. Verwenden Sie ask (nicht nur Blockierungen mit Exit-Code 2) für Vorgänge, bei denen Sie eine menschliche Entscheidung statt einer Ablehnung wünschen. - Das Classifier-Modell wird pro Sitzung festgeschrieben (v2.1.210). Der Auto-mode-Classifier verwendet standardmäßig Sonnet 5 und wird für die Sitzung festgeschrieben. Modellwechsel während einer Sitzung ändern daher nicht mehr, welches Modell die Berechtigungsklassifizierungen vornimmt.⁶⁹ Eine konsistente Klassifizierung ist eine Governance-Eigenschaft; damit entfällt eine unauffällige Ursache für Abweichungen. - MCP-Server verschwinden nach /clear nicht mehr. In .mcp.json, plugins und claude.ai-Connectors konfigurierte Server waren nach einem /clear in der VS Code-Erweiterung, im JetBrains-plugin und in Agent SDK unbemerkt aus der aktiven Gruppe verschwunden. Die Korrektur ist in v2.1.136 enthalten. Falls „MCP server X went missing mid-session“ auftrat, war dies die Ursache. - Verlust des MCP-OAuth-Aktualisierungstokens bei gleichzeitiger Aktualisierung. Benutzer mit mehreren entfernten MCP-Servern sollten sich nicht mehr täglich neu authentifizieren müssen. Gleichzeitige Aktualisierungsschreibvorgänge hatten sich gegenseitig überschrieben. - Plan mode blockiert Dateischreibvorgänge jetzt korrekt. Eine passende Edit(...)-allow-Regel hatte den Schreibschutz von Plan mode umgangen. Plan mode wird nun unabhängig von allow-Regeln durchgesetzt. - Die plugin-hooks Stop und UserPromptSubmit schlagen nicht mehr während einer Sitzung fehl. Bei der Cache-Bereinigung wurden plugin-Versionsdateien gelöscht, die von der laufenden Sitzung noch verwendet wurden. Dadurch fielen speziell diese beiden hook events aus. Die Korrektur hält verwendete Versionen fest. - skills-Eintrag in plugin.json. Durch das Festlegen von skills wurde der standardmäßige skills/-Ordner des plugins ausgeblendet. Nun wird der Eintrag korrekt ergänzt; verweist er auf einen Dateipfad, erscheint eine ausdrückliche Fehlermeldung, anstatt dass der Vorgang unbemerkt fehlschlägt. - Veraltete Umgebungsvariablen aus SessionStart hooks über CLAUDE_ENV_FILE. Variablen, die SessionStart hooks über CLAUDE_ENV_FILE exportierten, waren nach /resume oder /clear veraltet. Dies wurde in v2.1.136 behoben. Bei diesen Ereignissen lesen Sitzungen die Umgebungsdatei nun erneut ein.

Für Governance-harnesses sind autoMode.hard_deny als neuer Mechanismus und die Korrektur für das Verschwinden von MCP besonders relevant – letzteres war ein stiller Fehler, der lange Sitzungen beeinträchtigte. Alles andere sind Verbesserungen 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 relevant sind: eine Exec-Form mit args: string[] für Command hooks und continueOnBlock für PostToolUse hooks.⁴²⁴⁴ Bevorzugen Sie args, wenn ein hook dynamische Werte oder Pfadplatzhalter benötigt. Der Befehl wird direkt ohne Shell gestartet, wodurch eine ganze Klasse von Fehlern bei Anführungszeichen und Injection 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. Betrachten Sie dies als Funktion für eine bessere Operator-Erfahrung, nicht als Umgehung der Sicherheit. Ein blockierendes Gate muss das unsichere Ergebnis weiterhin verhindern.

Dieselbe Version übergibt CLAUDE_PROJECT_DIR an MCP-stdio-Server und erlaubt plugin-Konfigurationen, ${CLAUDE_PROJECT_DIR} in Befehlen zu referenzieren.⁴² MCP tools sollten projektbezogene Pfade anhand dieses Werts auflösen, nicht anhand des zufälligen Prozessarbeitsverzeichnisses, aus dem der Server gestartet wurde. Die Versionen von Anfang Juli 2026 (v2.1.203–v2.1.206) übertrugen dasselbe Prinzip auf die Protokollebene: MCP roots/list enthält nun die zusätzlichen Arbeitsverzeichnisse der Sitzung und sendet bei Änderungen roots/list_changed-Benachrichtigungen. Ein Server, der die MCP roots berücksichtigt, bildet damit die tatsächliche Struktur eines Arbeitsbereichs mit mehreren Verzeichnissen ab, statt von einem einzigen Projektverzeichnis auszugehen.⁶⁸

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

Claude Code v2.1.141 ergänzt hook-Ausgaben um das Feld terminalSequence, das Desktop-Benachrichtigungen, Fenstertitel und Signaltöne ohne steuerndes Terminal ermöglicht.⁵⁰ Betrachten Sie dies als Signalisierung für Operatoren, nicht als Durchsetzungsmechanismus. Sicherheits- und Qualitäts-Gates sollten Fehler weiterhin über den üblichen Blockierungsvertrag mitteilen: strukturierte hook-Ausgaben zusammen mit dem Exit-Verhalten, das die unsichere Aktion verhindert. Dieselbe Version ergänzt claude agents --cwd <path> zur Beschränkung von Agent View auf ein Verzeichnis, CLAUDE_CODE_PLUGIN_PREFER_HTTPS für plugin-Installationen in Umgebungen ohne GitHub-SSH-Schlüssel und ANTHROPIC_WORKSPACE_ID für Regeln zur Workload-Identity-Föderation, die mehr als einen Arbeitsbereich abdecken.⁵⁰ Für Team-harnesses sind dies Architekturdetails: enger begrenzte Betriebsansichten, weniger Annahmen bei der plugin-Installation und eine explizite Geltungsbereichszuweisung für Enterprise-Tokens.

Claude Code v2.1.142 ist für die Orchestrierung von Hintergrundsitzungen wichtiger als für die Semantik von hooks.⁵¹ claude agents kann Hintergrundsitzungen nun mit expliziten Flags für Verzeichnis, Einstellungen, MCP, plugin, Berechtigungen, Modell und Rechenaufwand starten, statt vom Zustand eines Wrappers abhängig zu sein. In dieser Version verwendete Fast mode standardmäßig Opus 4.7; mit CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE=1 lässt sich ein harness fest auf Opus 4.6 einstellen, wenn dessen Verhalten nachweislich erforderlich ist. Seit v2.1.219 gehört Opus 4.7 gar nicht mehr zum Fast mode, und /fast gilt für Opus 5 und Opus 4.8.⁸⁴ Die Erkennung von SKILL.md auf der Stammebene eines plugins und die Sichtbarkeit der vom plugin bereitgestellten LSPs verringern Unklarheiten bei der Paketierung. Korrekturen an MCP_TOOL_TIMEOUT, bereits vorhandenen Worktrees von Hintergrundsitzungen, Ruhe-/Aufwachvorgängen und Bereinigungen nach Upgrades beim Daemon sowie an der plugin-Cache-Bereinigung schließen Zuverlässigkeitslücken, die andernfalls wie Orchestrierungsfehler wirken.

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

Vier Änderungen von Anfang Juni sind für das Design von harnesses und Multi-Agent-Systemen relevant.⁵⁹

Stop/SubagentStop hooks erhielten einen Steuerungskanal. Seit Claude Code v2.1.163 kann ein Stop- oder SubagentStop hook über hookSpecificOutput.additionalContext Feedback an Claude übermitteln und den Turn fortsetzen, ohne dass die Antwort als hook-Fehler gekennzeichnet wird. Zuvor war die Blockierung mit Exit-Code 2 das einzige echte Steuerungsmittel eines Stop hooks; sie wird als Fehler dargestellt und auf die Höchstzahl aufeinanderfolgender Blockierungen angerechnet. Für einen harness mit Qualitäts-Gates ist dies das sauberere Grundelement: Erkennt ein Stop hook „Sie haben den Vorgang als abgeschlossen bezeichnet, aber die Tests schlagen fehl“, kann er nun „Folgendes schlägt noch fehl, fahren Sie fort“ einspeisen, statt hart zu blockieren. Verwenden Sie die Blockierung für tatsächliche Abbruchbedingungen und additionalContext für „noch nicht abgeschlossen – hier ist der Grund“.

Sitzungsübergreifende Nachrichten übertragen keine geliehene Autorität mehr. v2.1.166 härtete den Fall mehrerer Sitzungen ab: Nachrichten, die über SendMessage aus einer anderen Claude-Sitzung weitergeleitet werden, übertragen nicht mehr die Autorität des ursprünglichen Benutzers. Daher lehnt die empfangende Sitzung weitergeleitete Berechtigungsanfragen ab, und Auto mode blockiert sie. Wenn sich Agenten in Ihrer Orchestrierung gegenseitig Nachrichten senden, behandeln Sie eingehende Nachrichten als nicht vertrauenswürdige Daten und nicht als authentifizierte Anweisungen. Dasselbe Prinzip wendet der Sicherheitsabschnitt auf tool-Ausgaben an; hier wird es auf die Kommunikation zwischen Agenten erweitert. Seit v2.1.199 erkennt und meldet Claude Code außerdem, wenn eine SendMessage fehlgeleitet wird, weil zwei Agenten denselben Namen haben. Dies ergänzt die Autoritätsgrenze um einen Zuverlässigkeitsschutz, denn eine Nachricht an den falschen gleichnamigen Agenten ist eine eigene Klasse von Orchestrierungsfehlern. Modellresilienz wurde zu einer zentralen Einstellung. Mit der Einstellung fallbackModel lassen sich nun bis zu drei Ersatzmodelle verketten, die der Reihe nach ausprobiert werden, wenn das primäre Modell überlastet oder nicht verfügbar ist. Bei unerwarteten, nicht erneut ausführbaren API-Fehlern wird ein Turn außerdem automatisch einmal mit dem Fallback-Modell wiederholt. In einem langfristig autonomen harness wird so aus einem vorübergehenden Ausfall des primären Modells eine kontrollierte Leistungsminderung statt eines abgebrochenen Laufs. claude agents --json erhielt zudem ein waitingFor-Feld (v2.1.162), das anzeigt, worauf eine blockierte Hintergrundsitzung wartet, etwa auf eine Berechtigungsabfrage — ein Gewinn an Beobachtbarkeit für jeden Koordinator, der regelmäßig den Status einer Agentenflotte abfragt.

Abgesicherter Modus für Clean-Room-Governance und Fehlerbehebung. Claude Code v2.1.169 führt das Flag --safe-mode (und die entsprechende Umgebungsvariable CLAUDE_CODE_SAFE_MODE) ein, das eine Sitzung startet, in der sämtliche Anpassungen gleichzeitig deaktiviert sind: CLAUDE.md, Plugins, skills, hooks und MCP-Server.⁶⁰ Dies ist die Umkehrung des harness — ein bewusst geschaffener Clean Room. Damit können Sie die Frage beantworten, die sich jeder Betreiber früher oder später stellt: „Stammt dieses Verhalten vom Modell oder von etwas, das ich konfiguriert habe?“ Wenn ein hook fälschlicherweise ausgelöst wird, ein skill aktiviert wird, obwohl dies nicht geschehen sollte, oder ein MCP-Server den Kontext beeinträchtigt, liefert Ihnen --safe-mode eine bekanntermaßen leere Ausgangsbasis für einen Vergleich. Zugleich ist der Modus ein Governance-Baustein: Sie können das unveränderte Modell ohne die dauerhaften Befugnisse ausführen, die Ihr harness normalerweise gewährt. Das ist relevant, wenn Sie ein Ergebnis reproduzieren müssen, ohne dass eine vom Betreiber definierte Infrastruktur darauf Einfluss nimmt.

Hinweis zu den Modellstufen. Seit Claude Code v2.1.197 (30. Juni 2026) ist Claude Sonnet 5 das standardmäßig ausgelieferte Modell für neue Sitzungen — mit nativem 1M-Kontext und einem Aktionspreis von 2/10 US-Dollar pro MTok bis zum 31. August — und ersetzt Opus 4.8 als sofort einsatzbereite Standardwahl. Dieser Leitfaden betrachtet Opus 5 (claude-opus-5) als empfohlenen Standard für agentische Aufgaben: Sofern Sie sich nicht bewusst anders entscheiden, sollten autonome harnesses mit diesem Modell ausgeführt werden, denn gerade in langfristigen Agentenschleifen mit hohem Risiko rechtfertigt die größere Schlussfolgerungstiefe von Opus die Kosten. Opus 5 erschien am 24. Juli 2026 als neues standardmäßiges Opus in Claude Code v2.1.219 — mit 1M-Kontext, einem Preis von 5/25 US-Dollar pro MTok (derselbe Preis wie beim ersetzten Opus 4.8) und einem schnellen Modus für 10/50 US-Dollar bei ungefähr 2,5-facher Standardgeschwindigkeit. Anthropic zufolge erzielt es im Frontier-Bench v0.1 mehr als das Doppelte der Leistung von Opus 4.8 und liegt im CursorBench 3.2 bei halben Kosten höchstens 0,5 % hinter Fable 5.⁸⁴⁸⁷ Derselbe Preis, mehr Leistungsfähigkeit und ein Modell, das Anthropic als „deutlich besser darin, seine Arbeit zu überprüfen und sie sorgfältig zu überarbeiten“ charakterisiert, ergeben ein seltenes Upgrade, für das bei harness-Aufgaben kein Kostenargument nötig ist; für die Migration von 4.8 muss lediglich die ID geändert werden. Wechseln Sie bei kostensensiblen Aufgaben oder hohem Durchsatz zu Sonnet 5, wenn dessen Verhältnis von Geschwindigkeit zu Intelligenz den Ausschlag gibt. Oberhalb von Opus steht Claude Fable 5 (claude-fable-5), das am 9. Juni 2026 eingeführt wurde — eine neue Stufe, die als leistungsfähigstes Modell von Anthropic beschrieben wird: ein für den allgemeinen Einsatz abgesichertes System der „Mythos-Klasse“, das in Claude Code v2.1.170 über /model claude-fable-5 ausgewählt werden kann.⁶⁰ Greifen Sie gezielt auf die höhere Stufe zurück, wenn bei einer Entscheidung die reine Schlussfolgerungstiefe die Kosten rechtfertigt, statt sie pauschal für eine ganze Flotte festzulegen. Aus der Umstellung auf Opus 5 ergeben sich zwei administrative Konsequenzen: Opus 4.7 ist nicht mehr im schnellen Modus verfügbar (/fast gilt nun für Opus 5 und Opus 4.8), und der Fable-5-Fallback des Klassifikators für den automatischen Modus — seit v2.1.176 „das beste verfügbare Opus-Modell“ — verweist nun auf Opus 5.⁸⁴

Codex veröffentlichte Multi-Agent v2. Codex CLI v0.137.0 belässt die Wahl der Laufzeit bei jedem Thread, bietet übersichtlichere Standardeinstellungen für Follow-ups und Metadaten erzeugter Agenten (hide_spawn_agent_metadata ist nun standardmäßig auf true gesetzt) und leitet unverarbeitete Ereignisse des übergeordneten Threads an untergeordnete Listener weiter. Das subagent-Modell bleibt explizit: integrierte Agententypen default/worker/explorer, über TOML definierte benutzerdefinierte Agenten sowie Nebenläufigkeitskontrollen (agents.max_threads standardmäßig 6, agents.max_depth standardmäßig 1). Dieselbe Version ergänzt eine v1-skills-Erweiterung mit einer turnweisen Auflösung des skill-Katalogs sowie neuen Contributor-Ereignissen für den Thread-Start und Turn-Fehler. Dadurch verringert sich der Abstand zur hook-/skill-Oberfläche von Claude Code, während die Kernel-Sandbox-Haltung die standardmäßige Grenze bleibt. Codex v0.138.0–v0.139.0 härtete Multi-Agent v2 anschließend für den Produktiveinsatz: Nachrichteninhalte zwischen Agenten werden nun verschlüsselt, ein v2-Agentenkonfigurationskatalog verwaltet zusammen mit einem LRU für die Agentenresidenz, welche Agenten resident bleiben, und die Nebenläufigkeit wird anhand der aktiven Ausführung statt der Anzahl erzeugter Threads gezählt, sodass inaktive Agenten keinen Slot mehr belegen.⁶¹ Auch der Lebenszyklus-API wurde ausgereifter — close_agent wurde in v0.139.0 in interrupt_agent umbenannt, um deutlich zu machen, dass damit ein laufender Agent unterbrochen und nicht lediglich ein Handle geschlossen wird. Zudem bleiben MCP-Startwarnungen eines subagent nun auf den zugehörigen Thread beschränkt, statt zusätzlich im Transkript des übergeordneten Threads aufzutauchen.⁶¹ Für alle, die eine Codex-seitige Orchestrierung entwickeln, markieren diese Funktionen den Unterschied zwischen einer Demonstration und einer Flotte: verschlüsselter Nachrichtentransport, begrenzte Residenz, nach Ausführungen gezählte Nebenläufigkeit und Warnungen, die nicht über Thread-Grenzen hinweg durchsickern. Codex v0.140.0 öffnete anschließend eine Schnittstelle zwischen verschiedenen Tools: Mit /import lassen sich Einrichtung, Projektkonfiguration und aktuelle Chats selektiv aus Claude Code in Codex übernehmen. Sitzungen können außerdem dauerhaft gelöscht werden (codex delete / /delete, jeweils mit Sicherheitsabfragen zur Bestätigung).⁶⁴ /import ist die erste offizielle Anerkennung, dass Betreiber zwischen harnesses wechseln — die für ein System erstellte Konfiguration ist nicht länger darin gefangen.

Speicher und Kontext

Jede KI-Konversation findet innerhalb eines begrenzten Kontextfensters statt. Mit zunehmender Länge der Konversation komprimiert das System frühere Gesprächsrunden, um Platz für neue Inhalte zu schaffen. Diese Komprimierung ist verlustbehaftet. Architekturentscheidungen, die in Gesprächsrunde 3 dokumentiert wurden, sind in Gesprächsrunde 15 möglicherweise nicht mehr vorhanden.⁹

Die drei Mechanismen des Multi-Turn-Zusammenbruchs

Die Studie von MSR/Salesforce identifizierte drei unabhängige Mechanismen, die jeweils eine andere Gegenmaßnahme 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 sowie nach jeder Komprimierung.⁶

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

Die Datei MEMORY.md erfasst Fehler, Entscheidungen und Muster über mehrere Sitzungen hinweg. Wenn Sie feststellen, dass ((VAR++)) in Bash mit set -e fehlschlägt, wenn VAR den Wert 0 hat, halten Sie dies darin fest. Stoßen Sie drei Sitzungen später in Python auf einen ähnlichen Grenzfall mit Ganzzahlen, macht der Eintrag in MEMORY.md Sie auf das Muster aufmerksam.¹⁵

Auto Memory (v2.1.32+): Claude Code zeichnet den Projektkontext automatisch auf und ruft ihn wieder ab. Während Sie arbeiten, schreibt Claude Beobachtungen in ~/.claude/projects/{project-path}/memory/MEMORY.md. Auto Memory lädt zu Beginn der Sitzung die ersten 200 Zeilen in Ihren System-Prompt. Halten Sie die Datei knapp und verlinken Sie für ausführliche Notizen auf separate Themendateien.⁶ Seit v2.1.210 führt ein Schreibvorgang in MEMORY.md, der die Größenbeschränkung überschreitet, zu einem Fehler, statt den Inhalt stillschweigend abzuschneiden⁶⁹ — der Fehler wird beim Schreiben sichtbar und nicht erst durch Speichereinträge, die unbemerkt verschwunden sind. Wenn Ihr harness Speicherschreibvorgänge automatisiert, behandeln Sie diesen Fehler entsprechend; die Plattform signalisiert Ihnen damit, dass die Datei kuratiert werden muss und kein erneuter Versuch erforderlich ist.

Speicherkuratierung statt Speichervolumen (Mai 2026): Ein aktueller arXiv-Preprint zur Zusammenarbeit von LLM-agents beschreibt einen umfangreicheren Abruf als möglichen Fehlermodus: In den Experimenten der Autoren verschlechterte eine längere sichtbare Historie die Zusammenarbeit in 18 von 28 Modellspielszenarien.⁴⁸ Betrachten Sie dies als Warnung für das Design und nicht als endgültiges Gesetz. Die Produktionsregel ist bereits eindeutig genug: Halten Sie MEMORY.md kurz, verlinken Sie ausführliche Informationen und nehmen Sie entscheidungsreife Zusammenfassungen in Übergaben auf. Unbearbeitete Transkriptabzüge, Tool-Protokolle und lange Abruf-Feeds gehören in einen durchsuchbaren Speicher und nicht automatisch in den aktiven Prompt.

Strategie 2: Proaktive Komprimierung

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

Wann Sie komprimieren sollten: - Nach Abschluss einer eigenständigen Teilaufgabe (Funktion implementiert, Fehler behoben) - Bevor Sie mit einem neuen Bereich der Codebasis beginnen - Wenn Claude beginnt, sich zu wiederholen oder früheren Kontext zu vergessen - Bei intensiven Sitzungen ungefähr alle 25–30 Minuten

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 Konversation; der /cd-Befehl (Claude Code v2.1.169) schützt den Prompt-Cache. Mit ihm lässt sich eine Sitzung während des laufenden Vorgangs in ein neues Arbeitsverzeichnis verschieben, ohne den im Verlauf der Gesprächsrunde aufgebauten Cache zu beeinträchtigen.⁶⁰ Zuvor erforderten Verzeichniswechsel eine neue Sitzung und einen kalten Cache. Wenn eine lang laufende Sitzung von einem Repository zu einem benachbarten wechselt — was bei Arbeiten mit Monorepos und mehreren Diensten häufig vorkommt — behält /cd das aufwendig zwischengespeicherte Präfix bei und richtet gleichzeitig den Dateisystemkontext neu aus.

Strategie 3: Sitzungsübergaben

Erstellen Sie für Aufgaben, die sich über mehrere Sitzungen erstrecken, Übergabedokumente, in denen der vollständige Zustand festgehalten wird:

## 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 stellt der nachfolgenden Sitzung bei minimalem Token-Verbrauch den vollständigen Kontext zur Verfügung. Wenn Sie eine neue Sitzung mit claude -c (Fortsetzen) starten oder das Übergabedokument lesen, können Sie direkt mit der Implementierung beginnen.¹⁵

Strategie 4: Iteration mit frischem Kontext (der Ralph loop)

Starten Sie bei Sitzungen, die länger als 60–90 Minuten dauern, für jede Iteration eine neue Instanz von Claude. Der Zustand bleibt über das Dateisystem erhalten, nicht über das Konversationsgedächtnis. Jede Iteration erhält das vollständige Kontextbudget:¹⁶

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

Vergleichen Sie dies mit einer einzelnen langen Sitzung:

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

Der Ansatz mit frischem Kontext pro Iteration tauscht einen Mehraufwand von 15–20 % für den Orientierungsschritt (Lesen von Zustandsdateien, Durchsuchen des Git-Verlaufs) gegen die vollständigen kognitiven Ressourcen pro Iteration ein.¹⁶ Die Kosten-Nutzen-Rechnung lautet: Bei Sitzungen unter 60 Minuten ist eine einzelne Konversation effizienter. Ab 90 Minuten liefert ein frischer Kontext trotz des Mehraufwands qualitativ bessere Ergebnisse.

Strategie 5: Verwaltete Speicherkuratierung (Dreaming)

Die Claude Managed Agents von Anthropic führten am 6. Mai 2026 Dreaming als Research Preview ein.³⁵ Laut Anthropic: „Dreaming ist ein geplanter Prozess, der Ihre agent-Sitzungen und Speicherbestände überprüft, Muster extrahiert und Erinnerungen kuratiert, damit sich Ihre agents im Laufe der Zeit verbessern.“³⁵

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

Dreaming befindet sich in der Research Preview, daher kann sich sein Verhalten ä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

Ganze Dateien lesen, obwohl Sie nur 10 Zeilen benötigen. Das einmalige Lesen einer 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 der Fehlerbehebung enthält Ihr Kontext mehr als 40 Stacktraces aus fehlgeschlagenen Iterationen. Ein einzelnes /compact nach der Behebung des Fehlers entfernt diesen Ballast.

Jede Sitzung mit dem Lesen sämtlicher Dateien beginnen. Lassen Sie die Glob- und Grep-Tools von Claude Code relevante Dateien bei Bedarf finden. So sparen Sie mehr als 100.000 Tokens durch unnötiges Vorladen.¹⁵

Subagent-Muster

Subagents sind spezialisierte Claude-Instanzen, die komplexe Aufgaben selbstständig bearbeiten. Sie starten mit einem bereinigten Kontext (ohne Inhalte aus der Hauptkonversation), arbeiten mit festgelegten Tools und geben ihre Ergebnisse als Zusammenfassungen zurück. Die Untersuchungsergebnisse blähen Ihre Hauptkonversation nicht auf; zurückgegeben werden nur die Schlussfolgerungen.⁵

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 unverzichtbar, die die Codebasis beschädigen könnten.

Isolation ist nur dann Isolation, wenn die Grenze hält. Claude Code v2.1.210 behob einen Fehler, durch den Worktree-isolierte subagents den primären Checkout verändern konnten – genau den Fehlerfall, den dieser Mechanismus verhindern soll.⁶⁹ Wenn Sie isolation: worktree als Sicherheitsgrenze und nicht nur der Bequemlichkeit halber einsetzen, sollte v2.1.210 Ihre Mindestversion sein. Die zugehörige 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 somit auch für benachbarte Worktrees desselben Repositorys.⁶⁹ Für parallel arbeitende Worktree-Agenten ist das ergonomisch sinnvoll, bedeutet aber auch, dass eine während eines kurzlebigen Experiments erteilte Freigabe das Experiment überdauert. Berücksichtigen Sie beim Erteilen einer Freigabe deshalb das gesamte Repository und nicht nur den aktuellen Worktree.

v2.1.216 schloss die verbliebenen Lücken und machte die Worktree-Isolation von einer fehlerbereinigten Funktion zu einer zuverlässig durchgesetzten Schutzmaßnahme.⁷⁴ Die Korrektur in v2.1.210 verhinderte, dass Worktree-subagents den primären Checkout über gewöhnliche Git-Aufrufe veränderten. Git bietet jedoch ausdrückliche Umleitungen – git -C <path>, --git-dir sowie die Umgebungsvariablen GIT_DIR/GIT_WORK_TREE – und ein Worktree-isolierter Subagent konnte sie weiterhin auf den gemeinsam genutzten Checkout richten. All diese Fluchtwege sind nun geschlossen. Dieselbe Version behob außerdem, dass Worktree-Sitzungen gelegentlich im zurückgebliebenen 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 weder Symlinks noch Hardlinks durchläuft. Allen vier Korrekturen liegt dasselbe Prinzip zugrunde: Eine Isolationsgrenze muss auch gezielten Umleitungen standhalten – etwa überschriebenen Git-Umgebungsvariablen oder platzierten Symlinks – und nicht nur dem Standardverhalten. Wenn isolation: worktree in Ihrem harness eine Sicherheitsgrenze und keine bloße Komfortfunktion ist, gilt v2.1.216 als neue Mindestversion.

Parallele Subagents

Verwenden Sie parallele subagents für unabhängige Rechercheaufgaben, die keine gegenseitige Abstimmung 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 erzeugen Agenten weitere Agenten, die wiederum Agenten erzeugen. Dabei geht auf jeder Ebene Kontext verloren, während Tokens verbraucht werden. 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 Begrenzungen der Verschachtelungstiefe. Tiefenbasierte Begrenzungen verfolgen Eltern-Kind-Ketten (beispielsweise eine Sperre ab Tiefe 3), erfassen aber nicht deren Breite: 23 Agenten auf Tiefe 1 gelten weiterhin nur als „Tiefe 1“. Ein Erzeugungsbudget erfasst die Gesamtzahl aktiver Kindagenten pro Elternagent und begrenzt sie auf ein konfigurierbares Maximum. Das Budgetmodell bildet den tatsächlichen Fehlerfall – zu viele Agenten insgesamt – besser ab als die Ersatzmetrik der übermäßigen Verschachtelungstiefe.⁷

Der Standardwert für die Verschachtelungstiefe wurde dreimal geändert; bauen Sie nicht darauf. Mit Claude Code v2.1.172 (10. Juni 2026) konnten sub-agents eigene sub-agents erzeugen und sie bis zu 5 Ebenen tief verschachteln – zuvor war die Delegation praktisch auf eine Ebene beschränkt.⁶² Dies 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 standardmäßig die verschachtelte Erzeugung. Mit v2.1.219 (24. Juli 2026) landete er schließlich dazwischen: „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 – die letzten beiden Änderungen innerhalb von drei Tagen.

Daraus sollten Sie nicht schließen, dass einer dieser Werte grundsätzlich richtig ist. Vielmehr sucht die Plattform noch nach dem passenden Standardwert, weshalb ein harness nicht einfach den jeweils ausgelieferten Wert übernehmen sollte. Behandeln Sie die Verschachtelungstiefe als ausdrückliche Budgetposition: Setzen Sie CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH auf die von Ihrer Architektur tatsächlich benötigte Tiefe – für die meisten Orchestrierungen ist das 1 oder 2 –, damit ein Upgrade nicht unbemerkt verändert, wie tief Ihre Agenten delegieren. Das grundlegende Argument bleibt von diesen Änderungen unberührt: Ketten von Agenten, die an weitere Agenten delegieren, verbrauchen Kontext und Tokens schneller, als sie Ergebnisse liefern. Tiefe ist ein einzuplanendes Risiko und keine anzustrebende Fähigkeit. Der obige Rekursionsschutz 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 auch nach der nächsten Version die von Ihnen beabsichtigte Bedeutung.

Auto mode prüft Erzeugungsvorgänge jetzt vor dem Start. Claude Code v2.1.178 schloss die entsprechende Lücke in der Steuerung: Im auto mode bewertet der Berechtigungsklassifikator die Erzeugung eines Subagents vor dessen Start und nicht erst, wenn er mit der Ausführung von Aktionen beginnt.⁶³ Zuvor konnte ein Subagent erzeugt werden, um eine Aktion anzufordern, die der übergeordneten Sitzung verwehrt gewesen wäre – bereits das Erzeugen diente als Umgehung. Durch die Prüfung zum Erzeugungszeitpunkt greifen Rekursionsschutz und Berechtigungsmodell endlich ineinander: Ein Kindagent kann nicht mehr dazu verwendet werden, eine von der Richtlinie verbotene Aktion zu verschleiern.

Die Plattform bietet jetzt ein natives Erzeugungsbudget. Claude Code v2.1.212 (Juli 2026) führte integrierte Schutzmaßnahmen 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), während für WebSearch höchstens 200 Aufrufe pro Sitzung gelten (CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION).⁶⁹ Das seit v1.0 in diesem Abschnitt als benutzerseitiges Skript dokumentierte Erzeugungsbudget wird nun von der Plattform bereitgestellt – eine Bestätigung des Budgetmodells gegenüber dem Tiefenmodell. Beachten Sie jedoch die Dimensionierung: 200 Erzeugungsvorgänge liegen um eine Größenordnung über dem Budget von 12 Agenten in der obigen Konfiguration. Die nativen Obergrenzen sind Sicherungen gegen eine wirklich außer Kontrolle geratene Schleife und keine auf Ihre Architektur abgestimmten Budgets. Behalten Sie den benutzerseitigen Schutz für Budgets pro Elternagent, die Erfassung der Tiefe und Begrenzungen bei, die dem tatsächlichen Verhalten Ihrer Orchestrierung entsprechen. Die Plattformgrenze fängt ab, was dennoch durchrutscht.

Die integrierten Schutzmaßnahmen decken jetzt vier Achsen ab. Drei davon sichern genau die Werte ab, die der benutzerseitige Schutz in diesem Abschnitt erfasst: die Gesamtzahl der Erzeugungsvorgänge pro Sitzung (v2.1.212, Obergrenze 200, CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION), die Verschachtelungstiefe (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH, derzeit standardmäßig 3 und nachweislich instabil) sowie die gleichzeitige Ausführung (v2.1.217, standardmäßig 20, CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS – eine einzelne Nachricht kann nicht mehr unbegrenzt viele Hintergrundagenten auffächern).⁷⁸⁸⁴ v2.1.219 ergänzt eine vierte Achse, die benutzerseitige Schutzmaßnahmen üblicherweise nicht abdeckten: die Orchestrierungsbreite, also die Anzahl von Agenten, die ein einzelner geplanter Workflow enthalten darf. Sie wird als Standardrichtlinie „aim for fewer than 15 agents“ ausgeliefert und lässt sich über workflowSizeGuideline in jeder Einstellungsdatei festlegen (siehe den nachfolgenden Abschnitt zum Workflow Tool). Das Erzeugungsbudget wird damit auf jeder Achse, für die es konzipiert wurde, sowie auf einer zusätzlichen Achse durch die Plattform abgesichert.

Der Hinweis zur Dimensionierung gilt weiterhin, allerdings nicht für alle Werte gleichermaßen. 200 Erzeugungsvorgänge und 20 gleichzeitig aktive Agenten sind Sicherungen – eine Größenordnung über dem Budget von 12 Agenten für die Deliberation in der obigen Konfiguration. Sie sollen außer Kontrolle geratene Schleifen abfangen und nicht die Architektur formen. Die Richtlinie zur Breite ist der erste native Wert in der Größenordnung eines echten Budgets: 15 Agenten pro Workflow liegen unmittelbar neben den hier empfohlenen 12. Den Plattformstandard zu übernehmen, kostet Sie daher nichts; wenn Sie davon abweichen, sollte es dafür einen konkreten Grund geben. Legen Sie die drei Sicherungen auf Werte fest, die Sie begründen können, und richten Sie die Breitenrichtlinie an der tatsächlich beabsichtigten Form Ihrer Orchestrierung aus.

Agent Teams (Research Preview)

Agent Teams koordinieren mehrere Claude Code-Instanzen, die unabhängig voneinander arbeiten, über eine gemeinsame Mailbox und Aufgabenliste kommunizieren und die Erkenntnisse der jeweils anderen hinterfragen 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, viele Sitzungen zu beauftragen und zu verwalten, die Tätigkeit jeder Sitzung einzusehen und zu erkennen, welche davon Eingaben durch Bediener benötigen.⁴³ Damit erhält die Multi-Agent-Arbeit eine operative Übersicht, die abschließende Zusammenfassungen 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 jedoch nicht als Qualitätsnachweis. Sie schafft Beobachtbarkeit; ob die Arbeit solide ist, entscheiden weiterhin Tests, Prüf-Gates und evidenzbasierte Berichte.

Dieselbe Version führte /goal ein. Damit lässt sich eine Abschlussbedingung festlegen, während Claude über mehrere Durchläufe hinweg weiterarbeitet, bis sie erfüllt ist – auch bei interaktiver Nutzung, mit -p und über Remote Control.⁴² Behandeln Sie /goal als sitzungsbezogene Abschlussschleife und nicht als Ersatz für deterministische Gates. Es hilft dabei, einen Agenten auf ein Ziel auszurichten. Tests, Zitationsprüfungen, Deployment-Prüfungen und security hooks sollten jedoch weiterhin auf Befehlen oder Skripten beruhen, wenn ein Fehler den Ablauf blockieren muss.

Workflow Tool (v2.1.147+)

Claude Code v2.1.147 ergänzt ein standardmäßig deaktiviertes Workflow tool für deterministische Multi-Agent-Orchestrierung. Aktivieren Sie es mit CLAUDE_CODE_WORKFLOWS=1.⁵² Aus architektonischer Sicht ist das bedeutsam, weil Claude Code dadurch ein integriertes Orchestrierungsprimitiv für Abläufe erhält, die zuvor eigene Dispatch-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 aber nicht Ihr Sicherheitsmodell. Behalten Sie PreToolUse- und PostToolUse-hooks als blockierende Ebene bei, verwenden Sie weiterhin Erzeugungs- oder Workflow-Schrittbudgets gegen unkontrollierte Breite, halten Sie den Dateisystemzustand prüfbar und trennen Sie abschließende Evidenzberichte von der Selbsteinschätzung des Modells. In der Praxis bedeutet das: Workflow bestimmt die Form der Orchestrierung; hooks, Tests und Prüf-Gates bestimmen, was als wahr gilt.

Dynamische Workflows bringen jetzt eine Vorgabe zur Breite mit (v2.1.219). Dynamische Workflows verwenden standardmäßig eine Richtlinie mittlerer Größe – „aim for fewer than 15 agents“. Weitere Größen und eine uneingeschränkte Option stehen unter Dynamic workflow size in /config zur Verfügung; die aktuelle Richtlinie wird außerdem in der Statuszeile des laufenden Workflows angezeigt.⁸⁴ Der Wert ist eine Empfehlung und wird nicht erzwungen: Er lenkt den Planer, statt einen zu breiten Plan zu blockieren. Konfigurationswürdig ist vor allem der Bereitstellungsmechanismus: Der neue Einstellungsschlüssel workflowSizeGuideline kann in jeder Einstellungsdatei festgelegt werden – einschließlich verwalteter und projektspezifischer Einstellungen – und ist seit v0.3.219 in den Einstellungstypen von TypeScript SDK enthalten. Dadurch lässt sich die Orchestrierungsbreite auf Team- oder Organisationsebene standardisieren, statt von jedem Bediener neu ermittelt zu werden.⁸⁵ Legen Sie den Wert auf Projektebene so fest, dass er widerspiegelt, in wie viele Einheiten sich die Arbeit Ihrer Codebasis tatsächlich zerlegen lässt. Zwei Hinweise für Bediener: Der entsprechende Eintrag in /config wird ausgeblendet, solange eine Einstellungsdatei den Wert vorgibt. Das ist zwar korrekt, wirkt ohne Kenntnis des Grundes jedoch wie eine fehlende Einstellung. Außerdem lenkt die Richtlinie den Planer, statt die Ausführung zu blockieren, und gehört daher in die Kategorie Form, nicht in die Kategorie Sicherheit. Für außer Kontrolle geratene Breite ist weiterhin die Erzeugungsobergrenze zuständig.

Behalten Sie im Blick, dass dies eine vierte Achse der integrierten Schutzmaßnahmen darstellt – die Orchestrierungsbreite neben Erzeugungszahl, Verschachtelungstiefe und gleichzeitiger Ausführung – und zugleich die erste, die Anthropic auf eine plausible Arbeitsgröße statt auf eine Notfallgrenze ausgelegt hat. 15 Agenten pro Workflow liegen in derselben Größenordnung wie das seit v1.0 in diesem Leitfaden verwendete Deliberation-Budget von 12 Agenten. Wenn sich der Plattformstandard und Ihr eigenes Budget aus unterschiedlichen Richtungen annähern, kommt das einer unabhängigen Bestätigung dieser Zahlen so nahe wie möglich.

Sitzungs-Forking und automatisch im Hintergrund ausgeführtes MCP (Juli 2026)

Claude Code v2.1.212 gestaltete zwei Orchestrierungsprimitive neu.⁶⁹ /fork erstellt nun aus dem aktuellen Konversationszustand eine neue Hintergrundsitzung – der abgezweigte Verlauf wird unabhängig ausgeführt, während die ursprüngliche Sitzung weiterarbeitet. 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; mit /fork lässt sich dagegen unkompliziert eine parallele Hintergrundsitzung mit vollständigem übernommenem Kontext erzeugen, was eher einem Spawn in einer Ralph-Schleife als einem Subagent entspricht. Wenn Ihre harness-Skripte davon ausgingen, dass /fork innerhalb derselben Sitzung bleibt, verteilen sie nun Arbeit in den Hintergrund.

Dieselbe Version verschiebt langsame MCP-Aufrufe automatisch in den Hintergrund: Ein Aufruf eines MCP tools, der länger als zwei Minuten dauert, wird automatisch im Hintergrund weiter ausgeführt. Den Schwellenwert können Sie mit CLAUDE_CODE_MCP_AUTO_BACKGROUND_MS anpassen.⁶⁹ Ein langsamer MCP-Server hält die agentische Schleife dadurch nicht mehr an. Das bedeutet allerdings auch, dass „das Tool hat ein Ergebnis geliefert“ und „der Durchlauf wurde fortgesetzt“ nicht mehr dasselbe Ereignis sind. hooks oder Skripte, die eine synchrone Fertigstellung von MCP voraussetzten, sollten deshalb auf das Tool-Ergebnis und nicht auf die Grenze des Durchlaufs reagieren.

Für die Headless-Orchestrierung führte v2.1.211 --forward-subagent-text (Umgebungsvariable: CLAUDE_CODE_FORWARD_SUBAGENT_TEXT) ein, wodurch Assistenztexte von subagents an die stream-json-Ausgabe weitergeleitet werden.⁶⁹ Ein Koordinatorprozess, der den Stream des übergeordneten Agenten verarbeitet, kann den Fortschritt von subagents nun direkt beobachten, statt Transkripte abzufragen oder auf die abschließende Zusammenfassung zu warten – die beobachtbare Ergänzung zu standardmäßig im Hintergrund ausgeführten subagents. v2.1.219 erweiterte dies über die erste Ebene hinaus: Auch subagents, die auf Tiefe 2 oder tiefer erzeugt werden, erscheinen nun im weitergeleiteten Stream, gekennzeichnet durch die tool_use-ID des erzeugenden Agent.⁸⁴ Auf genau diesem Schlüssel sollten Sie aufbauen. Da die Verschachtelung wieder standardmäßig aktiviert ist, wäre ein flacher Stream aus Subagent-Texten mehrdeutig. Anhand der ID kann ein Koordinator erkennen, welcher Elternagent welches Kind erzeugt hat, und so den Delegationsbaum aus dem Stream rekonstruieren, statt ihn ableiten zu müssen. Wurde Ihr Stream-Verbraucher nur für eine Ebene von subagents entwickelt, empfängt er nun Texte von Agenten, deren Existenz ihm bisher unbekannt war. Gruppieren Sie deshalb nach der erzeugenden tool_use-ID, statt anzunehmen, dass jede weitergeleitete Zeile zu einem direkten Kindagenten gehört.

Multi-Agent-Orchestrierung

Single-Agent-KI-Systeme haben einen strukturellen blinden Fleck: Sie können ihre eigenen Annahmen nicht infrage stellen.⁷ Multi-Agent-Deliberation erzwingt eine unabhängige Bewertung aus mehreren Perspektiven, bevor eine Entscheidung festgeschrieben wird.

Tool-übergreifende Orchestrierung (April 2026): Google hat am 7. April Scion als Open Source veröffentlicht — einen Multi-Agent-Hypervisor, der Claude Code, Gemini CLI und andere „Deep Agents” als nebenläufige Prozesse ausführt, jeder mit isoliertem Container, Git-Worktree und eigenen Credentials. Läuft lokal, im Hub oder auf Kubernetes. Explizite Philosophie: „Isolation statt Beschränkungen” — Agenten laufen mit hoher Autonomie innerhalb von Grenzen, die auf der Infrastrukturebene durchgesetzt werden, nicht im Prompt.²⁵ Dies erweitert das Argument der Subagent-Isolation direkt auf verschiedene Tool-Anbieter. Wenn Ihr Workflow Claude und OpenAI-Modelle umfasst, ist Scion die erste echte Referenzimplementierung für tool-übergreifende Subagenten mit Worktree- und Credential-Isolation pro Agent.

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

Managed Multiagent Orchestration und Outcomes (Public Beta)

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

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

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

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

Minimal tragfähige Deliberation

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

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

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

Der Confidence-Trigger

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

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

Der Score wird drei Stufen zugeordnet:

Der Schwellenwert passt sich dem Aufgabentyp an. Sicherheitsentscheidungen erfordern einen Konsens von 0,85. Dokumentationsänderungen benötigen lediglich 0,50. Damit wird Over-Engineering bei einfachen Aufgaben verhindert, während riskante Entscheidungen geprüft werden.⁷

Die State Machine

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

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

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

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

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

Die Two-Gate-Validierungsarchitektur

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

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

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

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

Warum Übereinstimmung gefährlich ist

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

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

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

Vorgetäuschte Übereinstimmung erkennen

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

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

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

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

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

Was bei der Deliberation nicht funktioniert hat

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

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

Kosten der Deliberation

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

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

Wann zu deliberieren ist

CLAUDE.md-Design

CLAUDE.md ist 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 langfristige Aufgaben (April 2026)

Claude Opus 4.7 (16. April 2026) wurde mit spezifischen Fähigkeiten veröffentlicht, die verändern, wogegen ein harness Schutz bieten muss:²⁹

• Robustheit bei Tool-Fehlern: Opus 4.7 setzt die Arbeit nach Tool-Fehlern fort, durch die Sitzungen mit Opus 4.6 abgebrochen wurden. Defensive Retry-Wrapper im subagent-Code können Sie reduzieren, aber nicht vollständig entfernen. Behalten Sie die Schutzmechanismen auf hook-Ebene bei; kürzen Sie dagegen in Prompts Hilfskonstruktionen wie „Wenn das Tool fehlschlägt, versuchen Sie es dreimal erneut“.
• xhigh-Aufwandsstufe (nur Opus 4.7): Liegt zwischen high und max. Empfohlener Standard für Programmieraufgaben und agentische Workloads. Bei lang laufenden subagents übertrifft xhigh die Stufe high deutlich, während die Token-Kosten unterproportional steigen. Für besonders anspruchsvolle einmalige Schlussfolgerungen bleibt max die richtige Wahl; für länger andauernde Aufgaben eignet sich xhigh besser.
• Token-Budgetobergrenze: Über output_config.task_budget für jeden Agentenlauf konfigurierbar (Beta-Header task-budgets-2026-03-13). Das Modell sieht einen fortlaufenden Countdown und passt den Arbeitsumfang kontrolliert an das Budget an, statt unerwartet keine Tokens mehr zur Verfügung zu haben. Verwenden Sie dies für agentische Schleifen, bei denen die Token-Ausgaben vorhersehbar bleiben sollen, ohne die Qualität bei kurzen Prompts zu beeinträchtigen.
• Erkennung impliziter Anforderungen: Das erste Claude-Modell, das Tests zu „impliziten Anforderungen“ besteht – es erkennt also, wenn die wörtliche Anfrage des Benutzers nicht vollständig beschreibt, was tatsächlich benötigt wird. Dadurch verliert der Abschnitt mit „Klärungsregeln“ in CLAUDE.md an Bedeutung. Falls Ihre CLAUDE.md aus 200 Zeilen mit Schutzregeln nach dem Muster „Berücksichtigen Sie außerdem X, wenn der Benutzer nach Y fragt“ besteht, entfernen Sie diejenigen, die das Modell inzwischen nativ abdeckt.

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

Claude Code v2.1.133 ergänzt vier Einstellungen auf Administratorebene, die für produktive harnesses relevant sind:³⁹

Auf die Rücknahme bei worktree.baseRef sollten Benutzer besonders hingewiesen werden: Agenten, die sich auf das Verhalten der Versionen v2.1.128 bis v2.1.132 verlassen haben – Worktrees zweigten vom lokalen HEAD ab –, verlieren in neuen Worktrees den Zugriff auf nicht gepushte Arbeit, sofern sie dieses Verhalten nicht ausdrücklich wieder aktivieren.

OTel-Feedbackumfrage für die Observability in Unternehmen (8. Mai 2026)

Claude Code v2.1.136 ergänzte CLAUDE_CODE_ENABLE_FEEDBACK_SURVEY_FOR_OTEL, um die Qualitätsumfrage während der Sitzung für Unternehmen wieder zu aktivieren, die Antworten über OpenTelemetry erfassen.⁴⁰ Leitet Ihre Organisation OTel-Ereignisse an einen zentralen Observability-Stack weiter, nimmt diese Umgebungsvariable die Umfrage wieder in den Datenpfad auf. Dadurch durchläuft das Qualitätssignal dieselbe Pipeline wie Latenz- und Fehlermetriken. Behandeln Sie die Funktion als Opt-in: Standardmäßig bleibt die Umfrage unterdrückt, was für Installationen ohne OTel die richtige Einstellung ist.

Unternehmens-Launcher und Leistung bei MCP-Skalierung (Juli 2026)

Zwei Änderungen in v2.1.207 sind für Produktivbereitstellungen relevant.⁶⁸ Mit CLAUDE_CODE_PROCESS_WRAPPER können verwaltete Umgebungen den Claude Code-Prozess über eine unternehmenseigene Wrapper-Binärdatei starten – die vorgesehene Integrationsstelle für Endpoint-Agenten, Richtlinienprüfungen beim Start und Umgebungen, in denen jeder Prozess unter einem vorgeschriebenen Supervisor ausgeführt werden muss. Falls Ihr Unternehmen dies bisher mithilfe von Shell-Aliassen oder abgezweigten Launcher-Skripten nachgebildet hat, steht nun eine offiziell unterstützte Schnittstelle zur Verfügung.

Dieselbe Version senkte den Laufzeitaufwand dort, wo harnesses ihn am stärksten spüren: bis zu 7-mal schnellere Tool-Nutzungsrunden in Sitzungen mit einer hohen Anzahl von MCP-Tools sowie 79-mal kleinere Sitzungsprotokolle.⁶⁸ Dadurch wird die Empfehlung unter Kosten als Architektur abgeschwächt, aber nicht umgekehrt: Für zustandslose einmalige Operationen ist CLI-first weiterhin überlegen. Ein harness mit Dutzenden MCP-Tools zahlt jedoch nicht mehr den Rundenzuschlag vom Frühjahr, und die Speicherung von Sitzungsprotokollen ist bei langen autonomen Läufen kein versteckter Kostenfaktor mehr.

Der quality loop

Ein obligatorischer Prüfprozess für alle nicht trivialen Änderungen:

1. Implementieren - Schreiben Sie den Code
2. Prüfen - 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, Grenzfälle und Testabdeckung
4. Verfeinern - Beheben Sie jedes Problem. Verschieben Sie nichts auf „später“
5. Gesamtbild prüfen - Kontrollieren Sie Integrationspunkte, Importe und angrenzenden Code auf Regressionen
6. Wiederholen - Schlägt ein Kriterium des evidence gate fehl, kehren Sie zu Schritt 4 zurück
7. Berichten - Führen Sie die Änderungen und deren Überprüfung auf und nennen Sie konkrete Belege

Das evidence gate

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

Können Sie für eine Zeile keinen Beleg vorlegen, kehren Sie zum Verfeinern zurück.²²

Menschliche Merge-Befugnis

Eine arXiv-Studie vom Mai 2026 zu 29.585 Lebenszyklen von Pull Requests durch KI-Agenten trennt die operative Handlungsfähigkeit von der Merge-Governance.⁴⁷ Die nützliche Architekturlehre daraus ist einfach: Agenten können Arbeiten beginnen, Branches weiterführen, PRs öffnen, Arbeit prüfen und Risiken zusammenfassen, während die Merge-Befugnis eine separate Governance-Grenze bleibt.

Machen Sie diese Grenze im harness ausdrücklich sichtbar. Lassen Sie Agenten PRs vorbereiten und Belege sammeln; für Merges, Releases und destruktive Repository-Operationen sollte eine menschliche Genehmigung erforderlich sein, sofern die Organisation nicht über eine separat geprüfte Automatisierungsrichtlinie verfügt. Wird ein Merge automatisiert ausgeführt, bewahren Sie Protokolle auf, die zwischen dem ausführenden System und der Person oder Richtlinie unterscheiden, die den Vorgang autorisiert hat.

Muster für die Fehlerbehandlung

Atomare Dateischreibvorgänge. Wenn mehrere Agenten gleichzeitig in dieselbe Zustandsdatei schreiben, wird JSON beschädigt. Schreiben Sie zunächst in .tmp-Dateien und führen Sie anschließend ein atomares mv aus. Das Betriebssystem garantiert, dass mv innerhalb desselben Dateisystems atomar ausgeführt wird.¹⁷

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

Wiederherstellung nach Zustandsbeschädigungen. Wird der Zustand beschädigt, stellt dieses Wiederherstellungsmuster ihn aus sicheren Standardwerten neu her, 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 bei ((VAR++)). ((VAR++)) gibt den Exit-Code 1 zurück, wenn VAR den Wert 0 hat, da 0++ zu 0 ausgewertet wird, was Bash als falsch behandelt. Ist set -e aktiviert, wird das Skript dadurch beendet. Verwenden Sie stattdessen VAR=$((VAR + 1)).¹⁶

Klassifizierung des blast radius

Klassifizieren Sie jede Agentenaktion nach ihrem blast radius und sichern Sie sie entsprechend ab:²

Remote Control – die Verbindung mit lokalem Claude Code über einen beliebigen Browser oder eine mobile App – verwandelt das „externe“ Gate von einer blockierenden Wartephase in eine asynchrone Benachrichtigung. Während Sie die vorherige Aufgabe auf Ihrem Mobiltelefon prüfen, arbeitet der Agent an der nächsten weiter.²

Aufgabenspezifikation für autonome Läufe

Wirksame autonome Aufgaben umfassen 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: Bestehen oder Fehlschlagen von Tests, Linter-Ausgabe, HTTP-Statuscodes und Prüfungen auf vorhandene Dateien. Bei einer frühen Aufgabe, in der der Agent „erfolgreiche Tests schreiben“ sollte, entstanden assert True und assert 1 == 1. Technisch korrekt. Praktisch wertlos.¹⁶

Zu beachtende Fehlermodi

Konkreter Sitzungsablauf

Ein Sitzungsprotokoll aus einem autonomen Lauf, bei dem ein PRD mit 5 Stories verarbeitet wurde:²

1. SessionStart wird ausgelöst. Der dispatcher fügt das aktuelle Datum, die Projekterkennung, philosophische Vorgaben und die Initialisierung der Kostenverfolgung ein. Fünf hooks, insgesamt 180 ms.

2. Der Agent liest das PRD und plant die erste Story. UserPromptSubmit wird ausgelöst. Der dispatcher fügt den aktiven Projektkontext und den Ausgangswert für die Sitzungsabweichung ein.

3. Der Agent ruft Bash auf, um Tests auszuführen. PreToolUse:Bash wird ausgelöst. Prüfung der Zugangsdaten, Sandbox-Validierung und Projekterkennung. 90 ms. Die Tests werden ausgeführt. PostToolUse:Bash wird ausgelöst: Aktivitäts-Heartbeat wird protokolliert, Abweichung geprüft.

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 und Commit-Verfolgung.

5. Der Agent schließt die Story ab. Stop wird ausgelöst. Das Qualitäts-Gate prüft: Hat der Agent Belege genannt? Enthält der Bericht Unsicherheitssprache? Gibt es TODO-Kommentare im Diff? Schlägt eine Prüfung fehl, wird Exit 2 zurückgegeben und der Agent arbeitet weiter.

6. Unabhängige Überprüfung: Ein neuer Agent führt die Testsuite aus, ohne sich auf den Selbstbericht des vorherigen Agenten zu verlassen.

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

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

Über 5 Stories hinweg insgesamt ausgelöste hooks: ca. 340. Gesamtdauer der hooks: ca. 12 Sekunden. Dieser Mehraufwand verhinderte in einem einzigen nächtlichen Lauf drei Lecks von Zugangsdaten, einen destruktiven Befehl und zwei unvollständige Implementierungen.

Fallstudie: Nächtliche Verarbeitung von PRD

Ein produktiver harness verarbeitete 12 PRDs (47 Stories) in 8 nächtlichen Sitzungen. Die Metriken vergleichen die ersten 4 PRDs (minimaler harness: nur CLAUDE.md) mit den letzten 8 (vollständiger harness: hooks, skills, Qualitäts-Gates und Multi-Agent-Review).

Wegen der beiden Lecks von Zugangsdaten mussten API-Schlüssel rotiert und nachgelagerte Dienste geprüft werden: etwa 4 Stunden für die Reaktion auf die Vorfälle. Der Mehraufwand des harness, der vergleichbare Vorfälle verhinderte, betrug 2,4 Sekunden Bash-Ausführung pro Story. Die Rate falscher Abschlüsse sank von 35 % auf 4 %, weil der Stop hook die Tests unabhängig 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 einen formalen Rahmen für die Vertrauenswürdigkeit von Agents.²⁷ Die fünf Prinzipien entsprechen dem Konzept des evidence gate in diesem Leitfaden und erweitern es:

Anthropic spendete außerdem MCP an die Agentic AI Foundation der Linux Foundation und schloss sich damit AGENTS.md an, das nun gemeinsam mit OpenAI, Google, Cursor, Factory und Sourcegraph verwaltet wird. Standards für die Interoperabilität von Agents sind damit anbieterneutral.²⁷

Zustandsloser Turn und selbst gemeldete Identität von MCP (Juli 2026). Die MCP-Spezifikation befindet sich mitten im Übergang zu einem zustandslosen Kern (SEP-2575), bei dem der zustandsbehaftete Initialisierungs-Handshake entfällt, über den zuvor die Serveridentität übertragen wurde. Eine am 16. Juli zusammengeführte Änderung des Spezifikationsentwurfs (PR #3002) stellt die Identität als optionale Oberfläche wieder her: Server können in der Antwort unter _meta ein io.modelcontextprotocol/serverInfo-Objekt übermitteln, während clientInfo bei Anfragen optional wird.⁷¹ Für die Sicherheit ist entscheidend, was die Spezifikation über Vertrauen sagt: Diese Identität ist selbst gemeldet und nicht verifiziert – sie dient ausschließlich der Anzeige und Protokollierung – und SOLLTE NICHT als Grundlage für Sicherheitsentscheidungen verwendet werden. Wenn Ihr harness Zulassungslisten, Berechtigungsregeln oder protokollbasierte Audits an den deklarierten Namen eines MCP-Servers knüpft, ist dieser Name eine Behauptung und kein Berechtigungsnachweis. Binden Sie das Vertrauen an den Transport und die Konfiguration – also daran, welchen Server Sie an welchem Endpunkt konfiguriert haben –, niemals an die Selbstauskunft des Servers. Die endgültige Überarbeitung der zustandslosen Spezifikation ist für den 28. Juli 2026 vorgesehen. Rechnen Sie damit, dass sich die Protokolldetails in diesem Abschnitt mit der nächsten Aktualisierung festigen.

Tools für skill-Sandboxing: Für Teams, die skills als Angriffsfläche betrachten, führt SandyClaw von Permiso (veröffentlicht am 2. April 2026) skills in einer dedizierten Sandbox aus und liefert evidenzgestützte Bewertungen anhand von Sigma-/YARA-/Nova-/Snort-Erkennungen. Es ist das erste Produkt in der Kategorie der skill-Sandboxes.²⁸

Die Sandbox

Claude Code unterstützt einen optionalen Sandbox-Modus, der über settings.json oder den Befehl /sandbox aktiviert wird und Netzwerkzugriffe sowie Dateisystemoperationen mithilfe einer Isolation auf Betriebssystemebene einschränkt (Seatbelt unter macOS, Bubblewrap unter Linux). Ist die Sandbox aktiviert, kann das Modell weder beliebige Netzwerkanfragen stellen noch auf Dateien außerhalb des Projektverzeichnisses zugreifen. Ohne Sandboxing verwendet Claude Code ein berechtigungsbasiertes Modell, bei dem Sie einzelne Tool-Aufrufe genehmigen oder ablehnen.¹³

Sicherheitsuntergrenze vom Mai 2026. Claude Code v2.1.149 behob eine Umgehung der Arbeitsverzeichnisberechtigungen in PowerShell, mehrere Lücken bei der Berechtigungsanalyse von PowerShell-Zulassungsregeln und veralteten Variablen sowie einen Fehler in der Schreibzulassungsliste der Git-Worktree-Sandbox, durch den statt nur der gemeinsam genutzten internen Git-Daten das gesamte Stammverzeichnis des Haupt-Repositorys abgedeckt wurde.⁵³ Wenn Ihr harness PowerShell oder durch Worktrees isolierte Agents zulässt, sollten Sie v2.1.149+ als Untergrenze betrachten und Shell-Regeln eng fassen. Weitreichende PowerShell(*)-Regeln und Schreibausnahmen für das gesamte Repository sind Abkürzungen bei der Orchestrierung, keine Sicherheitsgrenzen.

Verschärfung der Sandbox von OpenAI Agents SDK (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 müssen nun innerhalb des Materialisierungsverzeichnisses base_dir liegen – dem aktuellen Arbeitsverzeichnis des SDK-Prozesses zum Zeitpunkt der Manifestanwendung –, sofern die Quelle nicht ausdrücklich über Manifest.extra_path_grants mit SandboxPathGrant freigegeben wurde.⁴¹ Relative lokale Quellen werden ausgehend von base_dir aufgelöst; absolute Pfade müssen sich bereits darin befinden oder über eine Freigabe verfügen. Dadurch wird eine lokale Artefaktgrenze geschlossen: Frühere Versionen erlaubten es Manifesten, beliebige Hostpfade in einen Sandbox-Arbeitsbereich zu übernehmen. Migration: Deklarieren Sie vertrauenswürdige Host-Stammverzeichnisse auf Manifestebene mit SandboxPathGrant(path=..., read_only=True) für schreibgeschützte Einbindungen. Behandeln Sie extra_path_grants als vertrauenswürdige Anwendungskonfiguration; befüllen Sie Freigaben niemals anhand von Modellausgaben oder nicht vertrauenswürdigen Manifesteingaben.

Nachgezogene Untergrenze für OpenAI Agents SDK (v0.17.3). Die Versionsreihe 0.17.1–0.17.3 ergänzte weitere Härtungen für Sandbox und Sitzungen: Begrenzungen bei der Archivextraktion, Validierung von GitRepo-Unterpfaden, verständlichere Fehler von Sandbox-Anbietern, Ausschluss von Anmeldedaten für Einhängepunkte aus Sandbox-Befehlen, Ablehnung relativer Stammverzeichnisse von Sandbox-Arbeitsbereichen sowie die Behandlung terminaler Zustände der Vercel-Sandbox.⁵⁴ Wenn Sie von OpenAI gehostete oder anbietergestützte Sandboxes statt ausschließlich Claude Code-hooks verwenden, sollten Sie 0.17.3 als aktuelle Untergrenze für die Muster in diesem Abschnitt betrachten.

Drei produktübergreifende Eindämmungsmuster (Anthropic, Mai 2026)

Der Engineering-Beitrag „How we contain Claude across products“ von Anthropic (25. Mai 2026) formuliert aus Anbietersicht die Prinzipien, die dieser Abschnitt schrittweise vermittelt: die oben beschriebene Sandbox auf Einstellungsebene, die Untergrenze für die Worktree-Isolation und die Haltung, alles als nicht vertrauenswürdig zu behandeln.⁸¹ Sein zentraler Ansatz besteht darin, die Stärke der Eindämmung auf die Produktoberfläche abzustimmen. Diese Zuordnung ist selbst die Lehre: Es gibt nicht das eine richtige Isolationsdesign, sondern nur eine Isolation, die dazu passt, wer die Vorgänge überwacht und was schiefgehen kann.

• Kurzlebige gVisor-Container (claude.ai). Die serverseitige Ausführung erfolgt in gVisor-Containern auf isolierter Infrastruktur mit einem kurzlebigen Dateisystem pro Sitzung. Das Bedrohungsmodell betrifft die Isolation von Infrastruktur und Mandanten. Der Rechner des Benutzers ist niemals erreichbar, sodass lokal nichts geschützt werden muss.
• Betriebssystem-Sandboxing mit menschlicher Kontrolle (Claude Code). Das im vorigen Sandbox-Absatz beschriebene Muster, als Richtlinie formuliert: Seatbelt unter macOS und Bubblewrap unter Linux, wobei Lesezugriffe erlaubt, Schreibzugriffe auf den Arbeitsbereich beschränkt und Netzwerkzugriffe standardmäßig verweigert werden. Was die Grenze nicht abdeckt, genehmigt der Mensch. Anthropic veröffentlichte die Laufzeitumgebung als Open Source (sandbox-runtime), damit die Grenze überprüfbar ist. Der Beitrag benennt die Schwachstelle offen: Rund 93 % der Berechtigungsabfragen werden genehmigt. Der Auto-Mode-Klassifikator – der etwa 83 % übereifriger Verhaltensweisen vor der Ausführung erkennt und zugleich die Zahl der Genehmigungsabfragen um 84 % reduziert – existiert genau deshalb, weil Genehmigungsmüdigkeit eine Sicherheitseigenschaft und keine UX-Beschwerde ist. Das entspricht der Haltung einer Prüfebene, 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 –, in die nur der ausgewählte Arbeitsbereich und der Ordner .claude eingebunden werden; alle übrigen Hostbereiche bleiben unsichtbar. Anmeldedaten gelangen niemals in die VM: Sie verbleiben im Schlüsselbund des Hosts, während jede Sitzung ein eingeschränktes, unabhängig widerrufbares Token erhält. Ein defensiver MITM-Proxy innerhalb der VM setzt dies durch und lässt ausschließlich Anfragen passieren, die das für die VM bereitgestellte Sitzungstoken enthalten. Ein vom Angreifer eingebetteter Schlüssel wird an der Grenze abgewiesen, weil nur die VM die Herkunft kennt.

Die übertragbare Komponente dieser Taxonomie sind die zugrunde liegenden Designprinzipien. Dämmen Sie zuerst auf Umgebungsebene ein und steuern Sie erst danach auf Modellebene: Jede probabilistische Abwehr besitzt eine von null verschiedene Fehlerquote. Deshalb müssen deterministische Grenzen auffangen, was die Steuerung auf Prompt-Ebene übersieht – das Argument dieses Leitfadens, dass hooks die Ausführung garantieren, hier nochmals vom Anbieter formuliert. Stimmen Sie die Isolationsstärke auf die Kontrollmöglichkeiten des Benutzers ab: Ein Entwickler kann einen Bash-Befehl vor der Genehmigung bewerten, ein Wissensarbeiter nicht. Deshalb zeigt Code einen Berechtigungsdialog an, während Cowork eine versiegelte VM erhält. Bevorzugen Sie bewährte Grundbausteine gegenüber eigener Isolationslogik: Hypervisoren, seccomp und Container-Laufzeitumgebungen haben bösartiger Prüfung besser standgehalten als die eigenen Zulassungslisten-Proxys und Konfigurationsparser von Anthropic. Behandeln Sie projektlokale Konfigurationen und Tool-Ausgaben als nicht vertrauenswürdig: Der Beitrag empfiehlt, das Öffnen von Projekten und das Laden von Konfigurationen wie jede eingehende Anfrage aus dem Internet zu behandeln und Tool-Ausgaben als Angriffsfläche zu betrachten, selbst wenn das Tool vertrauenswürdig ist. Dieselbe Haltung wendet dieser Leitfaden auf Nachrichten zwischen Agents, von subagents gelesene Inhalte und die selbst gemeldete Identität von MCP an. Halten Sie Anmeldedaten aus der Sandbox heraus: Verwenden Sie eingeschränkte, widerrufbare Tokens pro Sitzung statt allgemein verfügbarer Schlüssel, die der Agent preisgeben könnte.

Die Einstellungsoberfläche holt beim ersten Prinzip auf (v2.1.219). „Zuerst auf Umgebungsebene eindämmen“ lässt sich leicht befürworten, war jedoch umständlich zu konfigurieren, weil die Sandbox von Claude Code bei allem nachfragte, was ihre Regeln nicht abdeckten. Eine Berechtigungsabfrage ist eine probabilistische Abwehr im Kostüm einer deterministischen Grenze, wie die oben genannte Genehmigungsquote von 93 % eingesteht. sandbox.network.strictAllowlist beseitigt diese Rückfrage beim ausgehenden Datenverkehr: Ist die Einstellung gesetzt, wird die Anfrage eines Sandbox-Befehls an einen nicht zugelassenen Host unmittelbar verweigert, statt eine Abfrage auszulösen.⁸⁴ Kombinieren Sie dies mit sandbox.filesystem.disabled aus v2.1.216. Gemeinsam ergeben die beiden Einstellungen eine Sicherheitsposition statt einer Ansammlung von Schaltern: Dateisystem- und Netzwerkeindämmung lassen sich unabhängig auswählen, und die Netzwerkeindämmung kann nun deterministisch umgesetzt werden. Für ein unbeaufsichtigtes harness ist Letzteres wichtiger, weil aus einer eingeschleusten Anweisung erst durch ausgehenden Datenverkehr eine Exfiltration wird und der Endzustand der Genehmigungsmüdigkeit darin besteht, dass niemand an der Tastatur sitzt, der müde werden könnte. Der Preis ist der übliche Preis einer deterministischen Grenze: Die Zulassungsliste muss stimmen, und ein vergessener Host scheitert mit einer undurchsichtigen Ablehnung statt einer Rückfrage. Erfassen Sie die Hosts, die Ihre Agents tatsächlich benötigen, und entfernen Sie anschließend die Abfrage.

Nichts davon ersetzt die hook-Ebene; es liegt darunter. Die Eindämmungsmuster bilden die deterministische Untergrenze, und die Historie der Worktree-Durchsetzung in diesem Leitfaden vermittelt dieselbe Lektion im Kleinen: Eine Grenze zählt nur, wenn sie gezielter Umleitung standhält. Die Grundbausteine, die am wahrscheinlichsten standhalten, sind jene, die nicht eigens für diesen 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 auf die Parameterebene: Tool(param:value) gleicht die Eingabeparameter eines Tools ab, wobei * als Platzhalter dient. Das kanonische Beispiel lautet Agent(model:opus – eine Regel, die verhindert, dass subagents mit einer bestimmten Modellstufe gestartet werden.⁶³ Architektonisch schließt dies eine Lücke, die sich mit der obigen Tabelle der vier Ebenen nicht ausdrücken ließ: Zuvor konnten Sie ein Tool nur vollständig erlauben oder ablehnen, aber nicht einschränken, wie es aufgerufen wurde. Eine Governance-Richtlinie kann nun deterministisch festlegen: „subagents dürfen gestartet werden, aber nicht auf der Stufe Fable 5“ oder „Bash ist erlaubt, jedoch nicht mit diesem Flag“, statt dies lediglich auf Prompt-Ebene anzufordern.

Eine ergänzende verwaltete Einstellung, enforceAvailableModels (v2.1.175), schränkt die Modellauswahl von oben nach unten ein: Sie legt das Default-Modell fest und verhindert, dass benutzer- oder projektbezogene Einstellungen die verwaltete Zulassungsliste availableModels erweitern.⁶³ Beide Mechanismen ergänzen sich: Die Zulassungsliste bestimmt, welche Stufen in der Sitzung überhaupt verfügbar sind, während Regeln auf Parameterebene festlegen, wie subagents daraus auswählen dürfen. Seit v2.1.196 können Administratoren außerdem in der Organisationskonsole ein organisationsweites Standardmodell festlegen, das in /model als „Org default“ erscheint. So übernimmt eine gesamte Flotte einen verwalteten Standard, ohne dass jeder Betreiber selbst ein Modell fixieren muss – eine Untergrenze, die die Obergrenze der Zulassungsliste ergänzt.

Pfadbezogene Zulassungsregeln werden am Arbeitsverzeichnis verankert (Juli 2026)

Claude Code v2.1.214 beseitigte eine unauffällige Überübereinstimmung bei pfadbezogenen Berechtigungsregeln: Eine Zulassungsregel mit einem einsegmentigen Muster dir/** – etwa Edit(src/**) – genehmigte Änderungen automatisch in jedem Verzeichnis namens src auf jeder Tiefe, einschließlich vendor/some-package/src/ und sämtlicher anderer verschachtelter src/-Verzeichnisse, die der Autor der Regel nie freigeben wollte. Solche Regeln sind nun ausschließlich an <cwd>/dir verankert. Wenn Sie tatsächlich auf jeder Tiefe Übereinstimmungen wünschen, müssen Sie dies mit **/dir/** deklarieren.⁷⁴ Ablehnungs- und Abfrageregeln behalten absichtlich die bisherige Übereinstimmung auf jeder Tiefe bei. Diese Asymmetrie entspricht einem korrekten ausfallsicheren Design: Eine zu eng greifende Zulassungsregel fällt in einen sicheren Zustand zurück – Sie erhalten eine Abfrage –, während eine zu eng greifende Ablehnungsregel offen versagt und ein gesperrter Pfad durchrutscht. Deshalb wurden Zulassungen strenger, während Ablehnungen breit blieben. Wenn Ihre Einstellungen auf einsegmentige Zulassungsmuster angewiesen sind, um verschachtelte Pfade abzudecken, tun sie dies seit v2.1.214 stillschweigend nicht mehr. Genau so soll die Korrektur funktionieren, dennoch sollten Sie Ihre Zulassungslisten prüfen und die tatsächlich gewünschte Breite erneut deklarieren.

Schutzmaßnahmen für destruktive Befehle im Auto Mode (Juni 2026)

Claude Code v2.1.183 begrenzte den Aktionsradius des Auto Mode bei Operationen, durch die unbemerkt Arbeit verloren geht oder Umgebungen abgebaut werden. Sofern Sie sie in der Sitzung nicht ausdrücklich angefordert haben, blockiert der Auto Mode nun strikt 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 den Abbau von Infrastruktur (terraform destroy, pulumi destroy, cdk destroy), sofern Sie nicht den konkreten Stack genannt haben.⁶⁵ Architektonisch ergänzt dies die oben beschriebenen Prüfungen beim Starten und die Regeln auf Parameterebene: Statt zu kontrollieren, welches Tool verwendet oder wie es gestartet wird, kontrolliert es eine kleine Gruppe konkreter irreversibler Befehle anhand der Absicht. Der Agent kann sie weiterhin ausführen, jedoch nur auf ausdrückliche Anweisung und nicht aus eigener Initiative. Bilden Sie dasselbe Prinzip für ein autonomes harness in Ihren eigenen PreToolUse-hooks ab: Befehle, die Zustand zerstören, verdienen eine standardmäßige Ablehnungsregel, die nur durch ein explizites Signal des Betreibers aufgehoben wird.

Juli 2026: Der Auto Mode wird unternehmenstauglich, und eine Abfrage kann nicht mehr umgangen werden. Der Auto Mode erreichte mit v2.1.207 die allgemeine Verfügbarkeit auf Amazon Bedrock, Google Vertex AI und Microsoft Foundry. Die verwaltete Einstellung disableAutoMode dient als Opt-out für Unternehmen. Damit ist die Haltung „Klassifikator als Prüfebene“ auf jeder offiziellen Unternehmensplattform verfügbar, und seine Deaktivierung stellt eine ausdrückliche Governance-Entscheidung statt einer Plattformlücke dar.⁶⁸ v2.1.208 machte anschließend die Schutzmaßnahme gegen katastrophales Entfernen absolut: Bestätigungsabfragen für katastrophale Löschvorgänge durchbrechen nun sowohl --dangerously-skip-permissions als auch den Auto Mode.⁶⁸ Das ist ein bemerkenswerter Präzedenzfall – die erste Bestätigung in Claude Code, die von keiner Berechtigungshaltung, einschließlich des expliziten Umgehungs-Flags, außer Kraft gesetzt werden kann. Designs autonomer harnesses, die davon ausgingen, dass --dangerously-skip-permissions buchstäblich keine Abfragen bedeutet, müssen diese eine Ausnahme berücksichtigen. Sie wird genau dort ausgelöst, wo eine unbeaufsichtigte Schleife den größten unwiederbringlichen Schaden verursachen kann.

Schutzmaßnahmen gegen Fälschungen (Juli 2026)

Die Versionen v2.1.203–v2.1.206 schlossen zwei Wege, über die ein Agent seinen eigenen Audit-Pfad fälschen konnte.⁶⁸ Erstens verhindert eine Auto-Mode-Regel nun Manipulationen an Transkriptdateien: Die Sitzungsaufzeichnung kann nicht länger durch Tool-Aufrufe derselben Sitzung umgeschrieben werden. Zweitens weisen Benachrichtigungen zu Hintergrundaufgaben nun ausdrücklich darauf hin, dass während der Ausführung der Aufgabe keine menschliche Eingabe erfolgte. Letzteres zielt auf einen subtilen Fehler: Ein Modell konnte bei der Zusammenfassung einer Hintergrundaufgabe zuvor eine vermeintliche „Genehmigung“ im Transkript darstellen oder erfinden, die nie stattgefunden hatte, ohne dass die Benachrichtigung dem widersprach. Nun ist die Benachrichtigung selbst der Gegenbeleg.

Die architektonische Lehre lässt sich auf das evidence gate übertragen: Transkripte, Benachrichtigungen und Protokolle sind Audit-Oberflächen, und Audit-Oberflächen dürfen nicht von dem beschreibbar sein, was sie auditieren. Die Plattform setzt dies nun für ihr eigenes Transkript durch. Wenden Sie dieselbe Regel auf Ihr harness an: Evidenzberichte, Testergebnisse und Beratungsprotokolle gehören außerhalb des für das Modell beschreibbaren Pfads.

Abwehr von Prompt Injection

skills und hooks bieten mehrschichtigen Schutz 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 angewiesen 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

Die Isolation von subagents begrenzt den Schadensradius. Ein subagent mit permissionMode: plan kann selbst dann keine Änderungen vornehmen, wenn sein Prompt kompromittiert wurde.

Die Plattformuntergrenze wurde im Juli 2026 angehoben. Claude Code v2.1.210 härtete das Agent tool gegen indirekte Prompt Injection durch Inhalte, die ein subagent gelesen hat. Eine manipulierte Datei, Webseite oder Tool-Ausgabe, die von einem subagent eingelesen wird, kann die Delegationsoberfläche selbst nun schlechter beeinflussen.⁶⁹ v2.1.211 härtete außerdem das menschliche Glied der Kette: Berechtigungsvorschauen neutralisieren nun bidirektionale Steuerzeichen, Zeichen mit Nullbreite und optisch ähnliche Unicode-Zeichen. Dadurch kann ein Befehl nicht mehr so gestaltet werden, dass er im Genehmigungsdialog harmlos erscheint, während tatsächlich etwas anderes ausgeführt wird.⁶⁹ Die zweite Korrektur ist besonders wichtig für harnesses, bei denen ein Mensch gerenderte Vorschauen unter Zeitdruck genehmigt – auch die Anzeige war eine Angriffsfläche für Injection. Keine der Änderungen ersetzt die oben beschriebenen Abwehrmaßnahmen auf hook-Ebene; sie erhöhen die darunterliegende Untergrenze.

Agent-Protokolle und Schutzmaßnahmen sind Sicherheitsoberflächen

Zwei Sicherheitshinweise vom Mai 2026 bekräftigen ein Muster: Die Agent-Infrastruktur schafft neue Orte, an denen sensible Inhalte und ausführbare Richtlinien preisgegeben werden oder ausbrechen können. Der GitHub-Sicherheitshinweis GHSA-f3jg-756w-gm35 behandelt ein Problem im Nutzdatenfilter von Gryph Agents, bei dem sensible Inhalte aus Tool-Nutzdaten unter dem standardmäßigen Protokollierungsverhalten in lokalen SQLite-Protokollen verbleiben konnten.⁴⁵ OSV GHSA-wxxx-gvqv-xp7p behandelt einen Sandbox-Ausbruch aus einer LiteLLM-Schutzmaßnahme für benutzerdefinierten Code in einem administrativ geschützten Proxy-Endpunkt.⁴⁶

Die Produktionsregel lautet: Behandeln Sie Agent-Transkripte, Tool-Nutzdaten, SQLite-Protokolle und die Ausführung von Schutzmaßnahmen als sensible Infrastruktur. Schwärzen Sie Inhalte vor der Speicherung, legen Sie Aufbewahrungsfristen fest und halten Sie benutzerdefinierten Code für Schutzmaßnahmen in einer überprüfbaren Sandbox. Eine Regel auf Prompt-Ebene, die besagt, dass Geheimnisse nicht protokolliert werden sollen, genügt nicht. Der Protokollierungs- und Schutzmaßnahmenpfad benötigt deterministische Tests.

hook-Sicherheit

HTTP-hooks, die Umgebungsvariablen in Header einsetzen, benötigen eine ausdrückliche 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 Verantwortungsteilung zwischen Mensch und Agent

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

Das Muster: Menschen verantworten Entscheidungen, die organisatorischen Kontext, ethisches Urteilsvermögen oder strategische Ausrichtung erfordern. Agents verantworten Entscheidungen, die eine rechnergestützte Suche in großen Möglichkeitsräumen erfordern. hooks setzen diese Grenze durch.

Rekursive Durchsetzung von hooks

hooks werden auch bei Aktionen von subagents ausgelöst.¹³ Wenn Claude über das Agent tool einen subagent startet, werden Ihre PreToolUse- und PostToolUse-hooks für jedes vom subagent verwendete Tool ausgeführt. Ohne rekursive Durchsetzung der hooks könnte ein subagent Ihre Sicherheits-Gates umgehen. Mit dem Ereignis SubagentStop können Sie beim Abschluss eines subagents Bereinigungs- oder Validierungsschritte ausführen.

Das ist nicht optional. Ein Agent, der einen subagent ohne Ihre Sicherheits-hooks startet, kann einen Force-Push auf main durchführen, Anmeldedatendateien lesen oder destruktive Befehle ausführen, während Ihre Gates untätig die Hauptkonversation überwachen.

Kosten als Architektur

Kosten sind eine Architekturentscheidung und kein nachträglicher betrieblicher Gedanke.² Es gibt drei Ebenen:

Token-Ebene. Komprimierung des System-Prompts. Entfernen Sie Codebeispiele mit Tutorial-Charakter – das Modell kennt die APIs –, führen Sie doppelte Regeln aus mehreren Dateien zusammen und ersetzen Sie Erklärungen durch Einschränkungen. „Tool-Aufrufe ablehnen, die sensiblen Pfaden entsprechen“ erfüllt denselben Zweck wie eine 15-zeilige Erklärung, warum Anmeldedaten nicht gelesen werden dürfen.

Agent-Ebene. Neue Instanzen statt langer Konversationen. Jede Story in einem autonomen Durchlauf erhält einen neuen Agent mit einem sauberen Kontext. Der Kontext wächst nicht unkontrolliert, weil jeder Agent neu beginnt. Briefing statt memory: Modelle setzen ein klares Briefing besser um, als dass sie durch 30 Schritte angesammelten Kontexts navigieren.

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

Entscheidungsframework

Wann welcher Mechanismus zum Einsatz kommt:

Skills vs Hooks vs Subagents

FAQ

Wie viele hooks sind zu viele?

Die Leistung ist die Grenze, nicht die Anzahl. Jeder hook läuft synchron, daher addiert sich die gesamte hook-Ausführungszeit zu jedem passenden Tool-Aufruf. 95 hooks über Benutzer- und Projekteinstellungen hinweg laufen ohne spürbare Latenz, wenn jeder hook in unter 200 ms abgeschlossen ist. Der Schwellenwert, den Sie beobachten sollten: Wenn ein PostToolUse hook mehr als 500 ms zu jeder Dateibearbeitung hinzufügt, fühlt sich die Sitzung träge an. Profilen Sie Ihre hooks vor der Bereitstellung mit time.¹⁴

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

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

Wo sollte ich hook-Konfigurationsdateien ablegen?

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

Braucht jede Entscheidung deliberation?

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

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

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

Wie wirkt sich deliberation auf die Latenz aus?

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

Wie lang sollte eine CLAUDE.md-Datei sein?

Halten Sie jeden Abschnitt unter 50 Zeilen und die gesamte Datei unter 150 Zeilen. Lange Dateien werden durch Kontextfenster gekürzt, daher sollten die wichtigsten Anweisungen nach vorne: Befehle und Abschlussdefinitionen vor Stilpräferenzen.²¹

Funktioniert das auch mit anderen Tools als Claude Code?

Die Architekturprinzipien (hooks als deterministische Gates, skills als Domänenexpertise, subagents als isolierte Kontexte, Dateisystem als Gedächtnis) gelten konzeptionell für jedes agentische System. Die konkrete Implementierung nutzt die Lifecycle-Events, Matcher-Muster und das Agent tool von Claude Code. AGENTS.md überträgt dieselben Muster auf Codex, Cursor, Copilot, Amp und Windsurf.²¹ Das harness-Muster ist Tool-agnostisch, auch wenn die Implementierungsdetails Tool-spezifisch sind.

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

Dateispeicherorte

Änderungsprotokoll

Quellenangaben