はじめに
Claude Code、Cursor、Codex CLI などのAIコーディングエージェントを使っていると、既存コードの調査で大量のファイル探索が発生することがあります。
たとえば、以下のような依頼です。
このViewModelの影響範囲を調べて
このAPIServiceはどこから呼ばれている？
このメソッドを修正した場合、関連するテストはどれ？
小規模なプロジェクトであれば、大きな問題にはなりません。
しかし、電子書籍アプリ、ECアプリ、金融アプリ、SaaS、業務アプリのように、長期運用されている大規模コードベースでは、調査だけで時間もトークンも消費しやすくなります。
そこで有効そうなのが、今回紹介する CodeGraph です。
CodeGraphとは
CodeGraphは、コードベースを事前に解析し、AIエージェントが参照できる「コードの知識グラフ」を作るツールです。
簡単に言うと、AIエージェントに対して、
毎回コード全体を探し回るのではなく、事前に作ったコード構造マップを見てから調査してもらう
ためのツールです。
主な特徴は以下です。
- Claude Code / Cursor / Codex CLI / OpenCode 向け
- MCPサーバーとして利用できる
- コードのシンボル、呼び出し関係、影響範囲を調査できる
- ローカルで動作する
- SQLiteにコードグラフを保存する
- Swiftを含む複数言語に対応している
- MITライセンスのOSSとして公開されている
CodeGraphが嬉しい理由
AIエージェントは便利ですが、既存コードの理解では探索コストが大きくなりがちです。
たとえば、あるクラスの影響範囲を調べる場合、通常は次のような流れになります。
- ファイル名やクラス名で検索する
- 関連ファイルを読む
- 呼び出し元を検索する
- 呼び出し先を検索する
- 関連テストを探す
- さらに別の関連ファイルを読む
この流れでは、AIエージェントが grep、glob、Read などを使って大量のファイルを探索する可能性があります。
CodeGraphを使うと、事前に作成されたコードグラフをもとに、以下のような情報を取得しやすくなります。
- 対象シンボルの定義
- 呼び出し元
- 呼び出し先
- 影響範囲
- 関連ファイル
- 関連テスト候補
つまり、CodeGraphは 読むべきコードに早くたどり着くためのツール です。
その結果として、AIエージェントが不要なファイルを大量に読む場面を減らせるため、トークン数の節約にもつながります。
ただし、CodeGraphは「コードを一切読まなくてよくするツール」ではありません。
正しくは、読むべきコードを絞り込み、AIエージェントの探索コストとトークン消費を下げるためのツールです。
無料で使えるのか
CodeGraph本体は、MITライセンスのOSSとして公開されています。
そのため、CodeGraph自体は無料で利用できます。
なお、Claude CodeやCursorなど、連携先のAIエージェント自体の利用条件は各サービスに依存します。
インストール手順
公式READMEでは、以下のコマンドでインストールできると説明されています。
npx @colbymchenry/codegraph
インストーラーを実行すると、Claude Code、Cursor、Codex CLI、OpenCode などの利用環境を検出し、必要な設定を行ってくれます。
手動でグローバルインストールする場合は、以下の方法もあります。
npm install -g @colbymchenry/codegraph
プロジェクトでCodeGraphを初期化するには、対象プロジェクトのディレクトリで以下を実行します。
cd your-project
codegraph init -i
これにより、プロジェクト内に .codegraph/ ディレクトリが作成され、コードグラフのインデックスが作成されます。
動作確認には、以下のようなコマンドが使えます。
codegraph status
シンボル検索を試す場合は、以下のように実行できます。
codegraph query "UserService"
Claude Codeでは自然言語で指示すればよい
CodeGraphを導入した後は、基本的に開発者が毎回細かいコマンドを実行する必要はありません。
Claude CodeなどのAIエージェントに対して、自然言語で以下のように指示できます。
CodeGraphを使って、このクラスの呼び出し元と影響範囲を調べてください。
このViewModelを変更した場合に影響を受ける画面・API・テストをCodeGraphで確認してください。
grepやReadを多用する前に、まずCodeGraphで対象シンボル、呼び出し元、呼び出し先、影響範囲を確認してください。
つまり、CodeGraphは「開発者が毎回CLIを叩いて使うツール」というより、AIエージェントに自然言語で使わせる補助ツールとして考えると分かりやすいです。
ただし、最初のうちは 「CodeGraphを使って」 と明示するのがおすすめです。
何も指定しない場合、AIエージェントが従来どおり grep、glob、Read を多用する可能性があるためです。
Claude Code向けのおすすめ指示
プロジェクトの指示や作業開始時のプロンプトに、以下のようなルールを入れておくとよいです。
このプロジェクトではCodeGraphを利用しています。
コード調査では、grep / glob / Read を多用する前に、まずCodeGraphで以下を確認してください。
- 対象シンボルの定義
- 呼び出し元
- 呼び出し先
- 影響範囲
- 関連テスト
その後、必要最小限のファイルだけを読んでください。
これにより、AIエージェントが最初から大量のファイル探索をするのではなく、CodeGraphを使った構造的な調査を優先しやすくなります。
Claude Codeで使える主な調査観点
CodeGraphを使うと、以下のような調査を自然言語で依頼しやすくなります。
このクラスの呼び出し元を調べてください。
このメソッドが内部で呼び出している処理を確認してください。
このAPIServiceを変更した場合の影響範囲を調べてください。
このManagerがまだ使われているか確認してください。
この修正に関連しそうなテストを洗い出してください。
アプリ開発では、実装そのものよりも、既存仕様や影響範囲の把握に時間がかかることがあります。
CodeGraphは、その調査部分を効率化するための選択肢になります。
.codegraph/ は .gitignore に入れたほうがいい
.codegraph/ は .gitignore に入れるのが安全です。
理由は、.codegraph/ はプロジェクトごとのローカルインデックスだからです。
中にはSQLiteのDBなど、各開発者の環境で再生成できるデータが含まれます。
CodeGraph公式リポジトリ自身の .gitignore にも、.codegraph/ が除外対象として記載されています。
プロジェクトの .gitignore には、以下を追加しておくとよいです。
# CodeGraph local index
.codegraph/
.codegraph/ をGit管理しないほうがよい理由は以下です。
| 理由 | 内容 |
|---|---|
| 再生成できる | 各開発者が codegraph init -i で作れる |
| 差分が増える | DB更新により不要な差分が出る可能性がある |
| 環境依存 | OS、パス、ブランチ状態によって内容が変わる |
| 容量が増える | 大規模コードベースではDBが大きくなる可能性がある |
| コンフリクトしやすい | 複数人で同じDBを更新すると競合しやすい |
大規模・長期運用コードベースでは試す価値が高い
CodeGraphが特に有効だと感じるのは、大規模・長期運用のアプリ開発です。
たとえば、電子書籍アプリ、ECアプリ、ニュースアプリ、金融アプリ、業務アプリのようなプロダクトでは、以下のような特徴があります。
- 画面数が多い
- ViewModelやManagerが多い
- API連携が多い
- 古い実装と新しい実装が混在している
- 長年の仕様変更が積み重なっている
- テスト対象の把握が難しい
- 影響範囲調査に時間がかかる
このようなコードベースでは、AIエージェントに「この機能を調べて」と依頼しただけで、多くのファイル探索が発生しがちです。
CodeGraphを使うことで、まずコード構造をもとに当たりを付けられるため、調査の初速を上げられる可能性があります。
特に以下のような場面で有効です。
この画面の表示ロジックはどこで組み立てられている？
このAPIServiceを変更した場合、影響を受ける画面はどれ？
このManagerはまだ使われている？
このメソッドの呼び出し元を一覧化して
この修正で影響を受けるテストを洗い出して
大規模アプリ開発では、実装そのものよりも、既存仕様や影響範囲の把握に時間がかかることがあります。
CodeGraphは、その調査部分を効率化するための選択肢になります。
注意点
CodeGraphは便利ですが、万能ではありません。
まず、CodeGraphは「コードを読まなくてよくするツール」ではなく、読むべきコードを絞り込むための補助ツールです。最終的な修正判断では、実際のコード確認が必要です。
また、.codegraph/ はローカルインデックスなので、Git管理せず .gitignore に入れるのが安全です。
さらに、CodeGraph本体はローカルで動作しますが、Claude CodeやCursorなどのAIエージェントにコード断片を扱わせる場合は、会社やプロジェクトのAI利用ルールを確認しておくと安心です。
まとめ
CodeGraphは、Claude Code、Cursor、Codex CLIなどのAIコーディングエージェントに、コードベースの構造を効率よく理解させるためのMCPツールです。
ポイントは以下です。
- CodeGraph本体はMITライセンスのOSS
- ローカルでコードグラフを作成できる
- Claude Code / Cursor / Codex CLI / OpenCodeで利用できる
- Swiftを含む複数言語に対応
- 呼び出し元・呼び出し先・影響範囲調査に向いている
- 導入後は自然言語で「CodeGraphを使って」と指示できる
-
.codegraph/は.gitignoreに入れるのが安全 - 大規模・長期運用コードベースでは試す価値が高い
- 探索系タスクではトークン数の節約にもつながる
CodeGraphは、AIに「もっと賢くコードを探してもらう」ための補助ツールです。
大規模なアプリ開発では、実装そのものよりも、既存仕様の把握や影響範囲調査に時間がかかることがあります。
そのような環境では、CodeGraphを導入することで、AIエージェントによるコード調査の効率を上げられる可能性があります。
まずは個人環境で以下を試してみるのがよさそうです。
npx @colbymchenry/codegraph
cd your-project
codegraph init -i
codegraph status
そのうえで、Claude Codeに以下のように依頼します。
このプロジェクトではCodeGraphを初期化済みです。
コード調査では、grepやReadを多用する前に、まずCodeGraphで対象シンボル、呼び出し元、呼び出し先、影響範囲を確認してください。
既存コード調査や影響範囲調査に時間がかかっているアプリ開発者にとって、CodeGraphは試す価値のある選択肢です。