GitLab Knowledge Graph による AI エージェントのコード理解を検証してみた

AIAI駆動開発(AIDD)GitLaby-imai

こんにちは、クリエーションラインの今井です。今回は GitLab 18.4 でベータ版リリースされた Knowledge Graph を検証してみたいと思います。

はじめに

本記事では、AI エージェントの推論の精度を劇的に向上させると期待されている GitLab Knowledge Graph について、その機能概要と、実際にローカル環境で実施した機能検証の結果を共有します。具体的には、 Knowledge Graph をインストールし、Java のオープンソースプロジェクトである Spring Petclinic を対象にインデックスを作成し、Model Context Protocol (MCP) を通じて GitLab Duo Agentic Chat からコード理解のためのツールを実行しました。

本記事を通じて Knowledge Graph がどのようにコードベースを構造化し、エージェントがどのようなコンテキストを得ているのかを理解し、今後の GitLab Duo Agent Platform の未来像を把握することができます。

本記事では、検証用サンプルとして Spring Petclinic を使用しています。
出典：spring-projects/spring-petclinic（Apache License 2.0）
リポジトリ：https://github.com/spring-projects/spring-petclinic
参考：本家READMEのライセンス表記（Apache License 2.0）と LICENSE.txt を確認のこと。

Knowledge Graph とは

GitLab は、ソフトウェア開発ライフサイクルのあらゆる段階で AI を統合する AI-native プラットフォームへの変革を進めています。その中核となるのが、GitLab Duo Agent Platform であり、このプラットフォームにおける最も重要な基盤技術の一つが Knowledge Graph です。

GitLab は DevSecOps プラットフォームとして、ソースコードや知的財産だけでなく、プロジェクト計画、バグのバックログ、CI/CD 構成、セキュリティレポート、コンプライアンスデータなど、豊富な非構造化データを保持する「システム・オブ・レコード」として機能しています。Knowledge Graph は、この Unified Data Platform を拡張する要素として位置づけられています。

AI はコンテキスト (文脈) によって能力が向上します。 Knowledge Graph は、コードと非構造化データをインデックス化して縫い合わせ、特にエージェントからのアクセスに最適化されたグラフ構造を提供します。

Knowledge Graph は、ファイル、依存関係、開発パターン間の関係を理解することで、AI エージェントはコードベース全体の関係性を理解し、複雑な質問に対してより迅速で正確な応答を返せるよう設計されています。

GitLab Duo Agent Platform は、この Knowledge Graph を基盤として活用することで、AIエージェントの精度を高めています。

Knowledge Graph を使って実現できること

Knowledge Graph は、コードベースにわたるリッチなコードインテリジェンスを提供しており、以下の機能が実現されます。

  • Codebase RAG (Retrieval-Augmented Generation) の実現:
    コードベースをライブで組み込み可能なグラフデータベース（KuzuDB を使用）に変換し、RAG アプリケーションに活用します
  • コードナビゲーションと検索:
    「定義への移動 (go-to-definition)」、「すべての参照の検索」、「参照の追跡」といった機能を提供します
  • 影響分析 (Impact Analysis):
    ある変更がシステム内の他の部分にどのように影響するかを理解するのに役立ちます
  • アーキテクチャの可視化:
    システムの構造と依存関係の洞察に富んだダイアグラムを生成します

現時点の対応言語と解析粒度は以下の通りです。公式ドキュメントより引用しています。

言語定義とインポートファイル内参照ファイル横断参照
Ruby〇〇〇
Python〇〇×
TypeScript〇〇×
JavaScript〇〇×
Kotlin〇〇〇
Java〇〇〇

また、Knowledge Graph のローカルサーバーは、Model Context Protocol (MCP) エンドポイントを提供します。MCP は AI ツールがコードベースの構造を理解し、コンテキスト認識型の支援を提供することを可能にします。コード理解のための主な MCP ツールは以下の通りです。

  • list_projects:
    Knowledge Graph に登録されているプロジェクト一覧を取得します
  • search_codebase_definitions:
    定義名（クラス名や関数名など）の高速検索を行います
  • get_references:
    指定された定義の呼び出し元や参照元を列挙します
  • read_definitions / get_definition:
    定義本文を取得したり、コード内の呼び出し箇所から定義元へジャンプしたりします
  • repo_map:
    ディレクトリ構造と主要定義の要約を示す凝縮マップ(XML形式)を返します
  • index_project:
    インデックスを再実行し、変更を反映します

検証

ここからは検証した内容を具体的に記載していきたいと思います。

対象リポジトリの準備

Spring Petclinic をミラーリングして、GitLab にリポジトリを作成し、ローカルにクローンしました。

Knowledge Graph をインストール

curl -fsSL https://gitlab.com/gitlab-org/rust/knowledge-graph/-/raw/main/install.sh | bash

リポジトリのインデックス構築

対象リポジトリのディレクトリでgkg indexを実行し、コードを解析してローカルのグラフデータベース (KuzuDB) に格納しました。

gkg index --stats
2025-10-08T06:42:38.715542Z  INFO Created data directory: /home/y-imai/.gkg
2025-10-08T06:42:38.716891Z  INFO Discovering workspace: /home/y-imai/repos/spring-petclinic
2025-10-08T06:42:38.716938Z  INFO Cleaning up workspace: /home/y-imai/repos/spring-petclinic
2025-10-08T06:42:38.716945Z  INFO Indexing repositories in workspace: /home/y-imai/repos/spring-petclinic
2025-10-08T06:42:38.721854Z  INFO Finished indexing repositories in workspace: /home/y-imai/repos/spring-petclinic, statistics: WorkspaceFolderStatistics { file_count: 153, repo_count: 1 }
2025-10-08T06:42:38.721954Z  INFO Found 1 repositories with 153 files in workspace
2025-10-08T06:42:38.724090Z  INFO Starting repository indexing for: spring-petclinic
2025-10-08T06:42:38.735673Z  INFO Processing 43 files
2025-10-08T06:42:38.735725Z  INFO Using 8 CPU workers (spawn_blocking)
2025-10-08T06:42:38.751849Z  INFO 🔄 Progress: 11% (5/43 files) - 310.8 files/sec - 5 processed, 0 skipped, 0 errors
2025-10-08T06:42:38.754855Z  INFO 🔄 Progress: 23% (10/43 files) - 524.7 files/sec - 10 processed, 0 skipped, 0 errors

<中略>

2025-10-08T06:42:39.211178Z  INFO ✅ Workspace indexing completed in 0.49 seconds
2025-10-08T06:42:39.211220Z  INFO Indexing Summary:
2025-10-08T06:42:39.211254Z  INFO   - Total Projects: 1
2025-10-08T06:42:39.211260Z  INFO   - Total Files: 43
2025-10-08T06:42:39.211264Z  INFO   - Total Definitions: 213
2025-10-08T06:42:39.211268Z  INFO   - Total Imported Symbols: 430
2025-10-08T06:42:39.211271Z  INFO   - Total Definition Relationships: 448
2025-10-08T06:42:39.211276Z  INFO   - Total Imported Symbol Relationships: 0
2025-10-08T06:42:39.211279Z  INFO Project Timing:
2025-10-08T06:42:39.211283Z  INFO   - /home/y-imai/repos/spring-petclinic: 0.49s (43 files, 213 definitions, 430 imported symbols, 448 def relationships, 0 imp relationships)
2025-10-08T06:42:39.211289Z  INFO Language Breakdown:
2025-10-08T06:42:39.211292Z  INFO   - Java: 43 files, 213 definitions

サーバーを起動して、Web UI で解析したグラフを可視化

gkg server startを実行し、サーバーを起動すると http://localhost:27495 にアクセスすることでグラフを確認できます。

gkg server start

VS Code で解析したグラフを可視化

対象リポジトリをクローンしたディレクトリで VS Code を起動します。その後、コマンドパレットでShow Gitlab Knowledge Graphを実行すると VS Code 上でグラフを確認できます。
(VS Code に GitLab Workflow extension がインストールされている前提です)

MCP ツールを検証

次に Agentic Chat を使って MCP ツールの検証をしていきます。以下のコマンドでサーバーを再起動し、MCP 構成ファイルに登録します。

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

また、対象リポジトリのプロジェクトのトップグループにて、MCP を有効にします。

list_projects

list_projectsを試すために、VS Code で Agentic Chat を開いて、以下のプロンプトを入力します。

Knowledge Graph の list_projects を実行し、登録済みプロジェクト一覧を表示してください。
/home/y-imai/repos/spring-petclinic が含まれるかをチェックし、
存在する場合は「OK」とひとこと添えてください。

すると Agentic Chat からは以下のレスポンスが返ってきます。

search_codebase_definitions

search_codebase_definitionsを試すために以下のプロンプトを入力します。

search_codebase_definitions を使って、
project_absolute_path="/home/y-imai/repos/spring-petclinic"
search_terms=["PetClinicApplication","Owner","OwnerController","Pet","PetController","VetController","Visit"]
で実行してください。
name / definition_type / location（ファイル:行範囲）/ fqn を表でまとめ、次の推奨アクションを1行で示してください。

レスポンスは以下の通りです。

Run MCP tool knowledge-graph_search_codebase_definitionsが実行され、検索結果（Owner, Pet 関連定義）の要約が返されました。さらに、次のアクション候補として、read_definitionsで実装を読み取るか、get_referencesで使用箇所を調査する、という提案がされました。

read_definitions

read_definitionsを試すために、以下のプロンプトを入力します。

read_definitions で
definitions=[{"names":["OwnerController"],"file_path":"src/main/java/org/springframework/samples/petclinic/owner/OwnerController.java"}]
を入力に実行してください。
定義本文の先頭30行をコードブロックで示し、公開APIとして重要なメソッド名を3つ列挙して下さい。

レスポンスは以下の通りです。

Owner クラス定義の先頭30行が抽出され、さらに以下の「公開 API 的に重要なメソッド名」が3つ列挙されました。

単なるコードブロックの抽出に留まらず、グラフ情報に基づいてメソッドの「目的」を理解し要約できていることが確認できます。

get_references

get_referencesを試すために、以下のプロンプトを入力します。

get_references を使い、
definition_name="OwnerRepository"
file_path="src/main/java/org/springframework/samples/petclinic/owner/OwnerRepository.java"
を指定して実行してください。
参照タイプが CALLS のものだけを抽出し、file:line / 簡単なcontext を上位5件示してください。

レスポンスは以下の通りです。

Owner クラスの CALLS 参照がリストアップされました。参照元として、PetControllerTests.java、VisitControllerTests.java、OwnerController.javaなど、複数のテストクラスやコントローラーが検出され、「Ownerクラスは主にテストクラスとコントローラーでnew Owner()として直接インスタンス化されており、テストデータ作成やデフォルト値提供に使用されています」という簡潔な要約が返されました。

Java のファイル横断参照が機能しており、エージェントはコードの特定部分がアプリケーション全体でどのように利用されているかを瞬時に把握できることが確認できました。

get_definition

get_definitionを試すために、以下のプロンプトを入力します。

get_definition を使って、以下の行に含まれる symbol_name="PetClinicApplication" の定義を特定してください。
file_path="src/main/java/org/springframework/samples/petclinic/PetClinicApplication.java"
line="SpringApplication.run(PetClinicApplication.class, args);"

結果に primary_file_path / start_line / end_line を含めて返してください。

レスポンスは以下の通りです。残念ながら MCP ツールがうまく動作せず、違うアプローチで解析した結果が返ってきました。

repo_map

repo_mapを試すために、以下のプロンプトを入力します。

repo_map を
project_absolute_path="/home/y-imai/repos/spring-petclinic"
relative_paths=["src/main/java/org/springframework/samples/petclinic"]
depth=2
で実行してください。
返ってきたXMLの <files> セクションから、定義数が多い上位3ファイルと各定義数を簡潔に要約してください。

レスポンスは以下の通りです。

定義数が多い上位 3 ファイルがリストされました。

index_project

index_projectを試すために、以下のプロンプトを入力します。

repo_map を
project_absolute_path="/home/y-imai/repos/spring-petclinic"
relative_paths=["src/main/java/org/springframework/samples/petclinic"]
depth=2
で実行してください。
返ってきたXMLの <files> セクションから、定義数が多い上位3ファイルと各定義数を簡潔に要約してください。

レスポンスは以下の通りです。

プロジェクトに変更がなかったため、インデックス実行結果は「差分なし」となり、Class、Method、Constructor、Interface の定義数が前回と同一であることを示す統計値（例: Class: 44 (±0)）が返されました。

検証のまとめ

AI エージェントによるリアルタイムなコードベース理解

Agentic Chat は、gkg serverが提供する MCP エンドポイントを介して、コードベースの構造（定義、参照、パッケージ構造）をリアルタイムで把握し、コードスニペットの検索に留まらない深さの回答を提供できます。

複雑なコードベースの俯瞰

repo_mapやsearch_codebase_definitionsにより、新規参画者がコードベースの「主要なビジネスロジックが存在する場所」や「最も定義数の多いファイル」を短時間で把握できることが分かりました。

高度なナビゲーションの実現

Java におけるファイル横断参照の追跡（get_references）が機能しており、変更時の影響範囲の特定や、特定のクラスのインスタンス化パターンを分析することが可能です。

さいごに

現在（GitLab 18.4）の Knowledge Graph は、ローカルコードのインデックス化に焦点を当てています。今後は、このグラフ構造をさらに発展させ、DevSecOps プラットフォーム全体に統合することが期待されています。

GitLab データ全体の統合

今後のリリースでは、コードだけでなく、イシュー、マージリクエスト、セキュリティ脆弱性 など、すべての GitLab データが Knowledge Graph に「縫い合わせ」られ、接続されたマップが形成される予定です。

フル統合型サービスの実現

今回検証したローカルで実行するコミュニティエディション (gkg CLI) を基盤として、将来的にはGitLab.com および Self-Managed インスタンス内に完全に統合された Knowledge Graph Service が提供される予定です。

エージェントの推論加速

Knowledge Graph が拡張されることで、エージェントの推論と判断が加速され、より低コストで高品質なエージェントのアウトプットが提供されると期待されています。

Knowledge Graph の拡張により、GitLab Duo Agent Platform が人間と同じくらい自然に一緒に働くチームメイトとなるような、真の人間とAIのコラボレーション環境となることに期待したいです。

Author

今井陽祐

    GitLabの活用支援を中心としたカスタマーサクセスエンジニア
    GitLabのテクニカルサポートを軸に、プリセールスやコンサル支援まで担当

    今井陽祐の記事一覧

    新規CTA