Agent Harness: was um das Modell herum gebaut wird

Aufbau, Teile und ein echtes Beispiel mit Regeldatei, Tests und Vorschau

Veröffentlicht
Kategorien
Entwicklung

Inhalt

Zwei Teams nutzen dasselbe Sprachmodell für ihre Entwicklung. Beim einen entstehen brauchbare Pull Requests, beim anderen Änderungen, die mehr Arbeit machen, als sie sparen. Am Modell liegt das selten. Es liegt an dem, was um das Modell herum gebaut ist.

Ein Agent Harness ist alles, was um ein Sprachmodell herum gebaut wird, damit es zuverlässig Software schreibt: die Schleife aus Planen, Handeln und Prüfen, die Werkzeuge, der Kontext aus Projektregeln und die Kontrollen, bevor eine Änderung live geht. Bei kopfwelt.com gehören dazu eine Regeldatei im Repository, 122 Testdateien und eine Vorschau je Änderung, die ein Mensch freigibt.

Dieser Artikel erklärt die Teile eines Harness und zeigt sie an diesem echten Aufbau. Am Ende steht eine Anleitung für den ersten eigenen Harness. Er gehört zur Serie Agentic Software Factory.

Agent = Modell + Harness

Birgitta Böckeler von Thoughtworks fasst die Idee in einer Formel zusammen: Ein Agent besteht aus dem Modell und dem Harness, und der Harness ist alles außer dem Modell. Quelle: Harness engineering for coding agent users, 2. April 2026.

Für Coding-Agenten unterscheidet sie zwei Schichten. Die innere bringt das Werkzeug selbst mit, etwa Claude Code oder Codex: den Systemprompt, die Suche im Code, die Werkzeuge zum Lesen und Schreiben von Dateien. Die äußere baut das Team für sein eigenes Projekt. Um diese äußere Schicht geht es hier, denn nur sie kann man selbst gestalten.

Der Begriff Harness Engineering beschreibt diese Arbeit. OpenAI hat im Februar 2026 berichtet, wie sich die Aufgabe eines Teams dadurch verschob: weg vom Schreiben des Codes, hin zum Gestalten der Umgebung, zum Festlegen der Absicht und zum Bau von Rückmeldeschleifen für die Agenten. Quelle: OpenAI, Harness engineering, 11. Februar 2026.

Die Agent Loop: planen, handeln, prüfen

Im Kern jedes Coding-Agenten läuft eine Schleife, die Agent Loop. Der Agent liest die Aufgabe und den Kontext, plant einen Schritt, führt ihn aus und schaut sich das Ergebnis an. Ein Test schlägt fehl, also ändert er den Code und startet den Test erneut. Das wiederholt sich, bis die Aufgabe erledigt ist oder er nicht weiterkommt.

Wie gut diese Schleife funktioniert, hängt von zwei Dingen ab. Erstens davon, was der Agent vor dem ersten Schritt weiß. Zweitens davon, wie deutlich ihm die Umgebung nach jedem Schritt sagt, ob er richtig liegt. Beides gehört zum Harness.

Ein Detail zeigt, warum es ohne Harness nicht geht: Jede Sitzung eines Coding-Agenten beginnt ohne Erinnerung an die vorige. Was das Team gestern mit dem Agenten geklärt hat, ist heute weg, wenn es nicht irgendwo steht. Quelle: Claude Code Docs, How Claude remembers your project.

Aus diesen Teilen besteht ein Harness

Böckeler teilt die Teile eines Harness in zwei Gruppen. Leitplanken wirken vorher: Sie sollen den Agenten lenken, bevor er handelt. Sensoren wirken nachher: Sie beobachten das Ergebnis und geben dem Agenten eine Rückmeldung, mit der er sich selbst korrigieren kann.

Leitplanken, also was der Agent vorher weiß:

  • Eine Regeldatei im Repository, meist AGENTS.md oder CLAUDE.md. Sie beschreibt Befehle, Architektur, Konventionen und Fehler, die nicht wieder passieren sollen. AGENTS.md ist ein offenes Format, das inzwischen die Agentic AI Foundation unter dem Dach der Linux Foundation betreut. Quelle: agents.md.

  • Fachdokumente, auf die die Regeldatei verweist: Designsystem, Datenmodell, Entscheidungen.

  • Skills, also gebündelte Anleitungen für wiederkehrende Aufgaben. Wie man fremde Skills vor dem Einsatz prüft, steht im Artikel Agent Skills prüfen.

  • Werkzeuge, die der Agent aufrufen darf, etwa über MCP-Server, und Rechte, die festlegen, was er nicht darf.

Sensoren, also was ihm nachher sagt, ob er richtig liegt:

  • Tests, die bei jeder Änderung laufen.

  • Linter und Typprüfung, die Fehler finden, bevor etwas läuft.

  • Ein Build, der zeigt, ob die Anwendung überhaupt entsteht.

  • Eine Vorschau der laufenden Anwendung, in der Mensch und Agent das Ergebnis ansehen können.

  • Ein Review, durch ein zweites Modell oder einen Menschen.

Böckeler unterscheidet außerdem, wie ein Teil arbeitet. Berechnende Teile wie Tests und Linter sind deterministisch und schnell. Schlussfolgernde Teile wie ein KI-Review sind langsamer, teurer und liefern nicht jedes Mal dasselbe. Ein guter Harness stützt sich vor allem auf die berechnenden und nutzt die schlussfolgernden dort, wo es um Bedeutung geht.

Der echte Aufbau: der Harness von kopfwelt.com

Das Repository dieser Website besteht seit Oktober 2025, entwickelt wird es mit Coding-Agenten, vor allem mit Claude Code. Der Harness ist nicht auf einmal entstanden, sondern mit jedem Fehler gewachsen. Was im Repository liegt, Stand 22. November 2026:

Die Regeldatei: CLAUDE.md mit 1.070 Zeilen

CLAUDE.md liegt im Wurzelverzeichnis und wird bei jeder Sitzung geladen. Sie beginnt mit den Befehlen (pnpm dev, pnpm test, pnpm lint) und den Umgebungsvariablen. Danach erklärt sie die Architektur und vor allem die Regeln, deren Bruch etwas kaputt macht.

Jede Regel steht dort mit ihrer Begründung. Ein Beispiel: Die Liste der Seitenbausteine darf nie aus dem Layout importiert werden, weil sonst jede Komponente im JavaScript landet, das jede Seite lädt. Ein anderes: Nach einer Veröffentlichung in Storyblok darf keine Cache-Version an das CDN gehen, weil eine Seite sonst über vier Veröffentlichungen hinweg den alten Stand zeigte. Ohne Begründung würde ein Agent eine solche Regel bei der ersten Gelegenheit „vereinfachen“.

Ehrlich gesagt ist die Datei zu lang. OpenAI empfiehlt eine kurze Regeldatei von rund 100 Zeilen, die als Inhaltsverzeichnis auf ausführlichere Dokumente verweist, weil eine große Datei den Kontext verstopft und veraltet. Bei uns steht vieles direkt drin, was in eigene Dokumente gehört. Sie aufzuteilen wäre der nächste sinnvolle Schritt.

Die Tests: 122 Dateien, die frühere Fehler festhalten

Im Ordner test/ liegen 122 Testdateien für Vitest. Die meisten halten einen bestimmten früheren Fehler fest, und ihr Kopfkommentar sagt, welchen. test/storyblok-cache-version.test.ts beschreibt zum Beispiel genau den Cache-Fehler von oben und prüft, dass die Cache-Version aus jeder Anfrage entfernt wird. test/server-purity.test.ts listet die Bausteine, die kein JavaScript in den Browser schicken dürfen.

Die Regeldatei weist Agenten ausdrücklich an, den Kopfkommentar zu lesen, bevor sie eine fehlschlagende Prüfung „reparieren“. So wird aus einem Test ein Gedächtnis: Der Agent erfährt nicht nur, dass etwas falsch ist, sondern auch, warum es einmal schiefging. Dazu kommt ein Browser-Test mit Playwright im Ordner e2e/, der den Klickweg von einer Teaser-Karte zur Detailseite im Produktions-Build prüft.

Die Vorschau: ein Vercel-Deployment je Pull Request

Jede Änderung läuft über einen eigenen Branch und einen Pull Request. Vercel baut dazu automatisch eine Vorschau. Von den 286 zusammengeführten Pull Requests haben 273 diesen Vercel-Check; es fehlt nur bei den ersten 13. In der Vorschau prüft ein Mensch, ob die Seite aussieht und sich verhält wie gewünscht.

Arbeitsverzeichnisse und Prüfwerkzeuge

Mehrere Agenten arbeiten parallel, jeder in einem eigenen Git-Worktree unter .claude/worktrees/. Wie das funktioniert, beschreibt der Artikel Parallel arbeiten mit Git-Worktrees. Die Datei .claude/launch.json sagt dem Agenten, wie er den Entwicklungsserver und einen Produktionsserver startet. Für eine aufwendige Umstellung des Cachings liegt ein eigener Skill im Repository.

Freigabe durch einen Menschen

Alle 286 zusammengeführten Pull Requests sind über das Konto des Inhabers gemergt. Ein Agent öffnet den Pull Request, ein Mensch entscheidet, ob er live geht. Warum diese Grenze wichtig ist, beschreibt der Artikel Human in the Loop.

Was fehlt

Im Repository gibt es keinen GitHub-Actions-Workflow, der die Tests bei jedem Pull Request erzwingt. Sie laufen lokal mit pnpm test, gestartet vom Agenten oder von einem Menschen; Vercel prüft nur, ob der Build gelingt. Das funktioniert, solange alle sich daran halten. Ein Sensor, der von selbst anschlägt, wäre verlässlicher.

Den ersten Harness bauen: fünf Schritte

Ein Harness muss nicht am ersten Tag vollständig sein. Unserer ist aus einem leeren Repository und einem Fehler nach dem anderen entstanden. Diese Reihenfolge hat sich bewährt:

  1. Eine kurze Regeldatei anlegen. Wie man das Projekt startet, testet und baut. Welche drei, vier Regeln nie gebrochen werden dürfen, jede mit einem Satz Begründung. Was mehr Platz braucht, kommt in eigene Dokumente, auf die die Datei verweist.

  2. Jeden Fehler in einen Test verwandeln. Wenn ein Agent oder ein Mensch etwas kaputt macht, entsteht ein Test, der genau diesen Fehler findet. Im Kopf des Tests steht, was passiert ist und warum. Macht ein Agent denselben Fehler zweimal, gehört eine Regel in die Regeldatei.

  3. Eine Vorschau je Änderung einrichten. Jeder Pull Request bekommt eine eigene URL. Hosting-Plattformen wie Vercel, Netlify oder Cloudflare bieten das ohne großen Aufwand an.

  4. Einen festen Prüfschritt vor dem Pull Request. Tests, Linter und Build laufen, bevor ein Agent einen Pull Request öffnet, am besten zusätzlich automatisch in einer CI-Pipeline. Die Rückmeldung sollte so formuliert sein, dass der Agent daraus lernen kann.

  5. Rechte begrenzen und Freigabe festlegen. Der Agent bekommt nur die Zugänge, die er für seine Aufgabe braucht. Zusammenführen und Veröffentlichen bleiben bei Menschen.

Was in die Regeldatei gehört und was nicht, vertieft der Artikel Context Engineering mit AGENTS.md. Welche Voraussetzungen ein Team vorher klären sollte, fragt die Checkliste für KI-Agenten in der Entwicklung ab.

Was ein Harness nicht leistet

Ein Harness fängt viele Fehler ab, bevor ein Mensch hinsieht. Drei Dinge kann er nicht.

Er kann nicht prüfen, ob etwas richtig ist, wenn niemand gesagt hat, was richtig wäre. Böckeler schreibt, Korrektheit liege außerhalb der Reichweite jedes Sensors, wenn der Mensch nicht klar festgelegt hat, was er wollte. Gute Anforderungen sind deshalb Teil der Arbeit, siehe Spec-driven Development.

Er kann sich nicht allein auf Tests verlassen, die der Agent selbst geschrieben hat. Ein Test, den der Agent passend zu seinem Code schreibt, bestätigt oft nur, dass beide übereinstimmen. Sonar nennt das ausdrücklich: Bestandene Tests, die der Agent selbst geschrieben hat, reichen nicht. Quelle: Sonar.

Und er bleibt nicht fertig. Modelle ändern sich, und Teile des Harness, die heute eine Schwäche ausgleichen, sind morgen überflüssig. BCG Platinion schreibt, man baue die Factory, um sie wieder umzubauen, wenn sich die Fähigkeiten ändern. Quelle: BCG Platinion, The Agentic Software Factory.

Wer einen Harness für die eigene Entwicklung aufsetzen will, findet auf der Seite KI-gestützte Softwareentwicklung, wie wir dabei vorgehen.

Häufige Fragen zum Agent Harness

Was ist ein Agent Harness?

Alles, was um ein Sprachmodell herum gebaut wird, damit es als Agent zuverlässig arbeitet: die Schleife aus Planen, Handeln und Prüfen, die Werkzeuge, die Regeln und Dokumente als Kontext und die Prüfschritte wie Tests, Build und Review. Kurz: Agent ist gleich Modell plus Harness.

Was ist Harness Engineering?

Die Arbeit am Harness: Regeldateien schreiben, Tests als Rückmeldung für den Agenten bauen, Werkzeuge und Rechte festlegen und das Ganze anpassen, wenn der Agent Fehler macht. In einem Team mit Coding-Agenten verlagert sich ein großer Teil der Entwicklungsarbeit dorthin.

Was ist die Agent Loop?

Die Schleife, in der ein Agent arbeitet: Aufgabe und Kontext lesen, einen Schritt planen, ihn ausführen, das Ergebnis prüfen und je nach Ergebnis den nächsten Schritt planen. Sie läuft, bis die Aufgabe erledigt ist oder der Agent nicht weiterkommt.

Brauche ich einen Harness, wenn ich Claude Code oder Codex nutze?

Diese Werkzeuge bringen eine innere Schicht mit. Für das eigene Projekt braucht es eine äußere: eine Regeldatei, Tests und Prüfschritte, die zu eurem Code passen. Ohne sie weiß der Agent bei jeder Sitzung nur, was er im Code selbst findet.

Wie lang sollte eine AGENTS.md oder CLAUDE.md sein?

So kurz wie möglich. OpenAI hat mit einer Datei von rund 100 Zeilen gute Erfahrungen gemacht, die auf ausführlichere Dokumente verweist. Unsere eigene CLAUDE.md hat 1.070 Zeilen und ist damit zu lang.

Ersetzt ein Harness die Prüfung durch Menschen?

Nein. Er fängt viele Fehler ab und lenkt die Aufmerksamkeit der Prüfenden auf das, was zählt. Ob eine Änderung das Richtige tut und live gehen darf, entscheidet ein Mensch.

Quellen

  1. Birgitta Böckeler, martinfowler.com: Harness engineering for coding agent users, 2. April 2026.

  2. Ryan Lopopolo, OpenAI: Harness engineering: leveraging Codex in an agent-first world, 11. Februar 2026.

  3. Anthropic: Claude Code Docs, How Claude remembers your project, abgerufen am 22. November 2026.

  4. Agentic AI Foundation: AGENTS.md, abgerufen am 22. November 2026.

  5. Sonar: What is an agentic software factory?, 2. November 2026.

  6. BCG Platinion: The Agentic Software Factory, 26. März 2026.