• Vortrag: JUG Saxony Day 2026, Radisson Blu Park Hotel & Conference Centre, Radebeul bei Dresden, 25. September 2026
• Sprecher: Stefan Zörner (Softwarearchitekt bei embarc, Hamburg) — vorher Bayer AG, Mummert + Partner, IBM, oose
• Schwerpunkte: methodische Softwarearchitektur (Entwurf, Bewertung, Dokumentation), Architektur-Reviews
• Folien: https://embarc.de/download/ · Kontakt: https://linkedin.com/in/stefan-zoerner

Abstract

Bei keiner anderen Tätigkeit in der Architekturarbeit liegt es so nahe, Generative AI einzusetzen, wie beim Dokumentieren der Softwarelösung. Es ist ohnehin ein eher unbeliebtes Thema, die Arbeitsergebnisse sind oft textlastig — wie schön wäre es, wenn “die KI” dem Team dort das Leben erleichtern würde.

Aber was funktioniert wirklich, und wo wird es gefährlich? Der Vortrag zeigt anhand konkreter Beispiele, wie GenAI heute bereits beim Erstellen, Aktualisieren und Bewerten von Architekturdokumentation (oder Teilen davon) hilft. Dazu typische Risiken: Scheingenauigkeit, Kostenfallen durch permanente Aktualisierung, Governance-Fragen — plus Alternativen, wenn sich der KI-Einsatz nicht anbietet (oder verbietet).

Grundlegendere Frage am Ende: Müssen wir Architekturdokumentation mit GenAI nicht ohnehin neu denken, statt sie nur schreiben zu lassen?

Agenda

1. Motivation. Worum geht es?
2. Ergebnisse im Dialog erarbeiten und festhalten
3. Inhalte aus der Implementierung ableiten
4. Dokumentationsartefakte reviewen
5. Fazit und weitere Informationen

01. Motivation. Worum geht es?

Beobachtungen

• Architekturdokumentation anfertigen ist unbeliebt. Sie gilt als aufwändig aktuell zu halten und steht oft hinten an, wenn die Zeit knapp wird.
• Architekturdokumentation ist textlastig. Auch Diagramme lassen sich zu einem guten Teil textuell beschreiben (“Diagrams-as-Code”).
• Mit GenAI lassen sich Inhalte leicht erstellen. Moderne Sprachmodelle sind auf das Erzeugen, Zusammenfassen und Aktualisieren von Text spezialisiert.

Perfect Match?

Textlastig + unbeliebt + maschinell gut erzeugbar. Der Einsatz von GenAI in Architekturdokumentation liegt zumindest nahe.

Bezugsrahmen: arc42

Die Beispiele orientieren sich am arc42-Gliederungsvorschlag:

• Gliederungsvorschlag arc42 (Abschnitte 1–12)
• Inhalte zu Anforderungen in arc42
• Inhalte zur Lösungsarchitektur in arc42
• Vorgaben und Best Practices (arc42-Seite)

Ziele von Architekturdokumentation

1. Orientierung und Sicherheit beim Entwurf. Die Dokumentation hilft dabei, die Artefakte fallen quasi dabei ab — z.B. bei ADRs (Architecture Decision Records).
2. Nachvollziehbar und bewertbar machen. Außenstehende (z.B. neue im Team) bekommen einen Einstieg, etwa über einen prägnanten Architekturüberblick.
3. Verwässerung verhindern. Prinzipien, Muster und Konzepte werden auch zukünftig eingehalten.
4. Liefern müssen. Dokumentation als Teil der Software, um vertragliche oder regulatorische Anforderungen zu erfüllen.

These

„Die mit diesen Zielen verbundenen Aufgaben bleiben aus meiner Sicht bestehen. Gleichwohl eröffnet GenAI spannende Möglichkeiten."

02. Ergebnisse im Dialog erarbeiten und festhalten

Der Ansatz allgemein

• GenAI als interaktiver Sparringspartner
• fungiert als Ideengeber und bietet einen Rahmen
• generiert aus Stichpunkten erste Fassungen
• befüllt Strukturen iterativ im Gespräch

Beispiel: Agent für Qualitätsziele

Ziel: Einen ersten, fundierten Vorschlag für die Top-Qualitätsziele für ein konkretes Softwaresystem erarbeiten — im Dialog mit einem Ansprechpartner, der die Anforderungen des Systems kennt.

Vorgehen des Agenten:

1. Die Art des Softwaresystems erfragen
2. Herausfinden, was das System macht, was seine Aufgabe ist und was es auszeichnet
3. Ein Risiko-Brainstorming durchführen
4. Einen ersten Ergebnisvorschlag machen und den Ansprechpartner einladen, Verbesserungen vorzunehmen

Umsetzung: ein Prompt als erster Schritt, Einsatz in einem Chat-Interface.

Zum selbst ausprobieren: https://github.com/archon-ai-labs/quality-goal-dialog

Beispiel-Ergebnis (imaginäre Flipper-Software)

Erzeugt lokal in Ollama mit Google Gemma 4 (26b Parameter). Erster Vorschlag des LLMs, ohne Nachbessern im Dialog.

Fazit zum Beispiel

Positiv

• Ergebnisse überzeugen inhaltlich, vor allem zur Inspiration
• Form und Kriterien hält die Lösung sehr gut ein
• Perspektivisch: Verknüpfung mit anderen „Agenten" denkbar

Probleme bzw. offene Punkte

• Ergebnisse hängen stark vom verwendeten Sprachmodell ab (inkl. Vorgehen) und sind nicht reproduzierbar
• Die Lösung suggeriert Fachwissen, was den User in falscher Sicherheit wiegen könnte (z.B. durch Beispiel-Risiken)

Fazit zum Ansatz allgemein

Denkbar z.B. für:

• Erheben von architekturrelevanten Anforderungen (z.B. Systemkontext)
• Treffen und Dokumentieren von Architekturentscheidungen (ADRs)

Diskussion des Ansatzes

Stärken

• Liefert erste (!) Ideen für Inhalte, iterativer Ansatz
• Kennt Strukturen und hilft, sie einzuhalten
• Unterstützt bei Syntax-Fragen (z.B. Mermaid)

Kritisch zu sehen

• Qualität der Ergebnisse hängt von vielen Faktoren ab (Modell, Antworten im Dialog)
• In Gruppenprozessen im Team lassen sich oft bessere Ergebnisse erzielen

Eigene Notizen

• Arc42 as usual
• Risikoanalyse via KI
• Prompting mit KI-Agent (siehe Link oben)
• Sparringspartner; Output als Input für einen weiteren Agenten
• Typ des Modells wichtig fürs Vorgehen
• Auch denkbar für ADRs und Lösungen
• Qualitätsziele sind besser in der Gruppe mit Stakeholdern

03. Inhalte aus der Implementierung ableiten

Der Ansatz allgemein

• Mit GenAI aus der Umsetzung strukturierte Dokumentation destillieren
• Quellen z.B.: Codestrukturen, Kommentare, Build-Skripte
• Ergebnis können Texte oder Diagramme sein (z.B. via PlantUML oder Mermaid)

Beispiel: DeepWiki — https://deepwiki.com

Hersteller: Cognition (kommerziell, proprietär)

• Leitet aus einem Repository Wiki-Seiten ab (Texte und Graphiken, z.B. Überblicksdiagramme, Abläufe)
• Bietet ein Chat-Interface, um Fragen zur Lösung zu stellen
• Antworten leitet DeepWiki aus der generierten Dokumentation und den Quelltexten ab
• Für öffentliche Repositories kostenlos
• Viele prominente Open-Source-Lösungen sind bereits indiziert, z.B. Spring Framework, VS Code

Fazit zum Beispiel

Positiv

• Ergebnisse (Qualität der Texte) überzeugen
• Chat-Interface als möglicher neuer Zugang zur Dokumentation
• Perspektivisch: vielleicht die Zukunft der Architekturdokumentation (?)

Probleme bzw. offene Punkte

• Was passiert bei Änderungen in der Implementierung? Wie oft neu generieren? Bleibt die Dokumentation stabil?
• Einsatz von SaaS zum Lesen von Quelltexten ist in vielen Unternehmen und Organisationen kritisch

Freie Alternativen („Nachbauten"), Auswahl

Fazit zum Ansatz allgemein

Denkbar z.B. für:

• Tech-Stack inkl. verwendeter Programmiersprachen und Frameworks
• Bausteinsicht (arc42 #5) mit Modulen, ihren Verantwortlichkeiten und Beziehungen; andere Sichten; Laufzeitsicht (arc42 #6)

Diskussion des Ansatzes

Stärken

• Produziert (vergleichsweise) schnell vorzeigbare Ergebnisse — „besser als nichts"
• Oft ein guter Startpunkt

Kritisch zu sehen

• Für hohe Qualität vergleichsweise aufwändig (Dauer, Kosten)
• Wie arbeiten wir mit den Inhalten weiter, speziell bei Änderungen im Quelltext?

Eigene Notizen

• Doxygen (zieht Quelltext-Doku raus) — kann KI die Lücken füllen?
• CodeWiki ist der interessanteste Ansatz: akademisch, CLI-based, baut Markdown-Docs
• Blogpost dazu auf embarc.de

04. Dokumentationsartefakte reviewen

Der Ansatz allgemein

• GenAI begutachtet systematisch eine bestehende Architekturdokumentation
• Überprüfung auf inhaltliche Konsistenz
• Einhaltung von Vorgaben und Best Practices

Beispiel: arc42agentic

Autor Matthias Nissen, frei verfügbar (Creative Commons) — https://github.com/matthiasnissen/arc42agentic

• Agentensystem rund um arc42
• Review einer bestehenden Dokumentation (Markdown) gegen die Best Practices von der arc42-Seite
• 12 spezialisierte Agenten, einer pro Abschnitt in arc42
• weitere Konflikt-Agenten prüfen Beziehungen zwischen Abschnitten (z.B. Qualitätsziele / Lösungsstrategie / Qualitätsszenarien)
• finden Widersprüche, die in Einzelkapiteln unsichtbar bleiben
• Läuft u.a. in VS Code / GitHub Copilot (Demo auch in Cursor)
• Prüf-Kriterien sind pro Abschnitt definiert
• Beispiel-Input der Demo: https://dokchess.de

Fazit zum Beispiel

Positiv

• Ergebnisse sind gut nachvollziehbar und inhaltlich stimmig
• Gezielt einzelne Bereiche prüfbar, oder auch nur auf Konflikte
• Die Befunde sind inhaltlich tatsächlich gut

Probleme bzw. offene Punkte

• Die Ergebnisse variieren je nach eingesetztem LLM stark
• Dauer der Prüfung ist je Deployment sehr unterschiedlich und kann durchaus in die Stunden gehen

Fazit zum Ansatz allgemein

Denkbar z.B. für:

• Unternehmenseigene Vorgaben
• Inhalte aller Art — vor allem aber Texte
• Unterstützung beim Reviewen und zeitnah bereits beim Anfertigen

Diskussion des Ansatzes

Stärken

• Gut automatisierbar und in den Build-Prozess integrierbar
• Vergleichsweise leicht umzusetzen

Kritisch zu sehen

• Qualität hängt stark an den Kriterien
• Ergebnisse schwer reproduzierbar (heikel in formalen Prozessen)

Eigene Notizen

• arc42agentic: agentic Workflow, der Best Practices von arc42 auf arc42-Doku anwendet

05. Fazit und weitere Informationen

TL;DR

• GenAI eröffnet für Architekturdokumentation spannende Möglichkeiten: als Sparringspartner im Dialog, zum Ableiten von Inhalten aus der Implementierung und zum Reviewen bestehender Artefakte.
• Die Ergebnisse überzeugen oft schon im ersten Wurf. Sie bleiben aber Vorschläge, die wir prüfen müssen. LLMs suggerieren leicht ein Fachwissen, das sie nicht haben.
• Die mit den Zielen verbundenen Aufgaben bleiben bestehen, doch GenAI nimmt uns Routine ab und senkt die Hürde, überhaupt anzufangen.

Schreiben wir Architekturdokumentation bald nicht mehr selbst? Nein. Aber wir schreiben sie seltener allein.

Links