Architekturdoku ohne Drift: arc-steward
KI schreibt Code heute schneller, als ein Mensch ihn nachvollziehen kann. Eine gute Architekturdokumentation hilft, das Verständnis für das Gesamtsystem auch bei Änderungen zu behalten - aber nur, wenn sie korrekt ist. Und sie aktuell zu halten war schon ohne KI-Agenten eine echte Herausforderung für Teams: Veraltete Dokumentation fällt typischerweise erst verspätet auf. Irgendwann beschreibt das Diagramm ein System, das es so nicht mehr gibt, und niemand vertraut ihm genug, um es überhaupt zu öffnen. Das KI-Tempo verschärft das nur.
Aus diesem Grund habe ich arc-steward veröffentlicht.
Was ist arc-steward?
arc-steward ist ein Agent-Skill, den man in den eigenen agentischen Workflow einbettet. Er erstellt Architekturdokumentation und hält sie mit jeder Codeänderung aktuell - im Kern sind das Anweisungen, denen ein Coding-Agent folgt, plus ein kleines Prüfskript, das die Konsistenz sichert.
Die Doku folgt dabei keinem Freistil, sondern einem festen Kanon - und welchen, entscheidest du pro Repository: arc42 oder Simon Browns Software Guidebook. Beide sind etablierte Gliederungen, die feste Kapitel vorgeben - Kontext, Bausteine, Laufzeitsichten, Entscheidungen -, damit man nicht in jedem Projekt neu überlegt, was hineingehört. Genau diese Kapitel pflegt arc-steward.
In Aktion
Als Beispiel habe ich arc-steward sich selbst dokumentieren lassen - hier sein eigenes Kontextdiagramm, so wie die Fähigkeit es generiert hat:
Im Repository steht dieses Diagramm in einem markierten Block. Der Refresh ändert nur den Inhalt zwischen den Markern, sodass handgeschriebene Prosa unangetastet bleibt; der refs-Block verankert, aus welchen Quelldateien er stammt:
<!-- arc-steward:generated:context -->
… Kontextdiagramm …
<!-- arc-steward:refs
SKILL.md · conventions.md · scripts/verify.py
-->
<!-- /arc-steward:generated -->
Welche Codeänderung welches Diagramm betrifft, hält eine Routing-Tabelle fest: Eine Änderung an einem Pfad löst gezielt die Aktualisierung der zugeordneten Artefakte aus. Damit das Ergebnis verlässlich bleibt, gehört ein Prüfskript zum Skill: Es scannt die erzeugte Dokumentation, meldet jede Abweichung als Finding, und erst wenn es ohne Beanstandung durchläuft, gilt die Aktualisierung als abgeschlossen. Im Pull Request sieht ein Reviewer die aktualisierten Diagramme schließlich direkt im Diff, neben dem Code, der sie ausgelöst hat.
Verwendung im eigenen Workflow
arc-steward arbeitet in zwei Modi, und welcher greift, hängt allein davon ab, ob im Repository schon eine Dokumentation liegt.
Es gibt noch keine Doku: Bootstrapping
Fehlt die Architekturdokumentation komplett, legt arc-steward sie im Bootstrapping erstmalig an. Das ist ein bewusster, einmaliger Schritt - und einer, bei dem der Mensch mitredet: arc-steward liest die Struktur des Repositories aus, erkennt die Sprache der Doku und mögliche Schema-Quellen, leitet aus dem tatsächlichen Verzeichnis-Layout eine Routing-Tabelle ab und lässt sich die wesentlichen Geschäftsabläufe von dir bestätigen, statt sie zu erfinden. Erst wenn Standard - arc42 oder Guidebook - und Kapitelauswahl feststehen, schreibt es den Kanon: die Einstiegsseite, jedes gewählte Kapitel, und überall dort, wo der Code keine Antwort hergibt, ein ehrliches TODO(human). Weil dieser Lauf das ganze Repository berührt und Rückfragen stellt, stößt man ihn gezielt an - nicht nebenbei während einer fachlich anderen Aufgabe, deren Rahmen er sonst sprengen würde.
Die Doku existiert: Refresh
Ist der Kanon erst einmal da, übernimmt der Refresh. In diesem Modus bestimmt arc-steward den Diff des aktuellen Features, bildet die geänderten Pfade über die Routing-Tabelle auf die betroffenen Artefakte ab und aktualisiert ausschließlich diese - chirurgisch und klein. Berührt eine Änderung nichts Dokumentiertes, meldet er das und bleibt untätig. Gerade weil ein solcher Lauf so klein ist, passt er in denselben Pull Request wie das Feature. In meinem eigenen Entwicklungs-Workflow ist der Refresh deshalb ein fester Schritt vor jedem Pull Request, sodass die aktualisierten Diagramme neben dem Code landen, der sie ausgelöst hat. Den Anstoß gibt der Skill selbst: Seine Beschreibung sagt dem Agenten, wann er einspringen soll.
Grenzen
Was der Code nicht hergibt, erfindet arc-steward nicht, sondern markiert die Lücke ehrlich als TODO(human); die wesentlichen Geschäftsabläufe etwa musst du selbst benennen. Berührt ein Diff nichts, was dokumentiert ist, bleibt das Werkzeug bewusst untätig und läuft nur dann, wenn es tatsächlich etwas zu tun gibt. Und es ersetzt kein Review: Es hält die Dokumentation aktuell, aber ob sie das Richtige aussagt, entscheidest weiterhin du.
Ausprobieren
arc-steward ist Open Source: github.com/robertfoobar/arc-steward. Probier es an einem Feature-Branch aus und schau, was das Diagramm verfehlt hat. Über Rückmeldungen und Issues freue ich mich.