graftでリポジトリコンテキストを探索する
graftはリポジトリをあらかじめインデックス化したコンテキストグラフです。コードを理解したり、どこを修正すべきか探したり、変更の影響範囲を把握したりするとき、grepやファイルを直接開く代わりに先にgraftへ尋ねると、はるかに少ないトークンで正確なfile:line位置が得られます。
- graftとは何か、なぜ必要か
- grep/ファイル直接読み込みより先にgraftを使うべき理由
- 主要コマンド5つ (ask, grep, skeleton, callers, map)
- MCPツールとしてgraftを使う方法（対応環境）
- 実践ワークフローの例
- コード変更後のグラフ更新
1. graftとは何か
graftはリポジトリをスキャンし、ファイルごとに「このファイルが何をするか、どのシンボルを定義しているか、誰が呼び出しているか」を整理した小さなMarkdownノードのグラフを作成します。このグラフはgraft/ディレクトリに保存され、コードが変わるたびにgitと共に更新されます。
graftは2つの方法で使えます：
- CLI — ターミナルで
graft <subcommand>の形式で直接実行 - MCPツール — ホスト（Claude Codeなど）が
graft_find_code、graft_find_all、graft_trace_calls、graft_file_api、graft_repo_mapのようなツールを公開している場合、同じグラフをツール呼び出しで照会
2. なぜgrepではなくgraftなのか
| 状況 | grep / ファイル直接読み込み | graft |
|---|---|---|
| 「この機能はどう動作するか？」 | 関連ファイルを推測して複数開く必要がある | graft askがコードスニペット付きのランキング結果を即座に返す |
| 「このシンボルを誰が呼び出しているか？」 | 文字列検索＋手動照合（誤検出が多い） | graft callersが正確な呼び出し関係をグラフから直接照会 |
| 「このパターンが出現する箇所を全部探したい」 | grep -rnで可能だが結果が整理されない | graft grepが包含するシンボルごとにグループ化して表示 |
| 「このファイルのAPI全体をざっと確認したい」 | ファイル全体を読む必要がある（トークン消費が大きい） | graft skeletonがシグネチャだけを約10倍安く提供 |
| 「初めて見るリポジトリ、どこから始める？」 | READMEを読んでフォルダを一つずつ開いていく | graft mapがディレクトリクラスター・ハブ・ホットスポットをトークン予算内で要約 |
3. 主要コマンド
3.1 graft map — 初めてのリポジトリのオリエンテーション
初めて見るリポジトリでまず実行します。LLM呼び出しなし（無料、$0）で、ディレクトリ構造・ハブファイル・ホットスポットをトークン予算内で表示します。
graft map注意：mapそのものがオリエンテーションの答えです。mapが言及したすべてのサブシステムをskeletonで追いかけるのは過剰使用です。
3.2 graft ask — 理解・修正すべき場所を探す
「これはどう動作するか？」「このコードはどこにあるか？」といった質問に、コードスニペット付きのランキング結果を返します。
graft ask "ログイン失敗時のリトライロジックはどう動作するか" --source--source— 各結果に核心コード（デフォルト8行）を一緒に表示--full— 8行で不十分な場合、定義全体を表示- 理解・修正作業であれば、1位の結果がそのまま答えです。
covers:に明記されたfile:lineを引用し、--source結果からそのまま修正します。
3.3 graft grep — 網羅的検索
リテラル文字列やシンボルのすべての出現箇所を、それを包含するシンボル単位でグループ化して表示します。
graft grep "processPayment"インデックスされていないファイルまで確認が必要な場合のみ、生のgrep -rnで補います。
3.4 graft skeleton — ファイルAPIを一目で確認
ファイル全体を読まずに、すべての定義のシグネチャと位置を約10倍安く確認できます。API全体をざっと見たいときに便利です。
graft skeleton src/services/payment.ts3.5 graft callers — 正確な呼び出し関係を追跡
あるシンボルを変更する前に、それを誰が呼び出しているか（またはそれが何を呼び出しているか）を正確に把握します。リファクタリングや名前変更の前には必ず実行しましょう。
# このシンボルを呼び出している箇所（デフォルト）
graft callers formatCurrency
# このシンボルが呼び出しているもの
graft callers formatCurrency --direction out
# 全体の影響範囲（つながっているすべてのファイル）
graft callers formatCurrency --depth allgraft callers <symbol> --depth allでつながっているすべてのファイルを先に地図化してから修正しましょう。
4. MCPツールとして使う
Claude Codeのようなホスト環境では、同じグラフをCLIの代わりにMCPツール呼び出しで照会できます。対応関係は次の通りです：
| CLIコマンド | MCPツール |
|---|---|
graft ask | graft_find_code |
graft grep | graft_find_all |
graft callers | graft_trace_calls |
graft skeleton | graft_file_api |
graft map | graft_repo_map |
graft callers / graft_trace_callsがこのエッジを読む唯一の方法です。
5. 実践ワークフロー
初めて触れるプロジェクトであれば、まずgraft mapで全体構造を把握します。
理解・修正ならask --source、網羅的調査ならgrep、API確認ならskeleton、影響範囲の把握ならcallersを使います。
ask --sourceが返したfile:lineとコードスニペットをそのまま引用しながら修正します。結果が切り詰められている場合（+N more lines）は、その正確な範囲だけファイルで開いて確認します。
コードを大きく変更した後は、graft buildでグラフを最新状態に合わせます。
6. グラフの更新 (graft build)
graftのグラフは決定論的に生成され、LLM APIキーなしで無料で更新できます。大規模なコード変更（新規ファイル追加、大規模リファクタリングなど）の後は、グラフを再ビルドして最新状態を保ちましょう。
graft buildnew-project.ts)は、スキャフォールディングの過程でgraftグラフが自動的にビルドされます。グローバルにインストールされたgraftコマンドをまず使い、なければbunxで代替実行します。つまり、新しく作ったプロジェクトは最初からgraft askで質問できます。
2026-10アップデート：ワークスペース自体はgraftの統合ファイルをテンプレートとして同梱しなくなりました。skills/graftスキルはfrontmatterにmirror: falseとl2_propagate: falseを持ち、スキャフォールドされたAGENTS.mdには事前レンダリングされたgraftブロックが入らなくなっています — graftのサーフェスはツール所有のため、チェックアウトで一度graft initを実行すれば生成されます。上記のスキャフォールディング時のグラフビルドは以前と同じく動作します。