Coding Harness erklärt

Der Harness ist die Laufzeitumgebung hinter Claude Code. Er orchestriert Werkzeugaufrufe, isoliert Ausführungen, kontrolliert Permissions und verwaltet Output. Entwickler definieren seine Grenzen durch Konfiguration — sie sehen ihn nie direkt.

Kernaufgaben

Werkzeuge in Sandbox ausführen
Datei- und Netzwerk-Zugriffe kontrollieren
Output puffern, filtern, maskieren
Events und Hooks verarbeiten
Fehler isolieren (non-fatal)

Kernkonzept

Harness ≠ Code. Der Harness ist die Infrastruktur um deinen Code. Claude entscheidet was ausgeführt wird. Der Harness entscheidet wie und unter welchen Bedingungen.

Architektur: Vom Tool-Aufruf zum Output

So fließt eine Anfrage durch den Harness

Was der Harness IST — und definitiv NICHT

✓ Harness IST

Prozess-Isolations-Engine
Permission & Sandbox Manager
Event-Loop für Tool-Calls
Error Handler (non-fatal)
Output Buffer & Filter
Lifecycle Hooks & Callbacks

✗ Harness ist NICHT

Ein LLM oder AI-Model
Dein Code oder Skripte
Ein Compiler/Interpreter
Ein Web-Server oder Framework
Ein Datenspeicher (no state)
Ein CI/CD oder Deployment Tool

In der Praxis: 3 Szenarien

Bash-Befehl ausführen

Claude möchte eine Datei lesen. Der Harness fängt den bash-Aufruf ab, verifiziert Permissions, führt ihn in Sandbox aus, puffert Output und gibt Ergebnis zurück.

// Claude ruft auf:
const result = await bash('cat /src/file.txt');

// Harness verarbeitet:
// 1. Permission: /src readable? ✓
// 2. Sandbox: isolate with limited $PATH
// 3. Execute: bash "cat /src/file.txt"
// 4. Buffer: stdout → "file contents"
// 5. Filter: remove secrets (API keys, tokens)
// 6. Return: {success: true, stdout, stderr, exitCode}

// Claude erhält:
// {
//   success: true,
//   stdout: "file contents here...",
//   stderr: "",
//   exitCode: 0
// }

MCP Server Tool aufrufen

Claude ruft ein Tool auf einem Remote MCP-Server auf. Der Harness managt die Connection, validiert das Schema und verarbeitet die Response.

// Claude ruft auf:
const result = await invokeToolViaAgent('github-mcp', {
  name: 'create_issue',
  params: { title: 'Bug', body: '...' }
});

// Harness verarbeitet:
// 1. Connection: MCP server ready?
// 2. Schema: tool exists & params valid?
// 3. Request: send via protocol
// 4. Timeout: 30s limit
// 5. Response: parse JSON
// 6. Error handling: MCP-error ≠ Harness-error
// 7. Return structured result

// Claude erhält:
// {
//   success: true,
//   data: { issue_id: 12345, url: "..." },
//   toolName: "create_issue",
//   executionTime: 245
// }

Fehlerbehandlung

Wenn ein Tool fehlschlägt, isoliert der Harness den Fehler und rapportiert ihn strukturiert, ohne den Gesamtprozess zu stoppen.

// Claude ruft auf:
const result = await bash('rm -rf /etc/passwd');

// Harness verarbeitet:
// 1. Permission: /etc writable? ✗
// 2. Sandbox blocks: operation denied
// 3. Capture: error message
// 4. Isolate: don't crash harness
// 5. Return structured error

// Claude erhält:
// {
//   success: false,
//   error: "PermissionError",
//   message: "Permission denied: /etc/passwd",
//   stderr: "rm: cannot remove '/etc/passwd'",
//   exitCode: 1,
//   toolName: "bash",
//   timestamp: "2026-08-17T..."
// }

// ➤ Claude sees failure, can retry or handle gracefully
// ➤ Harness continues running (resilient)

Häufige Missverständnisse

Mythos #1

"Harness macht die KI-Entscheidungen."

Realität: Harness ist pure Infrastruktur. Claude wählt welches Tool und mit welchen Parametern. Der Harness wählt ob und wie es ausgeführt wird (Sandbox, Permissions, Timeout). Zwei völlig unterschiedliche Verantwortungen.

Mythos #3

"Harness erlaubt dir, alles zu tun."

Realität: Harness ist ein Zugangskontrolleur. Er blockiert Tools, Dateipfade, Netzwerk-Ziele und Environment-Variablen ohne explizite Permission. Deine Fähigkeiten sind genau so breit wie die Konfiguration erlaubt — nicht breiter.

Referenz: Was der Harness kontrolliert

Ubersicht über die Kontrollpunkte des Harness

Bereich	Wer kontrolliert	Beispiel
File I/O	Harness (via Permissions)	`Read /src` ✓, `Write /etc` ✗
Tool Execution	Harness (via Allowlist)	`bash` enabled, `docker` disabled
Network	Harness (via Firewall)	Local nur `localhost`, Remote: `api.example.com`
Environment	Harness (Isolation)	Keine $HOME, $USER. Nur whitelisted vars.
Timeouts	Harness (Default)	Bash: 120s, MCP: 30s, File I/O: 10s
Output Filtering	Harness (Pipeline)	API keys, tokens, passwords automatisch gemask
Error Isolation	Harness (Handler)	Tool-Fehler stoppen nicht die Harness-Loop

Best Practice

Konfiguriere Permissions nach Principle of Least Privilege — eng, nicht breit. Wenn ein Tool nicht in der Allowlist steht: Es gibt einen Grund. Frage nach, statt zu forcen.