なぜすべてのAIコーディングAgentにコード知識グラフが必要なのか

2026 年、ターミナルの Claude Code も、エディタ内の Cursor も、ファイル読取・テスト実行・数十パスの一括編集が当たり前になりました。それでもリリースを遅らせるのは「コードが書けない」より影響範囲の取りこぼしです。Swift プロトコルのリネームで Conformance を 1 箇所忘れる、公開 API 変更でモックが追従しない、Pod モジュール再構成で別 Target だけ CI が赤くなる——受託開発や社内アプリチームで毎週起きるパターンです。

コンテキストを伸ばし、モデルを強くし、@ ファイルを増やしても症状は緩和に留まります。コード知識グラフ（Code Knowledge Graph）こそが、リポジトリ理解を確率的検索から照会可能な構造へ寄せる層です。本記事では定義、Agent ワークフローでの位置づけ、クラウド Mac 上の CI との揃え方を、エンジニアリング視点で整理します。

コード知識グラフとは

マーケ用語ではなく、コード実体と関係を明示したグラフです。

• ノード— ファイル、ディレクトリ、モジュール（Package / Pod / Gradle module）、シンボル（クラス、struct、関数、extension）、テストケース、CI Job、Xcode Target など。
• 辺— imports、calls、inherits、implements、tests、owns、builds（Scheme がどの Target をビルドするか）。

ベクトル DB は「探しているものっぽい断片」を返します。グラフは「シンボル A から出発し、呼び出し／モジュール境界を辿れば必ず通るノード」を返します。リファクタ、セキュリティ修正、破壊的 API 変更では後者がレビュアの頭の中図と一致します。

RAG と巨大コンテキストだけではなぜ漏れるか

多くの Agent のコードベース索引はチャンク化＋埋め込み検索＋プロンプト投入です。新規ユーティリティやコメント駆動テスト生成には有効ですが、次の場面では構造的に弱いです。

日本の現場では英語コード＋日本語仕様書が混在することも多く、意味検索は依然重要です。ただし「誰が誰を import しているか」はベクトルでは代替できません。グラフが構造、ベクトルが意味——候補をグラフで絞り、埋め込みで表記ゆれを吸収するのが実務的なハイブリッドです。

Agent ループのどこにグラフを置くか

監査可能なループは 計画 → 検索 → 編集 → 検証。グラフは主に計画・検索と、検証時のスコープ確定を強化します。

（1）計画。「PaymentService を async/await に」と言われたら、まずグラフで引用辺と所属モジュールを引き、影響ファイル一覧を出してからサブタスク化——src/ 丸ごと読みは避けます。

（2）検索。「読むべきファイル」を確率イベントからグラフ走査結果へ。CLAUDE.md、.cursorrules のモジュール説明と重ね、幻覚パスを減らします。

（3）検証。編集後、旧シンボルへの辺が残っていないか確認。CI でグラフ diff と git diff を突き合わせ、Agent の取りこぼしをログに残します。SIer の品質記録や顧客監査でも説明しやすくなります。

グラフの構築：パーサ、増分、コンパイラとの一致

• LSP— IDE と同源でシンボル精度が高い。Swift、TypeScript、Go は特に成熟。
• SCIP／lsif— 大規模 monorepo と CI 向き。索引成果物を commit に紐づけやすい。
• tree-sitter— 軽量で Agent サンドボックスに載せやすい。動的言語の呼び出しはヒューリスティック追加が必要。
• コンパイラ／Xcode Build Graph— Target 依存とリンク関係を実ビルドと揃える iOS チーム向け。

原則は一つ：グラフのバージョンは Agent が編集する commit と一致させる。MacBook で索引が半端なまま蓋をすると、古いグラフで計画します。全量／増分索引を クラウド Mac CI の固定 Runner に載せれば、グラフ・ビルド・テストが同一 macOS 上の事実を共有できます。Xcode、CocoaPods、コード署名を含むリポジトリで効果が大きいです。

iOS／macOS リポジトリで増やすべきノード

• Target／Scheme— App Extension 変更時に Host App との依存を可視化。
• SPM／CocoaPods 境界— ソース Pod とバイナリ Pod を辺の種類で区別。
• @objc／動的ディスパッチ— 静的グラフにない呼び出しは「実行時バインドの可能性」として注記し UI テストを促す。
• Generated— SwiftGen、Protobuf 出力を generated として手編集禁止を Agent に伝える。

Mac mini vs クラウド Mac の論点と同型です。ボトルネックはしばしばマシンスペックではなく、ビルド図とコード図の不一致。App Store 提出前に Runner とグラフを先に揃える方が、モデル選びよりリリース日に効くことがあります。

オーケストレーション、OpenClaw、IM 起動

Slack や Telegram から Agent を起動する（OpenClaw 等のゲートウェイ経由）と、会話コンテキストはさらに断片化します。グラフはセッション外の長期記憶として機能し、前回 PR で触ったモジュールやテスト空白をクエリで新セッションに注入——チャット全文をウィンドウに押し込む必要が減ります。

オーケストレータは「いつ索引するか、いつテストするか」、グラフは「どこを直すか」を担当。リポジトリ・コマンド・終了コード・ログ要約の四元組とグラフ diff を一緒に保管すれば、後から「Agent がなぜそのファイルを触らなかったか」を追えます。

コスト、信頼、権限

全量索引は CPU・ディスクを食い、巨大 monorepo では数十分かかることもあります。増分（変更ファイルと近傍のみ）と キャッシュ（commit SHA 単位のスナップショット）が現実解です。クラウド Mac では長期ブランチごとに索引キャッシュを置き、Agent 起動時に同じスナップショットをマウントできます。

辺はパーサと commit にトレース可能であるべきで、Agent が依存を捏造しないようにします。機密リポジトリではグラフエクスポートから鍵パスや顧客データディレクトリを除外。コードを国外 SaaS に出せない契約では、自管 Runner 上のグラフが前提になります。

最小導入（今週から）

1. 単一 Swift Package など小さなサブツリーで LSP または SCIP からシンボルと引用をエクスポート。
2. CLAUDE.md に「public API 変更前に引用一覧を必ずクエリ」と明記（シェルでグラフ API を包む）。
3. GitHub Actions 自ホステッド Runner（クラウド Mac 固定推奨）で PR 時に増分索引＋テスト。失敗時は未カバーの引用辺をログ出力。

# シンボルから引用辺を走査（意味検索ではない）
refs = graph.out_edges(symbol="PaymentService.charge", type="references")
files = unique([r.source_file for r in refs])
# files を Agent 計画に注入してから claude / cursor agent を呼ぶ

結論：Agent の記憶には「地図」が要る

モデルは強くなりますが、ソフトウェア構造はプレーンテキストにはなりません。モジュール・呼び出し・ビルド図がある限り、AIコーディング Agent は「一箇所直すと全身が動く」問題にコード知識グラフで答える必要があります。ベクトルは連想記憶、グラフは解剖図。再現可能な macOS CI 上にグラフを置き、Claude Code・Cursor・OpenClaw が消費する——2026 年に Agent をデモから本番へ運ぶチームが、製品ページにあまり書かないが実際にやっていることです。

• ツール比較— Claude Code vs Cursor
• CI— OpenClaw とクラウド Mac
• コンピュート— Mac mini クラウド
• 関連— Windows からの Xcode ワークフロー、OpenHuman vs OpenClaw