Was ist Harness Engineering: wie Sie einen KI-Agenten zum funktionierenden Werkzeug machen

Harness Engineering in einfachen Worten

Harness Engineering ist die Disziplin, die beschreibt, wie man um ein Sprachmodell herum eine Umgebung baut, in der es zuverlässig echte Arbeit erledigt. Das Wort „Harness“ bezeichnet das Zaumzeug, mit dem man ein starkes Tier lenkt. Das Modell ist leistungsstark, aber von sich aus weiß es nicht, wohin es gehen, welche Werkzeuge es nutzen oder wann es aufhören soll. Das Harness lenkt diese Kraft.

Die kürzeste Formulierung lautet:

Agent = Modell + Harness

Das Modell sind die Gewichte und die Fähigkeit zu schlussfolgern und Text oder Code zu schreiben. Das Harness ist alles Übrige: Systemanweisungen und Dateien wie CLAUDE.md oder AGENTS.md, ein Satz Werkzeuge (Shell, Dateibearbeitung, MCP-Server), eine Sandbox, in der der Agent Befehle ausführt, Zustandsdateien für Sitzungen, sowie Tests, Linter und Hooks, die dem Agenten Fehler melden. Entfernt man das Harness, bleibt ein Chat, der nur mit Text antworten kann.

Warum der Agent mal „Senior“ und mal „Junior“ wirkt

Ein bekanntes Bild: In einem Repository arbeitet der Agent wie ein erfahrener Entwickler, in einem anderen verliert er sich, vergisst frühere Entscheidungen und meldet „fertig“ für ein Feature, das nicht funktioniert. Die erste Reaktion ist, auf ein neueres Modell zu wechseln. Meist hilft das nicht, denn das Modell ist in beiden Fällen dasselbe. Der Unterschied liegt in der Umgebung.

Hier beginnt der wichtigste Perspektivwechsel des Harness Engineering: Der Agent ist nicht kaputt, kaputt ist das, was ihn umgibt. Der Agent kann die Tests nicht starten, wenn er keinen Zugriff darauf hat. Er erinnert sich nicht daran, was er schon ausprobiert hat, wenn das nirgends festgehalten ist. Er erfährt nicht, dass ein Feature defekt ist, wenn keine Prüfung es ihm sagt. Das sind keine „Charakterzüge“ des Modells, sondern Konstruktionsfehler, und sie lassen sich systematisch beheben.

Typische Anzeichen eines schlechten Harness

• Jede neue Sitzung beginnt mit der Reparatur der Umgebung: falsche Abhängigkeiten, die Datenbank startet nicht, Variablen fehlen.
• Der Agent wiederholt bereits verworfene Lösungen, weil er sich an die letzte Sitzung nicht erinnert.
• Eine Regel steht ausdrücklich in den Anweisungen, der Agent ignoriert sie aber.
• „Die Tests sind grün“, und trotzdem ist das Feature defekt, weil die Tests das Falsche geprüft haben.
• Der Agent nimmt sich drei Aufgaben gleichzeitig vor und schließt keine davon ab.

Woraus ein Harness besteht: fünf Teilsysteme

Ein verbreiteter Irrtum ist, das Harness für eine einzelne Prompt-Datei zu halten. Tatsächlich sind es fünf Mechanismen, und jeder bricht auf seine eigene Weise.

Anweisungen

Anweisungen beantworten die Frage, ob der Agent die richtige Regel findet. Eine gute Einstiegsdatei ist eine Landkarte, kein Lehrbuch: ein kurzes Inhaltsverzeichnis mit Prüfbefehlen und harten Vorgaben, die Details stehen in eigenen Dokumenten, die der Agent bei Bedarf öffnet. Gute Anweisungen formulieren Invarianten („alle SQL-Abfragen sind parametrisiert“), statt die Umsetzung Zeile für Zeile vorzuschreiben.

Werkzeuge

Der Agent kann nur prüfen, worauf er Zugriff hat. Kann er den Linter nicht starten, nützt keine Regel „vor jedem Commit den Linter ausführen“. Werkzeuge werden über die eingebauten Fähigkeiten des Agenten angebunden (Dateien lesen und bearbeiten, Befehle ausführen) und über MCP, ein Protokoll, über das der Agent Zugriff auf Datenbanken, Browser und Aufgabenverwaltung erhält.

Umgebung

Die Umgebung ist der Ort, an dem der Agent Befehle ausführt. Sie sollte mit einem einzigen Befehl starten, von Sitzung zu Sitzung gleich sein und den Schaden eines Fehlers begrenzen: eine Sandbox ohne Zugriff auf die Produktion, ein eigener Branch oder eine eigene Arbeitskopie und die Möglichkeit, alles innerhalb einer Minute in den Ausgangszustand zurückzuversetzen.

Zustand

Ein Modell hat kein Gedächtnis zwischen Sitzungen: Alles, was nicht im Repository festgehalten ist, verschwindet mit dem Kontextfenster. Deshalb müssen Ziel, Erledigtes, getroffene Entscheidungen, Sackgassen und der nächste Schritt in Dateien leben. Ein einfacher Test: Öffnen Sie eine neue Sitzung, sagen Sie dem Agenten „mach weiter“ und beobachten Sie, ob er sofort arbeitet oder nachfragt, was zu tun ist.

Rückmeldung

Rückkopplungsschleifen sind das wichtigste Teilsystem. Ohne sie ist der Agent sein einziger Richter und hält die Aufgabe ehrlich für erledigt. Tests, Typprüfung, ein Linter, ein Hook, der nach jeder Änderung läuft, ein E2E-Szenario im Browser: All das gibt dem Agenten ein rotes Signal zurück, solange der Fehler noch günstig zu beheben ist.

Das Harness ist ein Kreislauf, keine Liste

Die fünf Teilsysteme arbeiten als geschlossener Kreislauf. Das Modell erhält Anweisungen, handelt über Werkzeuge in der Umgebung, nimmt Änderungen am Repository vor, und die Verifikation prüft das Ergebnis. Ein rotes Ergebnis geht zur Korrektur zurück an das Modell, ein grünes wird im Zustand festgehalten. Der Zustand aktualisiert wiederum die Anweisungen für die nächste Sitzung.

Anweisungen → Modell → Werkzeuge → Umgebung → Änderungen
                ↑                              ↓
                └──── rot ── Verifikation ─────┘
                                     ↓ grün
                                 Zustand → (nächste Sitzung)

Entfernt man einen Pfeil, bricht der Kreislauf an dieser Stelle. Ohne Verifikation erfährt der Agent nichts von seinen Fehlern. Ohne Zustand beginnt die nächste Sitzung mit Spurensuche statt mit Arbeit. Deshalb gleicht Investition in ein Teilsystem keine Lücke in einem anderen aus: Eine fünfseitige AGENTS.md ersetzt keine fehlenden Tests.

Worin sich Harness Engineering von Prompt- und Context-Engineering unterscheidet

Diese Konzepte sind ineinander verschachtelt, sie konkurrieren nicht.

Prompt-Engineering ist ein Teil des Teilsystems Anweisungen. Context-Engineering umfasst Anweisungen und Zustand: was der Agent in jedem Moment sieht. Harness Engineering ergänzt, was überhaupt nicht ins Kontextfenster passt: Zugriffsrechte, die Sandbox, Tests, Hooks, der Arbeitsprozess. Ein gut geschriebener Prompt hilft nicht, wenn der Agent die Tests physisch nicht starten kann.

Warum ein Harness nötig ist: die Mathematik langer Aufgaben

Intuitiv scheint ein Modell, das 95 % der Schritte richtig macht, nahezu perfekt. Doch eine Agentenaufgabe besteht aus vielen Schritten, und Fehler summieren sich. Sind die Schritte unabhängig, ist die Wahrscheinlichkeit, alle ohne Fehler zu bestehen, das Produkt der Einzelwahrscheinlichkeiten:

0.95 ^ 10 ≈ 0.60
0.95 ^ 20 ≈ 0.36
0.95 ^ 50 ≈ 0.08

Beim zehnten Schritt kommen nur etwa 60 % der Läufe ohne einen einzigen Fehler durch, beim fünfzigsten weniger als einer von zehn. Das Modell auf 97 % zu verbessern ist teuer und liegt nicht in Ihrer Hand. Den Fehler aber genau dort zu fangen, wo er entstanden ist, und dem Agenten zurückzugeben, ist die Aufgabe des Harness. Eine Rückkopplungsschleife verwandelt eine Kette, in der „ein Fehler den nächsten nach sich zieht“, in eine Kette kurzer, korrigierbarer Schritte.

Beispiel: derselbe Agent in zwei Repositories

Aufgabe: Einem Zahlungs-Backend auf FastAPI einen Rabatt per Promocode hinzufügen.

Ohne Harness

Der Agent liest ein paar Dateien, schreibt eine Funktion zur Rabattberechnung und einen Unit-Test, der diese Funktion isoliert prüft. Der Test ist grün, der Agent schreibt „fertig“. Er wusste nicht, dass die Gesamtsumme in einem anderen Modul berechnet wird, und konnte weder die Datenbank starten noch den gesamten Bestellvorgang durchspielen. Einen Tag später zeigt sich, dass der Rabatt im Warenkorb nicht angewendet wird.

Mit Harness

Im Wurzelverzeichnis liegt eine AGENTS.md mit einigen Dutzend Zeilen: wie die Umgebung aufgesetzt wird, welche Prüfbefehle verpflichtend sind, wo die Zahlungsarchitektur beschrieben ist. Die Umgebung startet mit docker compose up -d. Im Repository gibt es eine Planungsdatei mit einem Abnahmekriterium: „Das E2E-Szenario der Bestellung mit Promocode läuft durch“. Nach jeder Änderung führt ein Hook Linter und Typprüfung aus, und vor dem Abschluss muss der Agent den E2E-Test ausführen.

# AGENTS.md (Auszug)
## Prüfung — vor dem Wort „fertig“ zwingend
make lint        # ruff + mypy
make test        # pytest, Unit- und Integrationstests
make e2e         # Bestellszenario

## MUST
- Geld wird in Cent (int) gerechnet, niemals in float
- Alle SQL-Abfragen sind parametrisiert
- Bereits in Produktion angewendete Migrationen nicht anfassen

Das Modell ist dasselbe. Jetzt findet der Agent über die Projektkarte das Modul der Gesamtsumme, der E2E-Test schlägt beim ersten Versuch fehl, der Agent sieht, dass der Rabatt nicht im Warenkorb ankommt, behebt es und meldet erst nach einem grünen Lauf. Der Unterschied im Ergebnis ist vollständig das Verdienst des Harness.

Wo man anfängt

1. Beschreiben Sie, wie der Agent seine eigene Arbeit prüft: ein bis drei Befehle, die er zwingend ausführen muss. Die Rückmeldung bringt den größten Effekt, daher beginnen Sie damit.
2. Machen Sie die Umgebung reproduzierbar: Sie startet mit einem Befehl, und es gibt einen schnellen Weg zurück.
3. Legen Sie eine Zustandsdatei an: Ziel, Erledigtes, Entscheidungen und Sackgassen, nächster Schritt.
4. Kürzen Sie die Anweisungen zur Landkarte: Prüfbefehle, harte Vorgaben, Verweise auf ausführliche Dokumente.
5. Führen Sie ein Protokoll der Fehlschläge des Agenten: Notieren Sie bei jedem Fehler, welches Teilsystem ihn zugelassen hat. Das Protokoll zeigt, was als Nächstes zu reparieren ist.

Eine bewährte Übung: Bewerten Sie jedes der fünf Teilsysteme auf einer Skala von 1 bis 5, investieren Sie eine halbe Stunde in das schwächste und lassen Sie denselben Satz typischer Aufgaben vorher und nachher laufen. So werden Verbesserungen am Harness messbar statt „gefühlt“.

Fazit

Harness Engineering ist die Arbeit nicht am Modell, sondern an allem, was es umgibt: Anweisungen, Werkzeuge, Umgebung, Zustand und Rückkopplungsschleifen. Die Zuverlässigkeit des Agenten bestimmt das schwächste Glied dieses Kreislaufs. Deshalb heilt ein Modellwechsel selten die Instabilität, ein ergänzter Test oder eine Planungsdatei dagegen oft. Alle fünf Teilsysteme und der Aufbau des Harness als Ganzes werden im Kurs zum Harness Engineering praktisch behandelt.