code-graph

code-graph skill の概要

code-graph ができること

code-graph skill は、codebase-memory-mcp を通じて AST ベースのコードグラフを使い、ファイルを開く前にシンボルを見つけ、依存関係をたどり、影響範囲を見積もるのを Claude に助けます。生のテキスト検索よりも、構造を踏まえた高速なナビゲーションが重要なコード編集作業に向いています。

どんな人が導入すべきか

中規模〜大規模のコードベースを頻繁に変更する人、ファイルをまたぐ挙動をデバッグする人、編集前に「これって何に依存されている？」をより正確に把握したい人は code-graph を導入するとよいです。grep だけではノイズが多すぎると感じる場面で、code-graph skill が推測作業を減らしてくれるのが特に有効です。

何が違うのか

Code Editing における code-graph の主な強みは、エージェントに「まず構造を問い合わせ、ファイルはその次に読む」よう促す点です。フォルダを手で走査するところから始める一般的なプロンプトよりも、シンボル検索、呼び出し関係の追跡、リファクタ計画、影響分析に強くなります。

code-graph skill の使い方

インストールして有効化する

リポジトリの code-graph install 用インストールフローを使い、その後、Claude 環境で skill が利用可能になっていて MCP サーバーに到達できることを確認してください。skill 内の when-to-use ノートには、ファイルを読む前にグラフを問い合わせるよう書かれているため、グラフのバックエンドが実際につながっている場合にのみ有効化の意味があります。

適切な入力から始める

よい code-graph usage の依頼は、「このリポジトリを理解する手伝いをして」ではなく、対象シンボル、ファイル領域、変更の目的を明示します。たとえば、「AuthService がどこで呼ばれているかを code-graph で探し、依存関係をマップして、トークン更新を変える前に影響範囲を教えて」といった形です。こうすると、skill がグラフを効果的に検索できるだけの構造情報を得られます。

実践的なワークフロー

この code-graph guide の流れが実用的です。最初に関連シンボルや依存チェーンを尋ね、次に影響を受けるファイルを聞き、最後に挙動確認やコード編集に必要なファイルだけを開きます。アーキテクチャの質問にはグラフ検索を使い、実装詳細、設定値、あるいはコード構造だけでは表現しきれない文字列には直接のファイル読み取りを使うのがよいです。

まず読むべきファイル

まず SKILL.md を読んで、グラフ先行のルールと対応している MCP ツールを把握してください。次に README.md、AGENTS.md、そして存在するなら rules/、resources/、references/、scripts/ フォルダも確認します。このリポジトリでは SKILL.md が唯一のサポートファイルなので、code-graph install と利用範囲を判断するための主な情報源です。

code-graph skill の FAQ

code-graph は grep より優れていますか？

「このメソッドに何が依存しているか？」や「このシンボルをリネームしたら影響範囲はどこまでか？」のような構造的な答えが必要なときは、code-graph のほうが適しています。grep は、リテラル文字列、ログメッセージ、コード構造の外にある内容を探すときに依然として強いので、skill は置き換えではなく補完です。

使わないほうがよい場面は？

主に文章、ドキュメント、非コードファイル内の正確な文字列検索が目的なら、code-graph に頼らないほうがよいです。MCP サーバーが使えない場合や、ファイルを読むだけで十分な小さなリポジトリで単発の答えが欲しい場合も、適性は高くありません。

初心者にも向いていますか？

はい、目的をはっきり説明できるなら向いています。初心者は、編集前にシンボルマップ、依存パス、影響チェックを頼むほうが最も価値を得やすく、skill を広い意味でのリポジトリ案内として使おうとするより効果的です。

ファイルを読む作業は不要になりますか？

いいえ。skill の目的は、不要なファイル読み取りを減らすことであって、完全になくすことではありません。グラフで範囲を絞り、そのうえで挙動確認と安全な変更に必要な最小限のファイルを読むのが基本です。

code-graph skill を改善するには

グラフに具体的な対象を与える

code-graph skill で最も強い入力は、1 つのシンボル、1 つの機能領域、または 1 つの変更結果を明示するものです。「paymentIntent の参照をすべて見つけ、呼び出し元を示し、リトライ変更で影響を受けそうなファイルを特定して」は、「payments を解析して」よりずっと優れています。後者では広い要約しか返せませんが、前者ならグラフが使える経路を返しやすくなります。

解決策より先にスコープを尋ねる

よくある失敗は、いきなり実装に飛び込むことです。code-graph では、まず依存チェーン、影響を受けるモジュール、起こりそうなエッジケースを確認し、その後で編集方針を求める順番にしてください。この順序にすると、code-graph usage がよくなります。というのも、この skill はコードの書き換えより先に構造的な質問へ答えるよう作られているからです。

不確実性は対象を絞ったファイル読み取りで解消する

グラフが複数の候補パスを示したら、どれが正しいかを確認するために必要最小限のファイルだけを聞いてください。ここで code-graph for Code Editing が最も役立ちます。グラフで探索範囲を絞り、短い追加読み取りで正確な挙動を確認してから、実際の修正に進めます。

最初の結果をもとに絞り込む

最初の出力が広すぎるなら、正確な識別子、パッケージ名、あるいは変更種別を足して絞り込みます。変更種別は、rename、move、refactor、bug fix、dependency audit などです。優れた code-graph guide のプロンプトは、skill が意図を推測せずに、具体的な呼び出し元、依存関係、影響範囲を返せる程度に十分具体的です。