AIコーディングエージェントにコードベースのマップを作らせてみた結果

AIコーディングアシスタントにバグの修正や仕組みの説明を頼むたびに、たいていゼロからのスタートになる。ファイルを読み、grepで探し回り、昨日すでに持っていたはずのプロジェクト理解をゆっくりと再構築する。今日は2026年9月2日だが、この問題がますます注目されている理由は、AIコーディングエージェントが1年前と比べてはるかに自律的で多段階な作業をこなすようになったからだ。つまり、セッションごとに「ゼロからやり直す」コストが、時間的にもトークン料金的にも急速に積み上がっていく。

まさにその問題を解決しようとするのがGraftというツールだ。おもちゃのデモではなく実際のプロジェクトで試してみたので、実際に何をするのか、何がわかったのか、そしてどこが足りないのかを順を追って紹介したい。

Graftとは何か

Graftはコードの司書のようなものだと考えてほしい。AIエージェントが何かを理解する必要があるたびにフォルダを彷徨い歩く代わりに、Graftが一度だけインデックスを構築する。それは小さなテキストファイルがリンクされたフォルダで、コードの各部分が何をするか、どの関数がどの関数を呼び出すか、すべてがどう繋がっているかを記述している。

これは2つのレイヤーで行われる：

1. A 構造グラフ。tree-sitterというコード解析技術を使って構築される。このレイヤーにはAIモデルは一切不要だ。コンパイラがやるのと同じようにコードを読み取り、関数名やクラス、それらの間のつながりを抽出する。
2. オプションの コンセプトレイヤー。AIモデルを使って、コードの各部分が何のためにあるかを平易な言葉で要約する。この部分はAIモデルを呼び出すため実行に費用がかかるので、オプトイン方式になっている。

重要なのは、コードベース全体をマッピングする最初のレイヤーは無料で、APIキーも不要だということだ。ローカルでファイルを解析するだけでよい。

実プロジェクトでテストしようと思った理由

私は1つのリポジトリ内で複数の実コードベースを扱っている。Kotlinで書かれたAndroidアプリ、モダンなWebフレームワークで構築されたウェブサイト、いくつかの小さなバックエンドサービス、そして雑務用のPythonスクリプトがいくつか。そのうちの1つ、Androidアプリには、新機能が適切に分割されずに次々と継ぎ足されたせいで3,000行を優に超えるまで膨れ上がった単一ファイルがある。これは実際のソフトウェアプロジェクトでは非常によくある状況だ。みんな「後で」リファクタリングするつもりでいるのだが、その「後で」はずっと先延ばしにされ続ける。

そのようなファイルに手を入れる前に、何が何に依存しているかを正確に知っておきたい。小さな変更が3画面先で静かに何かを壊してしまわないように。まさにそういう質問に答えるためにGraftは作られているので、公正で正直なテストになると感じた。

セットアップ

ステップ1：ツールのインストール

Graftは小さなコマンドラインプログラムとしてインストールされる。マシンに開発者ツールをグローバルインストールするのと同じ要領だ：

npm install -g @nanonets/graft

ステップ2：変更内容のプレビュー

プロジェクトに何かを組み込む前に、まだ何も触らずに、作成または変更されるファイルの一覧を正確に表示させることができる：

graft init --dry-run

短いリストが表示された。AIコーディングアシスタント用のいくつかの設定ファイル、スキルファイル、そして生成されるグラフ自体のフォルダだ。何かを確定する前にこのリストを確認できるのは、プロジェクトを尊重するツールの良い兆候だ。

ステップ3：このプロジェクトだけに限定して実行

この種のツールの中には、作業中のプロジェクトだけでなく、マシン上のすべてのプロジェクトに影響するグローバル設定を書き込みたがるものもある。私はそれを望まなかったので、すべてをローカルに保つフラグを使った：

graft init --no-global -y

これにより、プロジェクト内のすべての実ソースファイル（私の場合、Kotlin、TypeScript、JavaScript、Pythonにまたがる77ファイル）が解析され、561個の個別のコード要素と1,229個のつながりを持つグラフが数秒で構築された。AIモデルは使わず、コストもゼロだ。

実際に使ってみる

ここからが面白くなった。Graftにリポジトリ全体の概観マップを求めたところ、あの巨大なAndroidファイル内の1つの関数が、プロジェクト全体で最も依存されているコードであることを即座に指摘した。10か所から呼び出されている。

次に、もっと具体的な質問をした。その1つの関数を変更した場合に影響を受けるものをすべて見せてほしいと。Graftは連鎖全体をたどった。すべての画面、すべてのヘルパーファイル、その関数の動作が波及するすべての箇所を、即座に、無料で。

手動でコードを読んだり、AIアシスタントにすべてをgrepさせたりして同じ答えを得るには、約200,000トークン分のファイル内容を読む必要があっただろう。Graft自身のアカウンティングツールによると、グラフを再利用することでそれだけのトークンを節約できたという。中間クラスのClaudeモデルの現在の価格で計算すると、1回のやり取りで約40セントの節約になる。小さく聞こえるかもしれないが、この節約は人間であれAIであれ、そのコードベースについて同様の質問をするたびに繰り返される。そこにこそ本当の価値が積み上がっていく。

気に入らなかった点

すべてが摩擦なしだったわけではない。組み込むと、Graftはすべてのメッセージ送信時に実行されるフックをインストールし、グラフに関連する情報があるかをチェックする。コードとは無関係な普通の会話の質問をした際に、2回ほど、グラフを確認するよう提案してきた。試みること自体は間違っていないが、そのやり取りでは不要なノイズだった。

また、これは非常に新しいツールであることを冷静に認識しておくべきだ。私がこれを書いているほんの数か月前に初めて公開され、その短い期間にすでに数十回の小規模なバージョンリリースを重ねている。この変化のペースはエキサイティングだが、古い開発者ツールが経てきた何年もの実戦テストをまだ経験していないということでもある。

結論

Graftは、AIコーディングアシスタントとの作業における日常的な苛立ち、つまりセッション間で変わらないコードの絶え間ない再発見という問題を解決する。本当に複雑なマルチ言語プロジェクトにおいて、ローカル解析だけを使い、数秒で、無料で、正確かつ有用な回答を生成した。魔法ではないし、ワークフローに多少のおしゃべりを加えはするが、AIアシスタントが変更を加える前にコードベースを理解するための基盤として、その存在価値を証明した。

利点

• コア機能にAIモデルを必要とせず、マルチ言語コードベースの完全なマップを数秒で構築できる
• 構造グラフは完全にオフラインで動作するため、実行コストがかからない
• 変更の「影響範囲」全体をトレースできる。つまり、編集しようとしているコードに依存しているすべてのものを把握できる
• 他のプロジェクトの設定に触れることなく、単一のプロジェクトにスコープを限定できる
• 生成されたデータは自動的にバージョン管理から除外されるため、共有リポジトリを散らかさない
• 同じプロジェクト内の複数のプログラミング言語にまたがって動作する

欠点

• すべてのメッセージで実行されるフックをインストールするため、コードに関係ない会話ではノイズに感じることがある
• 非常に新しいソフトウェアであり、実績がまだ短い
• より深いAI要約レイヤーを使うには独自のAIモデルアクセスが必要で、有効にすると費用が発生する
• セットアップ時にプロジェクト内の複数の設定ファイルに変更が加わるため、受け入れる前に書き込まれる内容を確認する価値がある

注意事項

この記事は教育を目的としており、特定の時点における特定のツールの実体験を反映している。ここで言及されているコマンド、数値、バージョンの詳細はツールの進化に伴い変更される可能性があるため、インストールする前にツールの公式ドキュメントを確認してほしい。共有プロジェクトで試す場合は、作成または変更が提案されるすべてのファイルをまず確認し、他の誰かが良い経験をしたからといって新しい開発者ツールにリスクがないと決して思い込まないでほしい。

よくある質問

• Graftとは何ですか？ — コードベースのローカルなリンク付きマップを構築するツールで、AIコーディングアシスタント（および開発者）が毎回ゼロから探索し直すことなく、素早くコードを理解できるようにするものです。
• 動作にAIモデルは必要ですか？ — いいえ。コア機能であるコードの構造マップは、コード解析技術を使って完全にオフラインで動作します。オプションのより深いレイヤーはAIモデルを使用しますが、その部分は必須ではありません。
• 既存のプロジェクトにインストールしても安全ですか？ — 何かに同意する前に、作成または変更される内容を正確にプレビューできます。これは新しい開発者ツールを導入する前の合理的な安全チェックです。
• 同じプロジェクト内で複数のプログラミング言語に対応していますか？ — はい。私のテストでは、コンパイル型モバイルアプリ言語と複数のWebスクリプト言語を含む、複数の言語を同じ実行で一緒に解析しました。
• 同じコンピュータ上の他のプロジェクトに影響しますか？ — 許可した場合のみです。すべてを単一のプロジェクトフォルダにスコープを限定する設定があります。
• 小規模でシンプルなプロジェクトでも使う価値はありますか？ — おそらくそれほどではありません。メリットはコードベースの規模と複雑さに比例して大きくなります。特に、多くの履歴が蓄積された大きなファイルがある場合に効果的です。
• 生成されたマップはバージョン管理にコミットする必要がありますか？ — いいえ。ローカルで再生成されるように設計されており、通常はバージョン管理から自動的に除外されます。
• 最大の欠点は何ですか？ — すべてのメッセージでチェックを行うフックです。コードに関係のない会話では、不要なおしゃべりのように感じることがあります。

タグ

#ai #developertools #codingagents #productivity #softwareengineering #devtools #automation #codereview #techtools #programming