Cursorで複数ファイルを直すとき、なぜ呼び出し元の半分を落とすのか？

Cursor や Claude Code で複数ファイルにまたがる修正（インターフェース変更、関数リネーム、モジュール抽出——十数から数百ファイルに及ぶことも）を試した経験があれば、呼び出し元の更新漏れ、誤ったファイルの修正、共有モジュールの巻き込みに何度も直面しているはずです。モデルは断片は読めても、システム全体は読めていない。2026 年時点で Agent はテスト実行や PR 作成まで自動化できますが、チームが大きく、リポジトリが古いほど、この失敗パターンは変わりません。根因はしばしば「モデルが足りない」のではなく、クエリ可能で増分更新でき、共有可能なコード知識グラフ（Code Knowledge Graph）がないことにあります。本稿ではその正体、ベクトル RAG や超長コンテキストだけでは足りない理由、そして Agent 向けの構造化「リポジトリ記憶」をどう作るかを整理します。

Agent の盲点：コンテキストウィンドウは「地図」ではない

現代の AI コーディング Agent の典型フローは、ユーザー質問 → 関連ファイル検索 → コンテキスト投入 → diff 生成です。検索手段には @ ファイル、ripgrep、embedding 類似度、製品内 codebase index などがあります。これらは「どのテキストが答えに似ているか」には強い一方、「ここを直すと誰に波及するか」では体系的に失敗します。理由は次のとおりです。

• テキスト chunk にトポロジがない：分割で呼び出しチェーンが壊れる。コメントが似た 2 関数が一緒に引かれても、本当の呼び出し関係は別 chunk にいる。
• grep は文字列だけで型がない：オーバーロード、ジェネリクス、マクロ生成、Swift extension により「同名 ≠ 同一シンボル」。
• コンテキスト予算はゼロサム：200 ファイルを詰めても、経路上のハブ 5 ファイルがどれかは分からない。
• セッションはステートレス：前回のリファクタで切ったモジュール境界を、次の会話でまた推測し直す。

シニアエンジニアが頼るのは全コードの暗記ではなく、階層化された地図——モジュール境界、依存の向き、テストの所在です。コード知識グラフは、その地図を外部化し、機械可読かつバージョン管理可能にします。

コード知識グラフとは

狭義には、ソフトウェア工学向けの属性グラフ（Property Graph）または異種グラフです。ノードがコード実体、辺が検証可能な関係を表します。一般の「知識グラフ」と違い、辺の多くは静的解析やビルドログから決定論的に導出でき、LLM の幻覚に頼りません。

価値はノード数ではなく、多ホップ推論の再現性にあります。「ユーザークリックから DB への SQL まで」が毎回推測ではなく、固定パスとして辿れることです。

ベクトル RAG との比較：意味的類似 ≠ 構造的関連

ベクトル検索はコードを自然言語段落として扱い、「支払処理っぽいロジック」を探すのに向きます。次のタスクは本質的にグラフ走査です。

• 廃止 flag 削除前に、if (featureX) の実参照（マクロ・生成コード含む）を列挙する。
• sync から async へ API を変える際、全リポジトリの呼び出しスタックとテストダブルを出す。
• God class を分割し、凝集サブグラフと外部への扇出しを特定する。

実務ではハイブリッド検索が定石です。意図分類後、構造型はグラフツール、探索型はベクトルへ。結果は「グラフ経路上のノード優先」で並べ、コンテキストに切り詰めます。embedding だけを積み、辺を作らない Agent は、ファイル数と依存が増えた monorepo で PR マージ率が頭打ちになりがちです。

LSP / IDE インデックスとの比較：セッション内 vs 組織全体

Language Server はジャンプ、参照、リネームを提供し、グラフノードと大きく重なります。違いはライフサイクルと利用者です。

• LSP は今開いているワークスペースに紐づき、CI やリモート Runner 上の Agent には同じ LSP がないことが多い。
• API リネームは対話的。Agent にはバッチでスクリプト化可能な get_callers(symbol_id) が必要。
• グラフには業務メタデータ（owner、deprecated 日、コンプライアンスタグ）を載せられる——LSP はここをモデルしない。
• ブランチ比較（main vs feature）はグラフ上で2 つの部分グラフ diffとして扱える。

現実的な路線は、LSP / コンパイラフロントを事実源に、グラフを永続化と Agent プロトコル層にすることです。車輪の再発明は避けましょう。

推奨アーキテクチャ：3 層記憶、中央にグラフ

Agent の「リポジトリ理解」を 3 層に分けると混乱が減ります。

構造層（コード知識グラフ）

答える問い：コードは何で、どう接続されているか。 静的解析、Bazel/Gradle/Xcode プロジェクトグラフ、OpenAPI/Proto から生成。更新トリガー：merge、定期フル、ファイル watch。保存：グラフ DB または隣接インデックス付き SQLite。外部公開：MCP tools。

意味層（ベクトルインデックス）

答える問い：どの実装がユーザー説明に「似ている」か。 関数本体、コメント、ADR、Issue を embedding。グラフと同一 symbol_id を共有し、「chunk は見つかったがシンボルが特定できない」を防ぐ。

エピソード層（タスク・設計記憶）

答える問い：前回なぜそう直したか。 PR 要約、Runbook、または OpenHuman 系 Memory OS の Topic ノード。グラフの代替ではなく、「議論済み」「廃止」などの重み付けを辺に載せる。

グラフが直接改善する 5 類の Agent タスク

1. 複数ファイルリファクタ：リネーム、インターフェース抽出、パッケージ移行——呼び出し辺に沿って一括更新し、漏れファイルを減らす。
2. 欠陥定位：スタックトップから calls 辺を辿り共有中間層を探す。エラー文字列の全文検索より確度が高い。
3. 新メンバー onboarding：「決済モジュールの入口」= UI route から service への部分グラフ。README より速い。
4. テスト選択：変更ノードの covers 辺から最小テストセットを選び CI を短縮——TestFlight 検証パイプライン と同機編成も可能。
5. セキュリティ・コンプライアンス：機密 API の reachable_from クエリは正規表現より正確。

構築の要点：増分、失敗許容、言語認識

最小構成パイプライン（冒頭 HowTo schema と一致）：

• 解析：tree-sitter（多言語）、SourceKit（Swift）、rust-analyzer などで AST シンボル表を出力。
• 辺構築：呼び出しは保守的近似（見逃しより誤検知を避ける）。継承・実装は厳密に。
• 増分：ファイル単位 hash。変更ファイルの上下 2 ホップ近傍を局所無効化。
• バージョン：グラフに commit_sha。Agent ツール引数でも必須にし、ブランチ混在を防ぐ。
• ツール面：6～10 個の高レベル API（get_callers、get_module_graph など）。ad-hoc Cypher はモデルに書かせない。

{
  "symbol": "PaymentService.charge",
  "callers": [
    {"id": "CheckoutViewModel.submit", "file": "ios/Checkout/VM.swift", "line": 88},
    {"id": "SubscriptionRenewalJob.run", "file": "jobs/renewal.ts", "line": 41}
  ],
  "graph_version": "a3f9c2e"
}

Apple / iOS 大規模コードベースの特殊性

Swift、Objective-C、SPM、Xcode project の組み合わせでは「純テキスト RAG」が特に不利です。extension、条件付きコンパイル、@objc ブリッジにより、静的には見えず実行時に現れる辺が生まれます。グラフ構築では次を意識します。

• Xcode と同型の macOS 環境で解析（ローカル Mac または Mac mini M4 クラウドホスト）。Linux CI で黙ってスキップされる失敗を避ける。
• .xcodeproj / SPM target 依存をModule 級の辺にし、そこからシンボル級へ下る。
• Flutter iOS 混合リポ では Dart ↔ Platform Channel のクロス言語辺（手動注釈 + 生成コードスキャン）。

インデックスは CPU/ディスクを食い、時間もかかります。専用 Cloud Mac で 7×24 増分実行し、ローカル Cursor は SSH/MCP でリモートグラフ API を消費——ノート PC は軽量クライアントに徹する。Mac VPS vs Cloud Mac で述べた「算力とディスクの分離」と同じ結論です。グラフサービスを超売り VPS と I/O 競合させない。

OpenClaw、agentmemory との役割分担

OpenClaw などのマルチチャネル Agent は、定期タスク、Webhook、外部ツール連携のオーケストレーションが得意です。コード知識グラフはその中の「リポジトリを読む」系の構造化バックエンド。OpenHuman の Memory Tree のような個人記憶は決定や会話の文脈を残すもので、呼び出しグラフの代わりにはなりません。

推奨統合：OpenClaw / Cursor MCP に code_graph_* ツールを登録。Memory OS には「今回のリファクタでチーム X に通知済み」などのメタデータだけを置き、検索時にグラフバージョンを監査ログへ書く。

よくある落とし穴とアンチパターン

• LLM に呼び出し関係を「推測」させる：回帰テスト不能。merge 後にグラフが腐る。
• グラフとソースの非同期：グラフがないより危険——Agent が自信満々に誤ファイルを直す。
• ファイル級ノードだけ：@folder と大差なく、rename/refactor を支えられない。
• グラフ全文を prompt に dump：ツール呼び出し + 多ホップ剪定が正しい。
• 生成コードと lockfile を無視：Protobuf、GraphQL codegen、Swift macro はビルドフックに含める。

FAQ

ベクトル RAG と二択？ いいえ。グラフが構造、ベクトルが意味。同一 symbol_id でつなぐ。

LSP だけで足りる？ 個人・単セッションなら近いが、組織 Agent には LSP 出力をグラフに永続化する。

小規模でも要る？ 「呼び出し元を毎回漏らす」信号が出たら。コストはマネージド索引で分散可能。

更新頻度は？ main merge ごとに増分。長タスク前に graph_version を検証。

製品内 index があるのに自前？ CI 連携、監査、ツール横断の単一真実源が必要なら yes。

クラウド Mac の用途は？ 永続グラフ DB、Swift/ObjC 解析、Xcode 同機、SSH でローカル IDE から消費。

セキュリティは？ モジュール構成とシンボル名を含む。権限はソースと同級。パブリック LLM ログへ出さない。

Memory OS との関係は？ グラフ = 構造的事実。記憶 = 決定と嗜好。インターフェースで合成。

結論

AI コーディング Agent の上限は、いますますリポジトリ構造の理解で決まり、単発 prompt の巧拙では決まりません。コード知識グラフは呼び出しチェーン、モジュール境界、テストマッピングを、クエリ可能・バージョン管理可能・監査可能なデータとして外部化し、ベクトル検索や個人 Memory OS と 3 層で補完し合います。2026 年も「より大きなコンテキスト + ファイル検索」だけに頼るチームは、複数ファイル変更が多い monorepo と Apple ツールチェーンで漏改コストを繰り返し払うでしょう。macOS 解析と永続ディスクという正しい環境に索引を置くこと——それが Agent を「コードが書ける」から「システムを直せる」へ進める最小の工程投資です。