Claude Code Harness — Referenz für AI Engineers

Stand: März 2026. Aus der täglichen Praxis mit Claude Code; Flags, Preise und Bugs können sich seitdem geändert haben. Siehe auch: Claude Code Tutorial.

Zielgruppe: Leute, die Claude Code schon nutzen. Fokus: Tuning, Config, Betrieb — kein Onboarding.

1. Architektur

Claude Code ist kein Wrapper, sondern ein natives Harness mit direktem API-Zugriff. Die Architektur besteht aus fünf Schichten:

CLAUDE.md (global + per-project)     ← deklarative Verhaltenssteuerung
       ↓
settings.json / settings.local.json  ← Permissions, Hooks, Modell
       ↓
Hooks (5 Lifecycle-Points)           ← Prozess-Steuerung
       ↓
Agents / Skills / Commands           ← Capability-Erweiterung
       ↓
MCP-Tools                            ← externe Tool-Integration

Lifecycle-Points:

Config-Hierarchie (letzte Regel gewinnt nicht — Regeln akkumulieren):

~/.claude/settings.json
~/.claude/settings.local.json   (Overrides)
~/.claude/CLAUDE.md             (globale Verhaltensregeln)
<project-root>/CLAUDE.md        (projektspezifische Regeln)

2. Konfiguration

settings.json — Hauptfelder

{
  "model": "claude-opus-4-6",           // Default-Modell
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  },
  "permissions": {
    "allow": ["Edit", "Write", "Glob", "Grep", "Agent", "Bash(git*)"],
    "deny":  ["Bash(rm*)", "Bash(apt*)", "Bash(dd*)"]
  },
  "hooks": {
    "PreToolUse": [
      { "matcher": "Agent", "hooks": [{"type": "command", "command": "~/.claude/hooks/enforce-background-agents.py"}] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{"type": "command", "command": "~/.claude/hooks/hook_inject.py"}] }
    ]
  }
}

Bash-Permissions nutzen Glob-Pattern: - Bash(git*) — alle git-Befehle - Bash(python3 /home/*) — python3 mit absolutem Pfad - Bash(*) — alles (gefährlich, nur in settings.local.json)

settings.local.json — Lokale Overrides

Nicht ins Git. Für Permissions die auf dem eigenen Rechner OK sind, aber nicht im Repo.

{
  "permissions": {
    "allow": ["Bash(gh api*)", "Bash(python3*)"]
  }
}

CLAUDE.md — Verhaltenssteuerung

Nicht wie ein Config-File behandeln — ist ein Aufmerksamkeitsbudget. Jede Regel konkurriert um Kontext.

Kritische Faustregel: Weniger Regeln, schärfer formuliert > viele Regeln, weich formuliert. Ab ~50 Regeln sinkt die Compliance messbar.

3. Tuning

Hook hinzufügen

// In settings.json, hooks.[HookPoint]:
{
  "matcher": "Write",   // Tool-Name oder "" für alle
  "hooks": [{
    "type": "command",
    "command": "~/.claude/hooks/my-hook.py"
  }]
}

Hook-Script bekommt JSON via stdin (tool, input, session_id). Exit-Code 0 = erlaubt, non-zero = geblockt (nur PreToolUse).

Skill erstellen

~/.claude/skills/my-skill/SKILL.md

Frontmatter + Inhalt. Wird via /my-skill getriggert. Skills sind Kontext-Injektionen, keine Tools.

Agent definieren

---
name: my-agent
model: claude-sonnet-4-6
tools: [Read, Edit, Write, Bash]
subagent_type: general
---
Hier steht das System-Prompt des Agents.

Datei nach ~/.claude/agents/my-agent.md. Agents erben alle aktiven Hooks — kein selektives Gate pro Agent möglich (aktuelles Limitation).

Custom Command erstellen

~/.claude/commands/my-cmd.md

Wird via /my-cmd aufgerufen. Verhält sich wie ein Slash-Command der den Datei-Inhalt als System-Prompt setzt.

Modell wechseln

// settings.json:
"model": "claude-sonnet-4-6"

Kein Runtime-Switching ohne Session-Neustart. Subagents können über Frontmatter ein anderes Modell nutzen.

Statusline anpassen

~/.claude/statusline.sh liest JSON von stdin (Context%, Token-Usage, Git-Branch, aktive Hooks) und gibt ANSI-formatierte Ausgabe zurück. Direktes Bash/Python-Skript, editierbar ohne Neustart.

Sidecar-NG Integration (Beispiel aus meinem Setup)

Der UserPromptSubmit-Hook ruft hook_inject.py auf. Dieser klassifiziert den Prompt (Keyword-First → LLM-Fallback) und injiziert additionalContext in den Hook-Response. Die Injection landet im nächsten LLM-Call, nicht im Session-Kontext dauerhaft.

Bekannter Bug #13650: SessionStart-Injections werden verworfen. Workaround: Injection über UserPromptSubmit statt SessionStart.

4. Vor- und Nachteile

Vorteile

Nachteile

5. Referenz

Dateipfade

Aktive Hooks (Beispiel aus meinem Setup)

Wichtige Befehle

claude                    # Session starten (Standard-Modell aus settings.json)
claude --plan             # Plan Mode — denkt vor Implementierung
/compact                  # Context komprimieren (lossless summary)
/status                   # Session-Status: Context%, Token-Usage, aktive Hooks
/my-skill                 # Skill triggern (Dateiname ohne .md)

Debugging

# Hook-Output testen (stdin simulieren):
echo '{"tool":"Write","input":{"file_path":"/tmp/test"}}' | ~/.claude/hooks/my-hook.py

# Event-Logs lesen:
# ~/.claude/events/YYYY-MM-DD.jsonl

# Token-Usage prüfen:
# ~/.claude/usage/YYYY-MM.jsonl