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