Technische Samenvatting: Code2UML – Agentische LLM's met Context Engineering voor Schaalbare Softwarevisualisatie

Probleemstelling

Softwaredocumentatie, met name actuele UML-diagrammen, wordt vaak verwaarloosd vanwege de hoge kosten en de foutgevoeligheid van handmatige creatie. Hoewel Large Language Models (LLM's) potentie bieden voor het automatiseren van deze taak, staan ze voor een fundamentele schaalbaarheidsbarrière wanneer ze worden toegepast op real-world codebases. De intermediaire representaties (IR) van projecten van middelgrote tot grote omvang overschrijden vaak de effectieve contextvensters van zelfs de meest geavanceerde LLM's. Naïeve benaderingen die proberen volledige representaties van codebases in één enkele LLM-aanroep te voeden, leiden tot afgekaptte output, hallucinerende relaties en het niet vastleggen van architectonisch significante structuren. Bovendien vereist de diversiteit aan UML-diagramtypen (bijvoorbeeld class, sequence, deployment) verschillende notatieregels en informatieve eisen, waardoor "one-size-fits-all" generatiebenaderingen ontoereikend zijn.

Methodologie

Het artikel introduceert Code2UML, een agentische architectuur die is ontworpen om UML-diagrammen direct te genereren vanuit broncode-repositories, terwijl wordt voldaan aan de contextbeperkingen van LLM's. Het systeem is gebouwd op de Claude Agent SDK (met gebruik van Claude Sonnet 4.6) en werkt via een pijplijn van vier fasen:

1. IR-Generatie en Normalisatie: Broncode in Java, Python, JavaScript en PHP wordt geparsed met Tree-sitter om een taalagnostische JSON Intermediaire Representatie (IR) te genereren. Een deterministische post-processing-stap normaliseert taal-specifieke constructen (bijvoorbeeld toegangsmodificatoren, overerving) naar een uniform schema.
2. Context Engineering (IR View Generatie): Om contextlimieten aan te pakken, maakt het systeem gebruik van een deterministische, op belangrijkheid gewogen IR-compactielaag. Deze pure-Python-transformatie converteert volledige project-IR's naar diagram-specifieke weergaven die gegarandeerd binnen de token-beperkingen passen (60 KB voor single-path, 100 KB voor deep-path).
   • Mechanisme: Het rangschikt elementen op basis van diagram-type-specifieke belangrijkheidsscores (bijvoorbeeld aantal methoden, aanwezigheid van overerving) en past iteratieve verkleining toe. Als de doelgrootte wordt overschreden, wordt het elementenbudget gehalveerd.
   • Efficiëntie: Dit proces vereist geen LLM-aanroepen en wordt in milliseconden voltooid.
3. Multi-Agent Architectuur: Het systeem maakt gebruik van een hiërarchie van vijf gespecialiseerde agenten, die elk een distinct cognitief deeltaken aanpakken:
   • PlannerAgent: Decomposeert het project in logische scopes (werkstromen/modules) op basis van projectgrootte.
   • AnalyzerAgent: Leest specifieke bronbestanden geïdentificeerd door de planner om high-signal context aan te halen (call chains, relaties) voor elke scope. Meerdere agenten draaien parallel.
   • DiagramAgent: Genereert de uiteindelijke PlantUML-code op basis van de gecompakteerde IR-weergave (voor architecturale overzichten) of de verrijkte context (voor gedetailleerde gedrags-/structuurdiagrammen).
   • CorrectorAgent: Valideert en repareert syntaxisfouten in gegenereerde .puml-bestanden met behulp van diagram-type-specifieke regelsets.
   • DependencyAnalyzerAgent: Analyseert broncode van third-party libraries onafhankelijk.
4. Orchestration Strategie: Het systeem maakt gebruik van een tweelaags routingstrategie:
   • SINGLE Path: Voor architecturale overzichten (Component, Deployment, System Context), waarbij één DiagramAgent wordt aangeroepen.
   • DEEP Path: Voor gedetailleerde diagrammen (Class, Sequence, Activity, Use Case), waarbij een pijplijn van drie fasen wordt aangeroepen (Planner → Analyzer → Diagram) met gepipelined correctie.

Belangrijkste Bijdragen

Het artikel claimt drie primaire bijdragen:

1. Deterministische Context Engineering: Een nieuwe aanpak die de data payload optimaliseert in plaats van alleen de prompttekst. Het transformeert grote IR's naar compacte, diagram-specifieke weergaven zonder LLM-aanroepen, waardoor architectonisch significante elementen overleven bij agressieve compressiefactoren. In tegenstelling tot Retrieval-Augmented Generation (RAG) werkt dit op gestructureerde IR's met deterministische scoring.
2. Gespecialiseerde Multi-Agent Hiërarchie: Een framework van vijf agenten dat monolithische prompt-gebaseerde benaderingen vervangt. Deze scheiding van verantwoordelijkheden staat onafhankelijke optimalisatie toe van planning, analyse, generatie en validatie, wat overeenkomt met gevestigde software-engineeringprincipes.
3. Uitgebreide Empirische Evaluatie: Een rigoureuze beoordeling over 12 open-source repositories (sprekend over 4 talen en 2 ordes van grootte in omvang, van 31 tot 4.578 IR-entiteiten) en 7 UML-diagramtypen, resulterend in 84 observaties die zijn geëvalueerd op vijf geautomatiseerde metrieken.

Resultaten

Het systeem is geëvalueerd op vijf geautomatiseerde metrieken: Syntactische Validiteit, Entiteit Recall, Relatie Precision, Structurele Kwaliteit en Structurele Complexiteitsindex (SCI).

• Syntactische Validiteit: Het systeem behaalde een gemiddelde validiteit van 91,5%. Component- en Deployment-diagrammen bereikten 100% validiteit. System Context-diagrammen hadden de laagste validiteit (58,3%) vanwege complexiteiten in C4-model-stereotypen.
• Relatie Precision: De gemiddelde precision was 0,858, wat aangeeft dat de overgrote meerderheid van de gegenereerde relaties entiteiten verbindt die daadwerkelijk in de broncode zijn gedeclareerd, met minimale hallucinatie.
• Structurele Kwaliteit: De gemiddelde kwaliteitsscore was 81,7/100. Cruciaal bleven de kwaliteitsscores stabiel over projectgroottes (variërend van 77,5 tot 83,6), wat aantoont dat de context-engineeringlaag succesvol de diagramkwaliteit behoudt ongeacht de schaal.
• Entiteit Recall: De gemiddelde recall was 0,313. Dit wordt geïnterpreteerd als een bewuste architecturale prioritering in plaats van een falen; het systeem richt zich op significante structuren in plaats van exhaustieve dekking. Class-diagrammen behaalden de hoogste recall (0,445), terwijl Use Case-diagrammen het laagst waren (0,165), consistent met hun abstracte aard.
• Taaloverstijgende Consistentie: De prestaties waren zeer consistent tussen Java, JavaScript, PHP en Python, met kwaliteitsscores die slechts met 0,6 punten varieerden tussen de talen.
• Schaalbaarheid: Sensitiviteitsanalyse bevestigde dat de kwaliteit niet verslechtert naarmate het aantal IR-entiteiten toeneemt van 31 tot 4.578.

Betekenis en Claims

Het artikel stelt dat Code2UML een kritieke beperking in huidige op LLM gebaseerde software-engineeringtools aanpakt: het onvermogen om betrouwbaar grote codebases te verwerken en te documenteren binnen de beperkingen van het contextvenster.

• Methodologische Verschuiving: Het werk toont aan dat het combineren van deterministische context engineering met een hiërarchie van gespecialiseerde agenten schaalbare, accurate en syntactisch valide UML-generatie mogelijk maakt. Deze aanpak wordt gepresenteerd als een noodzakelijke evolutie verder dan monolithische prompting of eenvoudige RAG voor complexe repository-niveau taken.
• Praktisch Nut: Door diagrammen te produceren die architecturaal coherent en syntactisch valide zijn over meerdere talen, draagt het systeem bij aan het verbeteren van geautomatiseerde softwaredocumentatie en architecturaal inzicht.
• Bescheiden Beperkingen: De auteurs erkennen dat geautomatiseerde metrieken geen subjectief menselijk nut vastleggen. Zij merken op dat System Context-diagrammen verdere uitbreidingen van regelsets vereisen voor C4-model constructen en dat de huidige evaluatie, hoewel breed, beperkt is tot open-source repositories. Het systeem prioriteert "architecturale significantie boven exhaustieve dekking", wat een ontwerpkeuze is en geen bug.

Concluderend presenteert Code2UML een levensvatbaar framework voor het schalen van op LLM gebaseerde softwarevisualisatie, en bewijst dat met de juiste context engineering en agent-specialisatie LLM's de complexiteit van real-world software-repositories effectief kunnen hanteren.