Agent-Architektur: Aufbau KI-gestützter Entwicklungs-Harnesses

TL;DR: Claude Code ist keine Chatbox mit Dateizugriff. Es ist eine programmierbare Laufzeitumgebung mit 29 dokumentierten Lebenszyklus-Events, von denen jedes mit Shell-Skripten gehookt werden kann, die das Modell nicht überspringen kann. Stapeln Sie Hooks zu Dispatchern, Dispatcher zu Skills, Skills zu Agents, Agents zu Workflows – und Sie erhalten ein autonomes Entwicklungs-Harness, das Beschränkungen durchsetzt, Arbeit delegiert, Speicher über Sessions hinweg persistiert und Multi-Agent-Deliberation orchestriert. Dieser Leitfaden behandelt jede Ebene dieses Stacks: von einem einzelnen Hook bis zu einem 10-Agent-Konsenssystem. Keine Frameworks erforderlich. Alles bash und JSON.

Andrej Karpathy hat einen Begriff geprägt für das, was um einen LLM-Agent herum wächst: claws. Die Hooks, Skripte und Orchestrierung, die es dem Agent ermöglichen, die Welt außerhalb seines Kontextfensters zu greifen.¹ Die meisten Entwickler behandeln KI-Coding-Agents als interaktive Assistenten. Sie tippen einen Prompt, beobachten, wie er eine Datei bearbeitet, und ziehen weiter. Diese Sichtweise begrenzt die Produktivität auf das, was Sie persönlich überwachen können.

Das mentale Modell der Infrastruktur ist ein anderes: Ein KI-Coding-Agent ist eine programmierbare Laufzeitumgebung mit einem LLM-Kernel. Jede Aktion, die das Modell ausführt, läuft durch Hooks, die Sie kontrollieren. Sie definieren Richtlinien, keine Prompts. Das Modell operiert innerhalb Ihrer Infrastruktur auf die gleiche Weise, wie ein Webserver innerhalb der nginx-Regeln operiert. Sie sitzen nicht am nginx und tippen Anfragen ein. Sie konfigurieren es, deployen es und überwachen es.

Diese Unterscheidung ist wichtig, weil Infrastruktur kumulativ wirkt. Ein Hook, der Credentials in Bash-Befehlen blockiert, schützt jede Session, jeden Agent, jeden autonomen Lauf. Ein Skill, das Ihre Bewertungsrubrik kodiert, wird konsistent angewendet, ob Sie es aufrufen oder ein Agent es tut. Ein Agent, der Code auf Sicherheit überprüft, führt die gleichen Checks durch, ob Sie zusehen oder nicht.²

Wichtigste Erkenntnisse

• Hooks garantieren Ausführung; Prompts tun das nicht. Verwenden Sie Hooks für Linting, Formatierung, Sicherheitsprüfungen und alles, was jedes Mal unabhängig vom Modellverhalten laufen muss. Exit-Code 2 blockiert Aktionen. Exit-Code 1 warnt lediglich.³
• Skills kodieren Domänenexpertise, die automatisch aktiviert wird. Das Feld description bestimmt alles. Claude nutzt LLM-Reasoning (kein Keyword-Matching), um zu entscheiden, wann ein Skill angewendet werden soll.⁴
• Subagents verhindern Kontext-Aufblähung. Isolierte Kontextfenster für Exploration und Analyse halten die Hauptsession schlank. Führen Sie unabhängige Subagents parallel aus und setzen Sie Agent-Teams ein, wenn Worker dauerhafte Koordination benötigen.⁵
• Speicher lebt im Dateisystem. Dateien überdauern Kontextfenster. CLAUDE.md, MEMORY.md, Regelverzeichnisse und Handoff-Dokumente bilden ein strukturiertes externes Speichersystem.⁶
• Multi-Agent-Deliberation deckt blinde Flecken auf. Einzelne Agents können ihre eigenen Annahmen nicht hinterfragen. Zwei unabhängige Agents mit unterschiedlichen Bewertungsprioritäten erkennen strukturelle Fehler, die Quality Gates nicht adressieren können.⁷
• Das Harness-Muster ist das System. CLAUDE.md, Hooks, Skills, Agents und Speicher sind keine unabhängigen Funktionen. Sie komponieren sich zu einer deterministischen Schicht zwischen Ihnen und dem Modell, die mit Automatisierung skaliert.

Wie Sie diesen Leitfaden nutzen

Jeder Abschnitt baut auf dem vorherigen auf. Das Decision Framework am Ende bietet eine Nachschlagetabelle zur Auswahl des richtigen Mechanismus für jeden Problemtyp.

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 zusammensetzbarer Satz von Dateien, Skripten und Konventionen, der einen AI-Coding-Agenten in deterministische Infrastruktur einhüllt. Die Komponenten:

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

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

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

Orchestration Layer: Multi-Agent-Muster koordinieren unabhängige Agenten für Recherche, Review und Deliberation. Spawn-Budgets verhindern unkontrollierte Rekursion. Konsensvalidierung sichert die Qualität.

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

Managed vs. Self-Hosted Harnesses (April 2026)

Anfang 2026 war der Pfad „Bauen Sie Ihr eigenes Harness” die einzige reale Option. Im April 2026 änderte sich das. Anthropic veröffentlichte Claude Managed Agents in der öffentlichen Beta (8. April): Harness-Loop + Tool-Ausführung + Sandbox-Container + State-Persistenz als REST API, abgerechnet zu Standard-Tokens plus 0,08 $/Sitzungsstunde. OpenAIs Agents SDK-Update (16. April) formalisierte dieselbe Aufteilung — Harness und Compute als getrennte Layer, mit nativen Sandbox-Anbietern (Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop, Vercel) und Snapshot/Rehydrate, um Container-Verlust zu überstehen.²³²⁴

Die tiefere SDK-Oberfläche auf der OpenAI-Seite landete in openai-agents Python v0.14.0 (veröffentlicht am 15. April 2026; angekündigt am 16. April): eine SandboxAgent-Subklasse von Agent mit default_manifest, Sandbox-Anweisungen und Fähigkeiten; ein Manifest, das den Fresh-Workspace-Vertrag beschreibt (Dateien, Verzeichnisse, lokale Dateien, Git-Repos, env, Benutzer, Mounts); eine SandboxRunConfig für die laufspezifische Verdrahtung von Sandbox-Client, Live-Session-Injection, Manifest-Overrides, Snapshots und Materialisierungs-Parallelitätslimits. Eingebaute Fähigkeiten umfassen Shell-Zugriff, Dateisystem-Bearbeitung, Bildinspektion, Skills, Sandbox-Memory und Komprimierung. Sandbox-Memory bewahrt extrahierte Lehren über Läufe hinweg und legt sie progressiv offen; Workspaces unterstützen lokale Dateien, Git-Repo-Einträge und Remote-Mounts (S3, R2, GCS, Azure Blob, S3 Files); Snapshots sind anbieterübergreifend portierbar. Backends: UnixLocalSandboxClient, DockerSandboxClient sowie gehostete Clients für Blaxel, Cloudflare, Daytona, E2B, Modal, Runloop und Vercel über optionale Extras.²⁴

Für Python-Projekte, die die Claude Code-Laufzeit als Bibliothek einbetten möchten — zwischen „shell out zu claude” und „REST API zu Managed Agents” — ist claude-agent-sdk-python die dritte Option. Die Serie vom 28.–29. April (v0.1.69 → v0.1.71) hob die mitgelieferte CLI auf v2.1.123 an, hob die Untergrenze der mcp-Abhängigkeit auf >=1.19.0 (ältere Versionen ließen CallToolResult-Rückgaben aus In-Process-MCP-Tools stillschweigend fallen, sodass das Modell mit einem Validierungsfehler-Blob zurückblieb) und brachte SandboxNetworkConfig auf Schema-Parität mit dem TypeScript SDK (allowedDomains, deniedDomains, allowManagedDomainsOnly, allowMachLookup).³⁰

Die architektonische Weggabelung ist nun real:

Wann Sie was wählen sollten: Self-Hosted bleibt richtig für Teams, die bereits Infrastrukturkompetenz besitzen, Skills/Hooks unter eigener Kontrolle wünschen oder einen spezifischen Workflow tiefgreifend optimieren. Managed ist richtig für Teams ohne dedizierte Plattform-Ingenieure, wenn Time-to-Value wichtiger als Anpassbarkeit ist, oder wenn Agent-Läufe Laptop-Schließungen zuverlässig überstehen müssen, ohne dass Sie diese Persistenzschicht selbst bauen. Beide sind kompatibel — Sie können ein Self-Hosted Harness betreiben, das spezifische langlaufende Aufgaben über dessen REST API an Managed Agents delegiert.

Wie das Harness auf der Festplatte aussieht

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

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

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

Skills-System

Skills sind modellaufgerufene Erweiterungen. Claude erkennt und wendet sie automatisch basierend auf dem Kontext an, ohne dass Sie sie explizit aufrufen müssen.⁴ Sobald Sie sich dabei ertappen, denselben Kontext über mehrere Sitzungen hinweg erneut zu erklären, ist es Zeit, ein Skill zu erstellen.

Wann Sie ein Skill erstellen sollten

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

Ein Skill erstellen

Skills befinden sich an vier möglichen Orten, vom breitesten zum engsten Geltungsbereich:⁴

Jedes Skill benötigt eine SKILL.md-Datei mit YAML-Frontmatter:

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

# Code Review Expertise

## Security Checks
When reviewing code, verify:

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

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

Frontmatter-Referenz

Das Description-Feld ist alles

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

Schlechte Beschreibung:

description: Helps with code

Wirksame Beschreibung:

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

Die wirksame Beschreibung enthält: was es tut (Code auf bestimmte Problemtypen überprüfen), wann es verwendet werden soll (Untersuchung von Änderungen, PRs, Qualitätsanalyse) und Auslöserphrasen (review, audit, check), die Benutzer auf natürliche Weise eintippen.

Kontextbudget

Alle Skill-Beschreibungen teilen sich ein Kontextbudget, das dynamisch auf 1 % des Kontextfensters skaliert, mit einem Fallback von 8.000 Zeichen.⁴ Wenn Sie viele Skills haben, halten Sie jede Beschreibung knapp und stellen Sie den wichtigsten Anwendungsfall an den Anfang. Sie können das Budget über die Umgebungsvariable SLASH_COMMAND_TOOL_CHAR_BUDGET überschreiben,¹¹ aber die bessere Lösung sind kürzere, präzisere Beschreibungen. Führen Sie während einer Sitzung /context aus, um zu überprü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 sie. Claude liest diese Dateien bei Bedarf, wenn das Skill aktiviert wird. Halten Sie SKILL.md unter 500 Zeilen und verschieben Sie detailliertes Referenzmaterial in unterstützende Dateien.¹²

Skills über Git teilen

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

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

Wenn Teamkollegen pullen, erhalten sie das Skill automatisch. Keine Installation, keine Konfiguration. Dies ist der wirksamste Weg, um Expertise im Team zu standardisieren.

Skills als Prompt-Bibliothek

Über Skills mit einem einzigen Zweck hinaus funktioniert die Verzeichnisstruktur als organisierte Prompt-Bibliothek:

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

Jedes Skill kodiert eine andere Facette Ihres Fachwissens. Zusammen bilden sie eine Wissensbasis, aus der Claude je nach Kontext automatisch schöpft. Ein Junior-Entwickler erhält 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 werden. Dadurch entsteht domänenspezifisches Verhalten, das andere Sitzungen nicht belastet:²

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

Philosophie-Skills aktivieren sich automatisch über SessionStart-Hooks und injizieren Qualitätsbeschränkungen in jede Sitzung, ohne explizit aufgerufen zu werden. Das Skill selbst ist Wissen. Der Hook ist die Durchsetzung. Zusammen bilden sie eine Policy-Schicht.

Häufige Fehler bei Skills

Zu breite Beschreibungen. Ein git-rebase-helper-Skill, das sich bei jedem git-bezogenen Prompt aktiviert (Rebases, Merges, Cherry-Picks, sogar git status), belastet den Kontext bei 80 % der Sitzungen. Die Lösung besteht entweder darin, die Beschreibung zu verschärfen oder disable-model-invocation: true hinzuzufügen und den expliziten Aufruf über /skill-name zu erzwingen.⁴

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

Wichtige Informationen in unterstützenden Dateien vergraben. Claude liest SKILL.md sofort, greift aber nur bei Bedarf auf unterstützende Dateien zu. Wenn wichtige Informationen in einer unterstützenden Datei stehen, findet Claude sie möglicherweise nicht. Stellen Sie wesentliche Informationen direkt in SKILL.md ein.⁴

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

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

Hook-Architektur

Hooks sind Shell-Befehle, die durch Claude Code-Lebenszyklusereignisse ausgelöst werden.³ Sie laufen außerhalb des LLM als reine Skripte, nicht als Prompts, die vom Modell interpretiert werden. Das Modell will rm -rf / ausführen? Ein 10-zeiliges Bash-Skript prüft den Befehl gegen eine Sperrliste und weist ihn ab, bevor die Shell ihn überhaupt zu Gesicht bekommt. Der Hook feuert, ob das Modell will oder nicht.

Verfügbare Ereignisse

Claude Code stellt zum Zeitpunkt dieser Aktualisierung 29 dokumentierte Lebenszyklusereignisse in acht Kategorien bereit. Die Ereignisliste wächst mit jedem Release, behandeln Sie daher die Referenzdokumentation als maßgebliche Quelle und prüfen Sie das Cheat Sheet auf die aktuelle vollständige Tabelle, bevor Sie produktive Hooks verdrahten:¹³

Exit-Code-Semantik

Exit-Codes bestimmen, ob Hooks Aktionen blockieren:³

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

Hook-Konfiguration

Hooks leben in Settings-Dateien. Auf Projektebene (.claude/settings.json) für gemeinsam genutzte Hooks. Auf Benutzerebene (~/.claude/settings.json) für persönliche Hooks:

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

Das Feld matcher filtert einen ereignisspezifischen Wert. Bei Tool-Ereignissen passt es auf tool_name-Werte wie Bash, Edit, Write, Read, Glob, Grep, MCP-Tool-Namen wie mcp__server__tool oder * für alle Tools. Einfache Namen und durch | getrennte Listen sind exakte Übereinstimmungen; Werte mit anderen Zeichen werden als reguläre Ausdrücke von JavaScript behandelt. Manche Ereignisse unterstützen keine Matcher und feuern bei Konfiguration immer.¹³

Hook-Eingabe-/Ausgabe-Protokoll

Hooks empfangen JSON über stdin mit vollem Kontext:

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

Für erweiterte Steuerung können PreToolUse-Hooks JSON ausgeben, um die Tool-Eingabe zu modifizieren, Kontext zu injizieren oder Berechtigungsentscheidungen zu treffen. Verwenden Sie den hookSpecificOutput-Wrapper — das ältere Top-Level-Format decision/reason ist für PreToolUse veraltet:

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

Drei Arten von Garantien

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

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

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

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

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

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

Qualitätsgarantien validieren den Zustand an Entscheidungspunkten. PreToolUse-Hooks auf git commit-Befehle führen Ihren Linter oder Ihre Test-Suite 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, keine 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 lebt 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 } zum Erlauben oder { "ok": false, "reason": "..." } zum Blockieren zurück. Verwenden Sie sie für nuancierte Bewertungen, die Regex nicht ausdrücken kann.

Agent-Hooks (type: "agent") starten einen Subagenten mit Tool-Zugriff (Read, Grep, Glob) für mehrstufige Verifikation. Sie sind experimentell; bevorzugen Sie Command-Hooks für produktive Gates und reservieren Sie Agent-Hooks für Prüfungen, die wirklich das Inspizieren tatsächlicher Dateien oder Testausgaben erfordern:

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

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

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

Asynchrone Hooks

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

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

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

Dispatcher statt unabhängiger Hooks

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

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

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

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

Hooks debuggen

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

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

SDK-seitiges Hook-Event-Streaming

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

Das Event-Stream-Pattern passt am besten, wenn Ihr Harness ohnehin in Python lebt und Sie Hook-Signale im selben Kontrollfluss wie die Modellausgabe haben möchten. Der Shell-Skript-Hook-Vertrag (Exit-Codes, stdin-JSON, Dispatcher) bleibt die richtige Antwort für Harnesses, die mehrere Tools komponieren, Hooks zwischen Claude Code und Codex teilen oder Exit-Code-Semantik zum Blockieren benötigen.

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

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

• effort.level in der Hook-Eingabe. Hooks empfangen jetzt ein effort.level-JSON-Feld auf derselben Eingabe, die tool_input und session_id trägt. Derselbe Wert wird als $CLAUDE_EFFORT-Umgebungsvariable exportiert, sodass Bash-Befehle ihn ohne JSON-Parsing lesen können. Verwenden Sie dies, um die Hook-Kosten mit der Effort-Stufe zu skalieren: überspringen Sie aufwändige Validierung bei low, führen Sie das volle Sicherheits-Gate bei xhigh oder max aus.
• CLAUDE_CODE_SESSION_ID-Umgebungsvariable in Bash-Subprozessen. Bash-Tool-Subprozesse sehen jetzt denselben session_id-Wert, den die Hooks sehen, exponiert als CLAUDE_CODE_SESSION_ID. Damit schließt sich die Provenienzlücke für Tools, die pro Session Zustand loggen und bisher Subprozess-Ereignisse nicht mit Hook-Ereignissen korrelieren konnten.

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

Speicher und Kontext

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

Die drei Mechanismen des Multi-Turn-Kollapses

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

Strategie 1: Dateisystem als Speicher

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

~/.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 Sessions hinweg. Wenn Sie entdecken, dass ((VAR++)) mit set -e in Bash fehlschlägt, sobald VAR den Wert 0 hat, halten Sie das fest. Drei Sessions später, wenn Sie auf einen ähnlichen Integer-Grenzfall in Python stoßen, taucht der MEMORY.md-Eintrag das Muster wieder auf.¹⁵

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

Strategie 2: Proaktive Verdichtung

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

Wann verdichtet werden sollte: - Nach Abschluss einer abgegrenzten Teilaufgabe (Feature implementiert, Bug behoben) - Bevor Sie einen neuen Bereich der Codebasis in Angriff nehmen - Wenn Claude anfängt, sich zu wiederholen oder früheren Kontext zu vergessen - Etwa alle 25-30 Minuten während intensiver Sessions

Benutzerdefinierte Verdichtungsanweisungen in CLAUDE.md:

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

Strategie 3: Session-Handoffs

Erstellen Sie für Aufgaben, die sich über mehrere Sessions erstrecken, Handoff-Dokumente, die den vollständigen Status erfassen:

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

Die Status/Files/Decision/Blocked/Next-Struktur stellt der Nachfolge-Session bei minimalen Token-Kosten den vollständigen Kontext zur Verfügung. Wenn Sie eine neue Session mit claude -c (continue) starten oder das Handoff-Dokument lesen, gelangen Sie direkt zur Implementierung.¹⁵

Strategie 4: Iteration mit frischem Kontext (der Ralph-Loop)

Spawnen Sie für Sessions, die 60-90 Minuten überschreiten, pro Iteration eine frische Claude-Instanz. Der State bleibt über das Dateisystem erhalten, nicht über das Konversationsgedächtnis. Jede Iteration erhält das volle Kontextbudget:¹⁶

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

Im Vergleich dazu eine einzelne lange Session:

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

Der Ansatz mit frischem Kontext pro Iteration tauscht 15-20 % Overhead für den Orientierungsschritt (Lesen von State-Dateien, Sichten der Git-Historie) gegen volle kognitive Ressourcen pro Iteration ein.¹⁶ Die Kosten-Nutzen-Rechnung: Für Sessions unter 60 Minuten ist eine einzige Konversation effizienter. Jenseits von 90 Minuten liefert frischer Kontext trotz des Overheads eine höhere Ausgabequalität.

Strategie 5: Kuratierte Speicherverwaltung (Dreaming)

Die Claude Managed Agents von Anthropic haben am 6. Mai 2026 Dreaming als Research Preview hinzugefügt.³⁵ Laut Anthropic: „Dreaming ist ein geplanter Prozess, der Ihre Agent-Sessions und Memory-Stores überprüft, Muster extrahiert und Erinnerungen kuratiert, sodass sich Ihre Agents im Laufe der Zeit verbessern.”³⁵

Dreaming läuft im Hintergrund zwischen Sessions, nicht auf dem kritischen Pfad. Es ergänzt das Muster „Dateisystem als Speicher”, anstatt es zu ersetzen: Ihre MEMORY.md-Datei bleibt die tragende Schicht; Dreaming schreibt kuratierte Speichereinträge in den Memory-Store der Managed Agents, den der Agent zu Beginn der Session liest. Die beiden Muster koexistieren für Harnesses, die selbstgehosteten Dateisystem-State mit verwalteter Kuratierung kombinieren.

Dreaming befindet sich in der Research Preview, daher kann sich das Verhalten ändern. Die oben dokumentierten Muster für Session-Handoffs und CLAUDE.md bleiben der maßgebliche Speichermechanismus für selbstgehostete Harnesses.

Die Anti-Patterns

Vollständige Dateien lesen, wenn Sie nur 10 Zeilen brauchen. Ein einzelnes Lesen einer Datei mit 2.000 Zeilen verbraucht 15.000-20.000 Tokens. Nutzen Sie Zeilen-Offsets: Read file.py offset=100 limit=20 spart den größten Teil dieser Kosten.¹⁵

Ausführliche Fehlerausgaben im Kontext behalten. Nachdem Sie einen Bug debuggt haben, hält Ihr Kontext über 40 Stack-Traces aus fehlgeschlagenen Iterationen. Ein einzelnes /compact nach der Behebung des Bugs befreit diesen toten Ballast.

Jede Session damit beginnen, jede Datei zu lesen. Lassen Sie die Glob- und Grep-Tools von Claude Code relevante Dateien bei Bedarf finden und sparen Sie so über 100.000 Tokens unnötigen Vorabladens.¹⁵

Subagent-Muster

Subagents sind spezialisierte Claude-Instanzen, die komplexe Aufgaben eigenständig bewältigen. Sie starten mit einem sauberen Kontext (keine Verunreinigung aus dem Hauptgespräch), arbeiten mit festgelegten Tools und liefern Ergebnisse als Zusammenfassungen zurück. Die Erkundungsergebnisse blähen Ihren Hauptkontext nicht auf; nur die Schlussfolgerungen kehren zurück.⁵

Eingebaute Subagent-Typen

Eigene Subagents erstellen

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

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

You are a senior security engineer reviewing code for vulnerabilities.

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

Focus on actionable security findings, not style issues.

Konfigurationsfelder für Subagents

Worktree-Isolation

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

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

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

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

Parallele Subagents

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

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

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

Der Rekursionsschutz

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

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

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

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

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

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

Entscheidende Lehre: Verwenden Sie Spawn-Budgets, nicht nur Tiefenlimits. Tiefenbasierte Limits verfolgen Parent-Child-Ketten (blockiert bei Tiefe 3), übersehen jedoch die Breite: 23 Agents auf Tiefe 1 sind immer noch „Tiefe 1”. Ein Spawn-Budget verfolgt die gesamten aktiven Children pro Parent und ist auf ein konfigurierbares Maximum begrenzt. Das Budget-Modell bildet den tatsächlichen Fehlermodus ab (zu viele Agents insgesamt) statt einer Hilfsmetrik (zu viele Verschachtelungsebenen).⁷

Agent Teams (Research Preview)

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

Aktivieren mit: export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

Wann Agent Teams statt Subagents verwenden:

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 operative Richtlinie für einen KI-Agenten, kein README für Menschen.²¹ Der Agent muss nicht verstehen, warum Sie Conventional Commits verwenden. Er muss den exakten auszuführenden Befehl kennen und wissen, wie „fertig” aussieht.

Die Hierarchie der Vorrangstellung

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

Was ignoriert wird

Diese Muster führen zuverlässig zu keiner beobachtbaren Veränderung des Agentenverhaltens:²¹

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

Mehrdeutige Direktiven. „Seien Sie bei Datenbankmigrationen vorsichtig” ist keine Einschränkung. „Führen Sie alembic check aus, bevor Migrationen angewendet werden. Brechen Sie ab, wenn der Downgrade-Pfad fehlt.” dagegen schon.

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

Style Guides ohne Durchsetzung. „Folgen Sie dem Google Python Style Guide” ohne ruff check --select D gibt dem Agenten keinen Mechanismus, die Einhaltung zu überprüfen.

Was funktioniert

Befehlsorientierte Anweisungen:

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

Abschlussdefinitionen:

## Definition of Done
A task is complete when ALL of the following pass:
1. `ruff check .` exits 0
2. `pytest -v` exits 0 with no failures
3. `mypy app/ --strict` exits 0
4. Changed files have been staged and committed
5. Commit message follows conventional format: `type(scope): description`

Aufgabenorientierte Abschnitte:

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

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

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

Eskalationsregeln:

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

Schreibreihenfolge

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

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

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

Dateiimporte

Verweisen Sie innerhalb von CLAUDE.md auf andere Dateien:

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 Home-Verzeichnis (@~/.claude/file.md). Maximale Tiefe: 5 Importebenen.⁶

Werkzeugübergreifende Anweisungskompatibilität

AGENTS.md ist ein offener Standard, der von jedem großen KI-Coding-Tool anerkannt wird.²¹ Wenn Ihr Team mehrere Tools verwendet, schreiben Sie AGENTS.md als kanonische Quelle und spiegeln Sie relevante Abschnitte in toolspezifische Dateien:

Die Muster in AGENTS.md (befehlsorientiert, abschlussdefiniert, aufgabenorientiert) funktionieren in jeder Anweisungsdatei unabhängig vom Tool. Pflegen Sie keine parallelen Anweisungssätze, die auseinanderdriften. Schreiben Sie eine maßgebliche Quelle und spiegeln Sie diese.

Codex-Paritätshinweise

Codex verfügt nun über erstklassige Entsprechungen für die wichtigsten Harness-Schichten, aber die Migration ist eine Musterübersetzung, kein Dateikopiervorgang. Codex liest AGENTS.md, bevor die Arbeit beginnt, und überlagert globale Vorgaben aus ~/.codex mit Projekt- und verschachtelten Repository-Anweisungen.³¹ Codex-Skills verwenden dasselbe mentale SKILL.md-Modell mit progressiver Offenlegung: Codex beginnt mit dem Skill-Namen, der Beschreibung und dem Dateipfad und lädt den vollständigen Skill erst dann, wenn er sich für dessen Verwendung entscheidet.³² Codex bietet zudem native Hooks, plugin-gebündelte Hooks, verwaltete Hooks, MCP-Unterstützung und explizite Subagent-Workflows.³³³⁴

Die praktische Zuordnung:

Der wichtige Unterschied: Claude-Subagents können automatisch anhand von Beschreibungen ausgewählt werden, während Codex Subagent-Workflows derzeit als explizit dokumentiert. Damit sind Skills und Hooks die richtige Standardwahl für stets aktives Harness-Verhalten in Codex; Subagents sind für gezielte Parallelarbeit, Reviews und Exploration vorgesehen.

Testen Ihrer Anweisungen

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

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

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

Der Säuretest: Bitten Sie den Agenten, Ihre Build-Befehle zu erläutern. Wenn er sie nicht wortgetreu wiedergeben kann, sind die Anweisungen entweder zu ausführlich (Inhalt aus dem Kontext verdrängt), zu vage (der Agent kann keine umsetzbaren Anweisungen extrahieren) oder werden nicht erkannt. GitHubs Analyse von 2.500 Repositories ergab, dass Vagheit die meisten Fehler verursacht.²¹

Produktionsmuster

Opus 4.7 Long-Horizon-Muster (April 2026)

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

• Resilienz bei Tool-Fehlern: Opus 4.7 fährt bei Tool-Fehlern fort, die Opus-4.6-Sitzungen zum Stillstand brachten. Sie können defensive Retry-Wrapper im Subagent-Code reduzieren — aber nicht eliminieren. Behalten Sie die Schutzmechanismen auf Hook-Ebene; entfernen Sie das In-Prompt-Gerüst nach dem Muster „falls das Tool fehlschlägt, dreimal erneut versuchen”.
• xhigh-Aufwandsstufe (nur Opus 4.7): Liegt zwischen high und max. Empfohlener Standard für Coding- und agentische Workloads. Bei lang laufenden Subagenten übertrifft xhigh high deutlich bei unterproportionalen Token-Kosten. max bleibt die richtige Wahl für einmaliges hartes Reasoning; xhigh ist besser für anhaltende Aufgaben.
• Token-Budget-Obergrenze: Pro Agent-Lauf konfigurierbar über output_config.task_budget (Beta-Header task-budgets-2026-03-13). Das Modell sieht einen laufenden Countdown und passt seinen Arbeitsumfang elegant an das Budget an, statt unerwartet leerzulaufen. Verwenden Sie es für agentische Loops, bei denen Sie vorhersehbare Token-Ausgaben wünschen, ohne die Qualität bei kurzen Prompts zu opfern.
• Bewusstsein für implizite Bedürfnisse: Erstes Claude-Modell, das „Implicit-Need”-Tests besteht — also erkennt, wann die wörtliche Anfrage des Benutzers zu wenig spezifiziert, was tatsächlich benötigt wird. Das macht den Abschnitt mit den Klärungsregeln in CLAUDE.md weniger notwendig. Wenn Ihre CLAUDE.md aus 200 Zeilen Schutzmechanismen nach dem Muster „berücksichtigen Sie auch X, wenn der Benutzer Y verlangt” besteht, entfernen Sie diejenigen, die jetzt nativ abgedeckt sind.

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

Claude Code v2.1.133 fügt vier Einstellungen auf Admin-Ebene hinzu, die für Produktions-Harnesses bekannt sein sollten:³⁹

Die worktree.baseRef-Rückkehr ist diejenige, auf die Benutzer hingewiesen werden sollten: Agenten, die sich auf das Verhalten von v2.1.128–v2.1.132 verlassen haben (Worktrees, die von lokalem HEAD verzweigen), verlieren in frischen Worktrees den Zugriff auf nicht gepushte Arbeit, sofern sie sich nicht erneut dafür entscheiden.

Der Quality Loop

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

1. Implementieren – Code schreiben
2. Überprüfen – Jede Zeile erneut lesen. Tippfehler, Logikfehler, unklare Abschnitte aufspüren
3. Bewerten – Das Evidence Gate durchlaufen. Muster, Edge Cases, Testabdeckung prüfen
4. Verfeinern – Jedes Problem beheben. Niemals auf „später” verschieben
5. Zoom Out – Integrationspunkte, Imports und angrenzenden Code auf Regressionen prüfen
6. Wiederholen – Falls ein Evidence-Gate-Kriterium fehlschlägt, zurück zu Schritt 4
7. Berichten – Auflisten, was sich geändert hat, wie es verifiziert wurde, mit Verweis auf konkrete Belege

Das Evidence Gate

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

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

Muster für Fehlerbehandlung

Atomare Dateischreibvorgänge. Wenn mehrere Agenten gleichzeitig in dieselbe State-Datei schreiben, beschädigt dies JSON. Schreiben Sie in .tmp-Dateien und benennen Sie diese dann atomar mit mv um. Das OS garantiert, dass mv auf demselben Dateisystem atomar ist.¹⁷

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

Wiederherstellung bei State-Korruption. Wenn der Zustand beschädigt wird, erstellt das Recovery-Muster ihn aus sicheren Standardwerten neu, anstatt abzustürzen:¹⁶

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

Die ((VAR++))-Bash-Falle. ((VAR++)) gibt Exit-Code 1 zurück, wenn VAR 0 ist, weil 0++ zu 0 ausgewertet wird, was Bash als false interpretiert. Mit aktiviertem set -e beendet das das Skript. Verwenden Sie stattdessen VAR=$((VAR + 1)).¹⁶

Klassifizierung des Blast Radius

Klassifizieren Sie jede Agent-Aktion nach Blast Radius und sichern Sie sie entsprechend ab:²

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

Aufgabenspezifikation für autonome Läufe

Wirksame autonome Aufgaben enthalten drei Elemente: Zielsetzung, Abschlusskriterien und Kontext-Pointer:¹⁶

OBJECTIVE: Implement multi-agent deliberation with consensus validation.

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

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

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

Fehlermuster, auf die Sie achten sollten

Ein konkreter Session-Trace

Ein Session-Trace eines autonomen Laufs, der ein PRD mit 5 Stories verarbeitet:²

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

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

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

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

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

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

7. Drei Code-Review-Agenten werden parallel gespawnt. Jeder prüft das Diff unabhängig. Wenn ein Reviewer CRITICAL meldet, geht die Story zurück in die Queue.

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

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

Fallstudie: Overnight-Verarbeitung von PRD

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

Die zwei Credential-Leaks erforderten das Rotieren von API-Keys und das Auditieren nachgelagerter Dienste: rund 4 Stunden Incident Response. Der Harness-Overhead, der das Äquivalent verhinderte, betrug 2,4 Sekunden Bash pro Story. Die False-Completion-Rate fiel von 35 % auf 4 %, weil der Stop-Hook Tests unabhängig ausführte, bevor er dem Agenten erlaubte, „fertig” zu melden.

Sicherheitsüberlegungen

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

Anthropic veröffentlichte am 9. April 2026 ein formales Framework für die Vertrauenswürdigkeit von Agenten.²⁷ Die fünf Prinzipien stehen parallel zum — und erweitern das — Evidence-Gate-Konzept dieses Leitfadens:

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

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

Die Sandbox

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

Berechtigungsgrenzen

Das Berechtigungssystem gatet Operationen auf mehreren Ebenen:

Prompt-Injection-Verteidigung

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

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

allowed-tools: Read, Grep, Glob

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

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

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

Hook-Sicherheit

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

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

Die Aufgabenteilung zwischen Mensch und Agent

Sicherheit in Agentenarchitekturen erfordert eine klare Trennung zwischen menschlichen und agentenseitigen Verantwortlichkeiten:¹⁷

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

Rekursive Hook-Durchsetzung

Hooks feuern auch für Aktionen von Subagenten.¹³ Wenn Claude einen Subagenten über das Agent-Tool spawnt, werden Ihre PreToolUse- und PostToolUse-Hooks für jedes Tool ausgeführt, das der Subagent verwendet. Ohne rekursive Hook-Durchsetzung könnte ein Subagent Ihre Sicherheits-Gates umgehen. Mit dem SubagentStop-Event lassen sich Cleanup- oder Validierungsschritte ausführen, sobald ein Subagent abschließt.

Das ist nicht optional. Ein Agent, der einen Subagenten ohne Ihre Sicherheits-Hooks spawnt, ist ein Agent, der einen Force-Push auf main durchführen, Credential-Dateien lesen oder destruktive Befehle ausführen kann, während Ihre Gates die Hauptkonversation beobachten und nichts tun.

Kosten als Architektur

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

Token-Ebene. Komprimierung des System-Prompts. Entfernen Sie Tutorial-Codebeispiele (das Modell kennt die APIs), bündeln Sie doppelte Regeln über Dateien hinweg und ersetzen Sie Erklärungen durch Constraints. „Lehne Tool-Aufrufe ab, die zu sensiblen Pfaden passen” leistet dieselbe Arbeit wie eine 15-zeilige Erklärung, warum Credentials nicht gelesen werden sollten.

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

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

Entscheidungsframework

Wann welcher Mechanismus zu verwenden ist:

Skills vs. Hooks vs. Subagenten

FAQ

Wie viele Hooks sind zu viele?

Die Performance ist die Beschränkung, nicht die Anzahl. Jeder Hook läuft synchron, sodass die gesamte Hook-Ausführungszeit zu jedem passenden Tool-Aufruf hinzukommt. 95 Hooks über benutzer- und projektbezogene Einstellungen hinweg laufen ohne spürbare Latenz, wenn jeder Hook unter 200 ms abgeschlossen ist. Der Schwellenwert, den Sie beobachten sollten: Wenn ein PostToolUse-Hook jeder Dateibearbeitung mehr als 500 ms hinzufügt, fühlt sich die Sitzung träge an. Profilieren Sie Ihre Hooks mit time, bevor Sie sie einsetzen.¹⁴

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

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

Wo sollte ich Hook-Konfigurationsdateien ablegen?

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

Benötigt jede Entscheidung eine Deliberation?

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

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

Testen Sie sowohl Erfolgs- als auch Fehlerpfade. Erfolg: Agenten widersprechen sich produktiv und erreichen einen Konsens. Fehler: Agenten konvergieren zu schnell, konvergieren nie oder überschreiten Spawn-Budgets. End-to-End-Tests simulieren jedes Szenario mit deterministischen Agentenantworten und überprüfen, dass beide Validierungs-Gates jeden dokumentierten Fehlermodus erfassen. Ein produktives Deliberationssystem führt 141 Tests über drei Schichten aus: 48 Bash-Integrationstests, 81 Python-Unit-Tests und 12 End-to-End-Pipeline-Simulationen.⁷

Welche Latenzauswirkungen hat die Deliberation?

Eine Deliberation mit 3 Agenten fügt 30–60 Sekunden Wandzeit hinzu (Agenten laufen sequenziell durch das Agent-Tool). Eine Deliberation mit 10 Agenten fügt 2–4 Minuten hinzu. Die Consensus- und Pride-Check-Hooks laufen jeweils 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 von Kontextfenstern abgeschnitten, stellen Sie also die kritischsten Anweisungen voran: Befehle und Closure-Definitionen vor Stilpräferenzen.²¹

Kann das mit anderen Tools als Claude Code funktionieren?

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

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

Speicherorte

Änderungsprotokoll

Referenzen