Harness Engineering: KI-Agenten nach dem Vorbild von Claude Code bauen

Die Idee „schreib einen guten Prompt und die KI erledigt den Rest“ reicht für brauchbare Agenten nicht mehr. Entscheidend wird Harness Engineering: das Gerüst um das Modell herum. Wer aus dem Testing den Begriff test harness kennt, kann sich die Agenten-Version so vorstellen: Tools, Kontext, Berechtigungen, Verifikation und eine Kontrollschleife rund um das LLM.

Claude Code ist dafür ein gutes Vorbild, weil es weit mehr als ein Chatfenster ist. Es kombiniert Dateiwerkzeuge, Shell-Kommandos, CLAUDE.md, Hooks, Permission Modes, Subagents und Memory. Dieser Leitfaden erklärt, warum Harness Engineering im Trend liegt, wie ein Mini-Harness in Node.js mit Policy JSON funktioniert und wie man das Muster für content automation, code review, SaaS integration, cloud operations und security boundaries nutzt.

Warum Harness Engineering Wichtig Wird

Ein LLM kann gut entscheiden, was als Nächstes passieren soll. Reale Arbeit verlangt aber mehr: Workspace lesen, Kontext auswählen, Tools ausführen, Fehler behandeln, riskante Aktionen begrenzen und beweisen, dass das Ergebnis funktioniert. Diese äußere Betriebsschicht ist der Harness.

Die Claude Agent SDK Dokumentation beschreibt, dass Claude-Code-artige Features wie project instructions, skills, hooks und permissions geladen werden können. Die Permissions-Dokumentation erklärt allow rules, deny rules, permission modes und runtime callbacks. Prompt Caching zeigt, wie langer statischer Kontext wiederverwendet wird. Das alles ist Engineering um das Modell herum.

Der OODA Loop macht die Rollen klar:

Phase	Inhalt	Verantwortlich
Observe	Dateien, Logs, URLs, Tickets, API-Zustände lesen	Harness
Orient	Kontext ordnen und komprimieren	Harness
Decide	nächste Aktion wählen	LLM
Act	Tool ausführen, Datei schreiben, API aufrufen	Harness

Drei von vier Phasen liegen größtenteils beim Harness. Ein starkes Modell mit schwachem Gerüst ergibt trotzdem einen schwachen Agenten.

Was In Einen Harness Gehört

Ein praktischer Harness beantwortet vor dem Start vier Fragen: Was darf der Agent lesen, welches Artefakt soll entstehen, welche Checks beweisen Erfolg und welche Aktionen sind automatic, ask-first oder forbidden?

In einem Blog-Workflow bedeutet das nicht nur „schreibe einen Artikel“. Der Harness liest bestehende Slugs, wählt ein nicht dupliziertes Thema, schreibt MDX, prüft Frontmatter, validiert Code Fences, fügt offizielle und interne Links ein, setzt CTAs zu /products/ und /training/, baut die Site und prüft die öffentliche URL.

Schicht	Beispiel	pitfall
Kontext	Projektregeln, Stil, alte Fehler	veraltete Annahmen bleiben aktiv
Tools	read, grep, write, test, API call	zu viele Tools verwirren das Modell
Policy	allow, ask, deny, sandbox	destruktive Aktion läuft unbeaufsichtigt
Verifikation	test, diff, screenshot, public URL	Output wirkt plausibel, ist aber kaputt
Memory	wiederverwendbare Präferenzen	temporäre Notiz wird Dauerregel

Konzeptdiagramm

Der Harness ist die Kontrollschicht vor und nach dem Modell. Der Prompt zählt, aber policy, context, tools, permission gate und verification loop entscheiden, ob der workflow belastbar ist.

flowchart LR
  A["Goal"] --> B["Harness policy"]
  B --> C["Context"]
  B --> D["Tools"]
  B --> E["Permissions"]
  C --> F["LLM decision"]
  D --> F
  E --> G["Safe action"]
  F --> G
  G --> H["Verification"]
  H --> I["Artifact"]
  H --> B

Lauffähiger Node.js Mini-Harness

Dieses Beispiel ist klein, aber vollständig: Modell, zwei Tools, Policy, Loop, Pfadgrenze und lesbare Fehler. Setze vorher ANTHROPIC_API_KEY.

mkdir harness-demo
cd harness-demo
npm init -y
npm install @anthropic-ai/sdk
node -e "const fs=require('node:fs');fs.mkdirSync('sandbox',{recursive:true});fs.writeFileSync('sandbox/README.md','# Demo\nShip a safer agent workflow.\nKeep writes inside sandbox.\n');"

Speichere policy.json.

{
  "workspace": "./sandbox",
  "maxSteps": 6,
  "tools": {
    "read_file": {
      "allow": true,
      "risk": "Read UTF-8 text only inside workspace"
    },
    "write_file": {
      "allow": true,
      "risk": "Write UTF-8 text only inside workspace"
    }
  }
}

Speichere mini-harness.mjs.

import Anthropic from "@anthropic-ai/sdk";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import path from "node:path";

const client = new Anthropic();
const policy = JSON.parse(await readFile(new URL("./policy.json", import.meta.url), "utf8"));
const model = process.env.ANTHROPIC_MODEL || "claude-sonnet-4-6";
const workspace = path.resolve(policy.workspace);

function safePath(requestedPath) {
  const resolved = path.resolve(workspace, requestedPath);
  const inside = resolved === workspace || resolved.startsWith(workspace + path.sep);
  if (!inside) {
    throw new Error(`Path escapes workspace: ${requestedPath}. Use a path under ${policy.workspace}.`);
  }
  return resolved;
}

function ensureAllowed(toolName) {
  const rule = policy.tools?.[toolName];
  if (!rule?.allow) {
    throw new Error(`Tool '${toolName}' is not allowed by policy.json.`);
  }
}

const tools = [
  {
    name: "read_file",
    description: "Read a UTF-8 text file from the allowed workspace.",
    input_schema: {
      type: "object",
      properties: { path: { type: "string" } },
      required: ["path"],
      additionalProperties: false
    }
  },
  {
    name: "write_file",
    description: "Write a UTF-8 text file inside the allowed workspace.",
    input_schema: {
      type: "object",
      properties: {
        path: { type: "string" },
        content: { type: "string" }
      },
      required: ["path", "content"],
      additionalProperties: false
    }
  }
];

async function executeTool(name, input) {
  ensureAllowed(name);
  if (name === "read_file") {
    return await readFile(safePath(input.path), "utf8");
  }
  if (name === "write_file") {
    const target = safePath(input.path);
    await mkdir(path.dirname(target), { recursive: true });
    await writeFile(target, input.content, "utf8");
    return `written ${input.path}`;
  }
  throw new Error(`Unknown tool: ${name}`);
}

async function run(goal) {
  const messages = [{ role: "user", content: goal }];

  for (let step = 0; step < policy.maxSteps; step++) {
    const response = await client.messages.create({
      model,
      max_tokens: 1200,
      tools,
      system: "You are a careful file assistant. Use tools when needed. Keep writes under policy workspace.",
      messages
    });

    messages.push({ role: "assistant", content: response.content });
    const toolUses = response.content.filter((block) => block.type === "tool_use");

    if (toolUses.length === 0) {
      const text = response.content
        .filter((block) => block.type === "text")
        .map((block) => block.text)
        .join("\n");
      console.log(text);
      return;
    }

    const results = [];
    for (const toolUse of toolUses) {
      try {
        const output = await executeTool(toolUse.name, toolUse.input);
        results.push({ type: "tool_result", tool_use_id: toolUse.id, content: String(output).slice(0, 8000) });
      } catch (error) {
        results.push({
          type: "tool_result",
          tool_use_id: toolUse.id,
          is_error: true,
          content: error instanceof Error ? error.message : String(error)
        });
      }
    }
    messages.push({ role: "user", content: results });
  }

  throw new Error(`Max steps reached: ${policy.maxSteps}`);
}

const goal = process.argv.slice(2).join(" ") || "Read README.md and write summary.md with three bullet points.";
await run(goal);

Starte:

node mini-harness.mjs

Schon dieses kleine Beispiel enthält das Kernmuster: Tool Schema, Policy, Sandbox, Schrittlimit, hilfreiche Fehler und ein prüfbares Artefakt. Mit grep, Tests, Approval UI, SaaS APIs und Hooks nähert man sich Claude Code an.

Fünf Konkrete Use Cases

1. content automation Ein schwacher Prompt sagt „schreibe einen Artikel“. Ein starker Harness liest alte Posts, vermeidet doppelte Themen, schreibt MDX, validiert Frontmatter und Code Fences, fügt offizielle und interne Links ein, setzt CTAs zu /products/ und /training/, führt Build aus und prüft die public URL. Der pitfall ist, schnelle, dünne Übersetzungen zu veröffentlichen.

2. code review Ein Review Harness liest git diff, Testergebnisse, geänderte Dateien und lokale Regeln. Die Antwort muss findings-first sein: Bugs, risk, Regressionen und fehlende Tests vor der Zusammenfassung. Das Risiko ist, dass das Modell nur die Änderung beschreibt.

3. SaaS integration Bei Notion, HubSpot, Stripe oder CRM müssen read-only lookup, dry-run mutation und approved write getrennt sein. Leads dürfen klassifiziert und Updates vorbereitet werden, aber echte Writes brauchen Zustimmung. Der pitfall ist eine falsche Kunden- oder Billing-Änderung in Produktion.

4. cloud operations Cloud-Betrieb ist mehr als deploy. Der Harness prüft Environment Variables, Build, Diff, Target, Rollback, Health Endpoint und public URL. Der risk ist, die letzte Logzeile zu reparieren statt die Ursache.

5. security boundaries Security boundaries gehören an den Anfang. Read darf breiter sein, Write bleibt im Workspace. Shell-Kommandos brauchen eine Allow-List. rm, Force Push, Produktionsdatenbank, Billing und Secrets gehören zu deny oder ask-first. Harness schützt vor übermäßigem Vertrauen.

Was Man Von Claude Code Übernimmt

Erstens: Kontext schichten. Stabile Regeln gehören in CLAUDE.md, Sitzungsfortschritt in den Plan, dauerhafte Präferenzen in Memory.

Zweitens: Deterministische Checks in Hooks verschieben. Format, Lint, Tests, Link Checks und Screenshots laufen als Commands. Claude interpretiert Fehler und korrigiert.

Drittens: Lärm isolieren. Lange Logs, breite Suche, mehrsprachige Übersetzungen und große Refactorings passen besser in Subagents oder getrennte Workflow-Stufen.

Häufige Pitfalls

Zu viele Tools senken die Genauigkeit. Starte mit 5 bis 10 klaren Tools.

Unlesbare Fehler verhindern Self-Repair. Statt Error: failed sollte die Meldung erklären, was fehlt und was als Nächstes möglich ist.

Ohne Prompt Caching werden lange statische Instruktionen immer wieder gesendet. Trenne statischen und dynamischen Kontext.

Ohne Verifikation kann schöner Output Produktion brechen. Artikel brauchen Frontmatter- und Code-Fence-Checks, Code braucht Tests, Cloud braucht Health Checks, SaaS braucht Audit Logs.

Permissions driften leicht. Allow, ask und deny müssen regelmäßig geprüft werden.

Nächster Schritt

Für Sicherheit zuerst lies den Claude Code Permissions Guide. Für Projektkontext nutze CLAUDE.md Best Practices. Für schwere Aufgaben lies Claude Code Subagent Patterns. Für Kostenkontrolle hilft Claude Code Token Optimization.

Als schnelle Referenz lohnt sich das Claude Code Quick Reference Cheatsheet. Templates und Playbooks findest du unter /products/. Wenn dein Team Permissions, Review Gates, Verifikation, Publishing und Revenue Workflow gemeinsam designen muss, starte bei /training/.

Was Ich Geprüft Habe

Im ClaudeCodeLab-Workflow ist der größte Wert des Harness, Fehler sichtbar zu machen. Ein Prompt kann einen Artikel erzeugen; ein Harness prüft Tiefe, Code Fences, Frontmatter, Links, CTAs und public URL. Damit vertraut man nicht blind dem Output, sondern betreibt einen Workflow mit echten Gates.

Zusammenfassung

Harness Engineering entscheidet, was das Modell sehen darf, was es tun darf, wo es stoppt und wie das Ergebnis verifiziert wird. Claude Code ist ein starkes Beispiel, weil der Wert nicht nur im Modell liegt, sondern im Scaffold darum herum. Führe den Mini-Harness oben aus und ergänze für deinen Use Case eine Boundary und einen Check.

Referenzen

• Claude Agent SDK: Claude Code features
• Claude Agent SDK permissions
• Claude Agent SDK hooks
• Claude API models overview
• Prompt caching