Blog

Bei keiner anderen Tätigkeit in der Architekturarbeit liegt es so nahe, Generative AI zu nutzen, wie beim Dokumentieren der Softwarelösung. Es ist ohnehin ein eher unbeliebtes Thema, die Arbeitsergebnisse sind oft textlastig … wie schön wäre es doch, wenn „die KI“ dem Entwicklungsteam das Leben dort erleichtert.

Worum geht es?

Architekturdokumentation schlägt die Brücke zwischen Anforderungen und Umsetzung. In klassischer Form Sammlungen aus Texten und Diagrammen, behandelt der zeitgemäße Docs-as-Code-Ansatz Dokumentation heute wie Quelltext („Treat Documentation as Code“). Das verschiebt zwar die Art der Erstellung und Pflege, ändert aber nichts an der Sache an sich: arc42 hat 2006 ein Word-Dokument gegliedert, heute strukturiert es einen Verzeichnisbaum mit Markdown-Dateien.

Mit Architekturdokumentation verfolgen wir sehr unterschiedliche Ziele:

• Wir möchten Orientierung und Sicherheit beim Entwurf der Lösung haben. Die Dokumentation hilft uns dabei und die Artefakte fallen quasi dabei ab, wie z.B. bei ADRs (Architecture Decision Records).
• Wir möchten die Lösung nachvollziehbar und bewertbar machen, und Außenstehende (zum Beispiel neue im Team) einen Einstieg ermöglichen, etwa in Form eines prägnanten Architekturüberblickes.
• Wir möchten sicherstellen, dass die Lösung mit der Zeit nicht verwässert, also Prinzipien, Muster und Konzepte auch zukünftig eingehalten werden.
• Wir müssen mitunter Dokumentation mit unserer Software liefern, um vertragliche oder regulatorische Anforderungen zu erfüllen.

Auch wenn Gen AI gerade die IT-Welt aufwirbelt: Die mit diesen Zielen verbundenen Aufgaben bleiben aus meiner Sicht bestehen. Gleichwohl eröffnet AI spannende Möglichkeiten. Schauen wir uns das genauer an!

Dokumentationsansätze mit AI

In Abbildung 1 lassen sich eine ganze Reihe von Tätigkeiten rund um Architekturentwurf und -dokumentation verorten, bei denen Werkzeuge unterstützen können. Das war auch schon vor Gen AI so, in Docs-as-Code spielt beispielsweise Automatisierung eine große Rolle. Mit dem technologischen Fortschritt ergibt sich aber durchaus neuer Spielraum. Wir diskutieren hier kurz drei konkrete und auch bereits gebräuchliche Ansätze mit Gen AI.

Abbildung 1: Die Welt klassischer Architekturdokumentation mit ausgewählten Gen AI-Ansätzen

Ansatz 1: Ergebnisse im Dialog erarbeiten und festhalten
Zu einem frühen Zeitpunkt im Architekturentwurf (Stichwort Architekturvision) dient Gen AI als interaktiver Sparringspartner. Es schärft Qualitätsziele (arc42, Abschnitt 1.2), strukturiert Rahmenbedingungen (Abschnitt 2) und fungiert als Ideengeber für Architekturansätze in der Lösungsstrategie (Abschnitt 4). Beim Festhalten von Entscheidungen im Rahmen eines ADRs (Abschnitt 9) kennt die AI die im Team präferierte Vorlage und generiert aus Stichpunkten einen ersten Entwurf des Dokumentes. Auch andere Inhalte wie eine Kontextabgrenzung (Abschnitt 3) lassen sich so gemeinsam mit der KI iterativ und im Gespräch grundbefüllen.

Ansatz 2: Inhalte aus der Implementierung ableiten
Gen AI hilft dabei aus dem Quelltext strukturierte Dokumentation zu destillieren. Es generiert aus bestehenden Codestrukturen, Kommentaren, Abhängigkeiten und Build-Skripten erste Entwürfe der Bausteinsicht (arc42, Abschnitt 5) mit Modulen, ihren Verantwortlichkeiten und Beziehungen. Spezialisierte AI-Agenten leiten aus dem Repository C4-konforme Diagramme auf Komponenten- oder Container-Ebene ab, etwa in Mermaid. Andere erarbeiten den Tech-Stack inkl. der verwendeten Programmiersprachen und Frameworks. Die Nachvollziehbarkeit stellt hier eine Grenze dar: Warum ein Team sich für eine Technologie entschieden hat, bleibt verborgen. Der Quelltext erzählt nicht die ganze Geschichte.

Ansatz 3: Dokumentationsartefakte reviewen (in sich selbst oder gegen anderes)
Mit Gen AI lässt sich Architekturdokumentation nicht nur zu erstellen, sondern auch systematisch begutachten. So überprüfen geeignete Agenten eine bestehende Dokumentation auf inhaltliche Konsistenz. Widersprechen sich beispielsweise die beschriebene Lösungsstrategie und die Architekturentscheidungen oder Konzepte? Auch ein Abgleich mit unternehmenseigenen oder externen Vorgaben ist möglich. In einem regulierten Umfeld lassen sich Dokumente gegen Normen und Standards abgleichen und so zumindest Verdachtsmomente aufspüren. Manuelle Review-Arbeit wird zu einem Prüfschritt, den man mit Gen AI zunehmend automatisieren kann.

Was Gen AI uns abnimmt und was nicht

In vielen Unternehmen und Organisationen ist der Einsatz von Gen AI heute grundsätzlich geregelt. Zu Beginn war das vielerorts eine nicht unerhebliche Hürde: „Darf ich solche Lösungen überhaupt für meine Arbeit nutzen?“ Natürlich lohnt für sensible Architekturinformationen ein genauer Blick in die Richtlinien.
Unabhängig davon ergeben sich aus den gezeigten Ansätzen Chancen und Risiken. So sinkt die Hürde zu einer ersten Fassung von Dokumentationszutaten. Gen AI erstellt aus Stichpunkten einen ersten Wurf, den das Team dann überarbeitet. Oder baut problemlos ein erstes Diagramm in plantUML, auch wenn das Team die Syntax noch nicht beherrscht. Auch ermöglicht Gen AI es weniger erfahrenen Teammitgliedern den Architekturentwurf kritisch zu beleuchten und Lücken aufzudecken. Finde ich beispielsweise zu allen Qualitätszielen passende Lösungsansätze in Abschnitt 4 (Lösungsstrategie)?

Auf der anderen Seite schlummern Gefahren: Gen AI mag plausibel klingende Texte erzeugen, aber sie sind nicht zwingend korrekt. Lücken wurden vielleicht fantasievoll gefüllt. Die Dokumentation wird nutzlos, und in einem regulierten Umfeld können Fehler sogar rechtliche Konsequenzen haben. Und wie steht es um die Akzeptanz und Verantwortung im Team für einen Architekturüberblick, den eine KI im Extremfall auf Knopfdruck herausgepustet hat?
Ich glaube, dass wir eine Architekturdokumentation, welche die oben beschriebenen Ziele adressiert, auch in Zukunft noch selbst verantworten. Gen AI hilft beim Erstellen und Pflegen. Und bietet in Zukunft sicher auch einen neuen Zugang zum Wissen. Mit einer Architekturbeschreibung zu chatten ist bereits heute möglich. Das eigentliche Denken bleibt beim Team.

Mehr zum Thema gibt es beim Software Architecture Forum 2026: Dort zeigt Stefan Zörner in seiner Session, wie sich GenAI sinnvoll in der Architekturdokumentation einsetzen lässt – und wo ihre Grenzen liegen.

Über den Autor:

Stefan Zörner (https://www.szoerner.io) ist Softwareentwickler und -architekt bei embarc in Hamburg. Er wirkt bei Entwurfs- und Umsetzungsfragen mit, unterstützt beim Festhalten von Architektur und beleuchtet Lösungsansätze in Bewertungen. Sein Wissen und seine Erfahrung teilt er regelmäßig in Vorträgen, Artikeln und Workshops. Stefan ist Autor des Buches „Softwarearchitekturen dokumentieren und kommunizieren“ (3. Aufl., Hanser-Verlag) und Co-Autor von „Software-Systeme reviewen“ (Leanpub). Im iSAQB ist er als Co-Kurator für den CPSA-Advanced Lehrplan ADOC (Architekturdokumentation) mit verantwortlich.