AIアシスタントにコードを書かせたり、巨大なコードベースの解読を任せたりする機会が増えてきました。しかし「この関数、どこから呼ばれているんだっけ？」「全体の構成はどうなっている？」といったコード構造の全体把握には、AIとの対話だけだと意外ともどかしさを感じることがあります。
2026年10月、X（旧Twitter）上で「コードを1ファイルずつ検索する代わりに、質問できる関係図（知識グラフ）に変換するツール」として「Graphify」が話題を集めました。公式READMEでは Claude Code 内で /graphify . と打ち込んだり、Codex で $graphify と呼び出したりして、エージェントのスキルとしてシームレスに機能させることが紹介されています。
「AIにコードを任せる運用」の一歩先として、コード構造を視覚的・構造的に可視化・検索できる仕組みはどれほど実用的でしょうか。
今回は、自作の公開プロジェクト（micro-tools）の特定のコミットを用いて、Graphifyがどのような関係図を抽出し、どのように検索・追跡できるのかをCLI経由でじっくり検証しました。導入から操作、画面の見方、実際に便利だった点と現時点の制約を率直にお伝えします。
Graphifyとは？ どのような仕組みか
Graphifyは、ソースコードやドキュメントを解析してノード（要素）とエッジ（関係）からなる「知識グラフ」を作成し、CLIやエージェント経由で検索（query / path / explain）できるようにするツールです。
Python 3.10以上で動作し、PyPI上の公式パッケージ名は graphifyy （末尾のyが2つ）、実行するコマンド名は graphify となっています。
一般的な導入方法と、今回の検証環境
通常、ユーザーが自身の開発環境やAIエージェント環境に導入する際は、以下のステップが案内されています。
- CLIツールのインストール:
uv tool install graphifyy - エージェントへのスキル登録:
graphify install - エージェント内からの実行:
Claude Code なら/graphify .、Codex なら$graphify
※なお、今回の検証では既存の日常エージェント環境へスキル登録する通常の導入ルートは実行せず、公式ソースコード（Graphify 0.9.95）を独立したPython 3.12.3の隔離仮想環境（venv）にインストールして、CLIコマンドとして単体実行しました。
今回試したプロジェクトと検証の範囲
検証対象としたのは、筆者がGitHubで公開している小規模なユーティリティ集 micro-tools です。
今回は、コード構造の解析機能のみに絞って検証を行うため、env -iによりAPIキーを含まない実行環境でCLIを起動し、コード以外のドキュメント抽出をスキップするオプションを指定して実行しました。
| |
この処理を実行したところ、Graph Reportに表示されたToken costは 0 input / 0 output でした（※コード解析のみをローカルで実施した結果であり、全機能が常に完全ローカルかつ無料であることを意味するものではありません）。
実際に動かしてみる：関係図の出力と可視化
抽出コマンドを実行すると、プロジェクト直下に graphify-out/ ディレクトリが生成され、以下のファイルが出力されます。
graphify-out/graph.json（グラフ構造の元データ）graphify-out/GRAPH_REPORT.md（抽出・サマリーレポート）graphify-out/graph.html（ブラウザで閲覧可能なインタラクティブ関係図）
最初の抽出結果（35 code, 152 nodes）
小規模なプロジェクトでの初回抽出ログでは、以下のような構造が確認できました。
- コード関連要素: 35（JSONやYAML等の設定ファイルを含む）
- ノード（識別子・関数・ファイル等）: 152
- エッジ（呼び出し・依存関係）: 196
- コミュニティ（自動分類されたグループ）: 11
なお、--code-only を指定したため、9個の文書ファイル（Markdown等）と1個の画像ファイルはスキップされました。また、.gitignore や styles.css などの6ファイルは未分類となり、analytics.js については「シンボル 0」という警告ログが出力されました。全ファイルや全記術の完璧な理解を保証するものではありませんが、主要なソースコードの構造は素早く可視化されました。
ブラウザで見るインタラクティブ関係図
出力された graph.html をブラウザ（および headless Chrome）で開くと、Canvas上にノードと線（エッジ）がインタラクティブに描画されます。
画面上でノードを検索・選択すると、右側のパネル（Source / Neighbors）に対象ノードのコード位置や隣接する呼び出し関係が表示されます。
上図は、準委任の精算幅・超過控除計算内の calculateSettlement ノードを選択した状態です。画面上のノード選択パネルには対象関数の相対ファイルパスが表示され、どの関数から呼び出されているかが一目で把握できます。なお、定義箇所の行番号についてはCLIのquery/explain実行時に確認できます。
なお、この graph.html 自体はローカルファイルですが、図の描画に使用するVis.js等のライブラリを外部CDNから読み込む仕様になっています。そのため「グラフの表示を含めて完全オフラインで完結する」わけではない点に注意してください。
実際に生成された関係図は、以下のリンクからお手元のブラウザで確認できます。
CLIでの検索体験：関数の呼び出し関係を調べる
Graphifyの真価は、生成したグラフ構造に対してCLIから自然言語や検索コマンド（query, path, explain）を投げられる点にあります。
1. graphify query —— 呼び出し元の特定
「この関数を呼び出しているのはどこか？」を調べるため、英語でクエリを投げました。
| |
【実行結果】
6つの関連ノードと正確な呼び出し関係が返ってきました。
sites/settlement-range-calculator/app.jsの41行目にあるrender()関数からcalculateSettlement()を呼び出しているcalculator.mjsの15行目にあるcalculateSettlement()内からvalidateNumber()を呼び出している
実際のソースコードと照合したところ、行数・関係性ともに完全に一致していました。英語での “calls” に絞った問いかけに対して、非常にノイズの少ない正確な部分グラフが取得できています。
日本語クエリの場合
同じ内容を日本語で実行してみました。
| |
同じ呼び出し関係自体は抽出できたものの、返ってきた関連ノード数は19個に増加し、やや広範囲のノードが拾われる挙動を示しました。
また、関数名を含まない抽象的な問い（サイトの公開URLはどこで選ぶ？）を投げたところ、「該当なし」という結果になりました。日本語が一切通らないわけではありませんが、関数名や識別子を明確に含めた検索の方が意図通りの結果を得やすい印象です。
2. graphify path —— 依存経路の探索と曖昧さ回避
特定ノード間の最短経路を調べる path コマンドも検証しました。
まず、単に render から calculateSettlement への経路を指定してみました。
| |
結果は、render という名前の関数がプロジェクト内の3つのファイルに存在するため、「曖昧である（Ambiguous）」というエラー（exit code: 3）を出して安全に停止しました。
そこで、ファイルパスを付与して厳密に指定します。
| |
このように指定することで、1ホップの正確な呼び出し経路（calls）が返ってきました。同名関数が複数存在する場合でも、明示的なパス指定で絞り込める仕様になっています。
3. graphify explain —— 構造の解説とトップレベル呼び出しの挙動
特定シンボルの定義やインポート関係を解説する explain コマンドを検証しました。
| |
このコマンドを実行すると、対象関数の定義場所やインポート元の情報が正しく返されました。
ただし、挙動の観察において1つ注目すべき点がありました。scripts/indexnow.mjs の20行目には、この関数を直接実行するトップレベルでの呼び出しが存在していましたが、このトップレベル呼び出し自体は calls の線（エッジ）としてレポートに出力されませんでした。
この1例のみをもって「Graphifyはすべてのトップレベル呼び出しに対応していない」と一般化することはできませんが、「関係図上に線が存在しない＝絶対に呼び出されていない」と過信するのは避け、コードの文脈と併せて確認するのが安全です。
使って見えた「得意なこと」と「現在の制約」
今回の検証を通じて、Graphifyを単体CLIとして動かした際の特徴と限界が明確になりました。
得意なこと：識別子を手がかりにした部分グラフのピンポイント取得
「関数名」や「モジュール名」などの識別子を指定して呼び出し元や定義箇所を取り出せるため、見慣れないプロジェクトで影響範囲を調べる作業には強力です。ただし、今回は35のコード関連ファイルからなる小規模な公開プロジェクト1件での検証にとどまり、大規模環境における効果や時間短縮の割合は未計測です。
LLMにコード全体を毎回読ませて回答させるアプローチとは異なり、決定論的に抽出されたノードとエッジの構造からピンポイントで関連箇所（部分グラフ）を引き出せるため、誤認識（ハルシネーション）を抑えた構造把握が期待できます。
現在の制約と留意点
1. 曖昧な質問・意図理解の壁
How are changed files submitted to IndexNow? のように、具体的な関数名を含めずシステム全体の挙動を尋ねる広範な英語クエリを実行したところ、目的の scripts/indexnow.mjs ではなく、主に scripts/build.mjs 内の indexNow 変数周辺が検索結果として返ってきました。
高度な自由質問理解をLLM単体で行わせるというよりは、「明確なコード名（シンボル名）を手がかりに依存関係を引いてくる」用途で真価を発揮するツールと言えます。
2. 部分一致・名前検索の挙動
存在しない架空の長い識別子を検索した際、その文字列内に test という単語が含まれていると、プロジェクト内に実在する test ノードがヒットする挙動が確認されました（完全に無関係な文字列 zzzqxv489 では「該当なし」となりました）。文字列検索のフックが意図しない部分一致を起こすケースがあるため、ヒットしたノードは実際のコード位置と合わせて確認が必要です。
3. コード仮変更時の復元ガード（dedup shrink）の挙動
動作検証の一環として、コード内の関数定義名1箇所のみを calculateSettlementRenamed へと仮変更し、動作を確認しました（※呼び出し元はあえて変更せず、定義名のみの仮変更です）。
- 再抽出前の
explainは旧名のまま保持され、変更警告等は出ませんでした。 - その後、再度
graphify extractを実行すると1 code changed / 34 unchangedと正しく検知され、新関数名がグラフに反映されました。
その後、検証を終えてコードを元の名前（calculateSettlement）へ復元した際、ノード数が153個から152個へ減少（ノード重複排除による縮小）しました。このとき、Graphify内部の「dedup shrink ガード」が働き、通常の --force オプションを付与しただけでは再生成が拒否されました。
今回のケースでは、意図的な仮変更からの復元であることが分かっているため、以下の明示的なオプションを付与してグラフの再生成を完了させました（検証完了後、元コードはGitの差分がない状態へ復元済みです）。
| |
実運用において、リファクタリング等でノード数が減少した際に生成をガードしてくれる安全機能ですが、意図した変更で再生成したい場合は --allow-dedup-shrink オプションが必要になることを覚えておくとスムーズです。
まとめ
Graphifyは、AI時代における「コードと開発者の間をつなぐ構造マップ」として非常に面白いアプローチを提供してくれます。
今回、35のコード関連ファイルからなる小規模な公開プロジェクトで検証した範囲では、主要な関数の呼び出し元や依存関係を正確に抜き出し、可視化・検索できることが確認できました。
一方で、今回の検証は以下の条件・範囲のものである点に留意が必要です。
- 未検証の範囲: 大規模なコードベースでの効果実証、ドキュメントや画像からの意味抽出機能、AIエージェントによる最終回答の品質、MCP（Model Context Protocol）統合、自動フック（hook/watch）機能。
- 未計測の項目: 処理速度、トークン削減率、他製品やLLMモデルとの性能比較。
AIにコード生成を全面的に任せる場面が増えるからこそ、開発者自身がシステム全体の構造を見失わないための「地図」を持っておく価値は高まっています。「この関数の影響範囲を素早く手元で可視化したい」という課題を感じている方は、まずはCLIで手元のコードベースを解析させてみてはいかがでしょうか。
参考
- Graphify 公式リポジトリ (GitHub) — 知識グラフ生成ツールの公式ソースコード。
- Graphify 追跡コミット (GitHub) — 本記事の検証時に参照した固定コミット。
- 検証対象コード：micro-tools (GitHub) — 今回Graphifyの解析対象として使用した自作ユーティリティコード。
- きっかけとなったXの投稿 — Graphifyの機能紹介が話題となった2026年10月20日の投稿。
この記事は Gemini Web が執筆しました。