Vom Work Item zum Pull Request: Ein KI-Harness für Brownfield-Projekte

Je mehr Dinge durch Tests abgedeckt sind, umso mehr kann eine KI auch selbstständig einen Punkt abschließen. Dazu liefern Tools wie SonarQube oder NDepend eine statische Codeanalyse, die einen Drift in technische Schulden vermeiden kann oder zumindest verringert. In meinem Projekt wurde bereits SonarCloud eingesetzt. Was mir aber fehlte, war eine Prüfung auf die Einhaltung von architektonischen Richtlinien und Namensmustern.

Solange ein menschlicher Entwickler diese Entscheidungen trifft, ist das kein großes Problem, aber für die automatische Abwicklung durch KI wollte ich mich nicht darauf verlassen, dass sie das schon richtig machen würde. Glücklicherweise gibt es mit ArchUnitNET ein Open Source Projekt, das genau diese Lücke füllen kann. Dabei hilft Claude, die bestehende Architektur zu analysieren und bereits Regeln dafür aufzustellen.

Der eigentliche Wert liegt in Regeln, die der Compiler gar nicht erzwingen kann. In .NET verhindert die Projektstruktur ohnehin, dass eine untere Schicht nach oben referenziert — spannend sind die Regeln innerhalb einer erlaubten Referenz. Im Brownfield-Projekt kommt eine zweite Schwierigkeit dazu: Eine neue Regel lässt sich selten sofort für den gesamten Bestand erzwingen, weil es bereits Verstöße gibt. Die Lösung ist eine eingefrorene Baseline — der bekannte Altbestand wird ausgenommen, aber jeder neue Verstoß scheitert sofort im Build. Ein zweiter Test wacht darüber, dass die Baseline nicht verrottet: Wird ein Altfall repariert, zwingt er dazu, den Eintrag zu entfernen, und die Regel zieht sich automatisch enger.

So verhindert der Harness neuen Schuldenzuwachs, während der Altbestand Stück für Stück abgebaut wird — ohne das laufende Projekt anzuhalten.

Diese Analyse kann auch helfen, “Fast-Regeln” zu erkennen. In meinem Fall gab es im Business-Layer nur eine Manager-Klasse, die nicht vom BaseManager abgeleitet hat. Nach genauerer Prüfung wurde klar, dass tatsächlich ein anderes Suffix für diese Klasse besser war, wodurch diese Regel entstand: Jede Klasse im Business-Layer, deren Name auf Manager endet, muss von BaseManager erben — sonst ist der *Manager-Suffix eine Rollenverwechslung und der Typ gehört unter einen anderen Namen (*Exporter, *Service).

Solche Regeln als Code sind das, was generische Linter nicht ausdrücken können — und genau das, was einem autonomen Agenten erlaubt, seine Struktur mechanisch zu verifizieren, statt sie richtig zu meinen.

Dazu kommen die Tests, die in den meisten Projekten bereits verbreitet sind. Unit- und Integrationstests, die die Businesslogik prüfen. Hier lohnt es sich, ein Augenmerk auf die Testabdeckung zu legen. Seltener sind bereits UI-Tests. In meinem Fall gab es im bestehenden Projekt zwar Tests der Weboberfläche, aber noch keine des MAUI-Projekts. Solange es hier keine Tests gibt, kann ein autonomer Agent jedoch keine Work Items in diesem Bereich abschließen. Es lohnt sich also, in die Erweiterung dieser Tests zu investieren.

Aktive Projekte haben meistens bereits definierte Codingguidelines. Hier reicht es aber nicht, dass diese in einem separaten Dokument niedergeschrieben oder gar nur mündlich kommuniziert werden. Sie müssen mit Analyzern geprüft werden, soweit das möglich ist. Das erlaubt es, die Einhaltung der Guidelines zuverlässig zu prüfen. In meinem Fall wurde bereits StyleCop verwendet. Wer nach einer Sammlung von Analyzern sucht, wird auch mit Roslynator fündig. Je mehr Regeln bereits mit Analyzern geprüft werden können, umso weniger hängt die Codequalität an der Interpretation des KI-Agenten.

Guidelines, die nicht in solchen Regeln abzubilden sind, wie beispielsweise die SOLID-Prinzipien oder Clean Code, können in Markdown-Dateien in einer Dokumentationssammlung erfasst werden. Eine solche Entwicklerdokumentation kann KI und Menschen gleichermaßen dienen.

Mir ist eine umfangreiche Dokumentation der Codebasis und der Funktionen wichtig. Nicht nur erleichtert das den Neueinstieg in ein Projekt, es erleichtert vielmehr auch dem KI-Agenten, sich in der Codebasis zurechtzufinden. Typisch für ein über Jahre gewachsenes Projekt, hatte auch mein Ausgangsprojekt zwar eine Dokumentation, die aber nicht an allen Stellen aktuell war und auch nicht den gesamten Umfang des Projekts umfasste.

Eine Erstfassung der Dokumentation habe ich mit Claude Fable 5 durchgeführt. Dabei habe ich den aktuellen Codebestand und die bestehende Dokumentation zusammengeführt und im Repository abgelegt. Ich habe mich für das beste Modell, das mir zur Verfügung stand, entschieden, damit die Dokumentation eine gute Ausgangsbasis hat.

Damit die Doku aktuell bleibt, reicht auch ein schwächeres Modell, wie in meinem Fall Claude Sonnet 5. In einem nächtlichen Task zieht sich der Agent die Änderungen seit der letzten Überprüfung und aktualisiert entsprechend die Dokumentation. So kann ein menschlicher Eingriff auf einmal monatlich beschränkt werden, um den aktuellen Stand zu prüfen.

Was der nächtliche Task konkret tut:

• Diff-getrieben: Was hat sich seit dem letzten Lauf in Repo und Backlog geändert?
• Ordnet die geänderten Pfade den betroffenen Handbuch-Kapiteln zu — nur verhaltensrelevante Änderungen, reine Refactorings brauchen keine Doku-Änderung
• Aktualisiert die betroffenen Abschnitte aus dem echten Code, minimaler Diff, die Stimme des Kapitels bleibt erhalten
• Kann er ein Kapitel nicht sicher aktualisieren, markiert er es stale — statt zu raten
• Schreibt nie direkt auf develop, sondern immer über Branch + Pull Request; das Review bleibt das Gate
• Läuft auf dem günstigen Modell; eine monatliche Konsolidierung auf dem starken Modell prüft das ganze Handbuch auf Drift

Ursprünglich habe ich das mit einer Claude Desktop Routine umgesetzt. Diese hatte allerdings das Problem, dass sie fast immer in einer Berechtigungsfrage geendet hat, die ich dann am Morgen abnicken musste, damit die Aufgabe abgeschlossen wird. Außerdem verlor die Routine sehr häufig die Verbindung zu Azure DevOps und musste neu gestartet werden. Die Lösung dafür war das System mit dem isolierten Runner, das ich weiter unten beschreibe.

Der Agent kann nur dann seine eigene Arbeit verifizieren, wenn es auch gute Quality-Gates gibt, die mit Tests und statischer Codeanalyse das Ergebnis prüfen können. Dazu hatte mein Projekt, wie viele andere Projekte auch, eine Pipeline, die im Zuge eines Pull Requests ausgeführt wird. Das benötigt allerdings viel Zeit und belegt einen Pipeline-Runner. Gleichzeitig pollt der KI-Agent regelmäßig, ob der PR bereits fertig ist. Das ist zwar beides auf jeden Fall weiterhin notwendig und gut, aber ich wollte die meisten Probleme schon früher abfangen. Dafür gibt es ein Skript in dem Entwicklungs-Loop, das sämtliche lokal ausführbaren Tests auch ausführt. Dabei ist es wichtig, auch die Analyzer auszuführen. Der Agent sieht ansonsten diese Coderegeln nie.

Die gesamten Quality-Gates, die ein Agent also durchlaufen muss, damit ein Punkt bereit ist für einen Pull Request, sind:

1. Statische Analyse (.NET) — Kompilieren mit den Analyzern (StyleCop + projekteigene Regeln); die Verstöße werden gezählt und sichtbar gemacht. Wegen des Brownfield-Altbestands scheitert das Gate nicht hart an bestehenden Warnungen — die verbindliche New-Code-Prüfung übernimmt SonarCloud im PR.
2. Skript-Analyse — PSScriptAnalyzer prüft die Build- und Automatisierungs-Skripte selbst; der Harness kontrolliert auch sein eigenes Werkzeug.
3. Frontend-Lint & Formatierung — ESLint und Prettier als harte Gates; ein Verstoß bricht den Lauf ab.
4. Backend-Tests — sämtliche .NET-Unit- und Integrationstests, inklusive der ArchUnit-Architekturtests. Optional nur die vom Diff betroffenen Projekte — mit einer Schutzwarnung, wenn uncommittete Änderungen dadurch ungeprüft blieben.
5. Frontend-Tests — die Angular-Testsuite, ebenfalls wahlweise auf die betroffenen Teile beschränkt.

Am Ende steht eine Zusammenfassung aller Schritte mit Pass/Fail — schlägt einer fehl, ist der Lauf rot und der Punkt nicht bereit für einen Pull Request. Nicht enthalten sind die Prüfungen, die erst im PR laufen: das SonarCloud-Quality-Gate und das CodeRabbit-Review.

Im Zuge der Arbeit mit dem Harness gibt es Dinge, die man immer wieder tut und wo es hilfreich ist, eine passende Vorlage im Zuge eines Skills aufzubauen.

Der implement-story Skill entspricht dem Ablauf, der weiter oben bereits beschrieben wurde. Der define-story Skill hat die Aufgabe, eine Anforderung zu schreiben, die die folgenden Punkte — das spec-gate — erfüllt. Dieses wird durch einen Sub-Agent, den spec-assessor, geprüft, damit ein frischer Kontext ohne Vorüberlegungen sich die Story ansieht.

Woran das Spec-Gate misst — noch bevor eine Zeile Code entsteht:

• Testbare Akzeptanzkriterien — ein beobachtbares given/when/then mit klarem Pass/Fail, kein “verbessere X”.
• Betroffene Bereiche identifiziert — durch Lesen des Codes gefunden, nicht geraten.
• Keine offene Produkt- oder Kundenentscheidung — kein “kommt drauf an”, kein TBD.
• Automatisch verifizierbar — ein Test oder der Build kann “fertig” beweisen.
• Keine externe Koordination — kein anderes Team, keine Drittanbieter-Änderung, kein Secret, keine koordinierte Migration.

Am Ende steht eines von drei Urteilen: spec-ok (die Anforderung darf in die unbeaufsichtigte Umsetzung), spec-gap (die Anforderung selbst ist lückenhaft — zurück an den Menschen) oder human-verify-only (implementierbar, aber nur durch menschliche Prüfung abnehmbar — also nicht für den autonomen Loop).

Ein generate-mobile-ui-test Skill hilft bei der KI-unterstützten Erstellung von Tests der MAUI-Oberfläche. Je nach Anwendungsfall kommen mit der Zeit weitere Skills dazu.

Ein wichtiger Schritt, damit der Prüfaufwand weniger wird, ist unabhängige Verifikation des Ergebnisses. Ein eigener Sub-Agent, der mit einem frischen Kontext startet, verifiziert das Resultat. Er erhält den Inhalt des Work-Items und die Änderungen am Code, jedoch nicht die Überlegungen des ausführenden Agenten, warum etwas gemacht wurde. Der Verifier prüft nun, ob der Sinn des Work-Items mit diesen Änderungen tatsächlich erfasst und umgesetzt wurde. Nur wenn dieser Verifier zufrieden ist, wird ein Pullrequest erstellt. Der Verifier sollte mit einem starken Modell ausgeführt werden. Ich habe mich hier für Claude Opus entschieden.

Woran der Verifier misst — alle Prüfungen in einem Durchgang, ein Urteil:

• Test-Treue — kodiert jeder Test tatsächlich das beobachtbare Ergebnis seines Akzeptanzkriteriums, oder ist er eine Tautologie, die nur die Implementierung zurückspiegelt? (Der wertvollste Fang: ein grüner Test beweist nichts, wenn er das Falsche prüft.)
• Intent vs. Gaming — erfüllt der Diff den Sinn des Work-Items, oder nur den Buchstaben der Tests?
• Coverage — bleibt ein Akzeptanzkriterium von Code oder Test unberührt?
• Security — führt der Diff eine Schwachstelle ein (Berechtigungslücke, Injection, Secret-Leak …)?
• Spec-Treue — erfassen die Akzeptanzkriterien das Item überhaupt vollständig, oder legt erst das Bauen eine Lücke offen?

Am Ende steht genau eines von drei Urteilen: bestätigt (der Pull Request wird geöffnet), widerlegt (zurück in die Schleife, Code oder Test nachbessern) oder Spec-Lücke (die Anforderung selbst ist unvollständig — zurück an den Menschen).

Der Harness ist kein feststehendes Konstrukt, das man einmal baut und nie wieder anfasst. Natürlich ist der Wartungsaufwand mit der Zeit geringer, aber besonders am Anfang ist es hilfreich, sich möglichst viele Informationen aus dem Ablauf des Harness zu ziehen. Ich habe hierzu Claude ein Dashboard machen lassen, das die Ausführungen mitprotokolliert. Bei jeder Ausführung des Docker-Runners werden auch Telemetriedaten mitprotokolliert. Außerdem ist das komplette Transkript weiterhin auslesbar.

Hier zeigen sich schon zwei wertvolle Dinge. Der Handbook-Upkeep ist 37-mal an fehlenden Berechtigungen gescheitert. Man kann über das Transkript dann erkennen, dass er versucht hat, mit Bash-Befehlen zu arbeiten und daran gescheitert ist:

Genau darin liegt der Wert der Telemetrie: Der Handbook-Upkeep braucht offensichtlich zusätzliche Rechte oder eine klarere Anleitung — und ohne die mitlaufenden Metriken würde man diesen Bedarf schlicht nie sehen. Das Zweite ist der Tokenverbrauch. Damit kann man einen Überblick behalten, wie aufwändig die Prozesse sind. Hier hilft offensichtlich Caching sehr viel. Dafür war keine besondere Anweisung nötig, sondern das macht Claude von selbst.