Graft レビュー: コードベース理解を markdown グラフとしてエージェントに渡す

エージェントが毎回同じ探索をやり直す問題

コーディングエージェントは、タスクを受け取るたびにリポジトリの地図をゼロから描き直す。README の説明では、用語を grep し、ファイルを開き、import をたどり、戻ってまた試す、という往復が発生する。この探索はタスクごとに繰り返され、セッションが終われば捨てられ、隣のチームメンバーのエージェントも同じ場所から始める。README はこの対比を「人間は一度だけオンボーディングし、エージェントは毎回オンボーディングする」と表現している。Graft が狙うのはこの再探索の削減であり、コードを賢く書くためのツールではない。対象読者は、1 つのリポジトリに対してエージェントを繰り返し走らせる開発者と、そのコストをチーム単位で見ている人だ。

graft/ に markdown ノードを書き出すという設計

Graft はコードベースの理解を一度だけ構築し、システム、API、概念ごとに 1 ノードを持つリンク済み markdown ファイル群としてリポジトリ内に書き出す。README はこれを「関数名の羅列ではない」と説明している。各ノードには、その部分が何をし、残りとどうつながるかが平易な英語で書かれる。重要なのは検索方式だ。埋め込みも類似検索も使わず、インデックスを常時温めておく必要もない。グラフはリンクされたファイルの集合にすぎず、エージェントはリポジトリ内の他のファイルを読むのと同じように、それを開き、grep し、リンクをたどる。ベクトル DB を別途運用する構成と比べると、外部プロセスを持たない点が運用上の違いになる。ただし README の記述は英語ノードが前提であり、日本語コメント中心のリポジトリで説明文がどう生成されるかは素材からは確認できない。

インストールと graft init が書き換えるもの

導入手順は README いわく 2 コマンドで完結する。npm install -g @nanonets/graft で CLI を入れ、graft init を実行する。init はどのエージェントを配線するかを尋ね、コードから graft/ を構築し、statusline とフックを .claude/ に配置する。以降のセッションでは、各プロンプトに該当ノードが引き込まれ、ターンごとにグラフがバックグラウンドで再構築される。デーモンはなく、既定で維持すべきものはない。確認したい場合の逃げ道も用意されている。graft init --dry-run は書き込む予定のファイルをすべて列挙し、graft init --agents claude はプロンプトを飛ばして Claude Code だけを配線する。グローバル導入を避けたい場合は npx @nanonets/graft init が同じ動作をする。graft build は graft/ を .gitignore に自動追加する。グラフは node_modules と同様のローカルで再生成可能なキャッシュという位置づけで、共有するのは .claude/ への配線であり、各メンバーが自分のグラフを生成する。

MCP サーバーと Claude Code 深部統合の違い

README はエージェント統合を 2 系統に分けている。MCP サーバー経由の接続と、Claude Code への深い統合だ。前者は MCP に対応するエージェントからグラフを引く経路、後者は init が .claude/ にフックと statusline を置くことで、プロンプトへのノード引き込みとターン後の再構築を自動化する経路になる。つまり MCP はエージェント側から明示的に叩く形、Claude Code 統合はセッションに同乗させる形だ。この差は導入の手間と、グラフ更新のタイミング制御のしやすさに直結する。自動再構築は便利な反面、エージェントが動くたびにバックグラウンドで処理が走ることを意味する。大規模リポジトリでその負荷がどの程度かは README に数値がないため判断できない。

graft grep、graft map、graft viz という調査手段

CLI にはグラフを人間が直接使うためのコマンドがある。graft grep と graft map は検索と全体把握のための入口で、graft viz はグラフを可視化する。これらはエージェント専用ではなく、開発者が「このリポジトリを Graft はどう理解したか」を確認する用途に向く。ノードの説明が実装とずれていれば、エージェントはそのずれた説明を根拠に動く。生成物をレビューせずに配線だけ済ませるのは危険で、graft viz や graft grep で中身を一度眺めてから運用に入るほうが安全だ。モノレポや複数リポジトリを 1 フォルダに並べた構成への対応も README に項目があるが、境界の扱いの詳細は素材からは読み取れない。

README が示すベンチマーク値の扱い方

README には数値が並んでいる。Tool-call reduction +46%、Token savings +42%、Time savings +60%、Correctness は 54% から 66% へ +12 ポイント。見出しには 4 倍安く 3 倍速いという表現もある。これらはすべてプロジェクト側が提示した数字であり、本記事では追試していない。条件は「Cold Claude Code」対「Claude Code with graft」とだけ書かれ、対象リポジトリ、タスク数、モデル、試行回数は素材からは分からない。SWE-bench Verified の節も存在するが、詳細な設定はここには引用されていない。数字を採用判断の根拠にするなら、自分のリポジトリで同じ計測をやり直す必要がある。少なくとも、コールド状態のエージェントとグラフ構築済みのエージェントを比べている以上、初回のグラフ構築コストは別勘定である点は押さえておきたい。

向かないケースと、代わりの選択肢

Graft が不要になるのは、エージェントに渡すコンテキストを自分で選べる場合だ。対象ファイルを明示してプロンプトに貼る運用なら、再探索はそもそも起きない。単発の小規模スクリプト、セッションをまたいで同じリポジトリを触らない作業、対応言語に含まれない言語だけで書かれたリポジトリも同様だ。代替として挙げられるのは、エディタやエージェント付属のコード検索インデックスをそのまま使う方法である。こちらはシンボル定義と参照を高速に引くが、ノードに相当する「この部分が何をするか」の説明文は持たない。Graft は説明文を持つ代わりに、その説明が古くなるリスクを負う。コードを変更したのにグラフが再構築されていなければ、エージェントは誤った前提で動く。検索インデックスの陳腐化より影響が読みにくい種類の失敗だ。

ライセンス、保守コスト、確認すべき前提

ライセンスは MIT で、README のバッジにも明記されている。MIT は商用利用や改変、再配布を許容する寛容なライセンスだが、無保証であり、生成物の正確性について作者が責任を負うわけではない。法的判断はここでは扱わない。保守面では、グラフは再生成可能なキャッシュとして .gitignore に入るため、リポジトリを汚さない。共有されるのは .claude/ への配線だけで、変更があれば git add .claude してコミットする形になる。エージェントの設定ファイルをバージョン管理に載せることになるので、チームで .claude/ をどう扱うかの合意は先に取っておきたい。テレメトリは匿名でオプトアウト可能と README のバッジに記載がある。Node.js のバージョン要件はバッジで示されているが、具体的な下限はここでは確認できない。導入前に npm パッケージの engines を確認するのが確実だ。

編集部の結論

導入を検討すべきなのは、1 つのリポジトリを複数のエージェントや複数のチームメンバーが繰り返し触る構成で、毎回の再探索コストを削りたい場合だ。逆に、単発の小さなスクリプトや、エージェントをセッション単位でしか使わないワークフローでは、graft/ を生成して .gitignore に積む分だけ無駄が増える。導入前に確認すべきは 3 点ある。第一に、自分の主要言語が README の対応言語表に載っているか。第二に、graft init --dry-run の出力に、書き換えられたくない .claude/ 配下のファイルが含まれていないか。第三に、チームに Node.js のバージョン要件を満たす環境が揃っているか。この 3 つがクリアなら、まず 1 つのリポジトリで graft build を走らせ、生成された graft/ の中身を人間が読んで、ノードの説明が自分のコードベースの実態と合っているかを確かめるのが最初の一歩になる。

公式情報源

1. Issues
2. License: MIT
3. Project website
4. README
5. trailhq/Graft on GitHub