Der Coding Harness verstehen

Wie Claude Code Werkzeuge sicher ausführt, Ausführungen isoliert und Berechtigungen verwaltet

Hintergrund: Claude Code Architektur

Claude Code ist eine Umgebung, in der Claude mit deinem System interagieren kann — Dateien lesen, Befehle ausführen, APIs aufrufen und mehr. Aber Claude läuft in der Cloud. Dein System ist lokal. Wie führt Claude tatsächlich Code auf deinem Computer sicher aus?

Die Antwort ist der Claude Code Harness: ein Runtime-Manager, der zwischen Claudes Entscheidungen und deinen Systemressourcen sitzt. Stelle dir ihn als sorgfältigen Wächter vor.

Der Harness ist nicht neue Infrastruktur, die du aufbauen musst. Er ist bereits Teil von Claude Code. Deine Aufgabe ist, seine Grenzen zu verstehen und seine Berechtigungen zu konfigurieren.

Ohne Harness gäbe es drei Optionen: Entweder Claude könnte alles tun (gefährlich), Claude könnte nichts tun (nutzlos), oder jemand müsste jeden Befehl manuell genehmigen (mühsam). Der Harness automatisiert die Frage „wer entscheidet, was erlaubt ist" mit einer Konfigurationsebene.

Intuition: Was ist ein Harness?

Stelle dir vor, du stellst einen Handwerker ein, um dein Haus zu reparieren. Du würdest ihm nicht unbegrenzten Zugang geben — du würdest sagen „du kannst die Küche, den Flur und das Badezimmer benutzen; du kannst aber nicht ins Schlafzimmer". Diesen Regeln-Satz ist ein Harness.

Der Handwerker (Claude) entscheidet, welche Arbeit zu tun ist (den Wasserhahn reparieren). Der Harness (deine Regeln) entscheidet, ob diese Arbeit erlaubt ist (ja, wenn der Wasserhahn in der Küche ist). Wenn der Handwerker versucht, das Schlafzimmer zu streichen (nicht erlaubt), stoppt der Harness das.

Hier ist ein konkretes Beispiel:

// Claude entscheidet: „Ich lese die Konfigurationsdatei"
const content = await bash('cat /src/config.json');

// Harness prüft: „Ist /src lesbar?"
// Harness-Konfiguration sagt: „Ja, /src ist lesbar"
// Ergebnis: Harness erlaubt es, gibt Dateiinhalt zurück

// Claude entscheidet: „Ich lösche das System-Verzeichnis"
const result = await bash('rm -rf /etc');

// Harness prüft: „Ist /etc schreibbar?"
// Harness-Konfiguration sagt: „Nein, /etc ist nicht schreibbar"
// Ergebnis: Harness blockiert es, gibt Permission Denied zurück

Das ist die Kernidee: Claude schlägt Aktionen vor, der Harness erzwingt Richtlinien.

Die drei Arten von Tools

Der Harness verwaltet drei Arten von Operationen:

Tool-Typ Beispiel Was der Harness kontrolliert
Bash bash('ls -la /home') Welche Verzeichnisse lesbar/schreibbar sind, welche Befehle erlaubt sind
MCP Server invokeToolViaAgent('github') Welche MCP-Server erreichbar sind, welche Tool-Parameter erlaubt sind
Datei I/O read('/src/file.txt') Welche Pfade gelesen, welche geschrieben werden können, Dateigrößen-Limits

Alle drei fließen durch die gleiche Harness-Durchsetzung: Anfrage → Permission-Check → Ausführung → Output sammeln → Filtern → Ergebnis zurückgeben.

Verantwortung: Harness vs. Claude

Das ist das wichtigste Konzept. Der Harness und Claude haben unterschiedliche Aufgaben.

Claude entscheidet WAS. Welches Tool aufzurufen. Welche Parameter zu übergeben. Ob das Ziel sinnvoll ist.
Harness entscheidet OB und WIE. Ob diese Aktion erlaubt ist. In welcher Sandbox es laufen soll. Wie seine Effekte isoliert werden.

Szenario-Beispiel: Claude möchte ein Paket installieren.

Claudes Entscheidung: „Dieses Projekt braucht die 'express' Library. Ich führe npm install express aus"
Harness-Entscheidung: „Darf npm laufen? Kann es in node_modules schreiben? Ist das Internet verfügbar? Timeout ist 60s."

Zwei Möglichkeiten:

1. Konfiguration erlaubt npm, node_modules ist schreibbar:
   → Harness: „Erlaubt. Hier ist das Ergebnis."
   → Claude: „Großartig, jetzt kann ich express nutzen"

2. Konfiguration verbietet npm:
   → Harness: „Permission denied: npm ist nicht in der Allowlist"
   → Claude: „Ah, ich kann npm hier nicht nutzen. Lass mich einen anderen Weg versuchen"
Häufiges Missverständnis: „Wenn der Harness etwas blockiert, weiß Claude nicht warum." Falsch. Claude erhält einen strukturierten Fehler: {success: false, error: "PermissionError", message: "npm nicht in Allowlist"}. Claude kann dann eine andere Entscheidung treffen.

Diese Aufteilung der Verantwortung ist, warum Claude Code sowohl mächtig als auch sicher sein kann. Claude hat die Intelligenz, um Probleme zu lösen. Der Harness hat die Richtlinie, um Schaden zu verhindern.

Das Permission-Modell

Der Harness erfindet die Autorisierung nicht neu. Er verwendet ein einfaches Allowlist + Blocklist Modell für jede Art von Ressource.

Harness-Permission-Schichten
Datei I/O

/src ✓ lesbar
/etc ✗ schreibbar
/tmp ✓ lesen/schreiben

Tool-Ausführung

bash ✓ erlaubt
docker ✗ blockiert
npm ✓ erlaubt

Netzwerk

localhost ✓ erlaubt
api.example.com ✓ erlaubt
* ✗ standardmäßig blockiert

Wie Permission-Checking funktioniert

Wenn Claude eine Anfrage macht, führt der Harness eine Reihe von Checks in Ordnung durch. Erste Treffer gewinnt.

ANFRAGE: bash('cat /src/readme.md')

CHECKS:
1. Ist 'bash' in der Tool-Allowlist? → JA
2. Ist '/src' lesbar? → JA
3. Irgendwelche Umgebungs-Einschränkungen? → NEIN
4. Timeout OK (120s)? → JA

ERGEBNIS: Permission gewährt. Befehl ausführen.

Wenn ein Check fehlschlägt, wird die Anfrage verweigert:

ANFRAGE: bash('docker run ubuntu')

CHECKS:
1. Ist 'bash' in der Tool-Allowlist? → JA
2. Irgendwelche Umgebungs-Einschränkungen? → NEIN
3. Timeout OK (120s)? → JA

ERGEBNIS: Permission gewährt. Bash ausführen.

ABER DANN:

SUBPROCESS-CHECK: bash versucht 'docker' auszuführen
1. Ist 'docker' in der Tool-Allowlist? → NEIN

ERGEBNIS: Permission denied. Bash gibt Fehler zurück.
Wichtig: Der Harness prüft Tool-Invokation, aber auch, was innerhalb dieser Invokation passiert. Wenn du bash('rm -rf /etc') ausführst und der Harness /etc-Schreibvorgänge blockiert hat, wird das Dateisystem es verweigern — doppelter Schutz.

Fehler-Isolierung & Resilienz

Hier verdient der Harness seinen Lohn: Wenn etwas fehlschlägt, schlägt nur diese Operation fehl. Der Harness läuft weiter.

Ohne Harness könnte Claude, wenn er einen schlechten Befehl ausführt, die ganze Sitzung zum Crash bringen. Mit Harness erhält Claude einen strukturierten Fehler und kann entscheiden, was als Nächstes zu tun ist.

SZENARIO 1: Permission Denied
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Claude: „Lese /root/secret.txt"
Harness: „Permission denied: /root nicht lesbar"
Claude: „OK, ich lese /home stattdessen"
Harness: „OK, hier ist /home/file.txt"
→ SITZUNG LÄUFT WEITER

SZENARIO 2: Tool Timeout
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Claude: „Führe npm install aus (großes Projekt)"
Harness: [ausführen...]
Nach 120s: „Timeout: npm hat nicht rechtzeitig fertig gemacht"
Claude: „Ich versuche es mit --legacy-peer-deps"
Harness: „OK, versuchen wir es nochmal"
→ SITZUNG LÄUFT WEITER

SZENARIO 3: Befehl fehlgeschlagen
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Claude: „Baue das Projekt"
Bash: „Build fehlgeschlagen: Syntax-Fehler in src/main.js"
Harness: „Tool fehlgeschlagen mit Exit-Code 1. Hier ist stderr."
Claude: „Ich habe den Fehler gefunden. Lass mich ihn beheben."
→ SITZUNG LÄUFT WEITER

Der Schlüssel ist, dass Fehler Daten sind, keine Crashes. Der Harness gibt strukturierte Fehler zurück:

{
  success: false,
  error: "PermissionError",
  message: "Datei nicht lesbar: /etc/passwd",
  toolName: "bash",
  exitCode: 1,
  stderr: "bash: /etc/passwd: Permission denied",
  timestamp: "2026-08-17T14:30:00Z"
}

Claude sieht diese strukturierte Antwort und passt sich an. Das ist Resilienz durch Design.

Warum das wichtig ist: Ohne Fehler-Isolierung könnte ein einzelner schlechter Befehl deine ganze Sitzung blockieren. Mit dem Harness kann Claude versuchen, fehlschlagen, lernen und erneut versuchen. Das ist der Unterschied zwischen einem Werkzeug und einem Gewicht.

Konfiguration & Best Practices

Der Harness wird über deine Projekt-Datei .claude/settings.json oder .claude/settings.local.json konfiguriert. Du kontrollierst, was erlaubt ist.

Principle of Least Privilege

Die goldene Regel: Gewähre die minimalen Berechtigungen, die Claude braucht, um die Arbeit zu tun. Nicht mehr, nicht weniger.

Häufiger Fehler: „Lass mich einfach alles erlauben." Mach das nicht. Enge Berechtigungen zwingen dich, darüber nachzudenken, was Claude wirklich braucht. Wenn Claude etwas nicht tun kann, ist das Information — vielleicht soll es das gar nicht tun.

Konfiguration-Beispiel

// .claude/settings.json
{
  "permissions": {
    "bash": ["enabled"],
    "allowedTools": ["bash", "npm"],
    "fileAccess": {
      "read": ["/src", "/docs"],
      "write": ["/tmp", "/src/dist"],
      "deny": ["/etc", "/root", "/home"]
    },
    "network": {
      "allow": ["api.github.com", "registry.npmjs.org"],
      "deny": ["*"]
    },
    "timeouts": {
      "bash": 120,
      "mcp": 30,
      "fileIo": 10
    }
  }
}

Was das bewirkt:

Wenn Claude auf eine Permission-Grenze trifft

Das ist normal und nützlich. Claude sieht einen Fehler wie:

Error: Permission denied: docker not in allowlist

Claudes nächste Überlegung: „Ich kann docker nicht ausführen. Lass mich versuchen,
mit npm zu bauen stattdessen, oder frag den Nutzer, ob er docker
aktivieren möchte, wenn er Container-Builds will."

Das ist der Harness, der wie beabsichtigt funktioniert. Einschränkungen sind Merkmale, keine Fehler.

Quiz: Teste dein Verständnis

Diese Fragen prüfen, ob du die Kernkonzepte verstanden hast. Lies sorgfältig — jede Frage hat eine richtige Antwort und einen Grund dafür.

1. Claude möchte eine Datei löschen. Der Harness erlaubt bash, blockiert aber Schreibvorgänge auf /etc. Was passiert?
2. Was ist die primäre Verantwortung des Harness?
3. Claude führt einen bash-Befehl aus, der fehlschlägt. Was macht der Harness?
4. Deine Harness-Konfiguration verbietet docker, erlaubt aber bash. Claude versucht 'docker build' auszuführen. Was passiert?
5. Warum ist „Principle of Least Privilege" wichtig für die Harness-Konfiguration?