要点：AI コーディングの失敗は「モデルが間違ったコードを書いた」よりも「間違った場所を変更した」ことに起因することがほとんどです。原因は多くの場合、プロジェクトへの理解が断片的なテキスト検索に頼っていることにあります。エンジニアは見知らぬコードベースを IDE のジャンプや参照検索で読み進めます。その正体は、頭の中で維持しているシンボル関係のグラフです。Semibot はこのグラフを内蔵機能として実装しました。Agent は関係の辺をたどってナビゲートします。変更前に影響範囲を確認し、変更後はその関係に沿ってレビューする。
できること / できないこと
できること
- コードベースのシンボル単位インデックス：関数の呼び出し関係、インポート/エクスポート、型参照、クラスとインターフェースの階層。テキスト一致ではなく、構文木レベルの理解です。
- Agent のナビゲーションシステム：定義へ飛び、呼び出し元を探し、影響ファイルを特定する——エンジニアが IDE でジャンプするように、Agent はグラフ上を連続的に移動できます。
- ローカルで構築・保存：プロジェクトを開いたときにローカルでインデックスを構築します。グラフ構築のためにコードが外部に出ることはありません。
できないこと
- 人間向けの見た目重視の可視化ではない：グラフは装飾的な図を描きません。Agent の検索とワークフローに奉仕するものです。
- 実行時の解析ではない：プログラムが実行されたときに何が起きるかは分かりません。動的な振る舞いはテストの役割です。
- 全言語で同等の深さではない：TypeScript/JavaScript が最も深く、他の言語は浅くなります（後述の限界を参照）。
理念：なぜ Agent にはグラフが必要か
AI コーディングツールの失敗事例を見ると、あるパターンが見えてきます。めったに「モデルが間違ったコードを書いた」ではなく、たいてい「モデルが間違った場所を変更した」のです。そして根本原因はたいてい同じ——プロジェクトへの理解が断片的なテキスト検索から得られていたことです。
grep と勘は、運任せ
従来のやり方はキーワード検索です。関数名、エラー文字列、コメントの言葉を検索する。この方式には構造的な問題が三つあります。第一に、命名と意味のズレ——handleRequest という関数が、あなたが直したいリクエストを処理しているとは限りません。第二に、ノイズがコンテキストを圧迫する——十件ヒットして九件が無関係、本当に必要なファイルはヒットしないこともあります。第三に、間接的な関係が見えない——型のフィールドを変えても、キーワード検索ではすべての利用箇所を見つけられません。
人はプロジェクトをどう読むか
エンジニアはコードベースを最初から最後まで読みません。エントリーポイントからジャンプします。これはどこで定義され、誰が呼び、どのインターフェースを実装し、この型はどこから来るのか。これらの動作の土台にあるのがシンボル関係のグラフです。エンジニアは IDE を使ってそれを頭の中に維持しているだけです。
Semibot の理念は、このナビゲーション能力を丸ごと Agent に引き継ぐことです。まずグラフを築き、それから働く。検索のたびにキーワードで運任せになるのではなく、確定した関係の辺をたどれます。
「ネイティブ」が持つ二つの意味
- 外付けではなく内蔵：グラフは Semibot のネイティブ実装です（TypeScript 製、Python sidecar なし、言語サーバーの設定も不要）。プロジェクトを開けばすぐ使えます。
- 付属品ではなく第一級の基本操作：グラフは営業資料のための可視化ではありません。グラフへの問い合わせは、ファイルの読み書きやコマンド実行と同じ位の、Agent の基本的な動作です。その結果は編集計画と ChangeSet レビューに直接流れ込みます。
グラフが Agent の振る舞いを変える四つのシーン
シーン一：見知らぬプロジェクトを引き継ぐ
Agent に「このエラーを直して」と頼んだとします。グラフがなければ、エラー文を検索し、ディレクトリを眺め、エントリーポイントを推測します。グラフがあれば、エラー箇所から出発します。定義へ飛び、呼び出しチェーンを上り、実際に例外を投げている分岐を確認し、根本原因にたどり着く。触るファイルが減り、経路がまっすぐになり、時間とコストが目に見えて下がります。
シーン二：変更前に影響範囲を見る
「このフィールドをオプショナルにして」。グラフはまず答えます。このフィールドを誰が参照しているか、非 null 判定はどこにあるか、どの型定義が連鎖的に変わるか。Agent は手を動かす前に影響範囲を列挙でき、すべての利用箇所を覆盖する変更を作れます。主な呼び出し箇所だけ直して、テストの漏れを待つやり方とは違います。
シーン三：レビューを関係に沿って行う
ChangeSet は diff を見せます。グラフは「その diff で十分か」に答えます。自分や同僚の変更をレビューするとき、Agent は変更されたシンボルの辺をたどって確認します。呼び出し元はすべて対応したか。同じ変更が必要な並行実装はないか。レビューは「diff が正しそうに見えるか」から「影響範囲に沿って検証する」へ変わります。
シーン四：コンテキストを刀の刃に使う
モデルのコンテキストは希少な資源です。グラフ検索は「大量の低関連ファイル」の代わりに「本当に関連する少数のコード」をモデルに渡します。同じタスクでも、コンテキストがきれいなほど干渉が減り、コストが下がり、出力の質が安定します。
限界と境界
このサイトの他のガイドと同じく、はっきり言います。グラフには明確な適用境界があり、境界を知ることが上手な使い方の一部です。
- 言語ごとの深さに差がある：グラフは TypeScript/JavaScript 向けに作られ、これらのプロジェクトに最も深いデータを提供します。他の言語でもファイルの読み書きやコマンド実行は可能ですが、影響分析の精度は下がります。
- 静的解析の天井：動的ディスパッチ、リフレクション、文字列から組み立てられる参照、実行時生成のコードは追跡できません。これらはテストの守備範囲です。
- 巨大リポジトリでは取捨選択が必要：monorepo ではインデックス時間と関係カバレッジのバランスを取る必要があり、コールドスタートの索引には少し辛抱が必要です。
- グラフはテストの代わりにならない：グラフは「影響の可能性がある場所」を示し、テストは「本当に影響しているか」を検証します。補完関係であり、どちらか一方で十分ということはありません。
向いている人 / 向いていない人
グラフが最も価値を出す場面
- 中規模以上の TypeScript/JavaScript プロジェクト：関係が密であるほど、grep との差が大きく開きます。
- 他人のコードを引き継ぐことが多いチーム：関係ナビゲーションが「理解までの時間」を縮めます。
- 変更の品質基準が高いコードベース：編集前に影響範囲を確認し、レビュー時にそれに沿って検証する。
効果が限られる場面
- スクリプトや小さなツール：数十ファイルの規模なら普通の検索で十分です。
- 動的言語中心のプロジェクト：関係データが浅い場合、グラフはヒント出力装置と考え、影響分析の決定版としては期待しないでください。
- 実行時検証が中心の作業：パフォーマンスチューニングや並行性の問題は、実行時のデータで扱う仕事であり、静的なグラフの守備範囲外です。
FAQ
ネイティブコードグラフとは何ですか？
コードベースのシンボル単位インデックスです。呼び出し関係、インポート/エクスポート、型参照、クラスとインターフェースの階層を把握し、Semibot はローカルで構築します。Agent は関係をたどってナビゲートします。
IDE の「参照検索」と何が違いますか？
土台は似ていますが、使い手が違います。IDE の検索は人間に一度に一覧を見せるもの。グラフは Agent が連続的にナビゲートするための基本操作で、編集計画や ChangeSet レビューに直接使われます。
追加のインストールや設定は必要ですか？
不要です。Semibot に内蔵されたネイティブ TypeScript 実装で、Python sidecar も言語サーバーの設定も不要です。プロジェクトを開けば使えます。
グラフのデータはどこに保存されますか？
他の作業データと同様にあなたのマシンのローカルで構築・保存されます。グラフ構築のためにコードが外部に出ることはありません。
グラフがあってもテストは必要ですか？
必要です。グラフは静的解析であり、動的ディスパッチやリフレクション、文字列組み立ての参照は追跡できません。「影響の可能性がある場所」はグラフが見つけ、「本当に影響しているか」はテストが検証します。
リポジトリ全体をモデルに渡すのと何が違いますか？
リポジトリはどんなコンテキストウィンドウよりも大きい。グラフの価値はコンテキストの経済学にあります。関係検索で関連する少数のファイルを先に絞り込むことで、ノイズが減り、コストが下がり、出力が安定します。