Schluss mit dem Raten: Gib deinen KI-Agenten eine abfragbare Systemlandschaft

Immer mehr Teams übergeben echte Arbeit an KI-Coding-Agenten. Nicht nur Autovervollständigung, sondern echte Änderungen an echten Systemen. Und immer mehr von ihnen laufen gegen dieselbe Wand: Der Agent kennt ihre Systeme nicht. Er weiß nicht, welcher Service wofür zuständig ist, was mit was spricht oder wo die Daten eigentlich liegen.

Also rät er. Und Raten im großen Maßstab bedeutet: selbstbewusste, gut formulierte, falsche Antworten. Das Frustrierende daran ist, dass das Wissen, das der Agent braucht, im Unternehmen längst vorhanden ist. Es liegt nur nicht in einer Form vor, mit der irgendetwas arbeiten kann. Es steckt in den Köpfen einiger weniger erfahrener Entwickler und in einer Dokumentation, die schon eine Woche nach dem Schreiben veraltet war.

Genau dafür haben wir eine kompakte Vorlage gebaut und unter MIT-Lizenz als Open Source veröffentlicht: github.com/deniz-adbeam/agent-knowledge-base. Wer direkt loslegen und die eigenen Systeme abbilden möchte, findet dort alles. Der Rest dieses Beitrags erklärt, warum das funktioniert und wie man es denkt.

Was eine „Systemlandschaft“ wirklich ist

Mit Systemlandschaft meine ich kein weiteres Wiki. Ich meine etwas viel Kleineres und viel Nützlicheres: einen strukturierten, abfragbaren Graphen eurer Systeme. Jeder Service, jede Komponente ist ein Knoten. Jede Beziehung dazwischen ist eine typisierte Verbindung. Dieser Service ruft jenen auf, dieser hängt von jener Bibliothek ab, dieser publiziert Events auf jenes Topic, dieser speichert seine Daten hier.

In der Praxis erfasst eine gute Systemlandschaft Dinge wie:

• Verantwortlichkeit: welches Team oder welcher Service wofür zuständig ist
• Abhängigkeiten: was kaputtgeht, wenn diese Komponente sich ändert
• Datenspeicher: wo jedes Stück Daten tatsächlich liegt
• Event-Flüsse: wer publiziert und wer konsumiert
• Infrastruktur: wie und wo jedes Teil ausgerollt wird

Der entscheidende Punkt: Diese Systemlandschaft wird aus dem Code und der Konfiguration erzeugt, die ohnehin schon existieren. Sie bildet die Realität ab, nicht die Erinnerung an die Realität und nicht den Zustand von vor zwei Reorganisationen.

Ein konkretes Bild

Machen wir es greifbar, mit einem bewusst vereinfachten, zusammengesetzten Beispiel. Stellt euch eine sehr typische Unternehmensplattform vor, reduziert auf das Wesentliche:

• Eine Handvoll Backend-Services, die sich über HTTP gegenseitig aufrufen
• Ein Kafka-Event-Backbone, auf das sie publizieren und von dem sie konsumieren
• Eine MongoDB-Datenbank, die den gemeinsamen Zustand hält
• Mit Terraform bereitgestellte Cloud-Infrastruktur, auf die alle ausrollen

Stellt man das als Graph dar, wird die Form des Systems in Sekunden sichtbar. Die interaktive Systemlandschaft am Anfang dieses Artikels ist eine lebendige Version genau dieses Beispiels. Zieh die Knoten umher, fahr mit der Maus darüber, um Verbindungen hervorzuheben, und klick einen Knoten an, um seine Beziehungen zu sehen.

Schon in diesem Miniformat lässt sich die Struktur ablesen. Die eine Komponente, von der die Hälfte aller anderen abhängt. Das Event-Backbone in der Mitte. Die Single Points of Failure, die nie jemand an ein Whiteboard gemalt hat, weil ja „jeder wusste“, dass es sie gibt.

Warum das für das Geschäft zählt

Man muss sich nicht für Graphen oder Kanten interessieren, um sich für das zu interessieren, was das ermöglicht. Der Business Case ist unkompliziert:

• Schnellere, sicherere KI-gestützte Arbeit. Agenten handeln auf Basis von Fakten statt Vermutungen, das bedeutet weniger Fehländerungen und weniger Zeit fürs Aufräumen danach.
• Besseres Onboarding und weniger Abhängigkeit von einzelnen Köpfen. Die Systemlandschaft überlebt die Menschen, die sie erfasst haben, und kritisches Wissen läuft nicht mehr zur Tür hinaus, wenn ein erfahrener Entwickler geht.
• Sicherheit bei Änderungen. Man sieht den Wirkungsradius, bevor jemand eine gemeinsam genutzte Komponente anfasst.
• Günstigere Wissenspflege. Die Systemlandschaft wird aus der Quelle neu erzeugt, statt Menschen für die Pflege eines Wikis zu bezahlen, das schon zur Mittagszeit falsch ist.

Nichts davon ist exotisch. Es ist der Unterschied zwischen einer Organisation, in der die Antworten in ein paar Köpfen stecken, und einer, in der die Antworten in einer Form aufgeschrieben sind, mit der Menschen und Maschinen tatsächlich arbeiten können.

Für Neugierige: wie es gebaut ist

Diesen Abschnitt könnt ihr getrost überspringen, wenn euch nur das geschäftliche Bild interessiert hat. Für alle, die wissen wollen, wie die Wurst gemacht wird: Es ist erfreulich langweilig, und genau das ist der Punkt.

Die Systemlandschaft ist eine Sammlung reiner Text-Notizen: Markdown-Dateien in einem leichtgewichtigen, offenen Format, eine pro Konzept, mit typisierten Verbindungen dazwischen. Ein kleines Skript liest diese Notizen, validiert sie und erzeugt einen interaktiven Graphen, den man im Browser öffnet. Keine neue Plattform, kein Server, der laufen muss.

Die Notizen müssen nicht von Hand geschrieben werden. Ein kurzer Extraktor liest die Build-Dateien, die Service-Konfiguration und die Infrastruktur-Definitionen, die ohnehin existieren, und schreibt die Notizen automatisch. Die Systemlandschaft wird also zuerst erzeugt und danach von einem Menschen geprüft, statt in einem Meeting von Grund auf erstellt zu werden.

Und weil alles nur Text ist, lebt es in Git direkt neben dem Code. Es ist versioniert, diffbar und wird wie jede andere Änderung reviewt. Die Continuous Integration hält es ehrlich, damit es nicht still und heimlich verrotten kann.

Genau die Vorlage, die wir dafür nutzen, haben wir als Open Source veröffentlicht. Wenn ihr sehen wollt, wie das Ganze zusammenspielt, oder eure eigenen Systeme abbilden möchtet: Sie liegt unter MIT-Lizenz auf GitHub: github.com/deniz-adbeam/agent-knowledge-base. Ins eigene Repo kopieren und loslegen.

Wo es hilft und wo nicht

Ich werde nicht so tun, als wäre das Magie, denn der schnellste Weg, Vertrauen zu verlieren, ist Überverkaufen. Hier die ehrliche Version.

• Die automatische Extraktion ist ein Best-Effort. Sie liefert schnell achtzig Prozent der Systemlandschaft; das letzte Stück ist menschliche Prüfung und Urteilsvermögen.
• Es ist eine Systemlandschaft, kein Wiki. Sie erfasst Struktur und Entscheidungen, keine ausformulierte Prosa-Dokumentation. Worte braucht ihr trotzdem irgendwo.
• Sie braucht maschinenlesbare Quellen. Wenn eure Systeme in Git mit Build- und Config-Dateien liegen, lässt sich die Struktur extrahieren. Was nur in Köpfen existiert, kann nichts auslesen.
• Sie braucht leichte Pflege. Erzeugt sie neu, während sich die Systeme weiterentwickeln, sonst driftet sie wie alles andere ab.

Ehrlich gesagt ist das Hebelwirkung, kein Wunder. In einem kleinen Beispiellauf mit einem Dutzend Services und rund hundert Verbindungen steht der erste Entwurf der Systemlandschaft in Minuten. Aber der bleibende Wert kommt nicht aus diesem ersten Entwurf. Er kommt daraus, die Systemlandschaft am Leben zu halten.

Die größere Verschiebung: agenten-native Organisationen

Tritt man einen Schritt zurück, ist das keine Dokumentations-Geschichte mehr. Je mehr Arbeit Agenten übernehmen, desto weniger wird das Modell die Unternehmen unterscheiden, denn alle haben Zugriff auf ungefähr dieselben Modelle. Der Unterschied wird sein, ob ihr Wissen diesen Agenten als Infrastruktur zur Verfügung steht.

Unternehmen, die ihre Architektur, ihre Entscheidungen und ihre Datenflüsse als abfragbare Ressource behandeln, geben jedem Agenten und jedem neuen Mitarbeiter dieselbe verlässliche Systemlandschaft. Alle starten von denselben Fakten. Das ist die Verschiebung, auf die es sich jetzt vorzubereiten lohnt, bevor die nie erfasste Systemlandschaft zum Engpass wird, den niemand erklären kann.

Weiterführende Lektüre

Wenn ihr mit der grundlegenden Frage ringt, wo euer Wissen überhaupt leben sollte, behandelt unser Beitrag zum Umzug der Dokumentation von Confluence zu Markdown in GitLab das Fundament, auf dem das hier aufbaut.