GitLab Knowledge Graphでコードベースの構造を「見える化」してみよう！

このブログは、Cloud Partner Advent Calendar 2025の1日目の記事です。

こんにちは！クラウドパートナーの大川です

ソフトウェア開発において、開発が進めば当然コード量も増えていきます

そんな中、新しいメンバーが加わったとき、「この関数、どこから呼ばれてる？」「あのモジュールの依存関係はどうなってる？」といったコードベース全体を俯瞰する作業が大きなボトルネックになることは多いと思います

そこで今回は、GitLabがベータ提供を開始した「GitLab Knowledge Graph」を利用して、
この課題を解決に近づけていきたいと思います

Knowledge Graphって何をしてくれるの？

簡単に言えば、Knowledge Graphは膨大なコードをグラフに変えてくれます

単なるテキスト検索やファイルリストではなく、コードに含まれる以下の要素を抽出し、
それらの「関係性」を構造化して格納します

• 構造的要素： ファイル、ディレクトリ、クラス、関数、モジュール。
• コードの関係性： 関数呼び出し、継承階層、モジュール間の依存関係。

実際に使ってみた、導入と解析ステップ

公式ドキュメントに従い、実際にKnowledge Graphをローカルリポジトリで試しました

Step 1: ワンラインインストール

まずは公式が提供しているワンラインスクリプトを使って、CLIツール（gkg）を含むフレームワークをインストールします

https://gitlab-org.gitlab.io/rust/knowledge-graph/

Step 2: リポジトリの解析

インストールが完了するとgkgコマンドが使えるようになります

コードの解析をしたいGitLabプロジェクトのルートに移動して、gkgコマンド実行します

gkg index

このコマンドでGitLabプロジェクトの現状のコード群を解析してくれます

その後、以下のコマンドでローカルサーバーを立ち上げます

gkg server start

CLIで出力されたURLを開くとKnowledge Graphが表示されます

Step 3: グラフを操作して確認

Knowledge Graphのノードの見方

グラフ内のノードは、コードベースを構成するさまざまな要素を表しており、色で分類されています。

ノードの色が示す意味は以下のとおりです。

グラフはスクロールや虫眼鏡ボタンで拡大・縮小して確認できます。

MCPでKnowledge GraphとAI Agentの連携を検証

Knowledge Graphは、MCP設定することでAI Agentと簡単に連携させることができます。

今回は、GitLab Duo Agentからknowledge Graphのツールを検証してみます。

事前準備

• GitLabのプロジェクト（リポジトリ）にコードを設置する
• VSCode拡張機能の「GitLab Workflow」をインストールする
• GitLabのパーソナルアクセストークンを生成し、GitLab Workflowに登録する

拡張機能の設定は、以下を参考に。

https://docs.gitlab.com/editor_extensions/visual_studio_code/

上記の準備が完了すると、Gitlab Duo Agent PlatformというチャットがVSCodeで利用できるようになります。

サンプルコードを元に試す

サンプルコードの構成は以下のようにしました。

utils.pyに設定した共通ロジックを、他の実行コードで利用しています。

ここでは、共通ロジックのコードを変更する前に、
影響範囲がどれくらいあるのか確認するタスクを実行します。

test-knowledge-graph-mcp/
├── batch_processor.py
├── calculator.py
├── config_manager.py
├── data_analyzer.py
├── data_processor.py
├── main.py
├── report_generator.py
├── scientific_calculator.py
└── utils.py <-- 他の全てのファイルで利用する共通コードを定義

まず最初に、以下のコマンドで現状のコードを解析します。

gkg index

また、GitLab Duo Agent側にMCPの情報を追加するために、以下を実行します
これでローカルサーバーを起動しつつ、MCPの設定を自動で登録してくれます

この登録コマンドは、一度だけ実行すれば問題ありません。

gkg server start --register-mcp ~/.gitlab/duo/mcp.json

サーバーが起動したら、
Agent Chatに以下のプロンプトを渡してみましょう

utils.pyのコードを変更しようと思うが、
どのファイルに影響が発生するかをMCPのget_referencesを使って確認し、
リスト化して。

表示結果

MCPのget_referencesを使って、現在のコードの構成を解析してくれました

utils.py関数の使用ファイル一覧

calculate関数 (6ファイルで使用)
・main.py - main()関数
・calculator.py - Calculator.perform_calculation()メソッド
・data_analyzer.py - analyze_dataset()関数
・report_generator.py - ReportGenerator.generate_summary()メソッド
・scientific_calculator.py - ScientificCalculator.advanced_calc()メソッド

format_result関数 (7ファイルで使用)
・main.py - main()関数
・calculator.py - Calculator.perform_calculation()メソッド
・config_manager.py - ConfigManager.load_config()メソッド
・data_analyzer.py - analyze_dataset()関数
・data_processor.py - process_data_list()関数、calculate_average()関数
・report_generator.py - ReportGenerator.generate_summary()メソッド
・scientific_calculator.py - ScientificCalculator.advanced_calc()メソッド
・batch_processor.py - process_batch()関数

validate_input関数 (6ファイルで使用)
・main.py - main()関数
・config_manager.py - ConfigManager.load_config()メソッド
・data_analyzer.py - analyze_dataset()関数
・data_processor.py - process_data_list()関数、calculate_average()関数
・scientific_calculator.py - ScientificCalculator.advanced_calc()メソッド
・report_generator.py - ReportGenerator.generate_summary()メソッド

process_config関数 (2ファイルで使用)
・config_manager.py - ConfigManager.load_config()メソッド
・batch_processor.py - process_batch()関数

log_operation関数 (2ファイルで使用)
・report_generator.py - ReportGenerator.generate_summary()メソッド
・scientific_calculator.py - ScientificCalculator.advanced_calc()メソッド
・batch_processor.py - process_batch()関数

transform_data関数 (1ファイルで使用)
・data_analyzer.py - analyze_dataset()関数


影響を受けるファイル総数: 8ファイル
1. main.py
2. calculator.py
3. config_manager.py
4. data_analyzer.py
5. data_processor.py
6. report_generator.py
7. scientific_calculator.py
8. batch_processor.py

Knowledge Graph MCPで使えるツール

今回はget_referencesを試しましたが、他にもMCPで利用できるツールがあります

現状のコードを解析するツールがいくつかありますね

• list_projects: ナレッジグラフ内の全プロジェクトのリストを取得します。
• search_codebase_definitions: コードベース内の関数、クラス、メソッドなどの定義を効率的に検索し、その情報（名前、FQN、種類、場所、コンテキスト）を返します
• index_project: プロジェクトのナレッジグラフインデックスを新規作成または再構築し、
  最新の変更を反映させます。
• get_references: コード定義（関数、クラス、定数など）への参照をコードベース全体から見つけます。
• read_definitions: コードベース内の複数の定義の本体（コード）を読み取ります
• get_definition: 特定の行にある関数やメソッドの呼び出しから、その定義元に直接移動します
• repo_map: リポジトリのセグメント（ファイルやディレクトリ）の簡潔なAPI形式のマップ（ASCIIツリーと定義情報）を生成します

利用できるツールについては、以下から確認

https://gitlab-org.gitlab.io/rust/knowledge-graph/mcp/tools/

導入してみて感じたメリット

開発者体験と生産性の向上

• 影響範囲の正確な把握: 特定のクラスや関数を変更した場合に、どのファイルやモジュールに影響が及ぶかをグラフ上で可視化・クエリでき、変更リスクを確認できる
• システムアーキテクチャの可視化: コードベースの構造（ディレクトリ、ファイル、クラス）とそれらの関係性を俯瞰的に目視で確認できる

AI駆動開発の強化

• AI回答精度の向上: MPC設定を行うことで、AI AgentとKnowledge Graphを連携させることができました。AIエージェントに構造化されたコンテキストを提供し、複雑な質問やタスクに対する回答の正確性を高められそうです

ご注意：この機能は現在2025年12月10日時点で「パブリックベータ版」です

今回ご紹介したGitLab Knowledge Graphは、現時点ではパブリックベータ版（Public Beta）として提供されています。一部の機能はまだ改良中とのことなので、今後の情報に期待しましょう

参考

https://gitlab-org.gitlab.io/rust/knowledge-graph/

https://gitlab-org.gitlab.io/rust/knowledge-graph/mcp/tools/

お知らせ
GitLabを活用したアジャイル開発にご興味はありませんか？