株式会社ホコサキ

graphifyでコードベースをナレッジグラフ化してAIに渡す

天京祐輔
天京祐輔
graphifyでコードベースをナレッジグラフ化してAIに渡す

業務システムの開発を続けていると、ある時点で必ずこういう場面に出くわします。
「この POST /orders エンドポイントが依存しているテーブルを教えて」と AIアシスタントに聞いたとき、返ってくるのはコードの断片だけ。
DBスキーマとの対応関係も、その設計意図が書かれた仕様書の場所も、AIには分からない。

これは AIが賢くないのではなく、 ファイルを読んでいるから 起きる問題です。
graphify はこの構造的な断絶を、ナレッジグラフという形で解決しようとするツールです。
セットアップからグラフ構築・AIツール連携まで、実装の流れを一本で追います。

AIアシスタントが「文脈を失う」のは、ファイルを読んでいるからだ

コード・DBスキーマ・仕様書が別々のディレクトリや別ツール（Confluence、Notion、Googleドキュメントなど）で管理されている状況は、業務システム開発では当たり前です。
それ自体は悪くない。
でも AIアシスタントがセッション中に「ファイルを読む」という行動をとる限り、この分散は致命的な断絶になります。

たとえば Claude Code や Cursor が Grep でコードを検索しても、「orders テーブルを参照している」という事実は分かっても、「その orders テーブルがどの機能仕様に対応しているか」は分かりません。
仕様書を別で読ませても、コードとの接続は AIの推論任せになる。
関係性が消える んです。

ここで RAG（ベクトル検索）を使えばいいじゃないか、という発想は自然です。
ただ、RAGが得意なのは「この文章に意味的に近いドキュメントを持ってくる」という類似度の計算です。
「関数 A が関数 B を呼んでいる」「テーブル C がモジュール D から参照されている」という 有向の事実 は、ベクトル空間に埋め込んでも保持できません。
コサイン類似度は測れるが、呼び出し関係という構造は消える。
これが RAGの本質的な限界です。

グラフ構造はここで強みを発揮します。
ノード（関数・テーブル・ドキュメント）をエッジ（呼び出す・依存する・説明する）でつなぐと、「AがBを呼んでいる」という事実がそのまま保持されます。
多ホップの問い、たとえば「このエンドポイントが間接的に依存しているテーブルをすべて列挙して」という問いに、グラフはトラバーサルで答えられます。
RAGは答えられない。

graphify が解こうとしているのは、まさにこの問題です。

graphify の構造：何がノードで、何がエッジか

graphify はプロジェクトフォルダを丸ごと解析して、コード・SQLスキーマ・ドキュメント・画像などをひとつのナレッジグラフに変換します。
具体的に何がノード・エッジになるかというと、こんな種別が対象です。

  • ノード: ファイル・関数・クラス・テーブル・ドキュメント（Markdown、PDF、論文）・画像・動画・設定ファイルなど
  • エッジ: 関数呼び出し・モジュール依存・テーブル参照・意味的近接（LLMが判断する関連性）・ドキュメントとコードの対応関係

出力形式は graph.json（MCPサーバー経由でクエリできる形式）と cypher.txt（Neo4j・FalkorDB へのプッシュ用）の2種類です。
ローカルのグラフファイルをそのまま使うか、外部グラフDBに接続するかは用途次第で選べます。

codebase-memory-mcp というツールと比較されることがよくあります。
codebase-memory-mcp 自身の README が「graphify の graphify-out/ ディレクトリに精神的に近い」と言及しているように、両者は似た問題意識から生まれています。
ただし codebase-memory-mcp は単一リポジトリのコード構造（関数・クラスの呼び出し関係）を高速に記憶することに特化しており、LLMを使わずに AST解析だけで動きます。
graphify はそこに加えて、SQLスキーマ・仕様書・画像・動画まで横断するグラフを構築できる点が違います。
コードだけ見ればいい場面では codebase-memory-mcp が軽くて速い。
スキーマや仕様書を巻き込んだ横断クエリが必要になったとき、graphify の出番です。

RAGとグラフの使い分けについては、2025年のベンチマーク研究（Wang et al., GraphRAG-Bench）が参考になります。
単一ホップの質問（「このドキュメントに書かれている仕様は何か」）では RAGが優位で、多ホップの質問（「このAPIが間接的に依存するすべてのテーブルを列挙して」）ではグラフが優位という結果が出ています。
問いの性質で選ぶ、というのが実務的な判断軸です。

セットアップとグラフ構築：インストールから /graphify . まで

インストールは uv か pip で一行です。

# uv を使う場合（推奨）
uv tool install graphifyy

# pip を使う場合
pip install graphifyy

パッケージ名が graphifyy（y が2つ）なのは注意点です。
graphify という名前は PyPI で別のパッケージが先に取っていたためで、インストール時に typo しやすいので気をつけてください。

次に、プロジェクトルートに .mcp.json を配置します。
Claude Code や Cursor がこのファイルを読んで MCPサーバーを起動します。

{
  "mcpServers": {
    "graphify": {
      "command": "graphify",
      "args": [".", "--mcp"],
      "cwd": "${workspaceFolder}"
    }
  }
}

グラフ本体の構築は、Claude Code を使っている場合はチャット欄に /graphify . と入力するだけです。
コード・ドキュメント・画像を読んで LLMが意味的な接続も判断するフルグラフを構築します。
LLMの呼び出しが発生するので、プロジェクト規模によってはコストがかかります。

Claude Code を使わずにまず動作を確認したい場合は、ターミナルから以下のコマンドでMCPサーバーを起動できます。

# MCPサーバーを起動してAIエディタから接続できる状態にする
graphify . --mcp

ただし、このコマンド単体でフルグラフが構築されるわけではありません。
ドキュメントや画像の意味的な接続を含むフルグラフは、Claude Code の /graphify . スラッシュコマンド（あるいは graphify スキルを持つ AIエディタ）から構築する必要があります。
まずコード構造の把握だけ試してみて、スキーマや仕様書を横断したくなったタイミングでフルグラフに移行する、という流れが現実的です。

グラフを常に最新に保つ方法は3つあります。

# 手動更新（変更後に実行）
graphify . --update

# git フックで自動更新（コミット・チェックアウト後に再構築）
graphify hook install

# ウォッチモード（編集中にリアルタイム更新）
graphify . --watch

Neo4j や FalkorDB に接続したい場合は、以下のコマンドで Cypher ファイルを生成するか、直接プッシュできます。

# Neo4j 用 cypher.txt を生成
graphify ./raw --neo4j

# Neo4j に直接プッシュ
graphify ./raw --neo4j-push bolt://localhost:7687

# FalkorDB 用
graphify ./raw --falkordb
graphify ./raw --falkordb-push falkordb://localhost:6379

チームで使う場合の git 管理方針も決めておくと楽です。
graphify-out/manifest.json はコミットして共有する（キーが相対パスで保持されるので、チェックアウト後の再構築が不要になる）。
graphify-out/cost.json はローカルのみで、.gitignore に追加します。

業務システムで使えるクエリ例：コード・スキーマ・仕様書を横断する

graphify の MCPサーバーが提供するツールは、query_graph・get_node・get_neighbors・shortest_path・list_prs・get_pr_impact・triage_prs です。
「どんな問いに使うか」という視点で整理すると、業務システム開発での使いどころが見えてきます。

たとえば「この POST /orders エンドポイントが依存しているテーブルと、その設計意図が書かれた仕様書を一度に取得したい」という問いには query_graph を使います。
MCPツールの具体的なインターフェース仕様は公開ドキュメントから確認できる部分が限られるため、ここでは概念的なイメージとして示します。
AIアシスタントに対して「/orders エンドポイントが依存するテーブルと、それらのテーブルの設計意図を説明しているドキュメントを教えて」という問いを投げると、graphify はエンドポイントノードからテーブルへのエッジをたどり、さらにそのテーブルに意味的に接続された仕様書ドキュメントのノードまで返します。
コード・スキーマ・仕様書を1回のクエリで横断できる。
これが graphify の核心です。

「このテーブルを参照しているコードをすべて列挙したい」という場面では get_neighbors が適しています。
orders テーブルのノードを起点に、inbound 方向でトラバーサルすると、そのテーブルを参照しているすべての関数・クラス・ファイルが返ってきます。
リファクタリング前の影響範囲確認に使えます。

「この変更がどのモジュールに波及するか」を調べたいときは shortest_path です。
ある関数から特定のモジュールまでの最短パスを返すので、変更の影響が直接的か間接的かを判断できます。
PRレビュー前に「どこまで影響が出るか」を確認する使い方が実務では多いです。

Claude Code との連携で面白いのが PreToolUse フックです。
graphify をインストールすると CLAUDE.md ディレクティブと PreToolUse フックが設定されて、Claude が Glob や Grep でファイルを検索する前にグラフを参照するようになります。
「ファイルを読む前にグラフに聞く」という動作順序に変わる。
これによってコンテキストウィンドウの消費を抑える効果が期待できます。
ただし graphify 自体のトークン削減効果について具体的な数値は公表されていません。
「6.8倍のトークン削減」という数値は codebase-memory-mcp が自ツールについて言及している数値であり、graphify の効果とは別の話です。

graphify・codebase-memory-mcp・RAG：どれを選ぶか

正直なところ、graphify はすべての場面で最適解ではありません。
フルグラフの構築には LLMの呼び出しが必要で、大きなプロジェクトではそれなりのコストが発生します。
ナレッジグラフを正しく構築・維持するには設計の手間がかかるというのは、RAGとグラフを比較した文脈で広く言われていることで、graphify はそのコストを大幅に下げているツールですが、ゼロにはなりません。

選択の軸は、アセットの種別と問いの性質の2つで大体決まります。

コードの構造だけ把握できれば十分なら、codebase-memory-mcp が軽くて速い選択肢です。
LLMを使わずに AST解析だけで動くので、コストもほぼゼロ。
単一リポジトリのコードを対象に「この関数を呼んでいるのはどこか」という問いに答えるだけなら、これで十分です。
SQLスキーマや仕様書・設計ドキュメントを横断したクエリが必要になったとき、graphify に移行するのが自然な流れです。
「まず codebase-memory-mcp で試して、スキーマや仕様書を巻き込みたくなったら graphify」という段階的な判断が実務的だと思います。

問いの性質も重要です。
「この仕様書に書かれている要件は何か」のような単一ドキュメントへの問いは、RAGが速くて正確です。
先述のベンチマーク結果と同様に、単一ホップの検索では RAGが優位で、多ホップの依存追跡になるとグラフが得意な領域に入ります。
「このAPIが間接的に依存するすべてのテーブルを列挙して」という問いが出てきたタイミングが、graphify を検討するサインです。

graphify は「コードベースの地図」を作るツールです。
地図がなくても開発はできますが、プロジェクトが大きくなるほど、AIアシスタントが迷子になる頻度は増えます。
その迷子コストが気になり始めたとき、試してみる価値はあると思います。

株式会社ホコサキは山口県宇部市を拠点に、業務システム開発・AI活用支援・DX推進に取り組んでいます。
graphify のような OSS ツールを実プロジェクトに組み込む支援も行っています。
興味があれば お問い合わせページ からご連絡ください。

    graphifyでコードベースをナレッジグラフ化してAIに渡す | 株式会社ホコサキ