定義：Semibot のネイティブコードグラフは、コードベース全体の呼び出し、参照、型の関係、構造的な接続をインデックスする TypeScript コード知識グラフエンジンです。コアランタイムに組み込まれており、Python サイドカーも外部 MCP 依存も不要です。Agent はこれを使って見慣れないプロジェクトをより速くナビゲートし、無関係なファイルを減らし、コードレビュー中に変更の影響範囲（blast radius）を追うことができます。グラフはナビゲーションの補助であり、正確性のオラクルではありません。コードが正しいかどうかは判断しませんが、コードの構造的なつながりを正確に把握する手助けをします。
キーワード検索が不十分な理由
キーワード検索（grep、find、意味検索）は「どのファイルにこの用語が含まれているか？」に答えます。コードグラフは「この関数に何がつながっていて、どのようにつながっているか？」に答えます。この違いが重要なのは、3 つのタスクの場面です。見慣れないプロジェクトへのオンボーディング（ファイルを見つけるのではなく構造を理解する）、変更の計画（他に何が影響を受けるかを知る）、コードレビュー（修正の影響を追跡する）です。
具体例で考えてみましょう。見慣れないプロジェクトで「この関数の戻り値を変えたい」と思ったとき、grep でその関数名を検索すると、定義と直接的な呼び出し箇所は見つかりますが、呼び出し元のさらに先でその戻り値がどう使われているかまでは追えません。コードグラフであれば、関数→呼び出し元→その呼び出し元の呼び出し元、という連鎖を辿り、変更の波及範囲を体系的に把握できます。特に大規模なコードベースでは、grep の結果が数百件に及ぶことも珍しくなく、その中から本当に影響を受ける箇所を特定するのは困難です。コードグラフは構造的な関係をたどるため、無関係なファイルを除外し、本当に読むべきファイルだけに絞ることができます。また、型の関係もインデックスされるため、インターフェースを実装するすべてのクラスや、ジェネリック型パラメータの具体的な型の流れも追跡できます。これは特に、型安全なリファクタリングの場面で威力を発揮します。あるインターフェースのメソッドシグネチャを変更する場合、その影響を受けるすべての実装クラスと呼び出し元を漏れなく把握できます。
Schema v4 と 4 層ツール契約
コードグラフは Schema v4 を使用します。統一構造ノード、能力レベルのレディネス、コミュニティ検出、データフロー、トポロジ、コード品質の派生インデックスです。エンジンは Agent に 4 層のツール（G1〜G5）を公開します。
- G1：基本クエリ。定義、参照、呼び出しサイトの検索。もっとも頻繁に使われる層で、コード内の「ここにある」「ここから呼ばれている」「ここを呼んでいる」という基本的な関係を返します。
- G2：構造クエリ。モジュール境界、依存方向、レイヤー違反。コードベースのアーキテクチャ的な構造を把握するために使います。例えば、「このモジュールは内部実装の詳細に依存しているか？」や「循環依存はないか？」といった問いに答えます。
- G3：影響分析。ノード X に変更があった場合、他のどのノードが影響を受けるか。blast radius を計算するための層で、コードレビューの場面で特に重要です。
- G4/G5：品質とトポロジのメトリクス。複雑さ、結合度、コミュニティ構造。コードベース全体の健康状態を測るための層です。計算コストが高いため、レート制限されています。
Agent はどの層を使うかを選択しません。Tool Gateway がタスクと Agent のリクエストに基づいてルーティングします。これにより、単純な参照検索で済む場面で Agent が誤ってコストの高いグラフ全体分析を実行することを防ぎます。G4/G5 の分析は計算リソースを大きく消費するため、必要な場面でのみ実行されるよう制御されています。
ナビゲーション vs 正確性
グラフは関係を示すものであり、コードが正しいかどうかを示すものではありません。関数 A が関数 B を呼び、B に 3 つの呼び出し元があることは教えてくれますが、B にロジックエラーがあることは教えてくれません。高リスクの結論（バグ、セキュリティ問題、パフォーマンス問題）はソースコードや再現可能なコマンドに戻る必要があります。グラフはナビゲーションを加速しますが、読み替えはできません。
この境界は設計によって強制されています。コードグラフは Tool Gateway ではナビゲーションツールとして公開されています。判決と誤解されかねない「分析レポート」や「品質スコア」を生成することはありません。Agent が解釈するデータを生成します。「関数 A は 5 つのモジュールから呼ばれている」という事実はグラフから得られますが、「関数 A は安全である」という結論はグラフからは得られません。この区別により、Agent がグラフのデータを過度に信頼して結論を出すことを防いでいます。
Agent が実際に使う方法
コード変更をレビューする際、Agent はグラフに「この関数を他に誰が呼んでいるか？」や「このファイルに依存するモジュールは？」と問い合わせることができます。これにより、変更によって影響を受ける可能性のあるコードのセットである blast radius が生成されます。Agent は関連ファイルを読み、影響を ChangeSet で報告します。グラフがなければ、Agent は grep して推測する必要があります。グラフがあれば、明示的な関係を辿ります。
実際のワークフローを具体的に説明します。ユーザーが「このエンドポイントのレスポンス形式を変えたい」と依頼した場合、Agent はまずコードグラフでエンドポイントのハンドラ関数を見つけます。次に、そのハンドラが呼び出すビジネスロジックの関数を辿り、さらにその関数が参照するデータモデルやユーティリティを特定します。こうして構築された blast radius により、「この変更は 3 つのモジュールに影響し、テストファイルが 5 つ更新が必要」といった具体的な影響報告が可能になります。ChangeSet には、変更が必要なファイル、各ファイルの差分、実行すべきコマンド、期待されるテスト結果が含まれます。
限界
- グラフは静的関係をインデックスします。動的ディスパッチ、リフレクション、メタプログラミングは部分的にしか捕捉されないか、捕捉されません。JavaScript の dynamic import やプロパティアクセスによる動的な呼び出しは、静的分析では追えない場合があります。
- インデックスの鮮度が重要です。最後のインデックス後にコードベースが大きく変化した場合、グラフが古くなっている可能性があります。Agent は再インデックスをリクエストできますが、大規模なコードベースの再インデックスには時間がかかります。
- 言語サポートは現在 TypeScript/JavaScript に限られます。他の言語は Agent の汎用検索機能にフォールバックします。将来的な言語サポート拡張は検討されていますが、現時点では TypeScript プロジェクトの恩恵が最も大きいです。
- グラフはナビゲーション用であり、検証用ではありません。コードが正しいことや安全であることを証明することはできません。グラフは「どこを見るべきか」を教えてくれますが、「見たものが正しいか」は人間と Agent の判断に委ねられます。
- グラフ全体分析（G4/G5）はコストが高く、リソース枯渇を防ぐためにレート制限されています。数千ファイルのプロジェクトでコミュニティ検出やトポロジ分析を行う場合、完了までに時間がかかることがあります。
ベンチマークと、正直な失敗の記録
Semibot のコードグラフはネイティブ TypeScript 実装です。Python への依存も、言語サーバーも、sidecar プロセスもありません。構文は Tree-sitter の WASM 文法から、モジュール解決は TypeScript コンパイラ API を再利用します。グラフモデルは 15 種のノードと 10 種のエッジ（contains、imports、exports、calls、references、extends、implements、tests、depends_on、resolves_to）を定義し、すべてのエッジは解決レベル（構文正確 / リゾルバ正確 / ヒューリスティック / 未解決）、信頼度、証拠のフィンガープリントを持ちます。信頼度はリゾルバの規則が生成し、モデルが記入することは決してありません。シンボルキーは正規化され、行の移動で参照が壊れることはありません。
クエリは四層 26 ツールに整理されます。シンボル検索。関係の走査（呼び出し元・呼び出し先・影響の発見）。リポジトリ全体の品質とトポロジー（コミュニティ検出は Louvain、循環検出は Tarjan——いずれも決定論的）。そして変化を明示的に意識する支援層。前三層は ChangeSet や Git の状態を読めず、モデル提供の SQL や任意の走査 DSL も拒否します。クエリ能力は製品の定義であって、モデルの即興ではありません。設計文書はベンチマークを保持しています。10 万ファイルの完全インデックスの中央値は約 10.4 秒で、第三者参照の Python 実装の約 43.4 秒に対し、インデックスサイズは約 49%。シンボルと影響のクエリは p95 でおよそ 1 ミリ秒です。
同等に引用に値するのは、設計文書が項目ごとに保持する失敗の記録です。ウォームクエリの遅延とメモリフットプリントは内部ゲートを満たさず（資源圧力下の I/O 停滞も観測され）、リリースゲートはそれに応じて、ウォームクエリ p95 で基線より 20% 速いこと、ピーク増分メモリが第三者実装の 80% 以内であることをハードな验收項目としています。正確性のゲートも定量化されています。正確なシンボル検索は top-1 精度 99% 以上、深さ 2 の影響分析は再現率 98% 以上。失敗を設計文書に書き、それを验收条項に変えること——これがこのエンジンで最も「研究」的な部分です。
FAQ
コードグラフの動作に Git は必要ですか？
いいえ。コードグラフはファイルシステムをインデックスし、Git 履歴ではありません。Git は任意のソース管理です。グラフが参照するのはソースコードの現在の状態であり、コミット履歴ではありません。
Python/Rust/Go に対応していますか？
現在は TypeScript/JavaScript です。他の言語は Agent の汎用検索とユーザーのガイダンスにフォールバックします。TypeScript プロジェクトにフロントエンドとバックエンドの両方がある場合、グラフはその両方をカバーします。将来的な他言語への対応拡張は現在検討中です。
グラフに直接クエリできますか？
Agent が Tool Gateway を通じてクエリします。ユーザー向けのグラフ可視化やクエリインターフェースはありません。グラフの操作はすべて Agent を仲介して行われます。直接的なグラフクエリ言語を提供することは、セキュリティ上の理由からも設計上の理由からも現時点では想定していません。
インデックスはローカルに保存されますか？
はい。グラフインデックスは会話やナレッジと同じローカル SQLite データベースに保存されます。インデックスデータが外部に送信されることはありません。
どのくらいのサイズのプロジェクトに対応していますか？
数千ファイル規模のプロジェクトで動作します。ただし、非常に大規模なモノリポジトリでは初回インデックスの構築に時間がかかる場合があります。インデックスは増分更新にも対応しており、変更されたファイルだけを再解析します。初回構築以降は、ファイルの変更を検知して自動的にインデックスが更新されます。
モノレポに対応していますか？
はい。ワークスペース内のすべてのパッケージを横断的にインデックスします。パッケージ間の依存関係もグラフに含まれるため、あるパッケージの変更が別のパッケージにどう影響するかを追跡できます。ワークスペースルートから再帰的に解析され、各パッケージの構造が統一的なグラフとして表現されます。