レガシーコードの改修を頼まれたとき、最初に何をしますか。
IDEでファイル一覧を眺める、grepで関数名を検索する、git logでコミットメッセージを漁る——どれも間違っていないけれど、正直なところ「全体が見えている感覚」にはなかなかなれないですよね。
担当者がいれば聞けます。
でも中小企業の業務システムでは、担当者が退職していて引き継ぎ資料がExcelのメモだけ、コメントも最小限という現場が少なくありません。
PHPとMySQLで動いているWebシステム、VB.NETとSQL Serverの受発注システム——「なんとなく動いている」10年物のコードに初めて触れるときの、あの「どこから読めばいいか分からない」感覚は、経験した人なら共感してもらえると思います。
graphify は、そういう状況で 最初に地図を作る ためのツールです。
コードベースをAST解析して依存関係を知識グラフ化し、MCPスキルとしてエージェントに渡せます。
ベクトルDBも外部インフラも不要で、ローカルで完結します。
改修前にグラフを作り、エージェントに構造を把握させてから手を動かす——このフローが実務で何を変えるか、仕組みから順に掘り下げます。
ドキュメントのないコードを読む前に「地図」を作る
IDEの「定義へジャンプ」は便利です。
でもあれは 1ファイルずつ追う 作業です。
ある関数がどこから呼ばれているかは分かっても、「このテーブルを更新しているコードが全部でいくつあるか」「この設定値を参照しているモジュールの一覧」といった横断的な依存関係は、手作業では全容が見えません。
問題は精度よりも心理的なコストです。
「まだ見ていない重要なファイルがあるかもしれない」という不安を抱えたまま改修に踏み込むと、影響範囲の見積もりが甘くなります。
テストがなければなおさらで、「ここを変えたら他のどこかが壊れるかもしれない」を頭の中だけで管理しながら作業するのは、単純に消耗します。
grepやリーディングで問題が解けないわけではありません。
それは「コードを読みながら頭の中に地図を作っている」状態です。
graphifyが提案しているのは 先に地図を作ってからコードを読む という順番の入れ替えで、この発想の転換が作業感を変えます。
コードを触る前にグラフを生成して全体像を眺めておく。
「この関数はシステムのどこに位置しているか」「影響範囲はどのくらいか」を把握した上でエディタを開く。
些細な順番の違いに見えますが、心理的な余裕と改修の精度が変わります。
AST解析でエッジに「理由」を付ける──graphify の仕組み
graphifyは Tree-sitter を使ってコードをAST（抽象構文木）に変換し、そこからノードとエッジを抽出して知識グラフを構築します。
SQLスキーマや設定ファイル、PDFドキュメントも解析対象に含められます。
ここで重要なのが、エッジに 「理由」が付く という点です。
単なる「AがBを呼んでいる」ではなく、「getUserById は users テーブルを参照している（SELECTクエリとして）」というように、依存の種類と文脈がエッジに記録されます。
「なぜ関係があるか」という情報があるかどうかが、後からエージェントに問い合わせたときの回答の質に直結します。
主な特徴を整理すると次のとおりです。
- ノードの種類：関数・クラス・テーブル・設定ファイル・ドキュメント（PDF含む）
- エッジの意味：参照の事実だけでなく、依存の種類と理由が付与される
- コード解析にLLM呼び出しなし：Tree-sitterによる決定論的なAST解析のため、外部APIへのコード送信が発生しない
- 出力ファイル：graph.json（機械可読・MCP連携用）とgraph.html（ブラウザで開けるインタラクティブ可視化）
インストールと実行はシンプルです。
# インストール（パッケージ名は graphifyy、コマンド名は graphify）
uv tool install graphifyy
# プロジェクトルートで実行
graphify .
実行が終わると graphify-out/ ディレクトリに graph.json と graph.html が生成されます。
graph.html をブラウザで開くと、ノードとエッジが可視化されていて、依存が集中している「神クラス」的なノードがひと目で分かります。
コードを読む前にここを眺めるだけで、「このファイルは慎重に触らないといけない」という感覚がつかめます。
ベクトルストアは不要です。
埋め込み生成も外部インフラも要らず、ローカルのファイルシステムだけで完結します。
「まず動かしてみる」ときの摩擦の少なさは、実務的にかなりありがたいポイントです。
RAGが「何が書いてあるか」を探すなら、グラフは「なぜこの関係があるか」を辿る
RAGをコード理解に使ってみて、こんな経験をしたことはないでしょうか。
「orders テーブルを更新しているコードを教えて」と聞いたとき、意味的に近いコードは返ってくるのに、実際にUPDATE文を叩いているコードが漏れていた——というケースです。
これはRAGの設計上の特性から来ています。
類似検索は 確率的 です。
クエリと意味的に近いチャンクを返しますが、呼び出し経路を「辿る」わけではありません。
関数Aが関数Bを呼び、関数Bがテーブルを更新しているという連鎖を追うには、グラフのようにノードとエッジを辿る 決定論的な探索 が必要です。
もっとも、これはRAGが劣っているという話ではなく、役割が違うという話です。
RAGが得意なのは「このコメントや仕様書に似た処理はどこに書いてあるか」という意味検索です。
自然言語のドキュメントやコードコメントを横断して「意味的に近い場所」を探すのはRAGの本領で、そこは置き換えられません。
一方でgraphifyのグラフが得意なのは「このテーブルを参照しているコードはどこか」「この関数を変えたら影響する範囲はどこまでか」という構造的な追跡です。
呼び出し経路が存在するかどうかはエッジの有無で決まり、グラフが返す答えは決定論的で、同じ問いには同じ答えが返ります。
言い換えると、RAGはコードをテキストの集合として扱い、グラフはコードを関係の網として扱います。
コードの改修という文脈では「意味が近い場所を探す」と「構造的な経路を辿る」の両方が必要になることが多いので、用途に応じて使い分けるか組み合わせるのが現実的な選択肢です。
MCP経由でエージェントにグラフを渡す──Claude Code / Cursor での実際
生成されたgraph.jsonをエージェントに渡す方法は、大きく2つあります。
1つ目は スラッシュコマンド です。
Claude CodeやCursor、Gemini CLIなど20以上のAIコーディングアシスタントで /graphify コマンドが使えます。
MCPサーバーを立てなくてもすぐ使えるので、まず試してみたいときはここから始めるのが楽です。
2つ目が MCPサーバー として起動する方法で、大きなグラフをエージェントが能動的に問い合わせる用途に向いています。
まずMCP対応を追加インストールし、サーバーを起動します。
# MCPサーバー対応を追加
uv tool install "graphifyy[mcp]"
# サーバー起動（生成済みの graph.json を指定）
graphify-mcp --graph graphify-out/graph.json
Claude Codeで使う場合は、プロジェクトルートの .claude/mcp.json に次のように追記します。
{
"mcpServers": {
"graphify": {
"command": "graphify-mcp",
"args": ["--graph", "graphify-out/graph.json"]
}
}
}
Cursorの場合は .cursor/mcp.json に同様の記述を追加します。
サーバーはstdio通信で動作するためネットワークポートを開かず、コードは外部に出ません。
ローカルプロセスとして完結する点は、社内コードを扱う際に安心できる設計です。
設定が完了すると、エージェントは query_graph ツールを通じてグラフに問い合わせられるようになります。
たとえば「orders テーブルを参照しているコードをすべて教えて」とエージェントに聞くと、grepで全ファイルを舐めるのではなく、グラフのエッジを辿って該当ノードを決定論的に特定します。
「数万トークン消費してからようやく状況を把握し始める」という流れではなく、最初から構造を把握した状態でコードを読んでもらえるのが、体感として大きな違いです。
改修着手前の「グラフファースト」フロー──中小業務システムでの使いどころ
改修の依頼が来たら、コードを読む前に graphify . を走らせます。
graph.html をブラウザで開いて全体像を眺め、依存が集中しているノード（神クラスの候補）を把握します。
その後MCPサーバーを起動してエージェントに渡し、「この機能に関わるコードの影響範囲を教えて」と問い合わせてから、初めてエディタでコードを開きます。
「どこから読めばいいか分からない」状態を「まずここを読めばいい」状態に変えてから着手するという、シンプルな順番の変更です。
この流れが中小業務システムの現場と特に相性がいいのは、 グラフがドキュメントの代わりになる からです。
属人化が進んでいて担当者に聞けない、引き継ぎ資料がExcelのメモだけ、テストもないという状況でも、コードが存在するならグラフは生成できます。
ドキュメントを書く工数をかけずに、コードから直接「読める地図」を作れる点が、人手の少ない現場には刺さります。
セットアップの敷居感という意味では、
uv tool install graphifyy
の一行で始められます。
MCP連携が必要なら [mcp] オプションを付けるだけで、専用のサーバーやクラウドサービスは何も要りません。
一点補足しておくと、graphifyはクエリのログを ~/.cache/graphify-queries.log にJSON Lines形式で記録します。
コードの中身そのものは記録されませんが、ログを残したくない場合は環境変数 GRAPHIFY_QUERY_LOG_DISABLE を 1 に設定することで無効化できます。
セキュリティポリシーやライセンスについては、本番環境に持ち込む前に別途確認してください。
「改修前にまず地図を作る」という発想自体は特別新しいものではありません。
ただ、それをコマンド一発で自動生成してエージェントに渡せる形にするツールが出てきたのは、実務として使える変化だと感じています。
次にレガシーコードに触る機会があれば、着手する前に一度 graphify を走らせてみてください。
株式会社ホコサキは、山口県宇部を拠点に業務システム開発・Web制作・AI活用支援を手がけています。
graphifyのような開発ツールの実務への組み込み方や、レガシーシステムへのAI活用支援についてご相談があれば、お問い合わせページ からお気軽にどうぞ。