# Claude Code Harness — Referenz für AI Engineers

> Zielgruppe: Samuel (kennt Claude Code). 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:**

| Hook | Zeitpunkt | Kann blocken? |
|---|---|---|
| `SessionStart` | Session-Init | nein |
| `UserPromptSubmit` | vor LLM-Call | ja (additionalContext-Injection) |
| `PreToolUse` | vor Tool-Aufruf | ja (Blocking-Gate) |
| `PostToolUse` | nach Tool-Aufruf | nein |
| `Stop` | Session-Ende | nein |

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

```jsonc
{
  "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.

```jsonc
{
  "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

```jsonc
// 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

```markdown
---
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

```jsonc
// 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 (Samuel's 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

| Feature | Bewertung |
|---|---|
| Hook-System | Stärkstes auf dem Markt — PreToolUse-Blocking ist einzigartig |
| Subagent-System | 21 typisierte Agents, parallele Ausführung, Background-Support |
| CLAUDE.md | Deklarative Verhaltenssteuerung ohne Code |
| Plan Mode (`--plan`) | Strukturiertes Denken vor Implementierung |
| MCP-Integration | Externe Tools (Gemini, OpenCode) nativ einbindbar |
| Tooling-Ökosystem | Skills + Commands + Agents + Hooks + Statusline kombinierbar |

### Nachteile

| Problem | Impact |
|---|---|
| Kostenstruktur | Opus ~$15/1M Tokens — teuerster Harness |
| Modell-Lock | Nur Anthropic-Modelle, kein Runtime-Switch |
| Attention Budget | >50 CLAUDE.md-Regeln → messbare Compliance-Degradation |
| Session Hoarding | Lange Sessions akkumulieren toten Kontext |
| Hook-Freeze | Hooks-Änderungen erfordern Session-Neustart |
| Kein SessionEnd-Hook | Cleanup nach Session-Ende nicht möglich |
| Bug #13650 | SessionStart additionalContext wird verworfen |
| Hook-Inheritance | Subagents erben alle Hooks — keine differenzierten Gates |

---

## 5. Referenz

### Dateipfade

| Pfad | Zweck |
|---|---|
| `~/.claude/settings.json` | Hauptconfig: Modell, Permissions, Hooks |
| `~/.claude/settings.local.json` | Lokale Overrides (nicht im Git) |
| `~/.claude/CLAUDE.md` | Globale Verhaltensregeln |
| `~/.claude/agents/` | Agent-Definitionen (21 aktive) |
| `~/.claude/skills/` | Skill-Definitionen |
| `~/.claude/commands/` | Custom Slash-Commands |
| `~/.claude/hooks/` | Hook-Scripts |
| `~/.claude/statusline.sh` | Statusbar-Script |
| `~/.claude/usage/*.jsonl` | Token-Tracking |
| `~/.claude/events/*.jsonl` | Event-Logs (Telemetrie) |

### Aktive Hooks (Samuel's Setup)

| Hook | Trigger | Funktion |
|---|---|---|
| `enforce-background-agents.py` | PreToolUse → Agent | Blockt Agent-Calls ohne `run_in_background` |
| `coach-before.sh` | SessionStart | Rotiert Playbook-Regeln, Streak-Counter |
| `event_logger.py` | alle Events | JSON-Telemetrie aller Tool-Calls |
| `gsd-context-monitor.js` | PostToolUse | Context-Window-Überwachung |
| `hook_inject.py` (Sidecar-NG) | UserPromptSubmit | Prompt-Klassifikation + Context-Injection |

### Wichtige Befehle

```bash
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

```bash
# 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
```