はじめに
Claude Code、Cursor、Codex CLI などのAIコーディングエージェントを使っていると、Web開発の既存コード調査で大量のファイル探索が発生することがあります。
たとえば、以下のような依頼です。
このReactコンポーネントの影響範囲を調べて
このhooksはどの画面から使われている？
このAPI clientを修正した場合、関連するページやテストはどれ？
このNext.jsのroute handlerはどこから呼ばれている？
小規模なWebアプリであれば、大きな問題にはなりません。
しかし、React、Next.js、TypeScript、API client、hooks、middleware、server actions、共通UIコンポーネントなどが増えてくると、調査だけで時間もトークンも消費しやすくなります。
そこで有効そうなのが、今回紹介する CodeGraph です。
CodeGraphとは
CodeGraphは、コードベースを事前に解析し、AIエージェントが参照できる「コードの知識グラフ」を作るツールです。
簡単に言うと、AIエージェントに対して、
毎回コード全体を探し回るのではなく、事前に作ったコード構造マップを見てから調査してもらう
ためのツールです。
主な特徴は以下です。
- Claude Code / Cursor / Codex CLI / OpenCode 向け
- MCPサーバーとして利用できる
- コードのシンボル、呼び出し関係、影響範囲を調査できる
- ローカルで動作する
- SQLiteにコードグラフを保存する
- TypeScript / JavaScript / Python / Go / Rust など複数言語に対応
- Webフレームワークのルーティング認識にも対応
- MITライセンスのOSSとして公開されている
Web開発では、Reactコンポーネント、custom hooks、API client、route handler、middleware、server actions、共通UIなどの関係を追う場面が多いため、CodeGraphのような構造理解ツールと相性がよいです。
Web開発でコード調査が重くなりやすい理由
Web開発では、1つの機能が複数のファイルに分散しがちです。
たとえば、ECサイトの商品詳細画面を考えると、関連ファイルは次のように広がる可能性があります。
app/products/[id]/page.tsx
components/ProductDetail.tsx
components/AddToCartButton.tsx
hooks/useCart.ts
lib/api/products.ts
lib/api/cart.ts
store/cartStore.ts
middleware.ts
__tests__/ProductDetail.test.tsx
一見すると「ボタンを少し変更するだけ」に見えても、実際には以下のような調査が必要になることがあります。
- どのページで使われているか
- どのhooksに依存しているか
- どのAPI clientを呼んでいるか
- middlewareや認証状態に影響するか
- server component / client component の境界はどうなっているか
- 関連テストはどこにあるか
- 共通コンポーネントとして他画面にも影響するか
このような調査をAIエージェントに依頼すると、grep、glob、Read などで大量のファイルを探索することがあります。
CodeGraphは、この探索コストを下げるための補助ツールとして使えます。
CodeGraphが嬉しい理由
CodeGraphを使うと、事前に作成されたコードグラフをもとに、以下のような情報を取得しやすくなります。
- 対象シンボルの定義
- 呼び出し元
- 呼び出し先
- 影響範囲
- 関連ファイル
- 関連テスト候補
- Webルーティングとhandlerの関係
つまり、CodeGraphは 読むべきコードに早くたどり着くためのツール です。
たとえば、AIエージェントに以下のように依頼できます。
CodeGraphを使って、ProductDetailコンポーネントの呼び出し元と影響範囲を調べてください。
useCart hooksが使われている画面とコンポーネントを確認してください。
getProduct API clientを変更した場合に影響を受けるページ、hooks、テストを洗い出してください。
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-web-project
codegraph init -i
これにより、プロジェクト内に .codegraph/ ディレクトリが作成され、コードグラフのインデックスが作成されます。
動作確認には、以下のようなコマンドが使えます。
codegraph status
シンボル検索を試す場合は、以下のように実行できます。
codegraph query "useCart"
codegraph query "ProductDetail"
Claude Codeでは自然言語で指示すればよい
CodeGraphを導入した後は、基本的に開発者が毎回細かいコマンドを実行する必要はありません。
Claude CodeなどのAIエージェントに対して、自然言語で以下のように指示できます。
CodeGraphを使って、このReactコンポーネントの呼び出し元と影響範囲を調べてください。
このcustom hooksを変更した場合に影響を受けるページ・コンポーネント・テストをCodeGraphで確認してください。
grepやReadを多用する前に、まずCodeGraphで対象シンボル、呼び出し元、呼び出し先、影響範囲を確認してください。
つまり、CodeGraphは「開発者が毎回CLIを叩いて使うツール」というより、AIエージェントに自然言語で使わせる補助ツールとして考えると分かりやすいです。
ただし、最初のうちは 「CodeGraphを使って」 と明示するのがおすすめです。
何も指定しない場合、AIエージェントが従来どおり grep、glob、Read を多用する可能性があるためです。
Claude Code向けのおすすめ指示
プロジェクトの指示や作業開始時のプロンプトに、以下のようなルールを入れておくとよいです。
このプロジェクトではCodeGraphを利用しています。
Web開発のコード調査では、grep / glob / Read を多用する前に、まずCodeGraphで以下を確認してください。
- 対象コンポーネントの定義
- 呼び出し元
- 呼び出し先
- 関連するhooks
- 関連するAPI client
- 関連するroute handler
- 変更時の影響範囲
- 関連テスト
その後、必要最小限のファイルだけを読んでください。
これにより、AIエージェントが最初から大量のファイル探索をするのではなく、CodeGraphを使った構造的な調査を優先しやすくなります。
React開発で使える調査プロンプト例
React開発では、コンポーネント、hooks、state管理、API clientの関係を追う場面が多いです。
以下のようなプロンプトが使えます。
CodeGraphを使って、ProductCardコンポーネントがどこで使われているか調べてください。
useAuth hooksの呼び出し元と、それに依存している画面を洗い出してください。
CartProviderを変更した場合に影響を受けるコンポーネントとテストを確認してください。
Buttonコンポーネントを変更した場合、どの画面に影響する可能性がありますか？
getUser API clientの呼び出し元と、関連するhooksを確認してください。
Reactでは共通コンポーネントやhooksが広範囲に使われるため、変更前の影響範囲調査が重要です。
CodeGraphを使うことで、最初に関係するシンボルを把握し、その後に必要なファイルだけを読む流れを作りやすくなります。
Next.js開発で使える調査プロンプト例
Next.jsでは、ページ、layout、route handler、server actions、middlewareなどが関係するため、調査対象が広がりやすいです。
以下のようなプロンプトが使えます。
CodeGraphを使って、app/products/[id]/page.tsx に関連するコンポーネント、API client、hooksを調べてください。
このserver actionを変更した場合に影響を受けるページとフォームを確認してください。
middleware.ts の処理が影響するrouteを確認してください。
app/api/orders/route.ts の呼び出し元や関連するクライアント処理を調べてください。
このlayoutを変更した場合に影響を受けるページを洗い出してください。
Next.jsでは、ファイルベースルーティングによって構造が見えやすい一方で、server component / client component、API route、server actions、middlewareなどの関係が複雑になることがあります。
CodeGraphを使うと、AIエージェントに構造的な調査をさせやすくなります。
.codegraph/ は .gitignore に入れたほうがいい
.codegraph/ は .gitignore に入れるのが安全です。
理由は、.codegraph/ はプロジェクトごとのローカルインデックスだからです。
中にはSQLiteのDBなど、各開発者の環境で再生成できるデータが含まれます。
CodeGraph公式リポジトリ自身の .gitignore にも、.codegraph/ が除外対象として記載されています。
プロジェクトの .gitignore には、以下を追加しておくとよいです。
# CodeGraph local index
.codegraph/
.codegraph/ をGit管理しないほうがよい理由は以下です。
| 理由 | 内容 |
|---|---|
| 再生成できる | 各開発者が codegraph init -i で作れる |
| 差分が増える | DB更新により不要な差分が出る可能性がある |
| 環境依存 | OS、パス、ブランチ状態によって内容が変わる |
| 容量が増える | 大規模コードベースではDBが大きくなる可能性がある |
| コンフリクトしやすい | 複数人で同じDBを更新すると競合しやすい |
大規模Webサービスでは試す価値が高い
CodeGraphが特に有効だと感じるのは、大規模・長期運用のWebサービス開発です。
たとえば、ECサイト、SaaS、管理画面、予約サービス、メディアサイト、ダッシュボードなどでは、以下のような特徴があります。
- ページ数が多い
- 共通コンポーネントが多い
- custom hooksが増えやすい
- API clientが複数ドメインに分かれている
- 認証・権限・feature flagの条件分岐が多い
- server actionsやroute handlerが増えやすい
- middlewareの影響範囲が見えにくい
- テスト対象の把握が難しい
このようなコードベースでは、AIエージェントに「この機能を調べて」と依頼しただけで、多くのファイル探索が発生しがちです。
CodeGraphを使うことで、まずコード構造をもとに当たりを付けられるため、調査の初速を上げられる可能性があります。
特に以下のような場面で有効です。
この共通コンポーネントを変更した場合、どのページに影響する？
このhooksは本当にまだ使われている？
このAPI clientを削除しても問題ない？
このmiddleware変更で影響を受けるrouteはどれ？
このserver actionに関連するフォームとテストを洗い出して
Web開発では、見た目の変更が小さくても、共通コンポーネントやhooksを経由して広範囲に影響することがあります。
CodeGraphは、その調査部分を効率化するための選択肢になります。
注意点
CodeGraphは便利ですが、万能ではありません。
まず、CodeGraphは「コードを読まなくてよくするツール」ではなく、読むべきコードを絞り込むための補助ツールです。最終的な修正判断では、実際のコード確認が必要です。
また、.codegraph/ はローカルインデックスなので、Git管理せず .gitignore に入れるのが安全です。
さらに、CodeGraph本体はローカルで動作しますが、Claude CodeやCursorなどのAIエージェントにコード断片を扱わせる場合は、会社やプロジェクトのAI利用ルールを確認しておくと安心です。
まとめ
CodeGraphは、Claude Code、Cursor、Codex CLIなどのAIコーディングエージェントに、コードベースの構造を効率よく理解させるためのMCPツールです。
Web開発者にとってのポイントは以下です。
- CodeGraph本体はMITライセンスのOSS
- ローカルでコードグラフを作成できる
- Claude Code / Cursor / Codex CLI / OpenCodeで利用できる
- TypeScript / JavaScript などWeb開発で使う言語に対応
- Reactコンポーネント、hooks、API clientの調査に使える
- Next.jsのroute handler、middleware、server actions周辺の調査にも使える
- 導入後は自然言語で「CodeGraphを使って」と指示できる
-
.codegraph/は.gitignoreに入れるのが安全 - 大規模Webサービスでは試す価値が高い
- 探索系タスクではトークン数の節約にもつながる
CodeGraphは、AIに「もっと賢くコードを探してもらう」ための補助ツールです。
大規模なWeb開発では、実装そのものよりも、既存仕様の把握や影響範囲調査に時間がかかることがあります。
そのような環境では、CodeGraphを導入することで、AIエージェントによるコード調査の効率を上げられる可能性があります。
まずは個人環境で以下を試してみるのがよさそうです。
npx @colbymchenry/codegraph
cd your-web-project
codegraph init -i
codegraph status
そのうえで、Claude Codeに以下のように依頼します。
このプロジェクトではCodeGraphを初期化済みです。
Web開発のコード調査では、grepやReadを多用する前に、まずCodeGraphで対象コンポーネント、hooks、API client、route handler、影響範囲を確認してください。
既存コード調査や影響範囲調査に時間がかかっているWeb開発者にとって、CodeGraphは試す価値のある選択肢です。