Agent Harness Engineering: Was mir 8 Monate im Produktivbetrieb gelehrt haben

10 min read
Artificial Intelligence Software Engineering Programming Software Development Productivity
Agent Harness Engineering: Was mir 8 Monate im Produktivbetrieb gelehrt haben

Gleiches Modell. 36 Punkte höher in Benchmarks. Das Problem war nie das Modell.

Anthropic gab Opus 4.5 einen High-Level-Prompt, um eine produktive Web-App zu bauen. Es scheiterte. Nicht weil das Modell schlecht war. Sondern weil es alles auf einmal versucht hat (gib's zu, du machst das genauso), halbfertige Features über Context-Windows verstreut hat und zu früh den Sieg erklärt hat. Sie reparierten das Gerüst, fügten Progress-Tracking und inkrementelle Workflows hinzu: Das gleiche Modell fing an zu liefern. Sie nannten den Artikel "Effective Harnesses for Long-Running Agents."

TL;DR: "Harness > Modell" ist richtig, aber unvollständig. Der Mechanismus dahinter ist progressive disclosure: Zeig dem Modell nur was es braucht, wann es das braucht. Das gleiche Modell sprang 36 Punkte höher auf CORE-Bench, nur durch ein besseres Gerüst. Mein Framework nach 8 Monaten und 5 Produktions-Apps: Contracts statt Vibes, Constraints statt Tools, jedes Quartal vereinfachen. Copy-Paste-Templates inklusive.

Dann tauchte das Wort überall auf. OpenAI veröffentlichte "Harness Engineering." LangChain verbesserte ihren Coding-Agent von 52,8% auf 66,5%, indem sie nur das Harness änderten. Mitchell Hashimoto und Martin Fowler schrieben darüber. SWE-bench Pro bestätigte es im großen Stil: Gleiches Modell, anderes Gerüst, andere Ergebnisse.

Ich schaute auf meine CLAUDE.md, meine Prompt-Contracts, meine CLI-Wrapper und merkte: Das ist genau das, was ich seit acht Monaten mache, über fünf Produktions-Apps hinweg. Mir fehlte nur das Wort dafür. Harness. Das ist das Wort.

Also ja, das Harness ist wichtiger als das Modell. Das ist geklärt.

Aber zu wissen "das Harness ist wichtig" ist wie zu wissen "iss gesund und treib Sport." Wahr, nutzlos wenn du es nicht machst, und kurz davor eine ganze Industrie überkomplizierter Frameworks zu erzeugen, die den Punkt verfehlen.

Ich habe acht Monate damit verbracht, jeden Fehler im Buch zu machen. Das hier hat überlebt.

Die drei Fehler, die jeder machen wird

Ich weiß es, weil ich alle drei gemacht habe.

Fehler 1: Tools stapeln statt Contracts schreiben

Als ich anfing OpenClaw zu bauen, meinen Multi-Model AI Agent, verkabelte ich 12 MCP Tools. Search, Memory, Credit Checks, RSS Monitoring, Discord Alerts, Cron Status, User Queries, Backup Verification. Fühlte sich gründlich an. Professionell.

Der Agent verbrachte mehr Zeit damit zu entscheiden, welches Tool er aufrufen soll, als das eigentliche Problem zu lösen.

Bei einer simplen "braucht heute Morgen etwas meine Aufmerksamkeit?"-Anfrage feuerte er 4-5 Tool-Calls hintereinander ab, manchmal den gleichen Endpoint zweimal mit leicht unterschiedlichen Parametern, weil die Beschreibungen vage genug waren, um sich zu überschneiden. Eines Morgens rief er check_users auf, dann check_credits, dann check_users nochmal mit einem anderen Filter, dann gab er mir eine Antwort, die sich zwischen den Absätzen selbst widersprach.

Ich riss 8 Tools raus. Ersetzte 12 durch 4 mit präzisen Beschreibungen als Contracts. Nicht "query credit data" sondern "finde User, deren aktueller Credit-Stand um mehr als 10% vom erwarteten abweicht, markiere die Anomalie mit Drift-Betrag und sortiere nach Schweregrad." Gleicher Code darunter. Gleiches Modell. Das einzige was sich änderte war die Beschreibung.

40% weniger Tool-Calls. Outputs widersprachen sich nicht mehr. Die Tool-Beschreibung war die ganze Zeit das Problem.

Ich baute das komplette Prompt-Contracts-Framework um dieses Prinzip und es wurde die einzige wirkungsvollste Änderung in meinem gesamten Workflow. Du teilst keinen Code mehr mit dem Agent. Du teilst Intent, Constraints und erwartetes Verhalten. Die Beschreibung IST der Contract.

Fehler 2: Komplexität wählen, wenn Einfachheit funktioniert

47.000 Token. Das hat Phil Schmid als Kosten für die Integration von 6 MCP Servern auf Standard-Weg gemessen. Nur Schema-Definitionen. Bevor dein Agent überhaupt anfängt über dein eigentliches Problem nachzudenken, kaut er sich durch siebenundvierzigtausend Token JSON Tool-Beschreibungen.

Manus löste das, indem sie MCP Tools über einen CLI-Wrapper exponierten. Gleiche Fähigkeiten. Etwa 400 Token.

Ich kannte diese Zahlen nicht, als ich Ende 2025 meinen ersten MCP Server baute. Alle bauten sie. Das Protokoll war neu, glänzend, fühlte sich wie die richtige Abstraktion an. Also baute ich auch einen. Custom OAuth Flow, Token Refresh Handling, Multi-Source Data Aggregation, das volle Programm.

Sechzehn Commits. Vier Stunden Debugging eines Auth-Tokens, der mid-session ablief. Ich war in einem Hotelzimmer in Cancún mit einem Pool buchstäblich zehn Meter entfernt und schaute auf scrollende Logs statt zu schwimmen. Schließlich shipped und funktioniert jetzt gut. Aber dann baute ich auch CLIs, die das Gleiche für andere Services machten. Das CLI brauchte ein Bash-Script und JSON-Output. Funktionierte beim ersten Versuch.

Cool.

Vercel führte das gleiche Experiment im großen Stil durch. Starteten mit umfassenden Tool-Libraries, Search, Code, File, API Tools. Jede Fähigkeit, die du wollen würdest. Agents wurden verwirrt, machten redundante Calls, nahmen unnötige Schritte. Sie strippten auf das Wesentliche, gaben dem Agent direkten Bash-Zugang. Erfolgsrate ging auf 100%, Geschwindigkeit stieg um das 3,5-fache.

Ich schrieb über warum CLIs MCP für die meisten Agent-Setups schlagen und die Reaktion war wild. Stellte sich heraus, viele Builder vermuteten das Gleiche, aber fühlten sich komisch dabei, es zu sagen, während das ganze Ökosystem MCP als die Zukunft pushte.

MCP hat seinen Platz. Aber der Instinkt, zuerst zur komplexen Lösung zu greifen, ist genau wie Harnesses aufgebläht werden, bevor sie nützlich werden.

Fehler 3: Nie etwas entfernen

Dieser ist tückisch, weil es sich unverantwortlich anfühlt. Du hast etwas gebaut, das funktioniert. Es ist in Produktion. Es zu entfernen fühlt sich an wie eine Leitplanke von der Autobahn zu entfernen.

Aber Modelle verbessern sich. Und dein Harness weiß das nicht.

Letzten Monat entfernte ich ein ganzes Memory-Subsystem aus OpenClaw. External Context Retrieval, Embedding Lookups, Conversation History Injection. Es hatte zwei Wochen gedauert zu bauen und vier Monate zu warten. Ich löschte es an einem Donnerstag. Bis Freitag erzählten die Zahlen die Geschichte:

Response-Latenz fiel um 2,3 Sekunden pro Query. Der Agent hörte auf, "erinnerten" Context zu halluzinieren, der eigentlich veraltete Daten von vor drei Monaten waren. User-Zufriedenheit bei Support-Interaktionen stieg, weil der Agent auf das antwortete, was Leute tatsächlich sagten, statt auf das, was das Memory-System für relevant hielt.

Das Modell (Kimi K2.5) war gut genug geworden darin, Context innerhalb von Sessions zu behalten, dass die externe Memory-Schicht aktiv die Dinge verschlechterte. Ich zahlte für Infrastruktur, die mein Produkt degradierte.

Manus, wahrscheinlich der kampferprobste autonome Agent in Produktion gerade, lernte das fünfmal auf die harte Tour. Sie schrieben ihr ganzes Harness fünfmal in sechs Monaten um. Nicht weil sich Modelle änderten. Weil jede Umschreibung Komplexität strippte.

Ihre ursprüngliche Version nutzte eine todo.md-Datei, die der Agent bei jedem Schritt umschrieb, um Progress zu tracken. Etwa 30% aller Token gingen in das Update dieser Datei. Sie ersetzten es mit einem Sub-Agent-Planner, der ein strukturiertes Objekt zurückgibt und es nur injiziert, wenn nötig.

Sie reduzierten ihre Tools von Dutzenden dynamischer MCP Schemas auf weniger als 20 atomare Funktionen: bash, filesystem, code execution. MCP Tools sind nicht mal mehr im Context-Window. Sie werden über CLI exponiert, das der Agent durch bash aufruft.

Peak Ji, ihr Chief Scientist, sagte es unverblümt: "Während Modelle stärker werden, sollten wir nicht mehr Gerüst bauen, sondern dem Modell aus dem Weg gehen."

Anthropic sagt das Gleiche: "As model capabilities increase, the tools that your models once needed might now be constraining them."

Wenn dein Harness in drei Monaten nicht geschrumpft ist, ist es wahrscheinlich schon zu groß.

Das eine Pattern, das all das zum Funktionieren bringt

Alle drei Fehler teilen die gleiche Grundursache: dem Modell zu viel geben, zu früh, zu lange. Zwölf Tools, wenn es vier brauchte. MCP-Overhead, wenn ein Bash-Script gereicht hätte. Ein Memory-System, das veralteten Context injizierte, den das Modell überwachsen hatte.

Der Fix hat einen Namen. Progressive Disclosure. Zeig dem Modell nur was es braucht, wann es das braucht. Verstecke alles andere.

Cursor macht das aggressiv. Ihr Dynamic Context Discovery System filtert etwa 47% der verfügbaren Token vom Modell bei jedem gegebenen Schritt. Nicht aus Versehen, durch Architektur. Das Modell sieht nur was relevant ist für diese spezifische Aufgabe, diesen spezifischen Moment.

Claude Code macht es mit Skills. Du erstellst ein skills/ Verzeichnis, Claude sieht nur Skill-Namen und kurze Beschreibungen beim Session-Start. Es lädt den vollen Content nur, wenn es entscheidet, dass es ihn braucht. Lazy Loading für LLMs.

Manus macht es mit ihrem geschichteten Action Space. Level 1: 20 atomare Tools, immer sichtbar. Level 2: Sandbox-Utilities über bash aufgerufen, nie Context verschmutzend. Level 3: Der Agent schreibt seine eigenen Scripts für komplexe Ketten, statt drei separate LLM-Roundtrips zu machen.

Der Benchmark-Impact ist real. Gleiches Modell, Claude Opus 4.5, scorte 42% auf CORE-Bench mit einem generischen Scaffold. Mit Claude Code als Harness, 78%. Das ist nicht nur progressive disclosure, Claude Code bringt besseres Tool-Management, Environment-Setup und Compaction. Aber die Forscher, die den Test durchführten, waren unverblümt: Das Scaffold verdoppelte fast den Score. Das Modell änderte sich nicht.

Die drei Säulen unten sind, wie ich progressive disclosure in der Praxis anwende. Tools, Konfiguration, Wartung.

Das Framework: Contracts, Constraints, Cleanup

Kein 47-Layer-Architektur-Diagramm. Kein GitHub Repo mit 41 Skill-Definitionen und 11 Sub-Agents. Drei Dinge, die tatsächlich den Kontakt mit Produktion überlebt haben.

Säule 1: Contracts über Vibes

Du hast gesehen, was mit OpenClaws Tool-Beschreibungen passierte. Der Grund warum es funktioniert ist mechanisch: Das Modell macht Token-Level Pattern Matching auf deiner Beschreibung, um zu entscheiden, ob ein Tool relevant für die aktuelle Query ist. Vage Beschreibungen matchen alles. Präzise Beschreibungen matchen nur was du willst.

Das Template, das ich jetzt für alle meine Tool-Definitionen nutze, und ich würde vorschlagen, du machst das Gleiche für deine drei meistgenutzten Tools heute Abend:

name: [tool_name]
description: [WAS spezifisch es zurückgibt, nicht vage Nomen 
sondern die tatsächliche Form nützlichen Outputs]. 
Call this when [spezifische Trigger-Bedingungen]. 
Do NOT call when [häufiger Missbrauchsfall]. 
Expected output: [Format und Schlüsselfelder].

Die "Do NOT call when"-Zeile ist die, die alles verändert. Ohne sie behandelt das Modell jedes Tool als ein Vielleicht. Mit ihr hat das Modell einen Contract.

Säule 2: Constraints über Tools

Jedes Mal wenn du denkst "Ich brauche ein neues Tool dafür," stopp. Frag zuerst: Kann eine einzige Zeile in CLAUDE.md das stattdessen lösen?

Statt einem Linter MCP Server, ein Constraint: "Run tests before every commit." Statt einem Style-Checking Agent, ein Constraint: "Follow the conventions in CONVENTIONS.md." Statt einem Planning Tool, ein Constraint: "Always write plan.md before touching code."

Ein Constraint in CLAUDE.md kostet null Token zur Laufzeit und fügt null Failure Surface hinzu. Ein Tool kostet Token jedes Mal wenn es aufgerufen wird, fügt einen Decision Point hinzu, den das Modell falsch machen kann, und braucht Wartung. Die Mathematik ist offensichtlich, sobald du sie siehst.

Eine Starter CLAUDE.md, die ich tatsächlich als Basis über Projekte hinweg nutze. Kein Monolith, eine Navigation Layer, die auf spezialisierte Dateien zeigt:

## CLAUDE.md

## Role
Senior engineer. You plan before you code. You test before you push.

## Workflow
1. Read this file + any progress.md at session start
2. Plan first. Write plan.md before implementation.
3. One feature at a time. Commit after each.
4. Run existing tests before AND after changes
5. Update progress.md before session ends

## Constraints
- Never overwrite files without showing a diff first
- If a task needs more than 3 files changed, break it down
- When unsure, ask. Don't guess at business logic.
- Keep commits small and descriptive

## Project specifics
[Your stack, conventions, key files here]
See CONVENTIONS.md for code style rules.

Zwanzig Zeilen, die dem Agent sagen, wie er arbeiten soll, nicht was er wissen soll. Anthropics eigenes Harness für Long-Running Agents nutzt eine Progress-Datei, eine Feature-Liste und strukturierte Git-Commits auf einem ähnlichen Kern. OpenAIs Codex-Team lernte auf die harte Tour, dass eine riesige AGENTS.md scheitert. Ihr Rat: "give Codex a map, not a 1,000-page instruction manual."

Der Schlüssel ist progressive disclosure angewandt auf Config: eine kurze CLAUDE.md, die auf detaillierte Dateien zeigt, die der Agent liest, wenn er sie braucht. Kein 500-Zeilen-Monolith, den er überfliegt und ignoriert. Kein 10-Zeilen-Stub, der nichts sagt. Eine Navigation Layer.

Säule 3: Quartalsweise Aufräumen

Alle drei Monate setze ich mich mit meinem Harness hin und stelle fünf Fragen:

  1. Welche Tools hat der Agent in 30 Tagen nicht aufgerufen? Lösch sie.
  2. Welche CLAUDE.md-Regeln existieren, weil das alte Modell dumm war? Entfern sie.
  3. Welche Guardrails werden jetzt nativ vom Modell gehandhabt? Stripp sie.
  4. Ist die Context-Injection noch notwendig oder hat sich das Retrieval des Modells genug verbessert? Test ohne sie.
  5. Können zwei Tools zu einem mit besserer Beschreibung verschmelzen? Mach es.

Letztes Quartal bei OpenClaw: Ich löschte einen Retry-with-Different-Model-Fallback, der in 6 Wochen nicht getriggert hatte (Kimi K2.5 war stabil genug geworden). Ich entfernte drei CLAUDE.md-Regeln über JSON-Formatierung, die das Modell jetzt nativ handhabt. Ich verschmolz zwei Monitoring-Tools zu einem mit einem spezifischeren Contract.

Netto-Ergebnis: 30% weniger bewegliche Teile. Null Funktionalität verloren. Schnellere Responses. Weniger zu warten.

Manus führt diesen Prozess kontinuierlich durch. Peak Jis Test: Führe deine Agent-Eval-Suite gegen ein stärkeres Modell aus. Wenn sich die Performance nicht verbessert, hemmt dein Harness es. Diese Frage allein sagt dir alles darüber, ob du Gerüst baust oder einen Käfig.

Was das für dich heute Abend bedeutet

Fünfzehn Minuten. Das ist alles, was du brauchst, um tatsächlich anzufangen.

Schreib deine drei meistgenutzten Tool-Beschreibungen um. Find die Tools, die dein Agent am meisten aufruft. Öffne ihre Beschreibungen. Wenn sie sagen, was das Tool macht, statt wann man es aufruft und was man erwarten kann, schreib sie mit dem Contract-Template oben um. Fünf Minuten pro Tool. Der Impact ist sofort, der Agent hört auf zu raten und fängt an, Anweisungen zu befolgen.

Dann strukturiere deine CLAUDE.md als Navigation Layer. Wenn du noch keine hast, paste das Starter-Template oben und füll deine Stack-Details ein. Wenn du schon eine hast, check: Ist es ein Monolith oder eine Karte? Verschieb detaillierte Regeln in separate Dateien (CONVENTIONS.md, ARCHITECTURE.md) und halt deine CLAUDE.md bei etwa 20-40 Zeilen. Der Agent liest CLAUDE.md jede Session. Er sollte Richtungen finden, keine Enzyklopädie.

Und lösch eine Sache. Ein Tool. Eine CLAUDE.md-Regel. Einen Middleware-Hook. Pick etwas, was du in einem Monat nicht angefasst hast. Entfern es. Führe deinen normalen Workflow aus. Wenn nichts kaputt geht, hatte es kein Recht dort zu sein. Und wenn etwas kaputt geht, Glückwunsch, du hast gerade gelernt, was in deinem Harness tatsächlich wichtig ist. Das ist mehr wert als jedes Architektur-Diagramm, das jemand auf X gepostet hat 💀

Harness Engineering ist im Trend. Gib ihm sechs Monate. Es wird Kurse geben. Zertifizierungen. GitHub Repos mit 41 Skill-Definitionen, 11 Sub-Agents und einer README länger als die meisten Codebasen. Dreitausend Stars, null Produktions-Deployments.

Währenddessen werden die Builder, die tatsächlich Agents shippen, weiter das machen, was sie vor dem Wort gemacht haben. Klare Anweisungen schreiben. Einfache Tools wählen. Löschen, was aufgehört hat zu funktionieren.

Das Harness ist kein neuer Job. Es ist der gleiche Job mit einem besseren Namen.

Quellen:

Wenn diese Patterns dir Debugging-Zeit oder Token-Kosten sparen, schreibe ich regelmäßig über dieses Zeug. Prompt Contracts, Agent-Architektur, die langweiligen Infrastruktur-Entscheidungen, die AI Agents in Produktion funktionieren lassen, statt nur in Demos. Folg mit, wenn du die Feldnotizen willst, nicht den Hype.

AI hat das Cover-Bild gemacht. Ich allokiere mein Pixel-Budget ausschließlich für Terminal-Windows.