技術概要：Code2UML – スケーラブルなソフトウェア可視化のためのコンテキストエンジニアリングを備えたエージェント型 LLM

問題定義

ソフトウェアドキュメント、特に最新の状態を保った UML 図は、手作業による作成が高コストでエラーが発生しやすいため、頻繁に軽視されています。大規模言語モデル（LLM）はこのタスクの自動化に潜在的可能性を提供しますが、現実世界のコードベースに適用される際には、根本的なスケーラビリティの障壁に直面します。中規模から大規模なプロジェクトの中間表現（IR）は、最も高度な LLM でさえも有効なコンテキストウィンドウを超えてしまうことがよくあります。コードベース全体の表現を単一の LLM 呼び出しに投入しようとする単純なアプローチは、出力の切り捨て、幻覚的な関係性の生成、そしてアーキテクチャ的に重要な構造の捉え損ないをもたらします。さらに、クラス図、シーケンス図、デプロイメント図など、UML 図の種類の多様性は、それぞれ異なる表記規則と情報要件を必要とし、「万能型」の生成アプローチでは不十分であることを示しています。

手法

本論文は、ソースコードリポジトリから直接 UML 図を生成し、LLM のコンテキスト制約に準拠するように設計されたエージェント型アーキテクチャであるCode2UMLを導入します。このシステムはClaude Agent SDK（Claude Sonnet 4.6 を使用）を基盤として構築され、4 段階のパイプラインを通じて動作します。

1. IR 生成と正規化: Java、Python、JavaScript、PHP のソースコードを Tree-sitter を使用して解析し、言語に依存しない JSON 中間表現（IR）を生成します。決定論的な後処理ステップにより、アクセス修飾子や継承などの言語固有の構文を、均一なスキーマに正規化します。
2. コンテキストエンジニアリング（IR ビュー生成）: コンテキスト制限に対処するため、システムは決定論的で重要度に基づいた IR 圧縮層を採用します。この純粋な Python 変換は、プロジェクト全体の IR を、トークン制約（シングルパスで 60KB、ディープパスで 100KB）内に収まるように保証された、図表固有のビューに変換します。
   • メカニズム: 要素を、図表タイプ固有の重要度スコア（メソッド数、継承の有無など）に基づいてランク付けし、反復的な縮小を適用します。目標サイズを超えた場合、要素の予算は半分に削減されます。
   • 効率性: このプロセスは LLM 呼び出しを必要とせず、ミリ秒単位で完了します。
3. マルチエージェントアーキテクチャ: システムは、それぞれが異なる認知的サブタスクに対応する 5 つの専門エージェントの階層を利用します。
   • PlannerAgent: プロジェクトの規模に基づき、プロジェクトを論理的なスコープ（ワークフロー/モジュール）に分解します。
   • AnalyzerAgent: プランナーによって特定された特定のソースファイルを読み、各スコープに対して高シグナルのコンテキスト（呼び出しチェーン、関係性）を抽出します。複数のエージェントが並列で実行されます。
   • DiagramAgent: 圧縮された IR ビュー（アーキテクチャ概要用）または強化されたコンテキスト（詳細な動作/構造図用）に基づき、最終的な PlantUML コードを生成します。
   • CorrectorAgent: 図表タイプ固有のルールセットを使用して、生成された .puml ファイルの構文エラーを検証し修正します。
   • DependencyAnalyzerAgent: 第三者ライブラリのソースコードを独立して分析します。
4. オーケストレーション戦略: システムは 2 段階のルーティング戦略を使用します。
   • SINGLE Path: アーキテクチャ概要（コンポーネント、デプロイメント、システムコンテキスト）向けに、単一の DiagramAgent を呼び出します。
   • DEEP Path: 詳細図（クラス、シーケンス、アクティビティ、ユースケース）向けに、パイプライン化された修正を伴う 3 フェーズのパイプライン（Planner → Analyzer → Diagram）を呼び出します。

主要な貢献

本論文は、3 つの主要な貢献を主張します。

1. 決定論的コンテキストエンジニアリング: プロンプトテキストだけでなく、データペイロードを最適化する新しいアプローチです。LLM 呼び出しなしで、大規模な IR を圧縮された図表固有のビューに変換し、過酷な圧縮率でもアーキテクチャ的に重要な要素が生存することを保証します。検索拡張生成（RAG）とは異なり、これは構造化された IR 上で決定論的スコアリングで動作します。
2. 専門化されたマルチエージェント階層: 単一のプロンプトベースのアプローチに代わる 5 つのエージェントのフレームワークです。この関心の分離により、計画、分析、生成、検証の独立した最適化が可能となり、確立されたソフトウェア工学の原則を反映しています。
3. 包括的な実証評価: 4 つの言語にまたがり、サイズが 31 から 4,578 の IR エンティティと 2 つの桁の幅を持つ12 のオープンソースリポジトリと、7 つの UML 図タイプにわたる厳格な評価を実施し、5 つの自動化された指標に基づいて 84 の観測値を評価しました。

結果

システムは、構文妥当性、エンティティリコール、関係性精度、構造品質、構造複雑度指数（SCI）という 5 つの自動化された指標で評価されました。

• 構文妥当性: システムは平均妥当性**91.5%を達成しました。コンポーネント図とデプロイメント図は100%**の妥当性に達しました。システムコンテキスト図は、C4 モデルのステレオタイプの複雑さにより、最も低い妥当性（58.3%）を示しました。
• 関係性精度: 平均精度は0.858であり、生成された関係性の大部分がソースコードで実際に宣言されたエンティティを接続しており、幻覚は最小限であることを示しています。
• 構造品質: 平均品質スコアは81.7/100でした。重要なのは、品質スコアがプロジェクトサイズ（77.5 から 83.6 の範囲）全体で安定していたことで、コンテキストエンジニアリング層がスケールに関係なく図表の品質を維持することに成功したことを示しています。
• エンティティリコール: 平均リコールは0.313でした。これは失敗ではなく、意図的なアーキテクチャの優先付けとして解釈されます。システムは網羅的なカバレッジではなく、重要な構造に焦点を当てています。クラス図は最も高いリコール（0.445）を達成し、ユースケース図は抽象的な性質に一致して最も低く（0.165）、それぞれ対応していました。
• 言語間の一貫性: 性能は Java、JavaScript、PHP、Python 間で非常に一貫しており、言語間の品質スコアのばらつきは 0.6 ポイントのみでした。
• スケーラビリティ: 感度分析により、IR エンティティ数が 31 から 4,578 に増加しても品質が低下しないことが確認されました。

意義と主張

本論文は、Code2UML が現在の LLM ベースのソフトウェア工学ツールの重要な限界、すなわちコンテキストウィンドウ制約内で大規模なコードベースを信頼性高く処理・ドキュメント化できないという課題に対処していると主張します。

• 方法論的転換: この研究は、決定論的コンテキストエンジニアリングと専門化されたエージェントの階層を組み合わせることで、スケーラブルで正確かつ構文上妥当な UML 生成が可能であることを示しています。このアプローチは、複雑なリポジトリレベルのタスクに対して、単一のプロンプティングや単純な RAG を超える必要な進化として提示されています。
• 実用的有用性: 複数の言語にわたってアーキテクチャ的に整合性があり、構文上妥当な図を生成することで、自動化されたソフトウェアドキュメントとアーキテクチャ理解の向上に貢献します。
• 限定的な課題: 著者は、自動化された指標が主観的な人間の有用性を捉えていないことを認めています。システムコンテキスト図は C4 モデルの構文に対するさらなるルールセットの拡張を必要とし、現在の評価は広範であるものの、オープンソースリポジトリに限定されていると指摘しています。システムは「網羅的なカバレッジよりもアーキテクチャ的な重要性を優先」しますが、これは設計上の選択であり、バグではありません。

結論として、Code2UML は LLM ベースのソフトウェア可視化をスケーリングするための実行可能なフレームワークを提示し、適切なコンテキストエンジニアリングとエージェントの専門化があれば、LLM は現実世界のソフトウェアリポジトリの複雑さを効果的に処理できることを証明しています。