Source: https://aiprimetech.io/ja/blog/graphify-claude-code-knowledge-graph/ 2026年7月20日 · 6分 · ツール # Claude Code向けGraphify：リポジトリをクエリ可能なグラフに変換 A 著者 [AI Prime Tech](https://aiprimetech.io/ja/) · AI支援による執筆 ## Graphify Claude Code：リポジトリをクエリ可能なグラフに変換する 800,000行のコードを持つリポジトリでは、一見単純な質問への答えが、Terraformモジュール、データベースマイグレーション、生成されたクライアント、OpenAPIドキュメント、デプロイメントマニフェスト、そして数年前に書かれたランブックという、複数の異なる場所に分散していることがあります。 Claude Codeはこれらのファイルを検索して読み取れますが、リポジトリ全体に及ぶ作業は、エージェントがファイル間の関係をどれだけ速く見つけられるかによって制約されることがよくあります。次の項目をテキスト検索すると、 customer_id 出現箇所が見つかります。ただし、次のような関係が自動的に説明されるわけではありません。 - customer_id データベースマイグレーションで宣言されていること、 - APIスキーマで公開されていること、 - ORMモデルでマッピングされていること、 - イベントペイロードにコピーされていること、 - バックグラウンドワーカーによって利用されていること、 - そして、本番環境のロールバック手順で言及されていること。 Graphifyは、リポジトリ内の資料をナレッジグラフに変換することで、この問題に取り組みます。エンティティはノードに、参照や依存関係はエッジになり、Claude Codeは追加のコンテキストとしてその構造をクエリできます。 ここで重要な留意点は、グラフが魔法のように機能する別の信頼できる情報源ではないということです。グラフは、リポジトリを解釈してインデックス化したものです。その価値は、パーサーの対応範囲、更新の徹底、権限、そして得られた関係が実際のエンジニアリング上の問いにどれだけ適切に答えられるかに左右されます。 ## GraphifyがClaude Codeに追加する機能 Claude Codeには、プロジェクトを理解するための便利な手段がすでにいくつかあります。 - ファイルの直接読み取り - rg およびその他のシェル検索 - Gitの履歴と差分 - 次のファイル内のプロジェクト指示 CLAUDE.md - 繰り返し実行できるワークフローのためのスキル - 外部ツールやデータにアクセスするためのMCPサーバー Graphifyは、関係を中心に情報を取得するという、異なるアクセスパターンを追加します。 従来の検索では、次のように問いかけます。 このシンボルはどこに出現するか？ グラフクエリでは、次のように問いかけます。 このスキーマに依存するサービスは何か、それらのサービスをデプロイするインフラストラクチャは何か、そして運用上の影響を説明しているドキュメントはどれか？ この違いは、タスクが担当範囲やファイル形式の境界をまたぐ場合に重要です。 一般的なグラフには、次のようなノードが含まれます。 | ノードの種類 | 例 | コード | 関数、クラス、モジュール、パッケージ、インポート | データ | テーブル、列、インデックス、マイグレーション、ORMモデル | インターフェース | RESTルート、OpenAPIオブジェクト、GraphQL型、イベントスキーマ | インフラストラクチャ | サービス、コンテナ、キュー、データベース、Terraformリソース | ドキュメント | ADR、ランブック、READMEファイル、担当に関するメモ | 運用 | CIジョブ、デプロイ環境、アラート、ダッシュボード エッジは、次のような関係を表せます。 - imports - calls - implements - extends - reads_from - writes_to - publishes - consumes - deploys - configured_by - documented_by - owned_by - depends_on ノードとエッジに使われる具体的な語彙は、Graphifyの現在のインデクサーと設定によって異なります。グラフスキーマは、当然存在すると想定するものではなく、確認可能な製品の仕様として扱ってください。次のような関係を前提にプロンプトを組み立てる前に、 publishesインストール済みのバージョンが実際にその関係を出力することを確認してください。 ## Claude Code用のGraphifyをインストールする Graphifyは活発に開発されているプロジェクトのため、インストール方法や起動コマンドの名前が変わる可能性があります。まずリポジトリを確認し、採用するバージョンのドキュメントに記載されたインストールコマンドを使用してください。 ``` git clone https://github.com/Graphify-Labs/graphify.git cd graphify ``` 公開済みパッケージを利用する場合は、古いブログ記事からコピーするよりも、プロジェクトのドキュメントに記載されたパッケージマネージャーのコマンドを使うことをお勧めします。インストール後、大規模なモノレポをインデックス化する前に、以下の事項を確認してください。 ``` graphify --help graphify version graphify config --help ``` 上記のコマンドは、実施すべき確認の例です。インストールしたリリースが提供する実行ファイルとサブコマンドを使用してください。 安全に初回実行するには、小規模なテスト用リポジトリを対象にしてください。 ``` mkdir -p /tmp/graphify-fixture cd /tmp/graphify-fixture git init printf 'def charge(order):\n return order.total\n' > billing.py printf 'from billing import charge\n' > worker.py graphify index . ``` 初回のインデックス作成では通常、検出、解析、関係の抽出、グラフの永続化を組み合わせて実行します。実際のリポジトリでは、CIに追加する前に、生成された設定と保存先を確認してください。インデックスについて、次の点を把握する必要があります。 - ローカルにあるか、ホスティングされているか - 差分更新か、全体の再構築か - データベース、ファイル、組み込みストアのどこに永続化されるか - 別のインデクサーと安全に同時実行できるか - シークレット、ビルド成果物、ベンダー由来のディレクトリツリーを除外できるか Claude Codeと連携するには、プロジェクトがサポートする連携の仕組みを通じてGraphifyを公開する必要があります。一般的にはMCPが使われます。ローカルの .mcp.json は、次のようになります。 ``` { "mcpServers": { "graphify": { "command": "graphify", "args": ["mcp", "--project", "."], "env": { "GRAPHIFY_INDEX": ".graphify/index" } } } } ``` このサブコマンドがどの環境でも使えるとは考えないでください。次のコマンドでMCPのエントリーポイントを確認してください。 ``` graphify mcp --help ``` 続いて、Claude Codeからサーバーを検証してください。 ``` /mcp ``` Graphifyサーバーと利用可能なツールが表示されるはずです。ツール名とクエリ構文はバージョンによって異なります。有用なのは、実際の動作を確認することです。Claude Codeに、グラフツールを一覧表示し、対象を絞ったクエリを実行し、リポジトリのどのリビジョンがインデックス化されたかを報告するよう依頼してください。 よくある落とし穴は、誤ったディレクトリからClaude Codeを起動することです。次のファイル内の相対プロジェクトパス、 .mcp.json除外設定ファイル、Graphifyの設定は、必ずしも想定していたディレクトリではなく、サーバープロセスの作業ディレクトリに基づいて解決されます。 ## 実務で重要な関係 グラフが最も役立つのは、テキストから再構成するのが面倒な関係を明らかにする場合です。 ### コードからデータへのリネージ マイグレーションで次の名前を変更するとします。 accounts.status で、変更後の値は accounts.lifecycle_stateテキスト検索でも参照箇所を特定できますが、グラフなら影響範囲を整理できます。 ``` table accounts -> column lifecycle_state -> migration 2025_04_rename_status -> model Account -> repository AccountRepository -> API response AccountSummary -> dashboard query active_accounts ``` これにより、Claude Codeはマイグレーションのレビューをより適切な出発点から始められます。グラフが依存している可能性の高い対象を特定した後で、実際のファイルを調査できます。 ### サービスとインフラストラクチャのトポロジー インフラストラクチャの関係は、アプリケーションコードとデプロイ用コードが共存するモノレポで特に役立ちます。 ``` service payments-api -> container image payments-api -> Kubernetes deployment payments -> reads secret PAYMENTS_DATABASE_URL -> writes queue payment-events -> consumed by reconciliation-worker ``` これは、次のような問いに答えるのに役立ちます。 - ポートが変わる場合、どのデプロイメントを変更する必要があるか？ - このキューを利用しているのは何か？ - このデータベースを共有しているサービスはどれか？ - どの設定が環境固有か？ - この依存関係を作成するTerraformリソースはどれか？ Graphifyは、静的ファイルから実行時の動作を完全に推測できるわけではありません。動的なサービス検出、リフレクション、生成された設定、環境変数を介した間接参照によって、把握できない部分が残ることがあります。トポロジーの結果を影響範囲のマップとして使い、そのうえで重要なエッジをデプロイ設定と実行時設定で検証してください。 ### ドキュメントと実装の関係 ドキュメントとコードの関係は構文ではなく意味に基づくため、ドキュメントがコード検索から切り離されていることはよくあります。ランブックでは「決済プロセッサー」と呼んでいても、リポジトリ内では次の名前が使われている場合があります。 reconciliation-worker. Graphifyがドキュメント内の参照をコードやインフラストラクチャのエンティティに関連付けられれば、Claude Codeは手動で調べる手間を減らしながら運用上の問いに答えられます。 ``` "Where is the rollback procedure for the component that consumes payment-events?" ``` ドキュメント内の名前が正確にマッピングされている場合に限り、その答えは信頼できます。古い用語は、もっともらしくても誤ったエッジを生み出します。これは、検索で明らかに見つからない場合よりも危険です。 ## Graphify、スキル、MCPは異なるレイヤー Graphifyは、Claude Codeの既存の拡張ポイントを置き換えるのではなく、補完するものとして使うべきです。 | 機能 | 得意な用途 | 提供するもの | 主な制約 | Claude Codeの検索ツールとファイルツール | ローカルでの正確な調査 | 現在のファイル内容と差分 | 異なる形式をまたぐ関係の把握が苦手 | Claude Codeのスキル | 繰り返し実行できる動作 | 指示、チェックリスト、レビュー手法 | リポジトリに関する事実を作り出すものではない | MCP | ツールとデータの連携 | 外部システムへの制御されたインターフェース | ツールの品質と権限が異なる | Graphify | リポジトリのトポロジーとリネージ | 成果物をまたぐ構造化された関係 | インデックスが不完全、または古くなっている可能性がある 有用なアーキテクチャは次のとおりです。 - Graphifyが候補となるエンティティと依存関係を検出します。 - Claude Codeがその結果を使ってファイルを選択します。 - 標準のファイルツールが現在の実装を検証します。 - スキルがチームのレビュー手順や変更手順を適用します。 - テスト、リンター、デプロイチェックが最終的な裏付けを提供します。 たとえば、マイグレーションレビュー用のスキルは、次の場所に配置できます。 .claude/skills/review-migration/SKILL.md: ``` # Review Database Migration When reviewing a migration: 1. Identify renamed, removed, or changed columns. 2. Query Graphify for code, schema, event, and infrastructure dependents. 3. Read each high-confidence dependent from the working tree. 4. Check backward compatibility for deployed application versions. 5. Run the repository migration and contract tests. 6. Report uncertain graph relationships separately from verified findings. ``` スキルはワークフローを定義します。Graphifyは関係性のコンテキストを提供します。MCPは通信手段であり、ツールとの境界です。 この分離は重要です。グラフに関する知識をすべてスキルに組み込むと、時間とともに役に立たなくなる静的な指示になってしまいます。ワークフローのポリシーをすべてGraphifyに組み込むと、インデクサーに、信頼性をもって下せない判断まで担わせることになります。 ## インデックスのコストと鮮度の管理 インデックス作成には、計算資源、ディスク容量、レイテンシ、運用の複雑さというコストが伴います。コストは初回スキャンだけではありません。大規模なリポジトリでは、ブランチの変更、生成ファイルの再ビルド、依存関係グラフの無効化に伴う更新作業も発生します。 まず除外設定から始めます。 ``` # .graphifyignore .git/ node_modules/ vendor/ dist/ build/ coverage/ tmp/ *.min.js *.map .env *.pem ``` 構文は次のものと異なる場合があります。 .gitignoreそのため、Graphifyの無視ファイルの動作を確認してください。認証情報や機密性の高いエクスポートデータは、Gitですでに無視されていても明示的に除外します。ファイルをインデックス化するツールは、クエリ経由でその内容を公開する可能性があります。 段階的なインデックス作成ポリシーを採用します。 - アプリケーションのソース、スキーマ、インフラ、継続的に保守されているドキュメントをインデックス化します。 - 生成された出力は、それが正本となる成果物でない限り除外します。 - CIまたは定期実行ジョブで完全なインデックスを構築します。 - 対応している場合は、ブランチのインデックスを増分更新します。 - グラフのメタデータとともに、ソースのコミットを記録します。 - パーサーや設定を変更した後は再構築します。 ソースのリビジョンは、エージェントから確認できるようにする必要があります。次のようなレスポンス形式は、補足情報のない一覧よりもはるかに安全です。 ``` { "query": "dependents of table accounts", "indexed_revision": "9f31a7c", "generated_at": "2025-05-14T10:22:11Z", "results": [ { "entity": "AccountRepository", "relationship": "reads_from", "target": "accounts", "confidence": "high", "path": "src/accounts/repository.py" } ] } ``` 最後にインデックスを作成した後でClaude Codeが作業ツリーを変更している場合、グラフの結果は過去のコンテキストです。現在のファイルが優先されます。実際には、私はエージェントに、次の情報を推論に含めるよう指示しています。 indexed_revision また、グラフから導いたすべての主張を作業ツリーと照合して再確認するよう指示しています。 ## 精度、プライバシー、本番環境での境界 グラフは、不完全な情報を確かなものに見せてしまうことがあります。次のような問題を想定して備える必要があります。 - 動的インポートやリフレクションが検出されない。 - シェルスクリプトの関係性が変数展開に隠れてしまう。 - 生成されたクライアントによって元のスキーマが分かりにくくなる。 - ドキュメントのリンクで、パーサーが認識しないエイリアスが使われている。 - クリーンアップや再構築が実行されるまで、削除済みファイルが残る。 - エージェントが別のブランチで作業している間に、あるブランチのインデックスが照会される。 - 環境固有の値を考慮せずにインフラモジュールが解釈される。 本番環境のワークフローでは、可能な限り信頼度と来歴を提示してください。ファイルパス、リビジョン、抽出方法のない関係性は、監査が困難です。 プライバシーにも同じだけ注意を払う必要があります。リポジトリのグラフから、次の情報が明らかになる可能性があります。 - 内部サービス名 - 顧客や決済のデータモデル - ネットワークトポロジー - ファイル名や設定内の参照から分かる秘密情報 - 脆弱性に関わる機微な依存関係 - 独自の非公開ドキュメント 機密性の高いインデックスは、ローカル、またはリポジトリと同じ信頼境界の内側に保管してください。最小権限のMCP設定を使用し、秘密情報を除外し、組織がそのデータフローを承認していない限り、ホスト型サービスにグラフの内容を送信しないでください。Claude Codeがグラフを照会できるようになっても、リポジトリのアクセス制御要件は変わりません。 人気と信頼性も同じではありません。大きな注目を集めているプロジェクトでも、パーサーの対応範囲が未成熟だったり、グラフスキーマが不安定だったり、アップグレード時の保証が限定的だったり、モノレポ規模で頻繁に変更が発生した際の動作が不十分だったりすることがあります。自分たちのリポジトリから作成したテスト用データ群で評価してください。 - 既知のインポートやサービスの依存関係を識別できるか。 - 削除された関係性を除去できるか。 - 増分インデックス作成の結果が、クリーンな再構築の結果に収束するか。 - ユーザーが古い結果や信頼度の低い結果を見分けられるか。 - インデックスが利用できないとき、MCPサーバーは明確なエラーを示すか。 - クエリは、対話的なエージェント作業に十分な速さで実行されるか。 - CIでインデックスを再現できるか。 エージェントのあらゆる操作で、Graphifyを必須の前提条件にしないでください。通常のファイル検索にフォールバックする縮退モードが不可欠です。 ## 実践的な導入パターン APIの変更、データベースのマイグレーション、インフラのリファクタリングなど、関係性の発見にコストがかかり、ミスが表面化しやすいワークフローを選んで始めてください。 グラフのサイズではなく、有用な成果を測定します。 - 影響を受けるコンポーネントを特定するまでの時間 - レビューで見落とした依存元の数 - 古い関係性や誤った関係性の割合 - 通常のコミット後のインデックス作成時間 - クエリの失敗とフォールバックの頻度 - モデルに追加で開示されるデータ 推論の深さが重要な、リポジトリ全体にわたる調査にはSonnet 4.6を、軽量な分類や繰り返しの検索タスクにはHaiku 4.5を使用します。また、プロジェクトの1Mコンテキストのワークフローで、大量の根拠を保持することが実際に役立つ場合には、より大きなコンテキストに対応するFable 5を使用します。モデルの選択では、質の悪いグラフを修復できません。正確で最新の関係性を与えられた小さなモデルのほうが、フィルタリングされていないインデックスのダンプを受け取る大きなモデルよりも役立つ場合があります。 実践的なプロンプトのパターンでは、来歴を明示します。 ``` Use Graphify to identify likely dependents of the `accounts.lifecycle_state` column. For every result, include its path, indexed revision, relationship, and confidence. Then read the current files and discard relationships that do not exist in the working tree. Do not treat graph results as proof. ``` その最後の文は形式的なものではありません。古くなったコンテキスト層が、疑われることのない権威になるのを防ぎます。 ## 実践上のポイント - Graphifyの中核的な価値は、コード、スキーマ、インフラ、ドキュメントを横断して関係性を検索できることです。 - バージョンが明示されたツールをインストールし、実際のCLIコマンドとMCPコマンドを確認して、モノレポをインデックス化する前にテスト用データで試してください。 - Graphifyにはリポジトリのコンテキストを担わせ、再現可能なエンジニアリング手順にはClaude Codeのスキルを使用してください。 - グラフのレスポンスに、インデックスのリビジョン、来歴、信頼度を含めてください。 - 秘密情報、生成された不要なデータ、不要なベンダー提供コンテンツを除外してください。 - グラフの結果は、現在の作業ツリーで検証すべき手がかりとして扱ってください。 - 本番環境に導入する前に、増分インデックス作成、削除処理、ブランチの分離、縮退時の動作をテストしてください。 - 人気は評価を始める理由にはなりますが、依存する根拠になるのは、そのリポジトリにおける精度と運用時の動作だけです。 [コーディング](/ja/blog/tag/coding/)[Claude](/ja/blog/tag/claude/) A [AI Prime Tech](https://aiprimetech.io/ja/) このブログはAI Prime Techが公開しています。記事の草稿はAIの支援を受けて作成されています。モデルID、料金、制限など、バージョンによって異なる詳細については、利用の判断に用いる前に公式ドキュメントで確認してください。 Claude APIをより低価格で利用 Claude Opus 5.5、Sonnet 5、Haiku 4.5、Fable 5.1に加え、GPT-6のモデルを、単一のAPIキーで利用できます。従量課金制で、サブスクリプションは不要です。 [APIキーを取得 →](/register) AI Prime Techは独立したサードパーティのAPIゲートウェイです。Claude™およびAnthropic®はAnthropic, PBCの商標です。提携や推奨を示唆するものではありません。