Zum Inhalt springen
Matthias Bohlen

Ihr Coding-Agent kopiert Ihren schlechtesten Code

Coding-Agenten kopieren die Architektur, die sie sehen. Welche Architekturfakten Sie festhalten sollten, als Qualitätsattribute, Grenzen und ADRs, und wie Sie die Wirkung testen.

Softwarearchitektur · Software-Gießerei · Architekturdokumentation

Video abspielen
Beim Abspielen verbindet sich Ihr Browser mit YouTube.

In Archilab ausprobieren ↗

Das Video ist auf Englisch. Das Transkript unten ist eine Übersetzung.

Der Diff, der in Ordnung aussah

Das ist ein konkreter Diff aus einem meiner Beispielprojekte. Der Coding-Agent hat ein Feature ergänzt, die Tests laufen durch, der Typecheck ist sauber, das Review sah gut aus. Aber der neue Code im Billing-Modul importiert den Datenspeicher aus dem Orders-Modul und liest die Bestellungen direkt aus dem Datenspeicher des anderen Moduls.

War der Code schlecht? Nein, er war korrekt, lesbar und getestet. Nur hat dem Agenten niemand gesagt, dass dieser Aufruf verboten ist.

In einem Kundenprojekt ist das mehr als einmal passiert. Und als ich dieselbe Aufgabe 5 frischen Agent-Sessions gegeben habe, ist es ebenfalls 5 von 5 Mal passiert. Ich zeige Ihnen, was es tatsächlich verhindert hat.

Nach dieser Episode können Sie sich die schlechte Ausgabe eines Agenten ansehen und fragen, welcher Architekturfakt eigentlich gefehlt hat. Sie können diesen Fakt dann dort aufschreiben, wo der Agent ihn liest. Sie sehen ein kleines, konkretes Setup und eine Möglichkeit zu testen, ob es funktioniert: dieselbe Aufgabe, dasselbe Modell, derselbe Prompt, mehrfach ausgeführt, vorher und nachher.

Agenten kopieren, was sie sehen

Hier hat mich etwas überrascht. In der sauberen Version meines Beispiels hat der Agent diesen Fehler nicht gemacht. Fünf von fünf Sessions haben Billing aus den Daten von Orders herausgehalten, ohne dass man es ihnen gesagt hat. Sauberer Code trägt seine Architektur tatsächlich in sich, und der Agent liest sie.

Also habe ich eine Sache geändert. Ich habe die Codebasis so aussehen lassen wie eine echte nach ein paar Jahren, in der jemand schon eine Abkürzung genommen hat. Hier im Users-Modul wurde der Orders-Datenspeicher direkt importiert, um die Bestellanzahl des Benutzers zu lesen. Die Bestellanzahl wird hier unten direkt per Zugriff auf den Orders-Datenspeicher gelesen. Und niemand hat dem Entwickler gesagt, dass das ein Fehler war, und es stand auch nirgends geschrieben.

Das sind die Diffs der Agenten, die an dem Code gearbeitet haben. Auf diesem erodierten Code hat jede Session die Abkürzung kopiert. Drei haben sie sogar hübsch verpackt: einen Port in Billing plus einen Adapter in Billing, der Orders importiert. Das sieht aus wie Ports and Adapters, aber die Abhängigkeit zeigt in die falsche Richtung. Die Tests waren jedes Mal grün.

Die meiste schlechte Agentenausgabe ist eine lokal korrekte Lösung. Der Agent folgt dem Präzedenzfall, den er im Code findet, und nur das Team weiß, dass dieser Präzedenzfall falsch ist.

Der Agent sieht die Dateien, die er öffnet, nicht Ihre Geschichte. Qualitätsattribute, Context-Grenzen und verworfene Optionen leben in den Köpfen, in Wikis, die niemand öffnet, und in alten Meetings.

Ein Beispiel: Ein Agent verletzt die Grenze, wir korrigieren das im Review, in der nächsten Session verletzt er sie wieder. Korrekturen im Chat verschwinden mit der Session. Nur was im Repository steht, bleibt.

Sie könnten jetzt sagen: „Ein besseres Modell wird die Architektur in Zukunft ableiten.“ Auf sauberem Code tut es das schon, aber es kann nur ableiten, was der Code zeigt. Sobald der Code Ihrer Absicht widerspricht, kann der Agent die Regel nicht von der Ausnahme unterscheiden, und er weiß nicht, warum Billing keine Daten aus Orders lesen darf.

Was Sie aufschreiben sollten

Drei Arten von Wissen verändern die Agentenausgabe am stärksten: Qualitätsattribute, Context-Grenzen und Entscheidungen mit ihren Gründen.

Qualitätsattribute sollten Sie als testbare Aussagen formulieren. Nicht nur „unser System muss richtig schnell und skalierbar sein“, sondern „300 Millisekunden für den Checkout in 95 % der Fälle, unter normaler Last“. Billing lässt sich ohne Orders deployen. Das leitet den Agenten. „Skalierbar“ allein tut das nicht.

Bounded Contexts: Benennen Sie sie, listen Sie auf, wer mit wem sprechen darf, und sagen Sie, wie, etwa über Events oder APIs, niemals über den Datenspeicher des anderen Moduls. Ein Absatz und ein kleines Diagramm in Textform.

Und ADRs: Kontext, Entscheidung, Konsequenzen und vor allem die verworfenen Alternativen. Sonst schlägt der Agent die verworfene Alternative wieder vor, und zwar selbstsicher. Und in einer erodierten Codebasis steht die verworfene Alternative oft direkt im Code und wartet darauf, kopiert zu werden.

Ein Beispiel: das ADR für mein Beispielprojekt. Billing liest Bestelldaten nur über einen eigenen Port. Ich verwende das Y-Statement-Format, einen sechsteiligen Satz. Er liest sich so. Im Kontext der Rechnungsstellung für Bestellungen, angesichts der Anforderungen, mit denen wir es zu tun haben, nämlich getrennte Releases von Billing und Orders auf der einen und getrennte Datenhoheit auf der anderen Seite. Was haben wir entschieden? Wir haben uns für einen Port in Billing entschieden, den die Composition Root aus der öffentlichen API des Orders-Moduls befüllt, und wir haben andere Optionen verworfen, etwa dass Billing den Orders-Store importiert oder dass ein Adapter innerhalb von Billing Orders importiert. Wir wollen erreichen, dass Billing ohne Orders deployt werden kann, und nehmen dafür eine zusätzliche Funktion für die Verdrahtung in Kauf.

Sie könnten sagen: „Das ist viel zu schreiben.“ Stimmt, deshalb ein Tipp, wie Sie Zeit sparen. Beginnen Sie mit der einen Entscheidung, die Ihr Agent bereits verletzt hat. Schreiben Sie das ADR aus dem Review-Kommentar, den Sie gegeben haben. Machen Sie dasselbe beim nächsten Mal, wenn Ihr Agent nicht tut, was Sie wollen.

Dorthin schreiben, wo der Agent liest

Wissen hilft nur, wenn es zur richtigen Zeit im Kontext des Agenten ist und kurz genug, um genutzt zu werden.

In meinem Beispiel war es tatsächlich sehr wenig. Eine kurze CLAUDE.md-Datei, die sagt: Jedes Modul besitzt seine Daten, ein Modul importiert nur seine eigenen Dateien, wenn es etwas aus einem anderen Modul braucht, deklariert es einen Port, und die Composition Root, src/app.ts, befüllt die Ports. Dazu diese leere Composition Root, damit es einen offensichtlichen Ort für die Verdrahtung gibt.

In einem echten System wächst CLAUDE.md und enthält den Systemzweck, die drei wichtigsten Qualitätsattribute, die Context Map und Regeln wie „bevor du etwas modulübergreifend änderst, lies docs/adr/“, dazu einen Index der ADRs mit einzeiligen Zusammenfassungen. Dieser Index ist wichtig. Der Agent öffnet das für die Aufgabe relevante ADR, statt alles zu laden. Formulieren Sie die ADR-Titel daher als Aussagen, etwa „Ein Bounded Context liest nie Daten aus anderen Bounded Contexts“.

Vorher: Billing liest den Orders-Store. Nachher: Billing deklariert einen Port, Orders veröffentlicht die Lesemethode, und src/app.ts verbindet beides. In allen fünf Sessions.

Fairerweise: Das ist ein Modell, ein Feature, je fünf Läufe. Ihr Agent und Ihre Codebasis verhalten sich womöglich anders, also messen Sie es an Ihrem eigenen Code. Führen Sie dieselbe Aufgabe vorher und nachher einige Male aus und vergleichen Sie die Diffs.

Durchsetzen und lebendig halten

Dokumentation, die der Agent liest, ist die erste Schicht. Prüfungen, die den Build scheitern lassen, sind die zweite. Der Agent macht es billig, Dokumentation aktuell zu halten.

Machen Sie aus den wichtigsten Regeln Fitness Functions: einen Architekturtest, zum Beispiel mit ArchUnit, import-linter oder etwas Vergleichbarem, der bei jedem Import über eine Modulgrenze hinweg fehlschlägt. Alte Verstöße, falls es sie gibt, kommen auf eine Liste, die nur kürzer werden darf.

Hier hat mich wieder etwas überrascht. In meinen Läufen wurde der Test nie rot. Die Agenten haben ihn vor ihrer ersten Änderung gelesen und sich daran gehalten. Auch ohne CLAUDE.md haben der Test und die leere Composition Root alle fünf Sessions innerhalb ihrer Grenzen gehalten. Der Test ist also auch Dokumentation, und zwar eine, die glücklicherweise nicht veralten kann, ohne dass der Build es Ihnen sagt.

Fängt dieser Test einen Agenten, der alles ignoriert? Das konnten meine Läufe nicht zeigen, weil kein Agent das getan hat. Genau deshalb ist er da. Er kostet nichts, solange der Agent sich benimmt, und stoppt den Merge, wenn nicht. Er ist auch ein guter Prüfer. Führen Sie ihn nach jeder Agent-Session aus, und jede rote Zeile benennt einen neuen Import, der die Grenze überschreitet.

Sie könnten denken: „Das ist nur Dokumentation, wir haben sie nie aktuell gehalten.“ Nun, mit Coding-Agenten hat sich eines geändert. Früher hatte Dokumentation keinen Leser, der täglich danach handelte. Jetzt hat sie einen. Ein veraltetes ADR erzeugt sichtbar binnen Tagen falschen Code, also fällt Veralterung auf.

Machen Sie den Agenten zum Teil der Pflege. Widerspricht eine Änderung einem ADR, muss der Agent ihm entweder folgen oder im selben Pull Request ein neues ADR vorschlagen. Ein Mensch prüft diese Entscheidung, nicht die Prosa.

Halten Sie es also klein. Zehn korrekte ADRs sind viel besser als hundert ungelesene. Natürlich ersetzt das alles keine ordentlichen Reviews, und auch ein ADR kann falsch sein. Aber es macht den Dissens wenigstens sichtbar.

Zum Schluss: Probieren Sie es selbst aus

Merken Sie sich: Ihr Agent kopiert die Architektur, die er sieht. Wenn Ihr Code sie nicht mehr zeigt, schreiben Sie sie dort auf, wo der Agent liest.

Probieren Sie Folgendes aus. Nehmen Sie die letzten drei Review-Kommentare, in denen Sie einem Agenten oder einem Kollegen gesagt haben: „So machen wir das hier nicht.“ Schreiben Sie jeden als kurzes ADR oder als Zeile zu einem Qualitätsattribut, verlinken Sie sie aus CLAUDE.md und führen Sie eine der Aufgaben erneut aus. Vergleichen Sie die Diffs. Optional ergänzen Sie einen Architekturtest für die Regel, die am wichtigsten war.

Möchten Sie das in der Praxis ausprobieren? Nutzen Sie den Link zum Architecture Practice Lab in der Beschreibung dieses Videos. Dort bekommen Sie das erodierte Beispiel-Repository aus dieser Episode. Geben Sie ihm dieselbe Aufgabe mit Ihrem eigenen Agenten, Claude oder einem anderen, und sehen Sie, ob er die Grenzen einhält. Schreiben Sie dann die Architektur auf, versuchen Sie es noch einmal und holen Sie sich Feedback von meinem Reviewer-Agenten, den ich auf Regeln für gute Architektur trainiert habe.

Bis bald!

In Archilab ausprobieren ↗