Claude Code als Harness

Lernziele

Du ordnest jedem Teil der Harness-Anatomie die passende Funktion in Claude Code zu.
Du entscheidest, ob eine Regel in einen Prompt oder in einen Hook gehört.
Du startest Claude Code ohne Oberfläche und mit dem Agent SDK aus Python.

Claude Code eignet sich gut als Studienobjekt, weil Anthropic dieselbe Maschinerie zweimal ausliefert. Einmal als Produkt im Terminal und einmal als Claude Agent SDK, eine Bibliothek für Python und TypeScript. Laut Doku bietet sie dieselben Tools, denselben Agenten-Loop und dieselbe Kontextverwaltung wie Claude Code, programmierbar für eigene Agenten. Lies zuerst die Anatomie. Diese Lektion ordnet jedem Teil eine konkrete Funktion zu.

CLAUDE.md und Memory

CLAUDE.md ist eine einfache Markdown-Datei, die Claude Code zu Beginn einer Session · engl. sessionEin einzelnes Gespräch mit einem Agenten: der Verlauf aller Nachrichten und Tool-Ergebnisse plus der Arbeitszustand. Endet das Gespräch, endet die Session.Im Glossar liest: Konventionen des Projekts, Build-Befehle, Hausregeln. Die Dateien bauen aufeinander auf. Es gibt eine Ebene für dich als Person (~/.claude/CLAUDE.md), eine für das Projekt (./CLAUDE.md oder ./.claude/CLAUDE.md), eine lokale (./CLAUDE.local.md) und eine, die eine Organisation zentral vorgibt. Dateien aus übergeordneten Ordnern lädt Claude Code beim Start, Dateien aus Unterordnern erst, wenn es dort arbeitet. Alle gefundenen Dateien werden aneinandergehängt.

Dazu kommt das automatische Memory · engl. memoryWissen, das ein Agent über mehrere Sessions hinweg behält. Es besteht aus extrahierten Fakten wie Vorlieben und Entscheidungen, die ein Modell aus Gesprächen herauszieht und mit dem Bestand abgleicht.Im Glossar. Darin hält Claude selbst Notizen zu deinen Korrekturen und Vorlieben fest, abgelegt unter ~/.claude/projects/<projekt>/memory/ mit einer Übersicht MEMORY.md. Pro Session lädt Claude Code die ersten 200 Zeilen oder 25 KB davon. Die Lehre daraus: Dauerhafte Anweisungen gehören in Dateien, die der Agent liest. Warum das besser funktioniert als ein riesiger Prompt, erklärt Context Engineering.

Hooks

Hooks sind Befehle, die an Ereignisse im Ablauf gebunden sind, etwa PreToolUse, PostToolUse, SessionStart oder PreCompact. Die Doku listet 33 solche Ereignisse (Stand: Nov. 2026). Hooks setzen Regeln durch. Ein PreToolUse-Hook kann einen gefährlichen Befehl bei jedem einzelnen Aufruf blockieren. Eine Anweisung im Prompt senkt nur die Wahrscheinlichkeit, dass das Modell ihn wählt. Als Faustregel gilt: Prompts für Urteile, Hooks für Regeln.

Prompt oder Hook?

Ordne jede Regel danach, ob sie ein Urteil verlangt (Prompt) oder ausnahmslos gelten muss (Hook).

Noch offen (6)

Nie Dateien unter .env lesen.
Nach jeder Änderung an Python-Dateien den Formatter laufen lassen.
Kleine, gut lesbare Commits bevorzugen.
Kein git push --force auf main.
Bei unklaren Anforderungen erst nachfragen.
Tests im Stil der vorhandenen Tests schreiben.

Prompt: Urteil (0)

Hook: Regel (0)

Subagents

Subagent · engl. subagentEin Agent, den ein anderer Agent für eine Teilaufgabe startet. Er arbeitet in einem eigenen Kontextfenster und gibt nur sein Ergebnis zurück.Im Glossar laufen in einem eigenen Kontextfenster mit eigenem Systemprompt, eigenen Tools und eigenen Berechtigungen. Der aufrufende Agent sieht nur die Zusammenfassung am Ende. Die Zwischenschritte bleiben im Kontext des Subagents. Das hält seinen Verlauf sauber und vervielfacht den Kontext, der insgesamt nutzbar ist. Du definierst Subagents als Markdown-Dateien mit Frontmatter in .claude/agents/ (Projekt) oder ~/.claude/agents/ (persönlich), oder im SDK über die Option agents.

Skills

Ein Skill · engl. skillEin Ordner mit einer Datei SKILL.md, die einem Agenten eine wiederkehrende Aufgabe beschreibt. Claude Code lädt den Skill, wenn die Aufgabe passt oder du ihn mit seinem Namen aufrufst.Im Glossar ist ein Ordner mit einer SKILL.md und optional Skripten und Vorlagen. Im Kontext steht dauerhaft nur die kurze Beschreibung jedes Skills. Den Inhalt lädt Claude Code erst, wenn er gebraucht wird. So holt sich der Agent Anweisungen bei Bedarf und ertrinkt nicht im eigenen Handbuch. Die Doku dazu: Agent Skills.

MCP

Claude Code ist ein Client für MCP · engl. Model Context ProtocolEin offenes Protokoll, über das ein Agent Tools aus externen Servern einbindet, etwa für GitHub, Slack oder eine Datenbank. Jeder Server bringt eigene Tool-Definitionen mit.Im Glossar. Externe Server steuern Tools bei, die neben den eingebauten stehen. Du richtest sie pro Projekt oder für dich persönlich ein. Diese Erweiterbarkeit ist mächtig und zugleich die größte Angriffsfläche für eingeschleuste Anweisungen. Die Lektion Tools und MCP behandelt beides.

Berechtigungen

Jeder Tool-Aufruf läuft durch eine Berechtigungsschicht. Regeln in settings.json erlauben, verbieten oder verlangen eine Rückfrage (allow, deny, ask). Dazu kommen sechs Modi, darunter plan als reiner Lesemodus und acceptEdits, das Dateiänderungen ohne Rückfrage zulässt. Mit /sandbox schaltest du eine Sandbox für Shell-Befehle ein, die das Betriebssystem durchsetzt. Unter macOS nutzt sie Seatbelt, unter Linux bubblewrap. Die Annahme dahinter: Das Modell tut gelegentlich etwas Unbedachtes, also hält der Harness die Bremse.

Headless und SDK

claude -p "Auftrag" läuft ohne Oberfläche, einmal durch, und eignet sich für Skripte und CI. Mit --output-format json bekommst du ein Ergebnis, das ein Programm auswerten kann. So sah unser Lauf in einem kleinen Demo-Ordner aus (Claude Code 2.1.323, Modell Haiku):

claude -p "Was macht dieses Projekt? Antworte in einem Satz." \
  --output-format json --model haiku --max-turns 5

type:           result
subtype:        success
num_turns:      3
result:         Das Projekt ist ein kleines Demo-Rechenmodul, dessen einzige
                Funktion summe(a, b) in rechne.py zwei Werte addiert.
total_cost_usd: 0.0095
duration_ms:    4493

Das Agent SDK geht weiter. Mit query() startest du einen Agenten aus deinem eigenen Programm, mit Hooks, Subagents, eigenen Tools als In-Process-MCP-Server und Sessions, die du später fortsetzt oder abzweigst. Für Gespräche über mehrere Runden in derselben Session gibt es im Python-SDK zusätzlich die Klasse ClaudeSDKClient, die auch Unterbrechungen erlaubt. Damit steckt der ganze Harness in deinem eigenen Programm.

Das folgende Skript gibt dem Agenten einen Hook mit, der jeden Shell-Befehl mit rm ablehnt. Getestet mit claude-agent-sdk 0.2.181:

import asyncio

from claude_agent_sdk import ClaudeAgentOptions, HookMatcher, ResultMessage, query


async def kein_rm(input_data, tool_use_id, context):
    befehl = input_data["tool_input"].get("command", "")
    if "rm " in befehl:
        return {"hookSpecificOutput": {
            "hookEventName": "PreToolUse",
            "permissionDecision": "deny",
            "permissionDecisionReason": "Löschen ist in diesem Projekt gesperrt.",
        }}
    return {}


async def main():
    options = ClaudeAgentOptions(
        model="haiku",
        allowed_tools=["Read", "Bash"],
        max_turns=6,
        hooks={"PreToolUse": [HookMatcher(matcher="Bash", hooks=[kein_rm])]},
    )
    async for message in query(prompt="Lösche die Datei rechne.py.", options=options):
        if isinstance(message, ResultMessage):
            print(message.result)
            print(f"{message.num_turns} Turns, {message.total_cost_usd:.4f} USD")


asyncio.run(main())

Der Hook blockiert (eigener Lauf, 13.11.2026, gekürzt)1/5

$python sdk_demo.py

Der Hook ist eine kleine Python-Funktion. Er entscheidet bei jedem Bash-Aufruf gleich, egal wie das Modell den Auftrag deutet. Die Prüfung auf "rm " ist bewusst grob und lässt sich umgehen. Wie ein ernsthaftes Berechtigungssystem aussieht, zeigt der Build Berechtigungen und Kontext.

Unsere Einschätzung

Nach unserer Einschätzung ist Claude Code der vollständigste Harness, den es 2026 fertig zu kaufen gibt. Seine Begriffe sind das Vokabular, an dem sich der Rest des Feldes misst, wie die Landschaft zeigt. Der Preis: Du übernimmst die Entscheidungen von Anthropic und den Appetit des Harness auf Tokens. Ein erster Lauf derselben Ein-Satz-Frage las über 160.000 Tokens Eingabe, gut die Hälfte davon aus dem Cache. Für die meisten Teams ist das ein guter Tausch.

Merksätze

CLAUDE.md und Memory halten dauerhafte Anweisungen in Dateien, die in Ebenen aufeinander aufbauen.
Hooks setzen Regeln bei jedem Aufruf durch, Prompts verlangen ein Urteil.
Subagents arbeiten in eigenem Kontext, Skills laden Anweisungen erst bei Bedarf.
Berechtigungen kommen aus Regeln, sechs Modi und einer Sandbox für Shell-Befehle.
Das Agent SDK bringt denselben Harness in dein Programm, mit query() als Einstieg.

Prüf dich selbst

Denkfrage

Warum gehört „nie .env lesen“ in einen Hook und nicht nur in CLAUDE.md?

Denkfrage

Was gewinnt ein Agent, wenn er eine Recherche an einen Subagent abgibt?

Quellen

Agent SDK overview · Anthropic, Stand: Nov. 2026
Gleicher Loop, gleiche Tools, Python und TypeScript.
Manage Claude’s memory · Anthropic, Stand: Nov. 2026
Ebenen von CLAUDE.md, automatisches Memory.
Hooks reference · Anthropic, Stand: Nov. 2026
33 Ereignisse, Blockieren mit PreToolUse.
Subagents · Anthropic, Stand: Nov. 2026
Eigener Kontext, eigene Tools, nur die Zusammenfassung zurück.
Agent Skills · Anthropic, Stand: Nov. 2026
Beschreibung im Kontext, Inhalt bei Bedarf.
Permissions · Anthropic, Stand: Nov. 2026
allow, ask, deny und die Modi.
Sandboxing · Anthropic, Stand: Nov. 2026
Sandbox für Shell-Befehle, Seatbelt und bubblewrap.
Run Claude Code programmatically · Anthropic, Stand: Nov. 2026
claude -p und --output-format json.