Agent-Harness-Engineering mit Claude: 14-Schritte-Roadmap vom einzelnen Agenten zum selbstoptimierenden System.

Alle reden über Loops. Fast niemand spricht darüber, worauf der Loop läuft. 9 von 10 Entwicklern lassen Claude Code mit dem Standard-Harness laufen – ohne Regeln, ohne Sub-Agents, ohne Hooks, ohne Gedächtnis.

Dann wundern sie sich, warum ihr Loop nur Schrott produziert. Die Wahrheit ist einfach: Ein Loop ist nur so gut wie der Harness, der darunter liegt. Dies ist die 14-Schritte-Roadmap zum Harness – von einem einzelnen Agenten zu einem System, das sich selbst verbessert.

Folge meinem Substack für frische KI-Alpha:

movez.substack.com

Loop Engineering – der Aufbau eines Systems, das den Agenten nach einem Zeitplan promptet – hat diesen Monat die ganze Aufmerksamkeit bekommen. Aber Addy Osmani, der den ausführlichen Artikel über Loops geschrieben hat, hat sorgfältig auf das hingewiesen, was darunter liegt:

„Loop Engineering sitzt eine Etage über dem Harness. Der Harness ist die Umgebung, in der ein einzelner Agent läuft. Der Loop ist der Harness, aber er läuft auf einem Timer, erzeugt Helfer und füttert sich selbst.“

Harness Engineering ist das Entwerfen dieser Umgebung: das Modell, die Werkzeuge, die Berechtigungen, der Kontext, der Speicher.

Es ist die unglamouröse Schicht – und sie entscheidet darüber, ob alles, was darüber liegt, funktioniert. Ein großartiger Loop auf einem schlechten Harness ist der schnellste Weg, um im großen Stil Müll zu produzieren.

14 Schritte. 3 Ebenen. Die Grundlage, auf der alles andere steht.

Teil 1 · Was ein Harness ist

01. Ein Harness ist die Umgebung, in der ein Agent läuft.

Wenn man das Fachchinesisch weglässt, ist ein Harness vier Dinge: das Modell, das denkt, die Werkzeuge, auf die es zugreifen kann, die Berechtigungen für diese Werkzeuge und der Kontext, den es zu Beginn jedes Durchlaufs liest.

Das ist die ganze Oberfläche. Alles andere – Sub-Agents, Hooks, Gedächtnis – ist eine Möglichkeit, einen dieser vier Punkte zu formen.

Der Grund, warum der Harness wichtiger ist, als die Leute denken: Der Agent ist eine While-True-Schleife, die ein Werkzeug auswählt, es ausführt, sich das Ergebnis ansieht und den nächsten Schritt entscheidet.

Der Harness definiert, welche Werkzeuge existieren, was der Agent tun darf und was er weiß, wenn er startet. Gleiches Modell, anderer Harness, völlig anderer Agent.

02. Der gesamte Harness lebt in einem Ordner: .claude/

Alles, was Ihren Agenten formt, befindet sich in einem einzigen Verzeichnis im Projektstamm. Lernen Sie dieses Layout, und Sie können den Harness eines jeden auf einen Blick lesen:

1.claude/
2├─ CLAUDE.md          # stehende Fakten – werden in jeder Sitzung gelesen
3├─ settings.json      # Berechtigungen, Modell, Hooks
4├─ .mcp.json          # externe Werkzeugverbindungen
5├─ rules/             # pfadbezogene Verhaltensweisen
6│  ├─ tests.md
7│  └─ python-types.md
8├─ agents/            # Sub-Agent-Definitionen (~30 Zeilen pro Datei)
9│  ├─ reviewer.md
10│  └─ eval-runner.md
11├─ skills/            # wiederverwendbare Arbeitsabläufe
12│  └─ pr-checklist/
13│     └─ SKILL.md
14└─ agent-memory/      # was zwischen Durchläufen überlebt
15   └─ STATE.md

Eine Regel, die einen sauberen Harness von einem Chaos unterscheidet: Halten Sie ihn klein genug, dass Sie erklären können, warum jede Datei existiert. Wenn Sie nicht sagen können, wozu eine Regel, ein Hook oder ein Sub-Agent dient, löschen Sie ihn.

03. Harness vs. Loop vs. System. Drei Ebenen, vermischen Sie sie nicht.

Die meisten „Mein Agent-Setup ist ein Chaos“-Probleme entstehen durch die Verwechslung der drei Ebenen. Halten Sie sie auseinander:

• Der Harness ist die Laufzeitumgebung, in der ein Agent lebt. Statische Konfiguration: Modell, Werkzeuge, Berechtigungen, Kontext. Diese Ausgabe.
• Der Loop promptet den Agenten auf einem Timer, erzeugt Helfer, füttert sich selbst. Er läuft oben auf dem Harness.
• Das sich selbst verbessernde System ist ein Loop plus Gedächtnis, das sich akkumuliert – jeder Durchlauf macht den nächsten schärfer.

Die praktische Version: Stecken Sie stehende Fakten in den Kontext, Durchsetzung in Hooks, Prozeduren in Skills und Isolation in Sub-Agents.

Diese Dinge zu vermischen – Durchsetzung in CLAUDE.md, Prozeduren, die den Kontext aufblähen – ist die Hauptursache für inkonsistente, teure Agenten.

04. Der Standard-Harness. Was Sie von Haus aus bekommen.

Installieren Sie Claude Code, öffnen Sie einen Ordner, und Sie haben bereits einen Harness – nur einen leeren. Der Standard liefert Ihnen ein leistungsfähiges Modell, die eingebauten Werkzeuge (lesen, schreiben, bash, suchen) und Genehmigungsaufforderungen bei allem Riskanten. Kein Projektkontext, keine benutzerdefinierten Sub-Agents, kein Gedächtnis.

Für eine einmalige Aufgabe ist der Standard in Ordnung. Für alles, was Sie mehr als einmal tun, lässt der Standard den Agenten Ihr Projekt bei jeder Sitzung von Grund auf neu ableiten, um Erlaubnis für sichere Operationen bitten und alles vergessen, wenn Sie das Terminal schließen.

Die nächsten zehn Schritte dienen dazu, diese Lücke zu schließen.

05. CLAUDE.md: stehende Fakten, kurz gehalten.

CLAUDE.md wird zu Beginn jeder Sitzung gelesen. Es ist das stehende Wissen des Agenten über Ihr Projekt – Konventionen, Architektur, das „wir machen es nicht so, wegen des Vorfalls“.

Der mit Abstand häufigste Fehler: Es zu einem riesigen Prozeduren-Dokument wachsen zu lassen, das jede Sitzung aufbläht.

Die Regel von Praktikern, die das täglich nutzen: Halten Sie die Hauptgedächtnisdatei unter ~500 Token. Stehende Fakten gehören hierher.

Mehrschrittige Prozeduren gehören in Skills (Schritt 8). Pfadspezifische Verhaltensweisen gehören in rules/-Dateien, die auf den Bereich beschränkt sind, in dem sie gelten. Wenn ein Abschnitt von CLAUDE.md eher eine Prozedur als eine Tatsache geworden ist, gehört er woanders hin.

Lesen Sie Ihre CLAUDE.md laut vor. Jede Zeile sollte eine

Tatsache

sein, die der Agent in jeder Sitzung braucht („wir verwenden pnpm, nicht npm“). Wenn eine Zeile eine

Prozedur

ist („um eine Funktion hinzuzufügen, zuerst …“), verschieben Sie sie in ein Skill.

Wenn es eine Regel für einen Ordner ist, verschieben Sie es nach rules/.

06. settings.json: Berechtigungen und Modell, einmal eingestellt.

Der Standard-Harness fragt vor jeder riskanten Aktion nach. Das ist richtig, wenn Sie zusehen, und falsch, wenn Sie es nicht tun. In settings.json legen Sie fest, was Sie vorab genehmigen, was Sie ablehnen und welches Modell läuft.

1{
2  "model": "claude-sonnet-4-6",
3  "permissions": {
4    "autoApprove": [
5      "Read(*)", "Grep(*)",
6      "Bash(npm test)", "Bash(git status)"
7    ],
8    "deny": [
9      "Bash(rm -rf*)", "Bash(git push*)",
10      "Edit(.env*)", "Edit(secrets/*)"
11    ]
12  }
13}

Der Test für das, was automatisch genehmigt werden soll: Wenn das schiefgeht, wie schwer ist es, rückgängig zu machen? Günstig rückgängig zu machen → automatisch genehmigen.

Teuer rückgängig zu machen (Force-Push, Dateien löschen, Geheimnisse berühren) → immer ablehnen oder nachfragen. Der Mittelweg ist in Ordnung, um automatisch zu genehmigen, wenn Sie es protokollieren.

07. Sub-Agents: isolierter Kontext für die Drecksarbeit.

Ein Sub-Agent ist eine unabhängige Claude-Sitzung, die von der Hauptsitzung gestartet wird – ein eigener Kontextfenster, eine eigene Werkzeugliste. Der Sinn ist nicht Parallelität um ihrer selbst willen. Es geht darum, Rauschen aus dem Hauptkontext fernzuhalten.

Eine Rechercheaufgabe, die 40 Dateien liest, ein Review-Durchlauf, der eine neue Perspektive braucht, ein Evaluierungslauf, der eine Wand von Protokollen produziert – diese gehören in einen Sub-Agenten, damit sie den Hauptthread nicht verschmutzen.

GIF

Der wertvollste Sub-Agent in jedem Harness ist derjenige, der die Arbeit des Hauptagenten überprüft. Ein Modell, das seine eigene Ausgabe überprüft, ist zu nachsichtig mit sich selbst;

Ein separater Prüfer mit einem neuen Kontextfenster fängt ein, wovon sich der Schreiber selbst überzeugt hat. Dies ist die Schreiber-vs-Prüfer-Trennung, die jeden Loop über dem Harness vertrauenswürdig macht.

08. Skills: Prozeduren, die der Agent wiederverwendet.

Ein Skill ist eine SKILL.md-Datei, die der Agent ausführt – entweder wenn Sie sie mit /skill-name aufrufen oder automatisch, wenn die Aufgabe ihrer Beschreibung entspricht.

Im Gegensatz zu einem Sub-Agenten läuft es im gleichen Kontextfenster. Es sind nur wiederverwendbare Anweisungen, die Teil der Sitzung werden.

Der Auslöser, um einen zu erstellen: Sie bemerken, dass Sie in jedes neue Gespräch die gleichen Anweisungen einfügen. Das ist ein Skill, der nur darauf wartet, geboren zu werden. Eine PR-Checkliste, eine Evaluierungsprozedur, ein Release-Prozess – einmal geschrieben, für immer aufgerufen.

Und da Skills die wiederverwendbare Einheit sind, sind sie das, was den Harness im Laufe der Zeit verbessert: Jedes Mal, wenn die Prozedur auf eine neue Weise scheitert, fügen Sie die Lektion zum Skill hinzu, und der nächste Durchlauf erbt sie.

09. Hooks: deterministische Regeln, die das Modell nicht halluzinieren kann.

Bisher hängt alles davon ab, dass das Modell Ihre Anweisungen versteht. Hooks tun das nicht.

Ein Hook ist ein Shell-Befehl, der an einem festgelegten Punkt im Agenten-Lebenszyklus ausgelöst wird – bevor ein Werkzeug läuft, nachdem eine Datei geändert wurde, wenn die Sitzung endet – und sein Exit-Code kann die Aktion blockieren. Hooks sind Durchsetzung, CLAUDE.md ist ein Vorschlag.

Zwei Hooks verdienen ihren Platz in fast jedem Harness:

• Ein PreToolUse-Gate, das gefährliche Befehle deterministisch blockiert – rm -rf, Lesen von .env, Pushen zu main. Exit-Code 2 stoppt den Aufruf, bevor er stattfindet. Das Modell kann sich nicht daran vorbeireden.
• Ein PostToolUse-Formatierer, der Ihren Linter oder Formatierer nach jeder Bearbeitung ausführt. Der Agent liefert niemals unformatierten Code aus, weil der Harness automatisch formatiert.

1"hooks": {
2  "PreToolUse": [{
3    "matcher": "Bash",
4    "command": "./.claude/hooks/block-dangerous.sh"
5    // exit 2 = block the call before it runs
6  }],
7  "PostToolUse": [{
8    "matcher": "Edit|Write",
9    "command": "prettier --write \"$CLAUDE_FILE_PATH\""
10  }]
11}

Verwenden Sie Hooks für alles, was passieren muss oder niemals passieren darf – Sicherheit, Formatierung, Audit-Protokollierung.

Verwenden Sie sie nicht für Ermessensentscheidungen; dafür ist das Modell da. Ein guter Harness hat ein oder zwei scharfe Hooks, nicht zwanzig.

Teil 3 · Das System akkumulieren lassen

10. Fügen Sie einen Loop hinzu. Jetzt läuft der Harness auf einem Timer.

Ein konfigurierter Harness wartet immer noch darauf, dass Sie etwas eintippen. Ein Loop bringt ihn dazu, von selbst zu laufen. Die einfachste Version ist /loop in Claude Code – ein wiederkehrender Prompt in einem bestimmten Rhythmus.

Kombinieren Sie es mit /goal, und der Loop läuft weiter, bis eine objektive Bedingung erfüllt ist, die von einem unabhängigen Bewerter überprüft wird, anstatt dass der Agent sich selbst bewertet.

1> /loop 30m /goal Alle Tests bestehen und Lint ist sauber.
2  Neue Fehler priorisieren, Korrekturen in claude/-Branches entwerfen.
3
4▲ Claude verwendet den von Ihnen gebauten Harness:
5  - rules/ für Konventionen
6  - reviewer Sub-Agent, um jede Korrektur zu überprüfen
7  - PreToolUse-Hook blockiert Pushes zu main
8✓ Schleife läuft. Unabhängiger Bewerter entscheidet „erledigt.“

Beachten Sie, was gerade passiert ist: Der Loop hat keine Intelligenz hinzugefügt. Er hat alles im Harness wiederverwendet – die Regeln, den Reviewer-Sub-Agenten, den Sicherheits-Hook. Ein guter Harness macht einen Loop trivial. Das ist der springende Punkt, zuerst das Fundament zu bauen.

11. Fügen Sie dynamische Arbeitsabläufe hinzu. Der Harness schreibt seine eigene Orchestrierung.

Für Aufgaben, die zu komplex für einen einzigen Loop sind – massiv parallel, hochstrukturiert, adversarial – kann Claude seinen eigenen JavaScript-Harness spontan schreiben.

Das ist ein dynamischer Arbeitsablauf: agent() zum Erzeugen, parallel() zum Verteilen, pipeline() zum Streamen. Es kombiniert die Sub-Agents, die Ihr Harness definiert, zu Mustern wie Fan-Out-and-Synthesize oder adversarialer Verifikation.

Die Verbindung zum Harness Engineering: Ein dynamischer Arbeitsablauf ist nur so gut wie die Sub-Agents und Skills, die er aufrufen kann.

Wenn Ihr Harness einen scharfen Reviewer-Sub-Agenten und ein gut geschriebenes Evaluierungs-Skill hat, hat der Arbeitsablauf gute Bausteine, die er orchestrieren kann. Wenn der Harness leer ist, hat der Arbeitsablauf nichts, womit er arbeiten kann.

Der Arbeitsablauf ist der Dirigent, Ihr Harness ist das Orchester.

12. Fügen Sie Gedächtnis hinzu. Was der Agent vergisst, daran erinnert sich der Harness.

Dies ist der Schritt, der einen konfigurierten Harness in ein System verwandelt, das sich tatsächlich verbessert. Der Agent vergisst alles zwischen den Durchläufen. Der Harness muss das nicht.

Eine Zustandsdatei – eine Markdown-Datei in agent-memory/ oder ein Linear-Board – zeichnet auf, was versucht wurde, was funktioniert hat, was fehlgeschlagen ist, welche Regeln Bestand hatten.

Das Muster, das Gedächtnis akkumulieren lässt, abgeleitet von der Nutzung der stärksten Agenten:

• Schreiben, bevor Sie weggehen. Jeder Durchlauf endet mit der Aktualisierung der Zustandsdatei – gewonnene Erkenntnisse, bestätigte Fakten, was als nächstes kommt.
• Lesen Sie am Anfang. Jeder Durchlauf beginnt mit dem Lesen der Zustandsdatei und relevanter Skills, sodass er fortsetzt, anstatt neu zu starten.
• Destillieren Sie in Skills. Wenn eine Lektion allgemein ist („Windows-Runner brauchen bash, nicht PowerShell“), wandert sie von der Zustandsdatei in ein Skill, wo sie für jedes zukünftige Projekt gilt.

1# Projektspeicher
2
3## Bestätigte Fakten # raten Sie nicht mehr darüber
4- prc ist in Dollar, nicht in Cent (überprüft via SELECT MIN/MAX)
5- auth-middleware-Reihenfolge: rate_limit -> jwt -> rbac
6
7## Gewonnene Erkenntnisse # destillieren Sie die allgemeinen in Skills
8- Windows-CI-Runner scheitern an TLS 1.2 in PowerShell — bash verwenden
9- Migrationen bei Tabellen >1M Zeilen müssen in 10k-Blöcken erfolgen
10
11## Letzte Sitzung # fortsetzen, nicht neu starten
122026-06-11 · 3 Korrekturen zusammengeführt, 2 eskaliert. Als nächstes: rate-limit-Korrektur verifizieren.

13. Schließen Sie den Kreislauf. Ausgabe → Lektion → Skill → bessere Ausgabe.

Hier verriegeln sich die drei Ebenen zu etwas, das sich selbst verbessert. Jeder Durchlauf produziert eine Ausgabe. Der Reviewer-Sub-Agent (Schritt 7) überprüft sie.

Das Ergebnis – was bestanden hat, was durchgefallen ist, was gelernt wurde – wird in den Speicher geschrieben (Schritt 12). Die allgemeinen Lektionen werden in Skills destilliert (Schritt 8).

Der nächste Durchlauf erbt schärfere Skills und einen reicheren Speicher.

Das ist der gesamte sich selbst verbessernde Kreislauf, und beachten Sie, dass er vollständig aus Harness-Teilen besteht:

• Sub-Agent bewertet die Arbeit – objektive Prüfung, frischer Kontext.
• Gedächtnis zeichnet das Urteil auf – überlebt zwischen den Durchläufen.
• Skills verallgemeinern die Lektion – der nächste Durchlauf erbt alles, was der letzte gelernt hat.
• Der Loop führt es erneut aus – jetzt mit allem, was der letzte Durchlauf gelernt hat.

Das Modell hat sich nie geändert. Der Harness darum herum wurde schärfer. Das bedeutet „sich selbst verbessernd“ ehrlicherweise – kein Modell, das lernt, sondern ein Harness, der sich akkumuliert.

14. Versenden Sie den Harness. Packen Sie ihn. Teilen Sie ihn. Verwenden Sie ihn wieder.

Ein Harness, der in einem Projekt funktioniert, ist ein Asset.

Bündeln Sie die Skills, Sub-Agents und Regeln in einem Plugin, und Ihr gesamtes Team installiert das gleiche Setup in einem Schritt – gleiche Konventionen, gleiche Sicherheits-Hooks, gleicher Reviewer.

Der Harness hört auf, Ihr persönliches Setup zu sein, und wird zur gemeinsamen Infrastruktur.

Die Reihenfolge des Aufbaus, ein letztes Mal, weil die Reihenfolge die Lektion ist: Bekommen Sie einen manuellen Durchlauf auf einem sauberen Harness zuverlässig hin.

Fügen Sie den Kontext und die Berechtigungen hinzu. Fügen Sie einen Reviewer-Sub-Agenten hinzu. Fügen Sie Gedächtnis hinzu. Dann, und erst dann, wickeln Sie es in einen Loop. Ein Loop auf einem guten Harness akkumuliert sich. Ein Loop auf einem schlechten Harness blutet nur schneller.

§ Die Harness-Fehler, die jeden Loop verschlechtern

• Laufen mit dem Standard. Kein Kontext, keine Regeln, kein Gedächtnis – der Agent leitet Ihr Projekt bei jeder Sitzung neu ab.
• Ein aufgeblähter CLAUDE.md. Prozeduren, die in den stehenden Kontext gestopft werden, blähen jeden Durchlauf auf. Verschieben Sie sie in Skills.
• Durchsetzung in CLAUDE.md anstatt in Hooks. Das Modell kann einen Vorschlag ignorieren. Es kann einen Hook, der mit Exit 2 endet, nicht ignorieren.
• Ein Agent, der seine eigene Arbeit schreibt und bewertet. Fügen Sie einen Reviewer-Sub-Agenten mit einem frischen Kontextfenster hinzu.
• Kein Gedächtnis. Jeder Durchlauf startet von Null. Die Zustandsdatei ist das, was morgen fortsetzen lässt.
• Einen Loop um einen schlechten Harness wickeln. Der Loop produziert nur schneller Schrott. Bauen Sie zuerst das Fundament.
• Zwanzig Hooks. Ein oder zwei scharfe schlagen einen Haufen, den niemand versteht.
• Einen Harness versenden, ohne ihn zu scannen. Durchgesickerte Geheimnisse und zu weit gefasste Berechtigungen verbreiten sich auf alle, die ihn installieren.

Fazit:

Der Loop bekommt den Ruhm. Der Harness macht die Arbeit.

Loop Engineering ist der aufregende Teil – der Agent, der sich selbst promptet, während Sie schlafen. Aber ein Loop ist nur ein Harness auf einem Timer.

Alles, was entscheidet, ob die Ausgabe gut oder Müll ist, liegt eine Etage tiefer, in dem Modell, das Sie ausgewählt haben, den Werkzeugen, die Sie erlaubt haben, dem Kontext, den Sie geschrieben haben, dem Reviewer, den Sie hinzugefügt haben, dem Gedächtnis, das Sie bewahrt haben.

Bauen Sie diese Etage gut, und alles darüber akkumuliert sich: Der Loop verwendet Ihre Sub-Agents wieder, der Arbeitsablauf orchestriert Ihre Skills, der Speicher macht jeden Durchlauf schärfer als den letzten.

Selbstverbesserung war nie eine Eigenschaft des Modells. Es ist eine Eigenschaft des Harnesses, den Sie darum herum bauen.

Wählen Sie eine Sache, die Sie noch nicht tun – wahrscheinlich ein Reviewer-Sub-Agent, ein Sicherheits-Hook oder eine Zustandsdatei – und fügen Sie sie heute hinzu. Halten Sie den Harness klein genug, um ihn zu erklären. Dann setzen Sie einen Loop obendrauf und sehen Sie zu, wie das Fundament die Arbeit macht.