モノレポのコード分析において、ベクター埋め込みの代わりにナレッジグラフを活用する
よくある光景です。大規模なモノレポをAIアシスタントに投入すると、隣接するサービス間の関数呼び出しを混同し、モジュール間の接続を見失い、存在しない引数を捏造し始めます。従来のベクター検索は、類似したテキストフラグメントを見つけるにはかなり優れています。しかし、ベクター表現はコードの厳密な構造を理解することに苦慮します。単に変数名を変更したり、暗黙的なインポートを変更したりするだけで、アプリケーション全体のロジックが変わってしまうからです。
開発者のVitaliy氏は、この問題を体系的に解決するためにcode-graph-ragプロジェクトを作成しました。このツールは、ベクター埋め込みだけに頼るのではなく、コードベースのナレッジグラフを構築します。
内部的动作の仕組み
システムは、Tree-sitterパーサー、Memgraphグラフデータベース、Qdrantベクトルデータベースという3つのコアコンポーネントで構成されています。
動作の流れは以下の通りです：
- Tree-sitterがソースコードファイルを抽象構文木（AST）にパースします。
- アナライザーがノード（関数、クラス、メソッド、モジュール）とその間の関係を抽出します。
- データが統一された言語非依存のスキーマでMemgraphに書き込まれます。
- この構造の上に、CLIユーティリティの
cgrが自然言語の質問を高精度なCypherクエリに変換し、グラフデータベースにクエリを実行します。
結果として、「関数Xはどこで使用され、そのデータは次にどこへ流れるのか？」と質問すると、システムはベクトル空間での近接性に基づいて答えを推測しようとはしません。グラフに対してターゲットを絞ったクエリを実行し、実際のコールパスを返します。
Исходный код -> Tree-sitter -> AST-анализ -> Граф знаний Memgraph
|
Запрос пользователя -> AI-модель (Cypher) -> Запрос Cypher -> Результаты
ツールの機能
このプロジェクトは、Python、TypeScript、Go、Rust、Java、C++、C#、PHPを含む13の言語をサポートしています。Scalaのサポートはまだ開発中で、Rubyはast-grepパターンマッチング用于解析しています。
主な機能は以下の通りです：
- コードのナビゲーションとQ&A。関数ソースを名前だけでなく、意味やアーキテクチャでの役割でもクエリできます。
- デッドコード検出。ユーティリティはアプリケーションのエントリポイントから関係グラフを走査し、どのコールチェーンからも到達できない関数やモジュールを見つけます。
- 構造的な検索と置換。古典的な正規表現の代わりに、ast-grepを使用します。このツールは構文木でパターンを検索し、構造を保持しながら慎重にコードを書き換えます。
- データフロー追跡。
FLOWS_TO機能は、変数値が代入の連鎖、関数呼び出しを通じてどのように伝播し、I/O操作で終わるかをトレースします。現在、C#、Java、C、Goで動作します。
追加の利点はModel Context Protocol（MCP）のサポートです。つまり、code-graph-ragはMCPサーバーとして実行でき、Claude Codeやその他のMCP対応クライアントに直接接続できます。AIエージェントは独自の力で正確なプロジェクト構造をクエリし、 готовые diffとして変更を提案できるようになります。
クイックスタートとシステム要件
このツールはPythonパッケージとして配布されています。完全な機能には、Docker（MemgraphとQdrantコンテナに必要）、およびcmakeとripgrepシステムユーティリティのインストールが必要です。
CLIユーティリティをインストールする最も簡単な方法は、uvまたはpipxを使用することです：
uv tool install "code-graph-rag[treesitter-full,semantic]"
インストール後、ローカル環境をセットアップし、リポジトリのインデックス作成を開始する必要があります：
# Запуск контейнеров базы данных
cgr daemon up
# Индексация кодовой базы в новый граф
cgr start --repo-path /path/to/repo --update-graph --clean
# Интерактивный режим работы
cgr start --repo-path /path/to/repo
CI/CDの一部としてユーティリティを使用したり、MCP経由でエージェントに接続する予定の場合は、ドキュメントに設定の詳細とグラフエクスポートに関するセクションがあります。
採用する価値はあるか？
このプロジェクトは、多言語モノレポで作業するチームにとって有望に見えます。従来のAIアシスタントは、コードベースが10万行を超え、サービス間の接続が различныхフォルダ間の関数呼び出しに依存している場合、しばしばお手上げになります。グラフアプローチは、厳密なコードトポロジーと言語モデルの柔軟性を組み合わせることで、この問題を根本的に解決します。
もちろん、学習曲線を考慮する必要があります。Memgraphを含むDockerコンテナを実行し、初期スキャン中のグラフ構築にリソースを割り当て、LLM APIキーを設定する必要があります。しかし、複雑なプロジェクトのリファクタリング中にニューラルネットワークの幻覚にうんざりしているなら、code-graph-ragに半小时かけて精通する価値は十分にあります。
関連プロジェクト