こんにちは、VポイントマーケティングAIエンジニアの三浦です。
先日久しぶりに映画館に映画を見に行きました。やっぱり大きな画面と迫力のある音響で作品を見ると没入感があっていいなと思いました。それと、映画館の雰囲気ってちょっと日常から離れた感じがして好きです。
さて、私はエージェントを使っていろいろとアプリケーションの開発をしています。自分しか使わないアプリだったら仕様を決めた後はコードを全てエージェントに書いてもらう、といったことも増えてきました。
そんな風に開発したアプリのソースコードをいざ読んで理解しようとしてもコードの量が膨大でなかなか手が付けられず、そのことについて最近課題に感じていました。普段自分自身が使い慣れた開発言語やフレームワークであればまだなんとかなりますが、それ以外だとそもそもどこから手を付けたらいいのかすら分からなかったりします。
それらの対策としてコードを解説するMarkdownのドキュメントをエージェントに書いてもらうのですが、関数の呼び出しがあちこちに散らばっているような構造だとドキュメントだけでは理解しづらいこともあります。
「こういうのって実はグラフ構造になっていると理解しやすいんじゃないかな」と思い、「コードベースのナレッジグラフ化」という観点で調査していたのですが、これはいいな、と思ったツールに出会いました。Graphifyというツールです。
Graphifyはプロジェクト内に存在するコードをはじめ、ドキュメント、画像、動画等のファイルからナレッジグラフを構築し、コーディングエージェントが参照できるようにするツールです。プロジェクトをナレッジグラフにすることでエージェントがファイルを開いて読むよりもより効率にかつ正確にプロジェクト全体を把握できるようになります。
色々なコーディングエージェントに対応していて、Claude CodeはもちろんCodexやGemini CLI、Github Copilot CLIでも使うことが可能です。私はプライベートではCodex, 業務ではGithub Copilot CLIを使っていますが、どちらでも動かすことができました。
今回の記事ではこのGraphifyについて導入の仕方や使い方、ナレッジグラフをどのように構築しているのかをまとめてみたいと思います。
Graphifyを導入する
GraphifyはPythonのライブラリとAgent Skillで構成されています。Pythonのライブラリのインストール方法は共通ですが、Agent Skillは格納場所などがコーディングエージェントによって異なるため、使うエージェントに合わせたインストールが必要になります。
たとえばCodex向けだと以下のようになります。
uv tool install graphifyy && graphify install --platform codex
Github Copilot CLIだと以下です。
uv tool install graphifyy && graphify install --platform copilot
graphify install --platform xxxxx を実行すると（xxxxx の部分には、Codex の場合は codex、GitHub Copilot CLI の場合は copilot などプラットフォーム名を入力します）、各コーディングエージェントのユーザー単位のAgent SKill置き場(Codexだと~/.agents/skills, Github Copilot CLIだと~/.copilot/skills)にgraphifyというSkillが配置されます。
Graphifyはナレッジグラフを構築するときにサブエージェントを使用するのですが、Codexの場合はこれを有効にするために設定ファイル~/.codex/config.tomlに以下を追加する必要があります。
[features] multi_agent = true
Graphifyを使ってみる
使い方はとてもシンプルです。プロジェクトのディレクトリ内でコーディングエージェントを立ち上げてgraphifyスキルを実行します。
Codexの場合は$graphify ., Copilot CLIの場合は/graphify .です。
しばらくするとプロジェクトディレクトリにgraphify-outというディレクトリが生成されます。その中に含まれるgraph.htmlをブラウザで開くとプロジェクト全体のコードやドキュメントに含まれるクラスや関数、コンセプトなどのノードをcalls, imports, rationale_forといったエッジで接続したグラフを見ることができます。
さらに関連性の強いノード同士で形成されるコミュニティも自動で生成されます。コミュニティ一覧を見れば、だいたいこのプロジェクトでどんな機能が実装されているのかイメージすることができそうです。
ナレッジグラフを構築した後、コーディングエージェントにナレッジグラフに基づいてプロジェクトに関する質問に答えてもらうことができるようになります。こちらもAgent Skillを呼び出して行います。
/graphify query "MAP関連のUIの実装を詳しく教えて"
Graphifyはどのように動作しているのか
さて、Graphifyはどのようにナレッジグラフを構築しているのでしょうか。一覧の流れはgraphifyスキルのSKILL.mdを読むことで理解することができます。
ファイルの検出
プロジェクトに含まれるコード、ドキュメント、論文、映像、画像ファイルの検出を行います。ちなみにGraphifyでは対象から外したいファイルを.graphifyignoreに書くことで指定することができます。.gitignoreと同様の書き方ができてさらに!src/に書くとsrcディレクトリを除くすべてを対象から除外する、といった指定もできます。
映像・音声の文字おこし
映像か音声が対象ファイルに含まれている場合はWhisperを使って文字おこしが行われます。
エンティティと関係の抽出
ファイルからエンティティと関係の抽出を行います。ここではコードとそれ以外のファイル(ドキュメントなど)で異なる戦略で抽出処理が行われます。
まずコードに対してはTree-sitterというパーサを使って静的解析が行われ、木構造(AST: 抽象構文木)が抽出されます。ここではLLMは利用されません。
それ以外のファイルに対してはサブエージェントを使って解析を行います。
(ここでサブエージェントが呼ばれるため、Codexの設定ファイルにmulti_agent = trueが必要なのだと思います。)
サブエージェントにはファイルと解析用のプロンプトが渡され、プロンプトに従ってノード(エンティティ)とエッジ(関係)の抽出を実行します。エッジには関係性の説明のほかに信頼度を表すconfidence_scoreも含まれます。
またTree-sitterによる解析とサブエージェントによる解析は同時に実行されます。
2つの木構造の統合
コードから抽出された木構造とそれ以外のファイルからサブエージェントによって抽出されたセマンティックなグラフを統合します。ここはノードの名前に基づいて機械的に実行されます。
グラフの構築、クラスタリング、分析、出力
統合された木構造からグラフを構築し、エンティティをクラスタリングしてコミュニティを生成、グラフの解析と解析結果の出力が行われます。
コミュニティラベル生成
生成されたコミュニティごとに2～5語程度でラベルの生成が行われます。この処理の後はHTMLなど指定されたオプションに応じてグラフの出力が実行されます。
まとめ
今回はプロジェクトの内容をコーディングエージェント用にナレッジグラフにすることができるGraphifyというツールをご紹介しました。やっぱりプレーンな状態よりもグラフ化されていたほうがプロジェクト全体をつかみやすいと思います。上手に活用していきたいと思いました。
また、GraphifyのPythonのライブラリといっしょにエージェント用のSkillも展開するという方法は面白いなと思いました。ツールの利用者としてコーディングエージェントが当たり前のように想定されはじめているんだな、と感じたからです。こういう展開の仕方は今後増えてくんだろうな、と思いました。
