Generierung von Code- und Architekturdokumentation

Dokumentation verrottet als Erstes: Sie wird spät geschrieben, selten aktualisiert und fehlt genau dort, wo neue Teammitglieder oder Prüfer sie brauchen. LLMs, die ein ganzes Repository lesen, können Docstrings, READMEs, API-Referenzen, Architekturüberblicke und Diagramme entwerfen und lassen sich in die CI einbinden, sodass bei jeder Codeänderung Dokumentation als Pull Request vorgeschlagen wird. Typischer Nutzen: schnelleres Onboarding, weniger Herrschaftswissen und eine lesbare Ausgangsbasis vor einer Legacy-Migration (CODE-005).

Problem & Nutzen

• Heute: Dokumentation wird von Hand geschrieben, ist lückenhaft und veraltet. Architekturwissen steckt in wenigen Köpfen oder in veralteten Wiki-Seiten und Foliensätzen. Legacy-Systeme (COBOL, altes Java, undokumentiertes SQL) sind der schlimmste Fall. Onboarding und Störungsbehebung leiden; Prüfer verlangen technische Dokumentation, die nicht existiert.
• Nutzen durch KI: ein guter erster Entwurf in Minuten statt Tagen, einheitlicher Stil, Abdeckung jeder öffentlichen Funktion, Dokumentation, die im selben Pull Request wie der Code aktualisiert wird, und Fragen in natürlicher Sprache auf Basis des generierten Wikis.
• Regulatorischer Sog: Der EU Cyber Resilience Act verlangt technische Dokumentation für Produkte mit digitalen Elementen, und die KI-Verordnung (AI Act) verlangt technische Dokumentation für Hochrisiko-KI-Systeme — beides lässt sich mit generierter, an den Code gekoppelter Dokumentation leichter erstellen und aktuell halten [5][6].

Varianten

• Inline-Dokumentation: Docstrings/JSDoc/Javadoc/XML-Doc-Kommentare, generiert in der IDE oder in der CI.
• Repository-Wiki & Onboarding-Leitfäden: Überblick über das gesamte Repository, Modulbeschreibungen, „Wie funktioniert der Login?".
• API-Dokumentation: Referenz und Beispiele aus OpenAPI-Spezifikationen und Code; Dokumentationsseiten, die auch von KI-Agenten lesbar sind (llms.txt, von der Dokumentationsplattform bereitgestellte MCP-Server).
• Architekturdokumentation: C4-Kontext-/Container-Diagramme, Sequenzdiagramme, Abhängigkeitslandkarten, ADR-Entwürfe aus der Commit-Historie, arc42-Kapitel [4].
• Rückwärtsdokumentation von Legacy-Systemen: Geschäftsregeln und Datenflüsse, die vor der Migration aus COBOL/PL-SQL extrahiert werden (CODE-005); auch wertvoll für Systeme des öffentlichen Sektors mit verlorener Dokumentation.

So funktioniert es

1. repo + history + specs
2. parse & index (tree-sitter/AST, dependency graph, call graph, embeddings)
3. plan (which docs, which audience, which structure; config file in repo)
4. generate (LLM per module with retrieved context; diagrams as Mermaid/PlantUML text)
5. verify (render diagrams, compile examples, check links, lint style, compare with AST)
6. human review as pull request
7. publish (docs site / wiki) + staleness check on every later code change

• Kontextaufbau ist das Kernproblem: Ein Repository passt selten in einen einzigen Prompt. Werkzeuge kombinieren statische Analyse (Symbole, Importe, Aufrufgraphen) mit Retrieval über den Code und einer hierarchischen Zusammenfassung (Funktion → Datei → Modul → System).
• Diagramme als Code: Das Modell schreibt Mermaid-/PlantUML-/Structurizr-DSL, die gerendert und versioniert wird, sodass sich Diagramme wie Text vergleichen lassen.
• Verankerung: Jede Aussage sollte auf Quelldateien und Zeilen verweisen; Behauptungen ohne Code-Anker werden markiert.
• Mensch-in-der-Schleife (Human-in-the-Loop): Generierte Dokumentation kommt als Pull Request; ein Ingenieur, der das System kennt, prüft Absicht und Geschäftsregeln („warum"), denn das Modell kann nur das „Was" beschreiben.

Datenaufbereitung

Benötigte Daten: Quellcode-Repositories, Commit- und Pull-Request-Historie, Issue-Tracker, OpenAPI-/IaC-Dateien sowie vorhandene Wikis oder ADRs. In einem KMU liegen sie in GitHub/GitLab/Azure DevOps, auf Dateiservern, in Confluence- oder SharePoint-Wikis, manchmal nur auf den Rechnern der Entwickler.

Typische Lücken: Code außerhalb der Versionsverwaltung, fehlende oder widersprüchliche alte Dokumentation, generierter oder eingebundener Fremdcode, der den Kontext verunreinigt, Geheimnisse in Repositories, unklare Modulgrenzen und Herrschaftswissen, das nie in einem Ticket landete.

Schritte der Aufbereitung: - Den gesamten Code in die Versionsverwaltung bringen und Geheimnisse entfernen (Secret-Scanner wie gitleaks). - Generierte, eingebundene und binäre Ordner von der Indexierung ausschließen. - Vorhandene Dokumentation sammeln und als maßgeblich oder veraltet kennzeichnen (PREP-013, PREP-017). - Ein kurzes Glossar und Namenskonventionen (PREP-015) sowie eine Dokumentationsvorlage als Goldstandard (PREP-016) bereitstellen. - Zugriffsrechte auf Repositories prüfen, bevor ein Assistent alles indexiert (PREP-023). - Werkzeuge: tree-sitter, ctags, Repository-Indexer, Embedding-Speicher.

Grober Aufwandsanteil: gering, etwa 10–20 Prozent. Die meiste Arbeit besteht darin, den Umfang und die Prüfregeln festzulegen, nicht darin, Daten zu bereinigen. Siehe GUIDE-003 für einen schnellen Reifegradcheck.

Umsetzungswege

Welcher Weg für wen

• KMU: B. Dokumentationswerkzeuge laufen in der CI auf APIs in EU-Regionen und lassen sich ohne neue Infrastruktur in das bestehende Repository einbinden; ein fertiger Assistent (A) genügt für einen ersten schnellen Erfolg.
• Großunternehmen: C. Quellcode ist ein Geschäftsgeheimnis, und eine interne Plattform bedient mehrere Code-Anwendungsfälle (Baukasten-Effekt), daher lohnt sich der Selbstbetrieb.
• Entwickler: C. Lokale Open-Weight-Modelle mit Ollama oder Ähnlichem laufen gut auf einer Workstation und halten den Code privat.
• Öffentlicher Sektor: C. Souveränität und Vergaberegeln sprechen für selbst betriebene Modelle oder Modelle in einer souveränen EU-Cloud.

Weg A — Kaufen (Standardsoftware)

• Repository-Wikis: DeepWiki von Cognition/Devin (automatisch generierte Architekturdiagramme, Dokumentation und Quellenverweise; kostenlos für öffentliche GitHub-Repositories, private Repositories über eine Devin-Organisation; steuerbar über eine Datei .devin/wiki.json) [1].
• An den Code gekoppelte Dokumentation: Swimm (Dokumentation an Code-Ausschnitten verankert, markiert Dokumentation als veraltet, wenn sich der Code ändert) [2]; Mintlify und ähnliche Docs-as-Code-Plattformen für öffentliche API-Dokumentation, mit KI-gestütztem Schreiben und einem MCP-Server je Dokumentationsseite [3].
• IDE-/Plattform-Assistenten: GitHub Copilot, Cursor, JetBrains AI Assistant, Werkzeuge im Stil von Sourcegraph Cody und Claude Code können Docstrings, READMEs und Erklärungen erzeugen (CODE-001, CODE-002).
• EU-Optionen: Assistenten auf Basis von Mistral (Mistral Le Chat / Codestral über einen EU-Anbieter); JetBrains (tschechisches Unternehmen) und On-Premises-Installationen im Stil von Sourcegraph bei Anforderungen an die Datenresidenz. Prüfen Sie bei jedem Anbieter die Richtlinie zu Code-Aufbewahrung und Training.
• A wählen, wenn: ein kleines Team schnelle Erfolge möchte und der Code das Firmennetz verlassen darf.

Weg B — Auf Cloud-KI-Diensten aufbauen (für die meisten empfohlen)

• Modelle: ein starkes Code-/Reasoning-LLM (Claude, GPT, Gemini, Mistral Large/Codestral) über Endpunkte in EU-Regionen (Azure OpenAI EU, Vertex AI EU, AWS Bedrock Frankfurt, Mistral La Plateforme).
• Pipeline: ein CI-Job (GitHub Actions / GitLab CI), der beim Merge geänderte Module vergleicht, betroffene Dokumentation neu erzeugt und einen Pull Request öffnet; ein Coding-Agent mit einer Regeldatei zur Dokumentation kann dasselbe leisten (CODE-002). Dokumentationsseite mit Docusaurus, MkDocs, Sphinx oder Doxygen als Renderer; Mermaid in Markdown.
• Kontext-Werkzeuge: tree-sitter zum Parsen, ein Embedding-Modell plus Vektorindex für das Retrieval, strukturierte Ausgaben für API-Tabellen.
• B wählen, wenn: Sie eine eigene Struktur (arc42, Firmenvorlagen) und CI-Integration wünschen.

Weg C — Selbst betreiben (Open Source)

• Werkzeuge: DeepWiki-Open (Open-Source-Nachbau von DeepWiki mit Unterstützung lokaler Modelle) [7]; Doxygen, Sphinx, MkDocs, Docusaurus zum Rendern; Mermaid, PlantUML oder Structurizr für Diagramme.
• Modelle: Open-Weight-Code-LLMs wie Qwen3-Coder, DeepSeek-Coder/V3-Familie, offene Codestral-Varianten, gpt-oss, Llama-Familie; bereitgestellt mit vLLM oder Ollama; Embeddings mit bge-m3 oder Qwen3-Embedding.
• Hardware: HW2 bewältigt die Docstring-Erzeugung mit quantisierten Coder-Modellen um 30 Mrd. Parameter; HW3 liefert den langen Kontext und die Qualität, die für repositoryweite Architekturzusammenfassungen nötig sind.
• C wählen, wenn: der Quellcode ein Geschäftsgeheimnis ist, Regeln für Verteidigung/kritische Infrastruktur gelten oder ein großer Legacy-Bestand in großer Menge zu dokumentieren ist.

Weg D — Eigenes Training

Lohnt sich selten. Ein kleines Codemodell nur dann auf den eigenen freigegebenen Dokumentationsstil feintunen, wenn das Volumen sehr hoch ist (Millionen Zeilen) und Prompts plus Retrieval den Hausstil nicht erreichen. Vorhandene geprüfte Dokumentation und Paare aus Docstring und Code sind die Trainingsdaten.

Stand der Technik (2026)

• Verständnis auf Repository-Ebene ist praxistauglich: Modelle mit langem Kontext plus Retrieval und statische Analyse liefern brauchbare Architekturüberblicke, und Repository-Wiki-Produkte haben daraus eine Standardfunktion gemacht.
• Agentische Dokumentation: Coding-Agenten erkunden das Repository mit Werkzeugen (grep, Lesen, Tests ausführen) und schreiben Dokumentation, dann prüfen sie Beispiele durch Ausführen; Regeldateien zur Dokumentation (z. B. AGENTS.md, CLAUDE.md) nutzen diese Art von Inhalt und erzeugen sie zugleich.
• Dokumentation für Agenten: llms.txt und über MCP bereitgestellte Dokumentation machen Dokumentation zu einer maschinenlesbaren Schnittstelle für Coding-Assistenten, nicht nur für Menschen [3].
• Grenzen und Fehlerbilder:
• Beschreibt, was der Code tut, nicht warum; fachliche Absicht, verworfene Alternativen und Randbedingungen fehlen.
• Halluziniertes Verhalten, veraltete Parameter, erfundene Module oder falsche Diagramme bei großem, ungewöhnlichem oder stark dynamischem Code (Reflection, Metaprogrammierung, konfigurationsgesteuerte Abläufe).
• Schleichende Abweichung: Generierte Dokumentation veraltet so schnell wie handgeschriebene, solange die Neuerzeugung nicht automatisiert ist.

Gemeinsame Bausteine & Kombinationen

• Gleicher Stack (llm-code + embedding-text + vector-db): CODE-001 IDE-Assistenten, CODE-003 Code-Review, CODE-005 Legacy-Modernisierung, CODE-014 Fehlertriage; ein Repository-Index bedient alle.
• Naheliegende Kombinationen: CODE-005 (erst dokumentieren, dann migrieren), CODE-021 (Refactoring mit aktueller Dokumentation), CODE-003 (Reviewer prüft den Dokumentationsvergleich), KNOW-004 (Assistent für technische Dokumentation), KNOW-011 (Erzeugung einer Wissensbasis), DOC-014 (Dokumente für RAG parsen).
• Pipeline: dieselbe CI-/Agenten-Laufzeit wie CODE-002 (workflow-automation, agent-framework).

Aufwand, Kosten & Kennzahlen

• Weg A: Tage; Abonnements pro Nutzer oder pro Repository.
• Weg B: 2–6 Wochen für eine CI-Pipeline mit Vorlagen und Prüfregeln; die Kosten bestehen überwiegend aus Eingabe-Token je geändertem Modul, in der Regel gering im Vergleich zur Arbeitszeit der Ingenieure.
• Weg C: 1–3 Monate inkl. Modellbereitstellung; ein GPU-Server plus Betrieb.
• Kennzahlen: Dokumentationsabdeckung der öffentlichen APIs, Anteil der generierten Dokumentation, der ohne Änderungen akzeptiert wird, Veralterung der Dokumentation (Tage seit Codeänderung vs. Dokumentation), Zeit bis zum ersten PR neuer Entwickler, Supportanfragen an das Plattformteam, Prüfungsfeststellungen zu fehlender Dokumentation.

Menschen & Veränderung

Beziehen Sie die Entwicklungsleitung (Prozessverantwortliche) und die IT früh ein, dann die Geschäftsleitung für Budget und Richtlinien. Entwickler sind die Endnutzer und sollten die Dokumentationsvorlage mitgestalten. IT-Sicherheit prüft, welcher Code das Netz verlässt; Recht/Compliance prüft Lizenz- und Aufbewahrungsbedingungen des Anbieters (GUIDE-010, GUIDE-013).

Betriebsrat: abhängig. Die Dokumentationserzeugung selbst überwacht keine Beschäftigten, doch Plattformen, die Prompts, Commits oder Nutzung pro Person protokollieren, sind objektiv zur Überwachung geeignet und lösen die Mitbestimmung nach § 87 Abs. 1 Nr. 6 BetrVG aus. § 90 Abs. 1 Nr. 3 verlangt eine rechtzeitige Unterrichtung, wenn KI Arbeitsabläufe prägt. Nutzen Sie eine kurze Betriebsvereinbarung, die die Leistungsbewertung aus den Werkzeug-Logs ausschließt (GUIDE-004). Öffentlicher Dienst: Personalrat.

Datenschutz: Commits und Tickets enthalten Namen von Entwicklern und teils Kundendaten; beziehen Sie die/den Datenschutzbeauftragte(n) ein, schließen Sie einen AVV ab und führen Sie eine DSFA nur durch, wenn personenbezogene Daten in großem Umfang verarbeitet werden (GUIDE-005).

KI-Kompetenz: Unterstützen Sie das Team mit einer kurzen Schulung zur Prüfung generierter Dokumentation (GUIDE-006). Typische Sorge: „Die Dokumentation wird falsch sein". Begegnen Sie dem mit menschlicher Prüfung in Pull Requests, Quellenverweisen bei jeder Aussage und einem Bericht zu veralteter Dokumentation. Pilotieren Sie mit einem Repository und einem freiwilligen Team (GUIDE-009); Menschen geben jede übernommene Dokumentationsänderung frei.

Risiken, Regulierung & Compliance

• KI-Verordnung (AI Act): minimales Risiko (interne Entwicklerwerkzeuge). Die KI-Kompetenz (Art. 4) gilt. Wird generierter Text als KI-generierter Inhalt an Endnutzer veröffentlicht, sind die Transparenzpflichten zu prüfen (Art. 50) [6]. Generierte Dokumentation kann die technische Dokumentation von Hochrisiko-KI-Systemen (Anhang IV) oder die technische Akte nach dem Cyber Resilience Act unterstützen, ersetzt sie aber nicht [5].
• DSGVO: Code und Historie können personenbezogene Daten enthalten (Autorennamen/E-Mail-Adressen in Commits, Testdaten, fest codierte Kundendaten, Geheimnisse). Das Senden von Repositories an Cloud-APIs erfordert einen Auftragsverarbeitungsvertrag (AVV), wo nötig eine EU-Region sowie ein Scannen auf Geheimnisse/personenbezogene Daten vor der Indexierung.
• Geistiges Eigentum & Vertraulichkeit: Aufbewahrung beim Anbieter, Bedingungen ohne Training und die Lizenz des zusammengefassten Open-Source-Codes bestätigen; Geschäftsgeheimnisse wo nötig mit Weg C schützen.
• Prompt Injection: Repository-Inhalte (Kommentare, README-Dateien aus Abhängigkeiten) können Anweisungen enthalten, die sich an KI-Agenten richten; Dokumentationsagenten nur lesend und mit minimalen Berechtigungen betreiben.
• Genauigkeit: Generierte Architekturdokumente bei sicherheits- oder compliance-kritischen Systemen niemals ohne Freigabe durch einen Ingenieur als maßgeblich behandeln.

Erste Schritte

1. Ein Repository auswählen, die Ausgangslage messen (Dokumentationsabdeckung, Einarbeitungszeit) und Zielgruppe und Struktur festlegen (README + arc42-Überblick + API-Referenz).
2. Ein Repository-Wiki-Werkzeug ausprobieren (z. B. DeepWiki an einem öffentlichen/Open-Source-Teil oder ein Produkt aus Weg A) und die ursprünglichen Autoren die Genauigkeit bewerten lassen, besonders beim „Warum".
3. Einen CI-Job oder Agenten ergänzen, der Änderungen an Docstrings und Dokumentation als Pull Requests vorschlägt; menschliche Prüfung verlangen.
4. Automatisierte Prüfungen ergänzen: Dokumentation bauen, Mermaid rendern, Codebeispiele ausführen, Links prüfen, Warnungen zu Veralterung.
5. Vor der Indexierung auf Geheimnisse/personenbezogene Daten scannen, dann auf weitere Repositories und auf Legacy-Systeme ausweiten.

Quellen

1. Devin Docs — DeepWiki repository wikis — https://docs.devin.ai/work-with-devin/deepwiki
2. Swimm — code-coupled documentation — https://swimm.io
3. Mintlify documentation — https://mintlify.com/docs
4. arc42 architecture documentation template — https://arc42.org
5. Regulation (EU) 2024/2847 (Cyber Resilience Act) — https://eur-lex.europa.eu/eli/reg/2024/2847/oj
6. Regulation (EU) 2024/1689 (AI Act) — https://eur-lex.europa.eu/eli/reg/2024/1689/oj
7. DeepWiki-Open (open-source implementation) — https://github.com/AsyncFuncAI/deepwiki-open
8. Mermaid diagramming — https://mermaid.js.org