graphify 実践：任意のコードベースを検索可能なナレッジグラフに変える

中級 | 約20分 | graphify を使って、任意のコードリポジトリを検索可能なナレッジグラフへ変換する一連の流れを習得します。闇雲な grep は卒業し、71.5x Token 圧縮を実現する構造化コード理解へ。

プロジェクト概要

graphify は、Safi Shamsi によって開発された AI コーディングアシスタント用スキル（skill）で、GitHub は safishamsi/graphify です。位置づけはとてもシンプル：任意のフォルダ（コード、メモ、論文、画像、さらには動画まで）を、1枚の「検索可能なナレッジグラフ」に圧縮し、あなたと AI アシスタントの会話を、盲目的な全文マッチではなく「構造化された知識」に基づけます。

特徴は大きく3点です：

• マルチモーダル入力：コード（20種類の言語）、ドキュメント、画像、PDF、音声・映像をすべてサポートし、同じグラフに統一して取り込みます
• ゼロ embedding クラスタリング：Leiden のコミュニティ発見アルゴリズムで、グラフ構造（エッジのトポロジー）に基づいてクラスタリングします。ベクタDBは不要、embedding モデルを別途実行する必要もありません
• 誠実な信頼度：各リレーション（関係）エッジに EXTRACTED / INFERRED / AMBIGUOUS を付与します。どれが見つけたもの（抽出）で、どれが推論なのかが分かります

graphify は Claude Code、OpenClaw、Codex、Cursor、Trae などの主要な AI コーディングアシスタントで /graphify コマンドとして利用できます。さらに MCP Server や CLI 経由でも独立して呼び出せます。

対象読者

少なくとも 1 つの中規模プロジェクト（1,000 行以上）を書いたことがあり、日常的に Claude Code / OpenClaw / Codex、または他の AI コーディングアシスタントを使っている方。新しいコードベースに出会うと、まずは「ソースを直接読ませる」のが習慣。ですが、ファイルが増えるほど、Token 消費が大きいことや、コンテキストが断片化する問題が目立ってきます。この記事はその問題を解決するためのものです。

コア依存関係と環境

完全なプロジェクト構成

my-project/
├── graphify-out/
│   ├── graph.json          # 永続化ナレッジグラフ（セッションをまたいで検索可能）
│   ├── GRAPH_REPORT.md     # 構造化分析レポート（god nodes、意外な接続、提案質問）
│   ├── graph.html          # インタラクティブグラフ（vis.js、ブラウザで直接開く）
│   ├── cache/              # SHA256 キャッシュディレクトリ
│   └── transcripts/        # 音声・映像の文字起こしキャッシュ（video 依存を入れた場合のみ）
├── .graphifyignore         # 除外ルール（構文は .gitignore と同じ）
└── .graphify/hooks/            # graphify hook install 後に自動生成

手順

ステップ 1 — graphify のインストール

graphify は2段階です：まず Python パッケージをインストールし、次に AI コーディングアシスタント側のプラットフォーム適応層を入れます。

# 第1段階：PyPI パッケージを入れる
pip install graphifyy

# 第2段階：自分のプラットフォーム向け適応層を入れる
# Claude Code の例：
graphify install

# ほかのプラットフォームなら、対応するコマンドに置き換え：
# graphify install --platform codex
# graphify install --platform opencode
# graphify install --platform claw        # OpenClaw
# graphify install --platform aider
# graphify install --platform droid       # Factory Droid
# graphify install --platform trae
# graphify install --platform cursor
# graphify install --platform gemini

# Windows で問題が起きる場合は、プラットフォームを明示：
graphify install --platform windows

インストールが完了すると、AI コーディングアシスタントが /graphify コマンドを認識します。

ステップ 2 — 初回実行：ナレッジグラフの生成

解析したい任意のコードディレクトリに移動し、次を実行します：

# 現在のディレクトリを解析
/graphify .

# 指定ディレクトリを解析
/graphify ./src

# 指定ディレクトリを解析し、より攻めた推論モードを有効化
/graphify ./src --mode deep

# HTML 可視化をスキップし、レポートと JSON のみ生成（より高速）
/graphify ./src --no-viz

graphify は3ステップで処理します：

1. AST 抽出（LLM なし） — tree-sitter でコードファイルを解析し、クラス、関数、import 関係、コールグラフ、docstring、説明用コメントを抽出
2. 意味抽出（LLM 呼び出し） — ドキュメント、論文、画像などの内容を Claude に渡し、概念、関係、設計意図を抽出
3. グラフ構築とクラスタリング — すべての抽出結果を統合し、Leiden のコミュニティ発見アルゴリズム（embeddings 不要）でクラスタリング

実行後、graphify-out/ ディレクトリに3つの成果物が生成されます：

ls graphify-out/
# graph.json  GRAPH_REPORT.md  graph.html  cache/

ステップ 3 — 3つの成果物の使い方

graphify-out/graph.json — 永続化されたグラフ本体

これがシステムの核です。形式は標準の NetworkX JSON エクスポートです：

{
  "nodes": [
    {
      "id": "DigestAuth",
      "label": "DigestAuth",
      "source_file": "src/auth.py",
      "source_location": "L42",
      "community": "auth"
    }
  ],
  "edges": [
    {
      "source": "DigestAuth",
      "target": "Response",
      "relation": "imports",
      "confidence": "EXTRACTED",
      "confidence_score": 1.0
    },
    {
      "source": "Attention",
      "target": "Adam",
      "relation": "semantically_similar_to",
      "confidence": "INFERRED",
      "confidence_score": 0.87
    }
  ]
}

各エッジには confidence タグがあります：

• EXTRACTED：ソースに直接存在する関係（信頼度 1.0）
• INFERRED：妥当な推論で、confidence_score（0.0〜1.0）付き
• AMBIGUOUS：不確かな関係。レポートで明示され、人の確認用になります

graphify-out/GRAPH_REPORT.md — 構造化分析レポート

これは AI アシスタント向けの要約で、以下を含みます：

• God Nodes：最も次数が高い中核概念（他のすべてのノードはこれを経由します）
• Surprising Connections：ファイル横断／タイプ横断の思いがけない接続（「なぜ」が説明付き）
• Suggested Questions：グラフが独自に答えられる 4〜5 個の質問
• Design Rationale：docstring とコメント（# NOTE:、# WHY:、# HACK:）から抽出した設計意図

graphify-out/graph.html — インタラクティブグラフ

ブラウザで直接開くだけで、ノードのクリック、検索、コミュニティ単位のフィルタに対応します。コード構造の「人間的な探索」に向いています。

ステップ 4 — グラフのクエリ：3つの主要コマンド

グラフがあるだけでは足りません。検索できなければ意味がない。graphify には次の3つのクエリコマンドが内蔵されています：

query — 意味クエリ

# 最もよく使う：質問に関連するノードとパスをグラフから探す
graphify query "what connects Attention to the optimizer?"

# Token 予算を制限
graphify query "show the auth flow" --budget 1500

# DFS で具体的なパスを追跡（ランダムサンプルではない）
graphify query "what connects DigestAuth to Response?" --dfs

# デフォルト以外のグラフパスを指定
graphify query "..." --graph path/to/another-graph.json

出力には、ノードラベル、エッジ種別、信頼度、ソースファイル、ソース位置が含まれます。この出力をそのまま AI アシスタントに貼り付けて質問に答えさせられます：

Use this graph query output to answer the question. Prefer the graph
structure over guessing, and cite the source files when possible.

path — 2つのノード間のパスを探す

# ノード A からノード B までの完全なパスを追跡
graphify path "DigestAuth" "Response"

explain — 1つのノードのコンテキストを説明

# ノードの近傍、コミュニティ、関連エッジを表示
graphify explain "SwinTransformer"

ステップ 5 — Always-On Hook を統合（推奨設定）

毎回手で /graphify を打つのは少し面倒です。graphify は、グラフ知識を AI アシスタントの会話コンテキストへ自動注入し、あなたが質問するたびに「生ファイルの盲検索」より先にグラフを優先して見させることができます。

Claude Code

graphify claude install

これにより2点が行われます：CLAUDE.md にルールを書き込み（Claude が GRAPH_REPORT.md を読むようにする）、さらに settings.json に PreToolUse hook をインストールして、Glob と Grep の呼び出しのたびにグラフプロンプトを注入します：

graphify: Knowledge graph exists. Read GRAPH_REPORT.md for god nodes
and community structure before searching raw files.

OpenClaw / Aider / Trae など

これらのプラットフォームは tool hook に対応していないため、AGENTS.md を使います：

graphify claw install   # OpenClaw
graphify aider install  # Aider
graphify trae install   # Trae

Cursor

graphify cursor install

.cursor/rules/graphify.mdc に書き込み、alwaysApply: true を設定します。Cursor は各会話で自動的に読み込みます。

アンインストールは対応する uninstall コマンドで行います：

graphify claude uninstall
graphify cursor uninstall
# ...

ステップ 6 — 増分更新：毎回フル再構築しない

コードベースは毎日変わります。フル再構築は遅すぎます。graphify には2種類の増分メカニズムがあります：

--update：SHA256 キャッシュに基づく増分抽出

# 変更されたファイルだけを処理し、既存グラフに統合
/graphify ./src --update

cache ディレクトリには、ファイル内容のハッシュごとに前回処理結果が記録されています。graphify はファイルのハッシュを比較し、変化のあったファイルだけを改めて AST と LLM 抽出の手順へ回します。

--watch：ファイル変更を自動監視

# バックグラウンドで実行。コードファイル保存後、すぐに AST を再構築
/graphify ./src --watch

# ドキュメント／画像が変わったら、手動で --update を実行するよう通知

--watch で再構築されるのは AST のみで、速度が非常に速く、LLM 呼び出しは不要です。ドキュメントや画像が変更された場合は、LLM を使った再抽出が必要なため、watch は --update を手動で走らせるよう通知します。

ステップ 7 — git Hooks：コミットのたびに自動でグラフを再構築

手動で走らせたくない、バックグラウンド常駐もしたくない？なら、グラフ再構築を git に任せましょう：

graphify hook install

.git/hooks/ に post-commit と post-checkout の2つのフックを書き込みます。コミットやブランチ切り替えのたびに、git が自動でグラフを再構築します。再構築に失敗した場合（AST 解析エラー、LLM タイムアウト等）、フックは非ゼロの終了コードで git 操作を中断し、サイレント失敗を防ぎます。

状態確認とアンインストール：

graphify hook status
graphify hook uninstall

ステップ 8 — 高度な使い方

MCP Server：AI がネイティブにグラフへアクセス

AI アシスタントが MCP プロトコルに対応しているなら、グラフを MCP ツールとして公開できます：

python -m graphify.serve graphify-out/graph.json

出力されるのは MCP stdio の設定です。これを AI アシスタントの MCP 設定へ貼り付ければ完了です。公開されるツールは以下：

• query_graph：意味クエリでサブグラフを取得
• get_node：ノード詳細を取得
• get_neighbors：近傍ノードを取得
• shortest_path：2つのノード間の最短パスを探索

Neo4j へのエクスポート

より専門的なグラフ分析のために Neo4j に取り込みたいですか？

# Cypher スクリプトを生成（手動インポート）
/graphify ./src --neo4j

# もしくは、稼働中の Neo4j インスタンスへ直接送信
/graphify ./src --neo4j-push bolt://localhost:7687

Agent が読める Wiki を生成

# Markdown ウィキとしてエクスポート。AI Agent はファイルを読んで知識ベースをナビゲート可能
/graphify ./src --wiki

graphify-out/wiki/index.md（入口）に加え、各コミュニティと god node に対応する Markdown 記事が生成されます。

サポートされるファイル種類一覧

別の LLM 提供元を指定

graphify はデフォルトで、あなたのプラットフォーム内蔵モデルを使います（Claude Code は Anthropic、Codex は OpenAI）。別のモデルを強制したい場合は、環境変数で指定できます（対応する skill.md ファイルを参照）。

よくある質問とトラブルシューティング

1. インストール後に graphify コマンドが見つからない

多くの場合、Python 環境または PATH の問題です：

# パッケージのインストール先を確認
pip show graphifyy

# python -m で呼び出す（PATH に依存しない）
python -m graphify --help

# あるいは pipx で隔離インストール（推奨）
pip install pipx && pipx install graphifyy

2. グラフのノード数が非常に少ない／ほぼ空

まず .graphifyignore が対象ファイルを誤って除外していないか確認します：

# graphify が実際にどのファイルをスキャンしたか確認
/graphify ./src --no-viz  # --no-viz を付けると AST のみ実行し、LLM を呼ばないため高速

# .graphifyignore の構文（.gitignore と完全に同じ）
cat .graphifyignore

また、ファイル種類がサポート一覧にない可能性もあります。あなたのコードファイル拡張子が、上の「サポートされるファイル種類」表に載っているか確認してください。

3. LLM 抽出ステージでタイムアウト／API エラー

ネットワーク問題、または API Key 設定問題が考えられます：

# API Key が存在することを確認（Claude Code ユーザーは通常自動設定されます）
# 他のプラットフォームのユーザーは、対応するプラットフォームの API Key 環境変数を確認してください

# --budget で Token を制限し、1回のリクエストを大きくしすぎない
/graphify ./src --budget 2000

# タイムアウトしたら強制的にスキップして、ほかのファイルの処理を続行（全体の実行を止めない）

4. cache により増分更新後のグラフが不整合

SHA256 cache が壊れている、またはファイルが外部で改変された：

# cache を削除し、強制的にフル再構築
rm -rf graphify-out/cache
/graphify ./src

# もしくは特定ファイル分の cache だけ削除
rm graphify-out/cache/<対応するハッシュ>.json
/graphify ./src --update

5. Claude Code の PreToolUse hook が有効にならない

多くは settings.json のパスやフォーマットの問題です：

# hooks が正しく書き込まれているか確認
cat ~/.claude/settings.json | grep graphify

# IDE によってフォーマットが変更されている場合は、graphify hook 部分を手動で追記
# PreToolUse hook の形式は、graphify skill.md の該当部分を参照

6. --watch で watchdog が不足していると出る

watchdog は任意の依存です：

pip install graphifyy[watch]

追加読書 / 進化の方向性

1. カスタム Extractor：新しい言語の追加

あなたのコードベースで、graphify がまだサポートしていない言語（Racket、Nim など）を使っている場合は、extract.py に新しい extract_<lang> 関数を追加します。tree-sitter で AST を解析し、手順の参照として ARCHITECTURE.md の「Adding a new language extractor」部分に従ってください。流れはシンプルです：関数を書く → 接尾辞を登録する → 依存関係を追加する → テストを書く。

2. GraphRAG Pipeline：グラフ検索を RAG に接続

graphify のコア価値は：毎回、元のファイルを読み直す必要がなく、Token 消費を O(n×ファイルサイズ) から「サブグラフサイズ」へ下げられることです。RAG Pipeline と組み合わせる場合の推奨接続方法：

import json

# 1. まず GRAPH_REPORT.md で高レベルな意図を判断
# 2. 次に graphify query で関連サブグラフを取得
# 3. サブグラフをコンテキストとして LLM に渡す

with open("graphify-out/graph.json") as f:
    graph = json.load(f)

# graph["nodes"] と graph["edges"] がコンテキストになります

3. Penpax：graphify 作者のエッジ側デジタルツイン構想

graphify の長期ロードマップは Penpax —— エッジ側のデジタルツインプロジェクトです。会議記録、ブラウザ履歴、ファイル、メール、コードをすべて「継続的に更新されるナレッジグラフ」へつなげ、クラウドに上げず、あなたのデータでモデルを学習もしません。

4. マルチモーダル拡張：動画講座をグラフ化

技術講演、Conference の動画、ポッドキャスト音声があるなら、--video の依存を使ってそれらもナレッジグラフに取り込めます：

pip install 'graphifyy[video]'
/graphify ./corpus --whisper-model medium

Whisper はローカルで動作し、音声はあなたのマシンから出ません。文字起こし結果は graphify-out/transcripts/ にキャッシュされ、再実行ではキャッシュをそのまま読み込みます。

5. グラフ協調：チームで知識構造を共有

graphify の成果物（graph.json、GRAPH_REPORT.md）は純テキストなので、git に commit できます。チームメンバーが pull した後、graphify hook install が同じグラフを自動で再利用します。つまり、アーキテクチャ知識をバージョン管理でき、コードレビューではグラフノードを参照でき、PR の説明にも god nodes をそのまま引用できます——チームの知識理解が「誰に聞くか」に依存しなくなるのです。