Warum gehen KI-Agenten in alten Codebasen schief? Ein System, das seit Jahren läuft, lässt sich nicht mehr vollständig aus seinem Repository ablesen. Der Code ist die halbe Wahrheit. Die andere Hälfte steckt in Köpfen, in Tickets, in improvisierten Notlösungen und in Erwartungen, die andere Teams an dieses System richten.
Der Entwickler Addy Osmani, der viele Jahre in solchen Teams gearbeitet hat, beschreibt diese Lage in seinem Newsletter: Das Repository beschreibt nicht mehr das tatsächliche Verhalten. Institutionelles Wissen, Flickschusterei, alte Dienste und Zusagen an andere Abteilungen leben außerhalb des Verzeichnisbaums. Wer dort neuen Code schreibt, muss diese unsichtbaren Randbedingungen erst kennenlernen und danach belegen, dass er sie nicht verletzt hat.
Beim Brownfield Agentic Engineering geht es darum, KI-Agenten in eine gewachsene Codebasis zu bringen, ohne dass aus Tempo technische Schulden werden. Zwei Ziele zählen. Versteckte Zwänge sichtbar machen, und billige Änderungen vertrauenswürdig machen. Beides klingt bescheiden. Beides ist die Arbeit. Es geht nie um einen Neuanfang, sondern um sicheren Umgang mit Legacy Code bei laufendem Betrieb.
Warum Agenten in gewachsenen Codebasen falsch abbiegen
Man kann sich eine alte Codebasis wie eine gewachsene Stadt vorstellen. Es gibt Viertel aus den Neunzigern, in denen die Leitungen niemandem mehr gehören, der heute noch im Team ist. Es gibt Straßen, die offiziell gesperrt sind und trotzdem jeden Tag befahren werden, weil irgendein Prozess von dort kommt. Und es gibt Gegenden, in denen du ohne Begleitung nicht gräbst, weil dort die Versorgung für alles andere liegt.
Der Autor beschreibt, dass Agenten in dieser Umgebung gerne etwas abliefern, das funktioniert, aber die falsche Systemarchitektur hat und dazu brüchige Tests. Der Grund ist kein böser Wille des Modells. Ein Agent optimiert auf ein sichtbares Ziel, etwa einen grünen Testlauf oder eine formal erfüllte Anforderung, und nicht auf das, was ein Team unter gutem Design versteht.
Das Problem ist älter als die KI. Auch vorher liefen Modernisierungen in kleinen Stücken, mit starker Testabdeckung und einer dicken Schicht aus Vertrauen, damit niemand versehentlich etwas zerstört. Auf jede Nutzerreise folgte eine Batterie wiederholbarer Tests, die belegen sollte, dass sich das Verhalten nicht verschoben hat. Manche sagen heute, man sei schon im Brownfield-Modus, sobald ein Agent Code abliefert, den man nicht mehr Entscheidung für Entscheidung selbst geschrieben hat. Der Punkt stimmt, verschiebt aber nur die Frage: Wie organisierst du Änderungen so, dass sie billig bleiben?
Zonen, Blast Radius und wer die Landkarte zeichnet
Der Autor schlägt vor, die Codebasis in Zonen einzuteilen. Grün heißt: gute Tests, aktuelle Konventionen, saubere Isolation, dort darf ein Agent in einer engen Schleife arbeiten. Gelb heißt gemischte Qualität, dort wird zuerst ein Charakterisierungstest geschrieben und dann geändert. Rot heißt sensibel: Authentifizierung, Abrechnung, Berechtigungen, Lohnabrechnung. Überall dort, wo nur wenige Personen verstehen, wie es funktioniert, willst du keinen unbeaufsichtigten Umbau.
Typisch dafür sind Commerce-Landschaften. Fünf oder sechs Abteilungen betreiben ihre eigenen Mikroseiten, für den Nutzer fühlt sich alles wie ein einziger Auftritt an. Unter der Oberfläche steckt erhebliche Komplexität, und die eine Abteilung hat gute Tests, weil ihr Teil erst vor wenigen Jahren gebaut wurde, die andere womöglich nicht. Solche Unterschiede lassen sich nicht weglächeln, deshalb ist eine Karte nützlich.
Drei Regeln machen aus der Zonenidee ein Verfahren statt einer Metapher. Erstens: Ein Mensch zeichnet die Karte, nicht der Agent, denn überlässt man ihm die Wahl, beginnt er in der furchteinflößendsten Datei, weil dort die interessantesten Namen stehen. Zweitens: Zonen wandern nur, wenn sie es verdient haben; aus Gelb wird Grün, sobald Charakterisierungstests existieren und der Verantwortliche des Moduls die ersten Agentenänderungen geprüft hat. Drittens: Die Zone legt die Verben fest, Grün ist die enge Schleife, Gelb ist Test zuerst, Rot ist menschliche Begleitung bei jedem Schritt oder die Arbeit findet nicht statt. Autonomie folgt dem Blast Radius, also dem Ausmaß der Schäden bei einem Fehler, außerdem der Beobachtbarkeit und der Umkehrbarkeit. Die Selbstsicherheit eines Modells ist dafür ein schlechter Kompass.
Wie viel die Auswahl der richtigen Datei wert ist, zeigt ein Bericht von Teleport, der als bezahlte Anzeige in Osmanis Beitrag steht. Das Unternehmen richtete demnach ein Quartal lang die stärksten Modelle auf die eigene Codebasis, mit dreizehn Ingenieuren im Rücken. Es entstand ein ordentlicher Harness: Der Code wurde in Komponenten zerlegt, Agenten liefen darüber, skeptische Prüfer und Richter stritten über die Funde. Am Ende verlor dieser Aufbau gegen eine Person, die eine einzelne Datei öffnete und schrieb: Du bist in einem CTF, finde eine kritische Schwachstelle, fang hier an. Die schwere Frage ist offenbar nicht das Suchen, sondern das Wissen, welche Datei man öffnet. Schwachstellen in Brownfield-Codebasen zu finden heißt zuerst, den richtigen Ort zu kennen.
Was der Code nicht über sich selbst sagen kann
Wenn der Code die Quelle der Wahrheit ist, muss das Drumherum nur enthalten, was sich aus dem Code nicht ableiten lässt. Agenten finden erstaunlich viel über die Landkarte eines Systems selbst heraus. Es gab eine Phase, in der Teams Markdown-Dateien über alles schrieben und sie in das Kontextfenster stopften, meist vergeudeter Platz. Wertvoll sind die Dinge, die nirgends im Code stehen: team- und geschäftsspezifische Feinheiten, Kompromisse, die erklären, warum ein System so aufgebaut ist, Regeln, die keine statische Analyse erzwingt, und der historische Kontext hinter kontraintuitiven Implementierungen. Schreib auf, was der Code nicht sagen kann, und sonst nichts.
Für Gelb- und Rotarbeit empfiehlt der Autor einen separaten, nur lesenden Durchgang, der ein kurzes Verständnis-Memo erzeugt: Einstiegspunkte, Verantwortliche, Aufrufer, vorhandene Abstraktionen, Tests, Produktionssignale, relevante Vorgeschichte und offene Fragen. Jede Behauptung soll eine Datei, ein Ticket, eine Zuständigkeit oder ein Dashboard zitieren. Ohne dieses Artefakt zahlt der nächste Agent dieselbe Archäologie noch einmal. Der Agent versteht, wie der Auth-Flow läuft, erledigt seine Aufgabe und verliert dieses Verständnis, sobald die Sitzung endet. Der Chatverlauf ist kein gutes Archiv, besonders nicht, nachdem das Kontextfenster zusammengefasst wurde.
Nach der Recherche beginnt die Planung mit frischem Kontext. Welche Dateien berühren die plausiblen Wege? Welche Invarianten, also Zusicherungen, die immer gelten müssen, erhalten sie? Und wie würde man die Änderung wieder rückgängig machen? Den Pfad wählt ein Mensch. Wenn die Umsetzung merkt, dass die Karte falsch war, hält sie an, statt sich durchzuwurschteln. Die Prüfung startet später ebenfalls ohne Vorwissen und arbeitet rückwärts von den Abnahmekriterien. Ein unbeeinflusster Prüfer merkt eher, wenn ein Test die Implementierung belegt und die eigentliche Anforderung verfehlt.
Charakterisierungstests: Verhalten festnageln, bevor es besser wird
Wer KI-Agenten in Brownfield-Projekten einsetzt, sollte mit Arbeiten beginnen, die kein Risiko tragen. Nicht der Monolith in Rust, sondern: erst erklären lassen, wie die Dinge funktionieren, und dann Tests erzeugen, die das heutige Verhalten festhalten. Charakterisierungstests sind automatisierte Tests, die dokumentieren, was ein Modul heute tatsächlich tut, hässliche Stellen inklusive. In einem alten System ist ein Teil dieser Hässlichkeit genau das, wovon das Geschäft lebt. Ein Agent wird sie mit Freude reparieren, hinter einem grünen Testlauf.
Deshalb gilt eine Regel: Der Agent darf nicht in derselben Sitzung der einzige Autor der Tests sein, die er bestehen soll. Erst das Verhalten festnageln, in einem getrennten Durchgang oder von einem Menschen. Sonst entsteht eine grüne Suite, die genau jene Implementierung zementiert, die gerade erfunden wurde. Dieses Muster hat industrielle Vorbilder: Netflix nutzte beim Umstieg auf GraphQL dieselbe Idee, spiegelte Verkehr gegen alte und neue Pfade, verglich die Antworten und beförderte nur, was übereinstimmte. Wenn eine Oberfläche wie eine Startseite keine ehrliche Unit-Test-Suite hat, ist das der richtige Weg: nicht raten, sondern beides laufen lassen und vergleichen.
Danach folgen die mechanischen Umbauten: tote Codepfade, ungenutzte Exporte, Inventare. Der Autor rät ausdrücklich davon ab, mit den haarigsten Stellen zu beginnen. Er erinnert sich an eine Codebasis bei AOL, an einen freien Tag, an eine Nachricht des Vorgesetzten. Die Startseite lag komplett daneben, und es gab nicht genug JavaScript-Fachleute im Haus, um das kurzfristig zu durchdringen. Selbst bei offensichtlich defekten Dingen arbeiteten die Beteiligten mit großer Vorsicht. Das ist keine Nostalgie. Es ist die Erwartungshaltung, die man einem System entgegenbringt, das viele Menschen täglich benutzen.
Vom wiederholten Review-Kommentar zum Harness
Es hilft, die Werkzeugebenen sauber zu trennen. Anweisungen halten ungewöhnliche Fakten über ein Repository fest. Skills bündeln wiederverwendbare Abläufe, etwa das Prüfen des Blast Radius oder die Verifikation einer Schemaänderung. Plugins können geregelten Zugang zum Zuständigkeitskatalog, zum Incident-Archiv oder zu Dashboards geben. Der Harness ist die Arbeitsumgebung um den Agenten herum: Kontext, Werkzeuge, Berechtigungen, Tests, Logs und der Weg zurück. Eine Fabrik schließlich taktet viele verlässliche Schleifen, hält Zustand dauerhaft und gibt neue Fälle an Menschen zurück.
Der praktische Test ist die Frage, was passiert, wenn der Agent etwas falsch macht. Repariert man die Änderung still, wiederholt die nächste Sitzung denselben Fehler. Taucht derselbe Review-Kommentar ein zweites Mal auf, gehört er in eine Lint-Regel, einen Hook, einen Typ, einen Test oder einen Skill. Prosa bleibt für Zwänge, die sich nicht mechanisch erzwingen lassen. Eine Verbotsregel, ein eng begrenzter Zugangsschlüssel oder eine CI-Prüfung müssen sich nichts merken. Mit der Zeit wird der Harness zu einer Sammlung von Fehlern, die das Team beschlossen hat, nicht zweimal zu bezahlen.
Das ist auch die Antwort auf die Frage, wie Code-Verifikation in solchen Umgebungen skaliert. Mehr Zutrauen in das Modell hilft dabei nicht. Mehr Struktur um das Modell herum schon. Jede wiederholte Korrektur ist ein Hinweis auf ein fehlendes Stück Werkzeug. Wer diese Hinweise ernst nimmt, baut sich mit der Zeit eine Umgebung, in der Tests nicht nur grün leuchten, sondern etwas bedeuten.
Wie ein Einstieg in die eigene Codebasis aussieht
Für den Anfang braucht es keinen großen Umbau. Teile die Codebasis grob in Zonen ein und markiere, welche Bereiche niemand ohne Not anfassen sollte. Lass einen Agenten die Landkarte beschreiben und prüfe, wo er sich irrt. Schreibe ein Memo für Gelb und Rot, mit Belegen aus Dateien, Tickets und Dashboards. Und erzeuge für einen kleinen, gut abgegrenzten Teil Charakterisierungstests, bevor irgendjemand diesen Teil verbessern möchte.
Das bremst nicht. Es ist der Preis für Geschwindigkeit, die man behalten kann. Agentic Engineering in alten Codebasen funktioniert nicht, weil die Modelle plötzlich klug genug wären. Es funktioniert, wenn das Team vorher die unsichtbaren Zwänge sichtbar gemacht hat und danach jede Änderung belegen kann. Technische Schulden bei der Softwaremodernisierung vermeiden heißt genau das: früh festhalten, was gilt, und später nur das verbessern, was abgesichert ist.
Wer es nicht ernst nimmt, bekommt Code, der läuft, und eine Rechnung, die später kommt. Sie besteht aus technischen Schulden, die irgendwann niemand mehr auseinanderhalten kann. Die alten Systeme sind nicht deshalb alt, weil niemand etwas verstanden hätte. Sie sind alt, weil ihre Zwänge nie vollständig aufgeschrieben wurden. Das lässt sich heute mit Agenten nachholen. Man muss ihnen nur die Rolle geben, die zu ihnen passt: kein Architekt der Landkarte, sondern ein Arbeiter auf einem Terrain, das ein Mensch vermessen hat.
Quelle: addyo.substack.com
