Agent Operable Codebase

Image: AI generated

Eine Frage

Oeffnet die laengste Datei in eurem Projekt. Wie viele Funktionen stecken darin?

Lasst einen KI-Agenten eine Funktion in dieser Datei aendern. Der Agent liest die gesamte Datei. Er hat sie wegen einer Funktion geoeffnet, aber 19 unnoetige Funktionen kommen mit.

Hier beginnt das Problem.

Code, den Menschen lesen. Code, mit dem Agenten arbeiten

Bisher wurde Code fuer Menschen geschrieben. Gute Variablennamen, Kommentare, Dokumentation – alles um die kognitive Last des Menschen zu reduzieren.

Im Zeitalter der Agenten aendert sich die Frage. Ist Code, der fuer Menschen gut lesbar ist, derselbe wie Code, mit dem ein Agent gut arbeiten kann?

Nein.

Menschen scrollen durch eine 2.000-Zeilen-Datei und die Intuition sagt: “Diesen Teil nicht anfassen.” Ein Agent hat diese Intuition nicht. 2.000 gelesene Zeilen bedeuten 1.950 Zeilen Kontextverschmutzung.

Forschung bestaetigt dies. Wenn irrelevante Informationen beigemischt werden, sinkt die KI-Leistung um 30~85 %. Selbst wenn die unnuetzen Token Leerzeichen sind, verschlechtert sich die Leistung. Je kuerzer der Kontext, desto besser – das ist keine Intuition, sondern ein Experimentergebnis.

Stellt keinen Roboter in ein Menschenbuero. Baut eine Fabrik, in der der Roboter arbeiten kann.

Drei Dinge, die ein Agent braucht

Damit ein Agent stabil an einer Codebasis arbeiten kann, muessen drei Bedingungen erfuellt sein.

1. Lesen koennen – ohne Rauschen

Eine Datei, ein Konzept. Der Dateiname ist der Konzeptname.

before: read utils.go → 20 Funktionen, 19 unnoetig
after:  read check_one_file_one_func.go → 1 Funktion, genau das Benoetigte

filefunc loest dieses Problem. 22 Strukturregeln trennen Code in semantische Einheiten. Im Hono-Framework (star 23k+) wurden 186 Dateien in 626 aufgeteilt. 4.419 Tests, keiner ist gebrochen. Die Dateizahl stieg um den Faktor 3,4, aber keine einzige Zeile Logik hat sich geaendert.

“Werden es nicht zu viele Dateien?” – Agenten oeffnen keine Verzeichnisse. Sie suchen. Ob 500 oder 1.000 Dateien – ein einziger grep reicht. Wichtiger als die 5 noetigen zu greifen ist es, die 295 unnuetzen nicht zu oeffnen.

2. Pruefen koennen – mechanisch

Wenn eine Funktion ohne Tests geaendert wird, weiss niemand, was kaputtgeht. Der Agent auch nicht. Er landet im doom loop.

before: 0 Tests, unklar was bei Aenderung kaputtgeht
after:  527 Funktionen mit Tests, Verhaltensaenderungen sofort erkannt

tsma loest dieses Problem. Es indiziert alle Funktionen des Projekts, erkennt das Vorhandensein von Tests, misst die Abdeckung und gibt Zeilennummern fuer ungedeckte Zweige zurueck.

Ohne Feedback stoppt die Abdeckung bei 60~70 %, wenn man das LLM Tests schreiben laesst. Sagt man “line 41, 44, 70 nicht abgedeckt”, erreicht sie 100 %. Dasselbe Modell. Der Unterschied: nur die Aufloesung des Feedbacks.

Im Experiment mit einem Projekt von 527 Funktionen: TODO erreichte 0. Der autonome Agent blieb bei 40 stehen und erklaerte “alles fertig.” Mit Ratchet wurden alle 527 abgeschlossen.

3. Spezifikationen muessen kreuzvalidierbar sein

API-Schema, DB-Schema, Sicherheitsrichtlinien und Zustandsuebergaenge muessen mechanisch auf Konsistenz pruefbar sein. Wenn eines geaendert wird, muss vor der Kompilierung erkennbar sein, ob ein Widerspruch entsteht.

before: 200 Endpunkte, Spezifikationskonsistenz wird vom Menschen geprueft
after:  eine operationId verkettet alle Schichten, die Maschine erkennt Drift

yongol loest dieses Problem. 10 SSOT (OpenAPI, DDL, sqlc, SSaC, Rego, Hurl u.a.) werden ueber eine operationId verkettet und mit ~287 Regeln kreuzvalidiert. user_id ist in OpenAPI ein string, in DDL ein BIGINT – solche Widersprueche zwischen Schichten fangen bestehende Werkzeuge nicht.

Eine Struktur, die drei Werkzeuge durchzieht

filefunc, tsma, yongol sind unabhaengige Werkzeuge, aber sie teilen eine gemeinsame Struktur.

filefunc:  22 Strukturregeln → validate → korrigieren → wiederholen
tsma:      Abdeckung messen → Feedback zu ungedeckten Zweigen → korrigieren → wiederholen
yongol:    Kreuzvalidierung → Drift erkennen → korrigieren → wiederholen

Ueberall dieselbe Schleife.

Das LLM generiert → ein deterministisches Werkzeug urteilt → das Ergebnis geht an das LLM zurueck → wiederholen

Symbolic Feedback Loop. Eine zyklische Struktur, in der ein deterministisches Werkzeug die probabilistische Erzeugung des LLM korrigiert. Nicht KI verifiziert KI, sondern die Maschine verifiziert KI.

Gebt eine Meinung, und er schmeichelt. Gebt einen Fakt, und er korrigiert. Fragt “Ist der Code okay?” und er antwortet “Ja, sieht gut aus.” Sagt “line 41: field name mismatch” und er behebt es sofort. Feedback ohne Schmeichelobjekt – weil Zahlen und Positionen keine Emotionen sind.

Vom Legacy zum Agent-Operable

Die bestehende Codebasis muss nicht auf einmal umgebaut werden. Das ist kein Neubau des Fundaments, sondern eine Erdbebenertuechtigung. Das Gebaeude wird verstaerkt, ohne den laufenden Laden zu schliessen.

Stufe 1 – Lesbar machen

Beginnt mit der laengsten Datei. Fuehrt filefunc validate aus und bringt die Verstoesse auf 0. Alle bestehenden Tests muessen bestehen.

Stufe 2 – Pruefbar machen

Wiederholt tsma next. Fuegt Tests fuer ungetestete Funktionen hinzu, fuellt ungedeckte Zweige. Stirbt der Agent mittendrin, bleibt der Fortschritt erhalten. Ein neuer Agent fuehrt tsma next aus und macht weiter.

Stufe 3 – Kreuzvalidieren

Fuehrt SSOT ein und startet yongol validate. Die Maschine faengt Widersprueche zwischen Schichten.

Jede Stufe ist unabhaengig. Man kann Stufe 2 ohne Stufe 1 machen oder Stufe 1 ohne Stufe 2. Aber wenn alle drei zusammenkommen, waechst der Bereich autonomer Arbeit des Agenten sprunghaft.

Das Betriebssystem wechseln

Eine agent-operable Codebasis ist nicht einfach Lint oder Tooling. Es ist ein Wechsel des Betriebssystems der Codebasis.

Viele Leute machen den Zug schneller. Groessere Modelle, kluegere Agenten, bessere Prompts.

Je schneller der Zug, desto wichtiger die Schienen. Menschen, die Schienen verlegen, gibt es bisher kaum.

Verwandte Artikel

• filefunc – Eine Datei, ein Konzept – Eine Code-Struktur-Konvention, die LLM-Kontextverschmutzung mit 22 Strukturregeln beseitigt
• tsma – Die Verteidigungslinie gegen Regressionen in Legacy-Code – Ratchet-basierte Testautomatisierung: 527 Funktionen bis TODO 0
• Warum Coding-Agenten funktionieren und warum sie scheitern – Strukturelle Analyse des Symbolic Feedback Loop
• Feedback-Topologie statt Modell-IQ – Warum dasselbe Modell bei 40 stoppt oder 527 abschliesst
• whyso – Was git blame nicht zeigt – Automatische Extraktion der Aenderungshistorie pro Datei

Quellen

• Stanford, “Lost in the Middle: How Language Models Use Long Contexts” (2024) – Leistungsabfall von 30%+ wenn relevante Information in der Mitte des Kontexts vergraben ist
• Amazon, “Context Length Alone Hurts LLM Performance” (2025) – Leistungsabfall von 13,9~85 % selbst wenn unnuetze Token Leerzeichen sind
• Empirischer Nachweis am Hono-Framework – 186 Dateien → 626 Dateien, alle 4.419 Tests bestanden
• Empirischer Nachweis tsma, 527 Funktionen – PASS 246 (46,7 %), DONE 281 (53,3 %), TODO 0
• Ratchet Pattern-Experiment – Autonomer Agent 40/527 (7,6 %) vs Ratchet-CLI 527/527 (100 %)