Eigenes Agent-Harness bauen und optimieren

Ein Coding-Agent wird dann teuer und zickig, wenn sein Kontext unstrukturiert wächst. Die Hebel dagegen sind einfach: wenig dauerhaft geladener Text, viel on-demand Wissen, klare Regeln für Tools.

CLAUDE.md: kurz und konkret

Die Projekt-Datei CLAUDE.md (oder .claude/CLAUDE.md) wird in jede Session geladen. Zusätzlich liest der Agent ~/.claude/CLAUDE.md als persönliche Ebene und CLAUDE.local.md als private, nicht commitete Variante. Alle Dateien werden kaskadiert, nicht überschrieben.

Regeln für guten Inhalt:

• Unter 200 Zeilen bleiben. Alles, was nur manchmal gebraucht wird, gehört in Skills, nicht hierher.
• Konkret statt vage: "Nutze 2-Space-Einrückung" wirkt, "Schreibe sauberen Code" wirkt nicht.
• Mit @pfad/datei.md lassen sich weitere Dateien importieren (maximal 4 Ebenen tief).
• In größeren Projekten: .claude/rules/*.md mit Pfad-Filter - die laden nur, wenn passende Dateien im Spiel sind.

Skills: Wissen nur bei Bedarf

Ein Skill ist ein Ordner mit einer SKILL.md (YAML-Frontmatter plus Markdown), privat unter ~/.claude/skills/<name>/ oder projektbezogen unter .claude/skills/<name>/. Wichtigste Frontmatter-Felder sind name und description: die Beschreibung ist immer im Kontext, der Body erst, wenn der Skill passt oder per /skill-name aufgerufen wird.

So bleibt der Grundkontext klein, obwohl viel Wissen bereitliegt. Faustregeln: SKILL.md unter 500 Zeilen, Referenzmaterial in eigene Dateien neben die SKILL.md legen, Deploy- oder Test-Abläufe als eigene Skills versionieren. Ein eigener Skill lohnt sich, sobald du eine Prozedur zum dritten Mal im Prompt erklärst.

Subagenten und Modell-Routing

Subagenten (Markdown mit Frontmatter unter .claude/agents/*.md oder ~/.claude/agents/) haben ein eigenes Kontextfenster; nur ihr Ergebnis landet im Hauptkontext. Das entlastet die Session bei Suchen, langen Logs oder Test-Läufen.

Der große Kostenhebel ist das Modell-Feld im Frontmatter: model: haiku für Triviales (Datei suchen, Format prüfen), model: sonnet für Normalsachen, model: opus nur für Architektur und harte Bugs. In der Session wechselt /model live; --model setzt beim Start.

Token sparen, ohne Kontrolle zu verlieren

• Zwischen unabhängigen Aufgaben /clear statt /compact: Der Neustart ist gratis, /compact ist selbst ein großer Request.
• Mit /context sehen, was den Kontext fressen hat; mit /usage Kosten und Cache-Quote prüfen.
• Output-Filter: Ein PreToolUse-Hook darf langläufige Befehle umbauen, etwa Testläufe auf grep -E "(FAIL|ERROR)" | head -100 reduzieren. Aus zehntausenden Tokens Ausgabe werden Hunderte.
• Ungenutzte MCP-Server in /mcp deaktivieren: jede Tool-Definition kostet Kontext.

Hooks und Absicherung

Hooks stehen in settings.json und hängen Shell-Befehle an Lebenszyklus-Ereignisse: PreToolUse (prüfen oder blockieren, exit 2 blockt), PostToolUse, UserPromptSubmit, Stop. Typische Nutzung: gefährliche Befehle ablehnen, Linter nach jedem Edit laufen lassen, am Session-Ende Status melden.

Laufen mehrere Agenten parallel an denselben Dateien, brauchst du ein Lock-Muster: vor der Arbeit an geteilten Ressourcen ein Lock-File mit Zeitstempel und Beschreibung anlegen (z. B. in einem zentralen Verzeichnis), am Ende freigeben, mit einer TTL als Rettungsanker falls ein Agent crasht. Das verhindert die klassische Falle, dass zwei Agenten dieselbe Datei überschreiben.

MCP einbinden

Externe Werkzeuge kommen über das Model Context Protocol: claude mcp add --transport http <name> <url> für HTTP-Server, claude mcp add <name> -- <command> für lokale Prozesse (das -- ist Pflicht). Im Projekt-Root sorgt .mcp.json mit Scope project dafür, dass das Team dieselben Server bekommt. Lieber wenige, gut gewählte Server als ein Vollzeit-Firehose.