Harness Engineering: Codex in einer agentenorientierten Welt einsetzen

• Fallstudie eines Experiments, bei dem ein internes Team von OpenAI über 5 Monate lang ohne manuelles Schreiben von Code eine interne Beta eines Softwareprodukts aufgebaut und veröffentlicht hat; der gesamte Code wurde von Codex-Agenten erzeugt
• Gestartet mit 3 Ingenieuren wurden etwa 1 Million Zeilen Code und 1.500 Pull Requests verarbeitet, mit durchschnittlich 3,5 gemergten PRs pro Tag und Ingenieur
• Die Rolle der Ingenieure verlagerte sich vom direkten Codieren hin zu Umgebungsdesign, expliziter Formulierung von Absichten und Aufbau von Feedback-Loops; entscheidend war der Aufbau eines Scaffoldings, in dem Agenten zuverlässig arbeiten können
• AGENTS.md wurde nicht als Enzyklopädie, sondern als Inhaltsverzeichnis genutzt; durch strukturierte Dokumentation, Linter und strukturelle Tests wurde architektonische Konsistenz mechanisch durchgesetzt
• Je autonomer Agenten werden, desto unverzichtbarer werden Entropiemanagement und kontinuierliches Aufräumen nach dem Prinzip der Garbage Collection; die Disziplin beim Softwarebau verlagert sich vom Code zum Scaffolding

---

Ein Experiment, das mit einem leeren Git-Repository begann

• Ende August 2025 wurde der erste Commit in ein leeres Repository gemacht; das anfängliche Scaffold (Repository-Struktur, CI-Konfiguration, Formatierungsregeln, Paketmanager-Setup, Application-Framework) wurde auf Basis bestehender Templates mit GPT-5 im Codex CLI erzeugt
• Auch die anfängliche Datei AGENTS.md, die dem Agenten erklärt, wie im Repository gearbeitet wird, wurde direkt von Codex geschrieben
• Das Repository wurde von Anfang an ohne bestehenden, von Menschen geschriebenen Code vollständig von Agenten geformt
• Fünf Monate später umfasste es über Anwendungslogik, Infrastruktur, Tooling, Dokumentation und interne Entwickler-Utilities hinweg etwa 1 Million Zeilen Code
• Das kleine Team aus 3 Personen öffnete und mergte rund 1.500 Pull Requests, was einem Durchsatz von durchschnittlich 3,5 PRs pro Tag und Ingenieur entspricht
• Als das Team auf 7 Personen wuchs, stieg der Durchsatz sogar weiter
• Hunderte Nutzer verwendeten das Produkt intern täglich, darunter auch interne Power-User
• Während des gesamten Entwicklungsprozesses trugen Menschen nie direkt Code bei
• „Es gibt keinen manuell geschriebenen Code“ wurde zur Kernphilosophie des Teams

Die Rolle des Ingenieurs neu definiert

• Wenn Menschen nicht mehr direkt coden, braucht es eine andere Art von Engineering-Arbeit mit Fokus auf Systeme, Scaffolding und Hebelwirkung
• Dass der Anfang langsamer lief als erwartet, lag nicht an unzureichenden Fähigkeiten von Codex, sondern an einer unzureichenden Umgebung
  • Dem Agenten fehlten Werkzeuge, Abstraktionen und interne Strukturen, um übergeordnete Ziele zu erreichen
• Die Hauptaufgabe des Engineering-Teams verlagerte sich dahin, Agenten in die Lage zu versetzen, nützliche Arbeit zu leisten
• Große Ziele werden in kleinere Bausteine (Design, Code, Review, Test usw.) zerlegt; der Agent setzt diese Bausteine zusammen und löst so komplexere Aufgaben in einer Depth-First-Arbeitsweise
• Bei Fehlschlägen lautet die Kernfrage nicht „mehr anstrengen“, sondern: „Welche Fähigkeit fehlt, und wie machen wir sie für den Agenten lesbar und ausführbar?“
• Menschen interagieren fast vollständig über Prompts mit dem System
  • Sie geben Aufgabenbeschreibungen, starten Agentenläufe und lassen Pull Requests öffnen
• Damit ein PR fertig wird, wird Codex angewiesen, lokale Änderungen selbst zu prüfen, zusätzliche Agent-Reviews lokal und in der Cloud anzufordern, auf Feedback zu reagieren und das zu wiederholen, bis alle Agent-Reviewer zufrieden sind
  • Praktisch eine Ralph-Wiggum-Loop
• Codex nutzt Standard-Entwicklungswerkzeuge wie gh, lokale Skripte und im Repository eingebaute Skills direkt, um Kontext zu sammeln
• Menschliche Pull-Request-Reviews sind möglich, aber nicht verpflichtend; mit der Zeit wurde nahezu die gesamte Review-Arbeit auf Agent-zu-Agent-Interaktion umgestellt

Die Lesbarkeit der Anwendung erhöhen

• Mit steigendem Code-Durchsatz entstand ein Flaschenhals bei der menschlichen QA-Kapazität
• Da Zeit und Aufmerksamkeit von Menschen feste Grenzen sind, wurden Anwendung, Logs und App-Metriken so erweitert, dass Codex sie direkt lesen und verstehen kann
• Über die Funktion App-Start pro git worktree kann Codex für jede Änderung eine eigene Instanz starten und steuern
• Das Chrome DevTools Protocol wurde an die Agent-Runtime angebunden, und es wurden Skills für DOM-Snapshots, Screenshots und Navigationsaufgaben erstellt
  • Dadurch kann Codex Bugs selbst reproduzieren, Fixes verifizieren und direkt über UI-Verhalten nachdenken
• Dasselbe Prinzip wurde auch auf Observability-Tooling angewandt
  • Logs, Metriken und Traces werden Codex über einen pro Worktree temporär bestehenden lokalen Observability-Stack zugänglich gemacht
  • Nach Abschluss der Arbeit werden Logs und Metriken gelöscht
  • Der Agent kann Logs mit LogQL und Metriken mit PromQL abfragen
• Mit diesem Kontext lassen sich Prompts wie „Sorge dafür, dass der Service-Start in unter 800 ms abgeschlossen ist“ oder „Kein Span in vier zentralen User Journeys darf 2 Sekunden überschreiten“ leicht verarbeiten
• Ein einzelner Codex-Lauf kann über 6 Stunden lang an einer Aufgabe arbeiten, oft während Menschen schlafen

Repository-Wissen als System of Record nutzen

• Kontextmanagement ist eine der größten Herausforderungen, wenn Agenten große und komplexe Aufgaben effektiv ausführen sollen
• Eine frühe Erkenntnis: Codex braucht keine 1.000-seitige Anleitung, sondern eine Karte
• Der Ansatz „eine große AGENTS.md“ wurde ausprobiert und scheiterte vorhersehbar
  • Kontext ist eine knappe Ressource: Eine riesige Instruktionsdatei überlagert Aufgabe, Code und relevante Dokumente, sodass Agenten zentrale Constraints übersehen oder auf falsche Constraints optimieren
  • Zu viele Anweisungen sind keine Anweisungen mehr: Wenn alles „wichtig“ ist, ist nichts wirklich wichtig; der Agent betreibt dann lokales Pattern-Matching statt gezielter Exploration
  • Es veraltet extrem schnell: Ein uniformes Riesenhandbuch wird rasch zum Grab veralteter Regeln, und der Agent kann nicht beurteilen, was noch gültig ist
  • Schwer überprüfbar: Ein einzelner Blob eignet sich schlecht für mechanische Checks wie Coverage, Aktualität, Ownership und Querverlinkung; Drift ist unvermeidlich
• Die Lösung: AGENTS.md nicht als Enzyklopädie, sondern als Inhaltsverzeichnis behandeln
• Die Wissensbasis des Repositorys wird im strukturierten Verzeichnis docs/ als System of Record gepflegt
• Eine kurze AGENTS.md (etwa 100 Zeilen) wird in den Kontext eingefügt und dient vor allem als Karte, die auf tiefere und verlässlichere Informationsquellen verweist
• Die Design-Dokumentation ist klassifiziert und indexiert und enthält grundlegende Überzeugungen zum Verifizierungsstatus und zu agentenorientierten Betriebsprinzipien
• Architekturdokumentation liefert die oberste Karte von Domänen und Package-Layering
• Qualitätsdokumentation bewertet jede Produktdomäne und jede Architekturschicht und verfolgt Lücken über die Zeit
• Planung wird als First-Class-Artefakt behandelt
  • Flüchtige, einfache Pläne werden für kleine Änderungen genutzt
  • Komplexe Arbeiten werden in Ausführungsplänen inklusive Fortschritt und Entscheidungslog gespeichert und im Repository abgelegt
  • Laufende Pläne, abgeschlossene Pläne und bekannte technische Schulden werden versioniert am selben Ort abgelegt
• So wird schrittweise Offenlegung möglich: Agenten starten mit kleinen, stabilen Einstiegspunkten ohne Überlastung und arbeiten sich dann weiter vor
• Mechanische Durchsetzung: Dedizierte Linter und CI-Jobs prüfen, ob die Wissensbasis aktuell, querverlinkt und korrekt strukturiert ist
• Ein periodisch laufender „Doc-Gardening“-Agent prüft veraltete oder ungültige Dokumente und öffnet Pull Requests zur Korrektur

Lesbarkeit für Agenten als Ziel

• Weil das Repository vollständig von Agenten erzeugt wurde, ist es vorrangig auf Lesbarkeit für Codex optimiert
• Das Ziel der menschlichen Ingenieure ist, dass der Agent direkt aus dem Repository selbst über die gesamte Business-Domäne nachdenken kann
• Aus Sicht des Agenten existiert praktisch nicht, was im Laufzeitkontext nicht zugänglich ist
  • Google Docs, Chat-Threads und Wissen in den Köpfen von Menschen sind für das System nicht zugänglich
  • Zugänglich sind nur versionierte Artefakte im Repository wie Code, Markdown, Schemas und Ausführungspläne
• Selbst ein in Slack abgestimmtes Architekturmuster ist für Agenten unlesbar, wenn sie es nicht durchsuchen können
• Mehr Kontext für Codex bedeutet nicht, es mit Ad-hoc-Anweisungen zu überladen, sondern die richtigen Informationen zu organisieren und offenzulegen, damit der Agent schlussfolgern kann
• Bessere Ergebnisse entstehen, wenn man den Agenten ähnlich einarbeitet wie ein neues Teammitglied: mit Produktprinzipien, Engineering-Normen und Teamkultur, bis hin zu Emoji-Vorlieben
• Bevorzugt werden Abhängigkeiten und Abstraktionen, die sich im Repository vollständig internalisieren und durchdenken lassen
• „Langweilige“ Technologien sind für Agenten oft leichter zu modellieren, weil sie gute Kopplungseigenschaften, API-Stabilität und Repräsentation im Trainingsmaterial haben
• In manchen Fällen ist es günstiger, dass der Agent Teilfunktionen selbst neu implementiert, statt sich auf undurchsichtiges Upstream-Verhalten öffentlicher Bibliotheken zu verlassen
  • Beispiel: Statt eines generischen p-limit-artigen Pakets wurde ein eigener Helper für Map-with-Concurrency gebaut, eng mit OpenTelemetry-Instrumentierung integriert, mit 100 % Testabdeckung und exakt dem erwarteten Laufzeitverhalten
• Je stärker das System in eine Form gebracht wird, die Agenten inspizieren, verifizieren und direkt ändern können, desto größer wird die Hebelwirkung nicht nur für Codex, sondern auch für andere Agenten wie Aardvark

Architektur und Präferenzen durchsetzen

• Dokumentation allein reicht nicht aus, um eine von Agenten erzeugte Codebasis vollständig konsistent zu halten
• Durch Durchsetzung von Invarianten ohne Mikromanagement der Implementierung kann der Agent schnell liefern, während das Fundament stabil bleibt
  • Beispiel: Man wollte, dass Codex Datenformen an den Grenzen parst, legte aber nicht genau fest, wie das geschehen soll oder welche Library zu verwenden ist; das Modell tendiert zu Zod
• Agenten arbeiten am besten in Umgebungen mit strengen Grenzen und vorhersehbarer Struktur
• Die Anwendung wurde um ein strenges Architekturmodell herum aufgebaut
  • Jede Business-Domäne ist in einen festen Satz von Schichten getrennt, mit streng validierter Abhängigkeitsrichtung und einem begrenzten Satz erlaubter Kanten
  • Code fließt in der Reihenfolge Types → Config → Repo → Service → Runtime → UI
  • Querschnittsthemen wie Authentifizierung, Konnektoren, Telemetrie und Feature Flags werden ausschließlich über eine explizite Schnittstelle namens Providers eingebracht
  • Alles andere ist nicht erlaubt und wird mechanisch durchgesetzt
• Diese Constraints werden über maßgeschneiderte Linter und strukturelle Tests durchgesetzt, die von Codex erzeugt wurden
• Ein solches Architekturniveau wird oft bis zu Organisationen mit Hunderten von Ingenieuren aufgeschoben, ist für Coding-Agenten aber eine frühe Voraussetzung
• Maßgeschneiderte Lints setzen strukturiertes Logging, Benennungsregeln für Schemas und Typen, Dateigrößenlimits und plattformspezifische Stabilitätsanforderungen statisch durch
  • Weil die Lints maßgeschneidert sind, können Fehlermeldungen so formuliert werden, dass sie direkte Reparaturanweisungen in den Agentenkontext einspeisen
• In menschenzentrierten Workflows mögen solche Regeln übertrieben detailreich oder einschränkend wirken, beim Einsatz von Agenten vervielfacht sich ihre Wirkung jedoch
• Constraints trennen klar, was wichtig ist und was nicht
  • Das ähnelt dem Betrieb einer großen zentralen Engineering-Plattformorganisation: zentral Grenzen setzen, lokal Autonomie erlauben
• Der resultierende Code entspricht nicht immer den stilistischen Vorlieben von Menschen, aber wenn die Ausgabe korrekt, wartbar und für Agentenläufe gut lesbar ist, ist das Kriterium erfüllt
• Menschliche Präferenzen fließen fortlaufend als Feedback ins System zurück
  • Review-Kommentare, Refactoring-PRs und nutzerseitige Bugs werden als Dokumentationsupdates festgehalten oder direkt ins Tooling kodiert
  • Wenn Dokumentation nicht ausreicht, wird die Regel in Code überführt

Ein Wandel in der Merge-Philosophie

• Mit steigendem Durchsatz von Codex können klassische Engineering-Normen sogar kontraproduktiv werden
• Das Repository wird mit minimalen blockierenden Merge-Gates betrieben
• Pull Requests leben kurz, und Test-Instabilität wird eher durch Folgeläufe gelöst als den Fortschritt unbegrenzt zu blockieren
• In Systemen, in denen Agentendurchsatz menschliche Aufmerksamkeit weit übersteigt, sind Fix-Kosten niedrig und Wartezeiten teuer
• Für Umgebungen mit geringem Durchsatz ist das möglicherweise nicht geeignet; es braucht den passenden Kompromiss

Der tatsächliche Umfang von „agentenerzeugt“

• Dass die Codebasis von Codex-Agenten erzeugt wurde, bedeutet wirklich alles, was sich in der Codebasis befindet
  • Produktcode und Tests
  • CI-Konfiguration und Release-Tooling
  • Interne Entwicklertools
  • Dokumentation und Design-Historie
  • Evaluierungs-Harnesses
  • Review-Kommentare und Antworten
  • Skripte zur Verwaltung des Repositorys selbst
  • Definitionsdateien für Produktions-Dashboards
• Menschen bleiben immer im Loop, arbeiten aber auf einer anderen Abstraktionsebene als früher
  • Sie priorisieren Arbeit, übersetzen Nutzerfeedback in Akzeptanzkriterien und validieren Ergebnisse
• Wenn Agenten Schwierigkeiten haben, wird das als Signal verstanden, um fehlende Werkzeuge, Guardrails oder Dokumentation zu identifizieren; die Korrekturen werden dann immer von Codex selbst geschrieben und zurück ins Repository gegeben
• Agenten holen Review-Feedback ab, antworten inline, pushen Updates und können ihre eigenen Pull Requests sogar squashen und mergen

Wachsende Autonomiegrade

• Da mehr Entwicklungsloops wie Test, Verifikation, Review, Feedback-Verarbeitung und Recovery direkt im System kodiert werden, wurde ein wichtiger Schwellenwert erreicht
• Dinge, die ein Agent nun auf einen einzigen Prompt hin ausführen kann:
  • Den aktuellen Zustand der Codebasis verifizieren
  • Einen gemeldeten Bug reproduzieren
  • Ein Video aufnehmen, das den Fehlerzustand demonstriert
  • Einen Fix implementieren
  • Die Anwendung starten und den Fix verifizieren
  • Ein zweites Video aufnehmen, das die Lösung zeigt
  • Einen Pull Request öffnen
  • Auf Feedback von Agenten und Menschen reagieren
  • Build-Fehler erkennen und beheben
  • Nur dann an Menschen eskalieren, wenn Urteilskraft erforderlich ist
  • Die Änderung mergen
• Dieses Verhalten hängt stark von der spezifischen Struktur und dem Tooling dieses Repositorys ab und sollte nicht ohne ähnliche Investitionen als verallgemeinerbar angenommen werden

Entropie und Garbage Collection

• Vollständige Autonomie von Agenten erzeugt neue Probleme: Codex repliziert Muster, die bereits im Repository vorhanden sind, auch wenn sie inkonsistent oder suboptimal sind; dadurch entsteht mit der Zeit unvermeidlich Drift
• Anfangs wurde das manuell aufgefangen; jeden Freitag, also 20 % der Woche, wurde Zeit für das Aufräumen des „AI slop“ verwendet
  • Wie zu erwarten war, ließ sich das nicht skalieren
• Als Alternative wurden „goldene Regeln“ direkt im Repository kodiert und ein regelmäßiger Aufräumprozess aufgebaut
  • (1) Statt selbstgebauter Helper werden gemeinsam genutzte Utility-Pakete bevorzugt, um Invarianten zentral zu halten
  • (2) Daten werden nicht im „YOLO-Stil“ exploriert; stattdessen werden Grenzen validiert oder typisierte SDKs genutzt, damit Agenten nichts versehentlich auf Basis erratener Formen bauen
• Es laufen Codex-Hintergrundjobs, die regelmäßig auf Abweichungen prüfen, Qualitätsbewertungen aktualisieren und gezielte Refactoring-PRs erzeugen
  • Die meisten davon lassen sich in unter einer Minute reviewen und automatisch mergen
• Das funktioniert wie Garbage Collection: Technische Schulden sind wie Hochzinsdarlehen; am effektivsten ist es, sie kontinuierlich in kleinen Beträgen abzutragen, bevor sich Zinsen anhäufen
• Sobald menschliche Präferenzen einmal erfasst sind, werden sie fortlaufend auf jede Codezeile angewandt, und schlechte Muster werden täglich erkannt und behoben, statt sich über Tage oder Wochen auszubreiten

Laufende Erkenntnisse und künftige Aufgaben

• Diese Strategie hat sich bei OpenAI bis zur internen Auslieferung und Einführungsphase bewährt
• Der nächste Schritt ist, die Investition durch echte Produkte für echte Nutzer in der Praxis zu verankern und langfristige Wartbarkeit sicherzustellen
• Noch offen ist, wie sich architektonische Konsistenz über Jahre hinweg in einem vollständig agentenerzeugten System entwickelt
• Es wird weiterhin gelernt, wo menschliches Urteilsvermögen den größten Hebel hat und wie sich dieses Urteil so kodieren lässt, dass es sich kumulativ nutzen lässt
• Auch wie sich dieses System mit weiter steigenden Modellfähigkeiten entwickeln wird, ist noch unklar
• Für den Bau von Software braucht es weiterhin Disziplin, aber sie zeigt sich zunehmend eher im Scaffolding als im Code
• Tooling, Abstraktionen und Feedback-Loops, die die Konsistenz der Codebasis erhalten, werden immer wichtiger
• Die derzeit schwierigste Aufgabe ist das Design von Umgebungen, Feedback-Loops und Kontrollsystemen, die Agenten dabei helfen, komplexe, stabile Software im großen Maßstab zu bauen und zu warten

[ragingwind]

40 Tage, 1 Million Zeilen, 13 Milliarden Token — Lablup-CEO Shin Jeong-gyu entdeckt die Realität agentischer Workflows - Park Jae-hongs Silicon Valley - https://wikidocs.net/blog/@jaehong/8206/