AI-friendly Architektur: So bleiben KI-Coding-Agenten im Projekt steuerbar

Eine AI-friendly Architektur hilft Coding-Agenten, vorhandene Funktionen zu finden und Änderungen möglichst innerhalb des betroffenen Moduls umzusetzen und zu testen. Feste Entwicklungsabläufe helfen, diese Eigenschaften zu erhalten: Änderungen werden mit der Architektur abgeglichen, die Dokumentation bei Bedarf aktualisiert und vorgeschriebene Prüfungen automatisch ausgeführt. Der Ansatz „Advanced Harness“ sieht zusätzlich vor, abgeschlossene Aufgaben auszuwerten und die Anweisungen, Skills und Abläufe des Agenten anhand dieser Erfahrungen zu überarbeiten.

Das Gespräch wurde redaktionell gekürzt und thematisch geordnet.

Christoph: Angenommen, die Module sind sinnvoll geschnitten und die Architektur ist dokumentiert. Wie erhalten wir diesen Zustand bei der Weiterentwicklung?

Robert: Dafür brauchen wir einen festen Prozess. Wir müssen festlegen, wie ein neues Feature entsteht und wie wir einen Bug beheben. Sonst erklären wir dem Agenten bei jeder Aufgabe erneut, was er grundsätzlich tun soll.

Ob ein Team dafür Spec-Driven Development oder Test-Driven Development oder Varianten davon verwendet, ist für mich zunächst zweitrangig. Wichtig ist, dass bestimmte Schritte verlässlich stattfinden. Die Eigenschaft „AI-friendly“ kann einer Codebasis auch wieder verloren gehen. Wenn wir sie einmal aufräumen und anschließend ohne Struktur weiterarbeiten, stehen wir irgendwann vor denselben Problemen.

Christoph: Wie viel Prozess braucht es dafür? Das klingt schnell nach zusätzlichem Aufwand für jede kleine Änderung.

Robert: Das kann überschaubar bleiben. Als Minimalvariante würde ich vier Schritte vorsehen: Zuerst gleichen wir die Aufgabe mit der Architektur ab und klären, wo die Änderung hingehört. Dann halten wir einen kurzen Plan mit den nötigen Änderungen fest. Danach folgt die Implementierung. Abschließend prüfen wir, ob sie tatsächlich so in die Architektur eingebettet wurde wie vorgesehen.

Zu diesem Abschluss gehört auch der Abgleich mit der Dokumentation. Ist etwas hinzugekommen oder haben wir eine bewusste Ausnahme gemacht, muss das dort stehen. So bleibt die Beschreibung für die nächste Aufgabe brauchbar.

Der Prozess braucht einen klaren Einstiegspunkt. Für ein Feature rufe ich den vorgesehenen Ablauf auf, für einen Bugfix den entsprechenden anderen. Für den Anfang kann das einfach ein vorbereiteter Prompt sein. Entscheidend ist, dass ich diesen Ablauf gezielt starte.

Christoph: Wie verbindlich sind solche Vorgaben, wenn der Agent sie selbst befolgen muss?

Robert: Da lohnt sich eine genaue Unterscheidung. Schreibe ich in einen Prompt „Bitte führe nach dem Coden Prüfung XYZ aus“, ist das erst einmal eine Anweisung. Ich verlasse mich darauf, dass der Agent daran denkt und sie korrekt umsetzt.

In einer Pipeline kann ich die Prüfung verbindlich hinterlegen. Sie läuft automatisch, und bei einem Fehler geht es an dieser Stelle nicht weiter. Der Agent muss das Problem beheben. Gerade bei solchen Prüfungen möchte ich möglichst wenig davon abhängig machen, ob er sie selbst anstößt.

Diese technisch verankerten Regeln helfen dabei, den Entwicklungsprozess auch tatsächlich einzuhalten.

Christoph: Worauf muss ein Review zusätzlich achten?

Robert: Auf die Einordnung der Änderung in das Gesamtsystem. Eine Funktion kann für sich betrachtet gut aussehen. Ob sie im richtigen Modul liegt oder etwas erneut implementiert, das wir anderswo schon haben, erkenne ich erst mit Wissen über die Architektur.

Genau diese Prüfung kostet Aufmerksamkeit. Ich muss verstehen, wie die betroffenen Teile zusammenhängen. Ein Blick auf die geänderten Codezeilen beantwortet diese Fragen häufig noch nicht.

Hintergrund: Der Artikel „Harness-Engineering: Wie KI-Coding-Agenten im Projektkontext steuerbar werden“ beschreibt die Arbeitsumgebung rund um einen Coding-Agenten und das Zusammenspiel von Anweisungen, Werkzeugen, Prüfungen und Feedback.

Christoph: Du hattest im Vorgespräch noch einen dritten Punkt „Advanced Harness“ genannt und der geht noch einen Schritt weiter. Was verstehst du unter einem Advanced Harness?

Robert: Mich interessiert besonders die Selbstreflexion des Systems. Wir haben einen Arbeitsprozess mit Anweisungen, Skills und Prüfungen definiert. Nun sollte es einen Schritt geben, der untersucht, ob dieser Prozess weiterhin passt und wo wir ihn verbessern müssen.

Das ist etwas anderes, als wenn wir prüfen, ob die Architekturdokumentation noch stimmt. Da stellen wir nur sicher das Code und Dokumentation zusammenpassen. Bei der Selbstreflektion schauen wir auf die Arbeitsweise des Agenten: Sind seine Skills aktuell? Passen die Anweisungen noch zu den verwendeten Bibliotheken? Fehlen Regeln, auf die wir ihn bei der Arbeit immer wieder hinweisen mussten in der Vergangenheit?

Ein Beispiel wäre eine Bibliothek, deren Verwendung sich geändert hat. Der Agent stößt auf eine Warnung und findet während der Aufgabe heraus, wie er damit umgehen muss. Diese Erkenntnis sollte anschließend in den passenden Skill einfließen. Sonst begegnet ihm beim nächsten Mal derselbe Fehler.

Ein anderes Beispiel wären neuen Style Guidelines, die wir definiert haben. Wenn ich nach einigen Wochen erneut erklären muss, wo sie liegen und dass sie zu berücksichtigen sind, haben wir die Erfahrung aus der vorherigen Aufgabe noch nicht ordentlich übernommen.

Christoph: Das wäre dann eine äußere Schleife im Sinne des Loop Engineerings?

Robert: Genau. Die innere Schleife bearbeitet eine konkrete Aufgabe und korrigiert das Ergebnis anhand von Feedback. Die äußere Schleife betrachtet die Arbeitsweise über mehrere Aufgaben hinweg.

Self-Correction und Self-Optimization betreffen damit zwei unterschiedliche Ebenen. Im einen Fall verbessern wir die aktuelle Änderung. Im anderen passen wir die Skills, Anweisungen oder Abläufe an, mit denen künftige Änderungen entstehen.

Christoph: Wie gehst du das heute praktisch an?

Robert: Mein bisheriger Ansatz ist ziemlich einfach, und ich wende ihn auch noch nicht konsequent überall an. Am Ende einer Aufgabe ist im Chat bereits viel Kontext vorhanden: welche Skills geladen wurden, welche Schritte der Agent ausgeführt hat und wo ich ihn korrigieren musste.

Darauf lasse ich einen weiteren Skill schauen. Der soll eine kurze Retrospektive schreiben: Was hat funktioniert? Wo gab es Schwierigkeiten? Sind Toolaufrufe gescheitert? Haben Skriptaufrufe aus den Anweisungen nicht funktioniert?

Diese Zusammenfassung wird separat abgelegt. Wenn solche Rückblicke regelmäßig entstehen, kann man darauf eine übergreifende Reflexionsschleife aufbauen. Wir haben dann konkrete Erfahrungen aus den Durchläufen, anhand derer sich die Arbeitsweise verbessern lässt. Das ist die Richtung, in die ich weitergehen möchte.

Weiterlesen: „Loop Engineering: So entstehen zuverlässige AI Coding Agents“ erläutert die verschiedenen Feedbackschleifen und unterscheidet unter anderem zwischen der Prüfung einzelner Ergebnisse und der Verbesserung des Systems über mehrere Läufe hinweg.

Christoph: Welche Rolle spielt dabei die Auswahl zusätzlicher Tools und Skills?

Robert: Die sollte zum Projekt passen. Dazu können Support-Tools, MCP-Server oder aufbereitete Informationen zu den verwendeten Bibliotheken gehören.

Ich bin allerdings kein Freund riesiger Skill-Sammlungen. Für eine Bibliothek gefällt mir ein kompakter Core Skill, der die wichtigsten Hinweise enthält und auf eine weiterführende, für Agenten gut lesbare Dokumentation verweist. Dann kann der Agent bei Bedarf nachschlagen. Eine große Menge einzelner Skills müssen wir schließlich auch pflegen und aktuell halten.

Christoph: Wie weit können wir uns dafür schon auf fertige Coding-Umgebungen verlassen?

Robert: Bei den Werkzeugen, die ich ausprobiert habe, habe ich Ansätze dafür gesehen. Teilweise behalten sie Informationen über Aufgaben hinweg oder reflektieren im Hintergrund. Ich konnte mich aber noch nicht darauf verlassen, dass daraus die Verbesserungen entstehen, die ich für mein Projekt brauche.

Außerdem wünsche ich mir mehr Einblick. Ich möchte sehen können, welche Informationen übernommen wurden und was das System an seiner Arbeitsweise verändert. Das ist für mich ein wichtiger Wunsch an die Weiterentwicklung der Harness-Werkzeuge.

Aber auch mit besseren Werkzeugen bleibt die Konfiguration für mich eine Engineering-Aufgabe, die ich nicht einfach der KI überlassen will. Für ein privates Projekt würde ich andere Abläufe wählen als für ein Kundenprojekt mit besonderen Qualitätsanforderungen. Welche Regeln gelten, welche Prüfungen verbindlich sind und wie wir mit der Codebasis arbeiten wollen, müssen wir weiterhin bewusst festlegen.

• Lange Suchläufe und doppelter Code sind Warnsignale. Wenn der Agent vorhandene Funktionen übersieht oder nicht weiß, in welchem Modul er arbeiten soll, lohnt sich ein Blick auf die Architektur und seine Anleitung. Solche Schwierigkeiten können sowohl bei von Menschen geschriebenem als auch bei KI-generiertem Code auftreten.
• Der Agent braucht einen Einstieg in die Architektur. Zu Beginn einer Aufgabe sollte er einen Verweis auf die Architekturbeschreibung erhalten. Sie erklärt, welche Aufgaben die Module übernehmen und wie sie voneinander abhängen. Für die Schnittstellen sollte feststehen, welche Eingaben sie erwarten, welche Ergebnisse sie liefern und welche Bedingungen gelten.
• Architekturprüfungen gehören in den Entwicklungsablauf. Robert schlägt vier Schritte vor: die Aufgabe mit der Architektur abgleichen, kurz planen, implementieren und abschließend prüfen. Dazu gehört auch, die Dokumentation bei Bedarf anzupassen. Verbindliche Prüfungen lassen sich in einer deterministischen Pipeline hinterlegen, sodass ihre Ausführung nicht vom Agenten abhängt.
• Rückblicke auf abgeschlossene Aufgaben können den Harness verbessern. Eine kurze Retrospektive hält fest, was funktioniert hat, wo Tool-Aufrufe gescheitert sind und welche Korrekturen nötig waren. Daraus lassen sich Anpassungen an den Prompts, Skills und Abläufen für künftige Aufgaben ableiten.
• Die Konfiguration bleibt eine Engineering-Aufgabe. Welche Regeln gelten und welche Prüfungen erforderlich sind, hängt vom jeweiligen Projekt ab. Auch mit besseren Coding-Werkzeugen müssen diese Anforderungen bewusst festgelegt und im Harness berücksichtigt werden.