Jeder Software-Architekt kennt das: Ein historisch gewachsenes System, über 15 Jahre alt. Der Code läuft stabil, aber die Dokumentation ist lückenhaft, veraltet oder schlicht nicht existent. Wer hier Änderungen plant oder neue Entwickler onboarden muss, betreibt digitale Archäologie.
Vor dieser Herausforderung stand ich kürzlich bei einem großen Konzernkunden. Das Entwicklerteam wochenlang mit dem manuellen Schreiben von Javadocs oder Readmes zu blockieren, stand außer Frage – das löst das Problem meistens ohnehin nur temporär, bis die Dokumentation beim nächsten Commit wieder veraltet.
Mein persönlicher Antreiber in solchen Momenten? Konstruktive Faulheit.
Ich habe eine tiefe Abneigung gegen repetitive Routineaufgaben. Um zu sehen, was technologisch heute machbar ist, habe ich mir die Frage gestellt: Können wir den ersten Schritt der Code-Analyse und der initialen Dokumentation automatisieren, um dem Team die monotone Vorarbeit abzunehmen?
Also habe ich mich für eine Woche hingesetzt und einen Proof of Concept (PoC) direkt an deren System hochgezogen. Das Ziel: Große Teile des Dokumentationsprozesses direkt aus dem Quellcode zu automatisieren.
Als technologisches Fundament nutze ich mein eigenes Open-Source-Framework prjxp (Project Expert) in Kombination mit der dazugehörigen Doc|Pipe-CLI.
Anstatt stumpf Text zu generieren, setzt der Ansatz auf eine modulare Pipeline:
- Content-Aware Chunking: Der Code wird nicht nach Zeichenlänge, sondern nach semantischen Java-Strukturen (Klassen, Interfaces) zerlegt, um den Kontext für das LLM zu wahren.
- Die Doc|Pipe Prompt-Template-Engine: Über eine Handlebars-Prompt-Engine und erweiterbare TemplateResolver steuern wir den Kontext hochgradig dynamisch. So lassen sich Quellcode-Strukturen (Source-Dumps), URLs, Groovy-Skripte oder prjxp-eigene RAG-Ergebnisse passgenau in die Prompts injizieren.
- Optimierung & Change-Detection: Über einen SHA-256-Hash-Vergleich der Prompts wird nur neu dokumentiert, was sich im Code verändert hat. Das spart erhebliche Token-Kosten.
Das Ergebnis des PoC?
Die Pipeline analysiert den Code (aktuell fokussiert auf Java und TypeScript) und erzeugt einsatzbereite Markdown-Artefakte direkt im Projekt: Strukturierte READMEs für den schnellen Moduleinstieg und ein automatisiertes Architecture Assessment mit konkreten Refactoring-Empfehlungen.
Zusätzlich macht ein integrierter MCP-Server das Projektwissen direkt in der IDE semantisch abfragbar. Und um die Praxistauglichkeit zu beweisen, ist das Framework komplett self-documenting: Jedes Dokument im GitHub-Repository wurde vollständig automatisiert von der eigenen Pipeline erzeugt.
Aber bleiben wir realistisch (und hier sehe ich auch die klare Grenze):
Code beschreibt das „Wie“, aber selten das „Why“. Eine KI kann Legacy-Strukturen analysieren, verständlich aufbereiten und uns tonnenweise Fleißarbeit abnehmen. Sie kann jedoch niemals die historischen Gründe, die Business-Kontexte oder die bewussten Trade-offs menschlicher Architekten ersetzen. (Das zeigen z.B. auch die ArchitectureAssessments, die prjxp über sich selbst erzeugt)
Die Architektur ist über offene Schnittstellen (SPI) für neue Sprachen und Tools erweiterbar. Das Projekt läuft als Open Source auf GitHub – schaut gerne mal unter die Haube, wie die Pipeline sich selbst dokumentiert. Den Link findet ihr im ersten Kommentar unten.
#Java #SoftwareArchitecture #LegacyCode #AI #OpenSource #SoftwareEngineering #Automation