Agent-Harness-Engineering

Problem: Du hast das Modell upgegradet. Die Performance hat sich kaum verändert. Du siehst immer wieder dieselben Fehler, Session für Session, egal welche Modellversion du verwendest.

Quick Win: Hör auf, das Modell zu tunen. Tune den Harness. Ein Team hat von 15 Tools auf einen einzigen Bash-Aufruf reduziert und gesehen, wie die Genauigkeit von 80% auf 100% sprang, während der Token-Verbrauch um 37% sank.

Verständnis: Agent = Modell + Harness. Das Modell übernimmt das Reasoning. Der Harness übernimmt alles andere: welche Tools der Agent erreichen kann, welchen Kontext er erhält, wie Fehler auftauchen, wie Ergebnisse verifiziert werden. In der Praxis ist der Harness die bindende Einschränkung für die reale Performance, nicht das Modell.

Was der Harness wirklich ist

Der Harness ist die Software-Schicht, die ein KI-Modell umgibt und alles außer dem Reasoning des Modells verwaltet. Er ruft Tools auf. Er verwaltet Memory. Er leitet Aufgaben weiter. Er führt Verifikationschecks durch. Er entscheidet, welcher Kontext im Prompt-Fenster ankommt und in welcher Form.

Martin Fowlers Definition ist präzise: Der Harness ist alles in einem Agenten außer dem Modell selbst. Zwei Kontrollrichtungen laufen durch ihn:

• Feedforward (Guides): Den Agenten vor dem Handeln steuern. System-Prompts, Kontext-Injektion, Tool-Einschränkungen. Diese erhöhen die Wahrscheinlichkeit, dass der erste Output korrekt ist.
• Feedback (Sensoren): Nach dem Handeln des Agenten beobachten und Selbstkorrektur ermöglichen. Linter, Type-Checker, Test-Runner, Build-Hooks. Diese fangen Fehler ab, bevor sie menschliche Augen erreichen.

Keine Richtung allein reicht aus. Feedback ohne Feedforward produziert einen Agenten, der dieselben Fehler wiederholt korrigiert. Feedforward ohne Feedback produziert einen Agenten, der Regeln kodiert, aber nie erfährt, wann sie fehlgeschlagen sind.

Warum Harness-Design Modell-Upgrades übertrifft

Das SWE-bench-Leaderboard macht das Argument deutlich. Bei Coding-Benchmarks kann dasselbe Modell mit einem Scaffold 42% und mit einem besseren 78% erzielen. Das Modell hat sich nicht verändert. Der Harness schon.

Das Vercel-Beispiel ist das klarste Beispiel, das zurzeit kursiert. Ihr Team hat einen Agenten von 15+ Tools auf ein einziges Bash-Tool reduziert. Auf ihrem Benchmark: Die Genauigkeit stieg von 80% auf 100%, die Tokens sanken um 37% und die Geschwindigkeit verbesserte sich um das 3,5-fache. Sie haben das Modell nicht angerührt. Sie haben die Harness-Komplexität reduziert.

Das Muster hält sich in allen Teams. Harveys Legal-AI-Team verbesserte die Task-Completion von 40,8% auf 87,7% durch Verbesserung des Systems rund um das Modell. OpenAIs internes Tooling-Team kam zu dem Schluss: "Unsere schwierigsten Herausforderungen drehen sich jetzt um das Design von Umgebungen, Feedback-Schleifen und Kontrollsystemen."

Das Modell ist der Motor. Der Harness ist das Auto. Den Motor aufzurüsten hilft. Ein besseres Auto zu bauen ist meistens der effektivere Schritt.

Die fünf Hebel

Jeder Harness ist aus denselben Steuerungspunkten aufgebaut. Die richtigen in der richtigen Reihenfolge zu ziehen, ist das eigentliche Handwerk.

1. Tool-Design

Die Tools, die einem Agenten zur Verfügung stehen, definieren seine Capability-Fläche. Zu viele Tools und der Agent verschwendet Kontext mit Disambiguierung. Zu wenige und er greift auf Workarounds zurück. Das Vercel-Ergebnis ist der kanonische Referenzpunkt: Wenige, schärfere Tools übertreffen ein breites allgemeines Toolkit.

Design Tools rund um Outcomes, nicht Capabilities. Ein Tool namens run_tests übertrifft eines namens execute_command, weil der Agent nicht entscheiden muss, was er ausführen soll.

2. Kontext-Injektion

Was der Agent weiß, bevor er handelt, bestimmt, was er produziert. Kontext-Injektion bedeutet, die richtigen Informationen zur richtigen Zeit ins Prompt-Fenster zu legen: Architektur-Docs, Coding-Standards, aktuelle Fehler, der aktuelle Datei-Baum.

Der Fehlermodus ist Over-Injection: Das Fenster mit allem verfügbaren Material zu fluten. Relevanter Kontext im richtigen Moment übertrifft einen großen, undifferenzierten Dump.

3. Memory-Architektur

Ein Single-Session-Agent vergisst alles, wenn das Fenster schließt. Ein richtig geharnischter Agent trägt weiter: getroffene Entscheidungen, beobachtete Muster, zuvor gesehene Fehler. Memory kann kurzfristig (Conversation State), mittelfristig (Session-Logs) oder langfristig (persistente Dateien, die der Agent beim Start liest) sein.

Claude Codes CLAUDE.md-Datei ist ein langfristiger Memory-Hebel. Der Agent liest sie beim Session-Start. Was du dort hinterlegst, prägt jede folgende Session.

4. Verifikationsschleifen

Der Harness führt Checks aus, die der Agent nicht überspringen kann. Type-Checker, Linter, Build-Befehle, Test-Suites. Wenn diese nach jeder Agenten-Aktion als automatische Sensoren laufen, tauchen Fehler in derselben Session auf, die sie erstellt hat. Die Korrekturkosten sinken.

Das Prinzip: Qualitätschecks so weit links wie möglich halten. Ein Typfehler vor dem Commit kostet Sekunden. Derselbe Fehler im Review kostet eine Stunde.

5. Constraint-Design

Was der Agent nicht tun kann, ist genauso wichtig wie das, was er kann. Schreibzugriff auf Produktions-Configs einschränken, bestimmte Tool-Aufrufe blockieren, einschränken, welche Dateien ein Agent berühren kann, sind alles Constraint-Hebel. Das Ziel ist nicht, den Agenten zu lähmen, sondern die Klasse von Fehlern zu eliminieren, die Constraints unmöglich machen.

Das Constraint-Paradoxon

Einem Agenten mehr Regeln hinzuzufügen, verbessert sein Verhalten nicht zuverlässig. Das ist das Constraint-Paradoxon: Ein Harness, der mit Anweisungen überladen ist, kann die Performance unter das senken, was der Agent mit minimaler Führung erreicht.

Der Mechanismus ist einfach. Jede Einschränkung verbraucht Kontext. Widersprüchliche Regeln erzeugen Rauschen, das der Agent navigieren muss. Ein langer Anweisungssatz, der jeden Randfall abdeckt, ist oft schlechter als ein kurzer, klarer, der die wichtigsten fünf abdeckt.

Die praktische Lösung ist Priorisierung. Identifiziere die Fehlermodi, die tatsächlich wiederkehren. Schreibe Constraints für diese. Lass alles andere dem Urteil des Modells über. Der Harness sollte die Fehler eliminieren, die häufig auftreten, nicht versuchen, jedes mögliche schlechte Ergebnis aufzuzählen.

Computationale vs. inferenzielle Kontrollen

Harness-Kontrollen teilen sich in zwei Typen auf.

Computationale Kontrollen sind deterministisch und schnell. Type-Checker, Linter, Test-Runner, Build-Systeme. Sie laufen in Millisekunden bis Sekunden. Ergebnisse sind zuverlässig und günstig genug, um bei jeder Agenten-Aktion zu laufen.

Inferenzielle Kontrollen verwenden ein Modell als Richter. Code-Review-Agenten, semantische Qualitätschecks, "LLM-as-Evaluator"-Muster. Sie sind langsamer, teurer und nicht-deterministisch. Sie fangen ab, was computationale Kontrollen verfehlen: semantische Duplikation, falsch angewendete Muster, missverstandene Anweisungen.

Die praktische Aufteilung: Computationale Kontrollen automatisch bei jeder Änderung ausführen. Inferenzielle Kontrollen selektiv, bei riskanteren Änderungen oder nach der Integration. Die beiden Schichten ergänzen sich, sie konkurrieren nicht.

Drei Harness-Kategorien

Ein Harness reguliert verschiedene Dimensionen des Agenten-Outputs. Sie zu unterscheiden hilft, weil die richtigen Kontrollen je nach Kategorie unterschiedlich sind.

Wartbarkeits-Harness: Guides und Sensoren rund um Code-Qualität, Stil und Struktur. Das ist die einfachste Kategorie aufzubauen. Bestehendes Tooling (Linter, Type-Checker, Coverage-Tools) lässt sich direkt einbinden. Die meisten Teams fangen hier an.

Architektur-Fitness-Harness: Guides und Sensoren, die strukturelle Constraints durchsetzen. Modul-Grenzen, Dependency-Regeln, Performance-Budgets. Fitness-Funktionen laufen als automatische Checks. Architektureller Drift wird abgefangen, statt Monate später in einem Review entdeckt zu werden.

Behavior-Harness: Guides und Sensoren rund um funktionale Korrektheit. Das ist die schwierigste Kategorie. KI-generierte Test-Suites sind noch nicht zuverlässig genug, um spezifiziertes Verhalten vollständig zu ersetzen. Die meisten Teams kombinieren derzeit Spezifikationsdokumente (Feedforward) mit KI-generierten Tests plus selektiver manueller Verifikation (Feedback). Das offene Problem ist, genug Vertrauen in agentengenerierte Tests aufzubauen, um manuelle Kontrolle zu reduzieren.

Startpunkte für Claude Code

Claude Code bietet mehrere Harness-Hebel direkt an.

CLAUDE.md ist deine primäre Feedforward-Kontrolle. Architekturentscheidungen, Naming-Conventions, Muster zum Befolgen oder Vermeiden, explizite Regeln darüber, was der Agent nicht tun soll. Diese Datei lädt bei jedem Session-Start. Was du hier hinterlegst, prägt das Standardverhalten des Agenten ohne jedes Prompting.

.claude/agents/-Spezialistendefinitionen lassen dich den Scope pro Agent einschränken. Ein Datenbank-Agent, der nur Migration-Dateien berühren kann, kann nicht versehentlich Frontend-Komponenten modifizieren. Scope-Einschränkung ist einer der günstigsten Constraints, den du hinzufügen kannst.

Hooks lassen dich computationale Sensoren in die Agenten-Schleife einbinden. Ein Post-Edit-Hook, der den Type-Checker ausführt, bedeutet, dass jede Dateiänderung validiert wird, bevor der Agent zur nächsten Aufgabe übergeht.

Permission-Regeln in settings.json definieren, auf welche Tools der Agent zugreifen kann. Mit weniger Tools zu starten und zu erweitern ist besser, als mit allem anzufangen und später zu versuchen, einzuschränken.

Der gute Harness zielt nicht darauf ab, menschlichen Input vollständig zu eliminieren. Er lenkt menschliche Aufmerksamkeit dorthin, wo sie am meisten zählt: die Entscheidungen, die Sensoren nicht abfangen können und die Urteilsvermögen, nicht Regeln, lösen müssen.

Häufige Fragen

Was ist Agent-Harness-Engineering?

Agent-Harness-Engineering ist die Praxis, alles rund um ein KI-Modell zu designen, außer dem Modell selbst. Dazu gehören Tool-Auswahl, Kontext-Injektion, Memory-Architektur, Verifikationsschleifen und Constraint-Design. Der Harness bestimmt, welche Informationen der Agent erhält, welche Aktionen er ausführen kann und wie Fehler erkannt und korrigiert werden, bevor sie in menschliche Review gelangen.

Warum ist der Harness wichtiger als das Modell?

Auf SWE-bench-Coding-Benchmarks erzielt dasselbe Modell mit einem Scaffold 42% und mit einem besseren 78%. Vercel hat 80% der Tools ihres Agenten entfernt und gesehen, wie die Genauigkeit von 80% auf 100% stieg, mit 37% weniger verwendeten Tokens. Das Reasoning des Modells ist fix. Der Harness bestimmt, wie viel von dieser Reasoning-Fähigkeit tatsächlich die Aufgabe erreicht.

Was ist ein KI-Agent-Scaffold?

Ein Scaffold ist die strukturelle Schicht, die rund um ein KI-Modell gebaut wird, um komplexe, mehrstufige Aufgaben zu ermöglichen. Er bietet dem Agenten Tools zum Aufrufen, Memory zum Lesen und Schreiben, eine Schleife zum erneuten Ausführen nach Fehlern und Feedback-Signale zur Selbstkorrektur. Scaffold und Harness werden in den meisten Kontexten synonym verwendet. Der Unterschied, wenn er gemacht wird, ist, dass ein Harness Kontrolle und Governance betont, während ein Scaffold Struktur und Ermöglichung betont.

Wie baue ich einen guten Agent-Harness?

Fang mit den fünf Hebeln in der Reihenfolge an: zuerst Tool-Design, dann Kontext-Injektion, dann Memory, dann Verifikationsschleifen, dann Constraints. Für jeden Hebel identifiziere die Fehlermodi, die du tatsächlich beobachtest, keine theoretischen. Baue die einfachste Kontrolle, die jeden Fehler verhindert. Führe computationale Checks (Type-Checker, Linter, Tests) automatisch nach jeder Agenten-Aktion aus. Füge inferenzielle Kontrollen nur dort hinzu, wo computationale sie nicht erreichen.

Was ist das Constraint-Paradoxon bei KI-Agenten?

Mehr Constraints hinzufügen, verbessert das Agentenverhalten nicht zuverlässig. Ein langer, erschöpfender Regelsatz ist oft schlechter als ein kurzer, klarer, weil jeder Constraint Kontext verbraucht und widersprüchliche Regeln Rauschen erzeugen. Die Lösung ist Priorisierung: Identifiziere die Fehlermodi, die am häufigsten wiederkehren, und schreibe Constraints nur für diese. Lass alles andere dem Urteil des Modells über.

Warum hat Vercel von 15+ Tools auf eins reduziert?

Vercels Team stellte fest, dass ein breites Tool-Set ihren Agenten dazu zwang, Kontext für Disambiguierung zu verbrauchen, also zu entscheiden, welches Tool aufgerufen werden soll, anstatt wie das Problem gelöst werden soll. Die Reduzierung auf ein einziges Bash-Tool entfernte diesen Overhead. Die Genauigkeit stieg von 80% auf 100%, Tokens sanken um 37% und die Geschwindigkeit verbesserte sich um das 3,5-fache auf ihrem Benchmark. Das Prinzip: Wenige, schärfere Tools übertreffen ein großes allgemeines Toolkit.

Weitere Agent-Konzepte erkunden:

• Agent-Muster: Orchestrierungsformen für Multi-Agenten-Arbeit
• Agent-Grundlagen: Sub-Agenten, Slash-Befehle und CLAUDE.md-Personas
• Sub-Agenten-Design: Architekturmuster zur Koordination mehrerer Agenten
• Team-Orchestrierung: Builder- und Validator-Schleifen in der Praxis
• Custom Agents: Spezialisierte Agentendefinitionen schreiben