AIコーディングエージェントが本番コードで失敗する本当の原因はモデルではなく「組織の文脈への接続不足」

8月26日、Postmanが「Why AI coding agents need context graphs」と題した記事を公開した。AIコーディングエージェントが実際のコードベースで壊れたコードを生成する場面を目撃したことがあるエンジニアは多いはずだ。先月廃止されたエンドポイントを呼ぶコード、別のチームがすでに構築済みのサービスを重複実装するコード、CIのコントラクトチェックで即座に落ちる変更——これらは「モデルの能力不足」ではなく、コンテキストの欠如が原因だと記事は指摘する。その解決策として提示されるのが、エージェントの外部に構築する「コンテキストグラフ」だ。

エージェントが失敗する本当の理由は「モデル」ではない

エージェントは目の前のファイルを読み、関数名をgrepし、レスポンスボディの形を推測する。だが、チームの人間が数ヶ月・数年かけて頭の中に静かに構築してきた「組織の文脈のグラフ」には手が届かない。

最初に試みられる解決策は「コンテキストウィンドウの拡大」だ。しかしこれは効かない。Chromaの2025年のcontext rot研究では18のフロンティアモデルを検証し、すべてのモデルがウィンドウが埋まる前に性能劣化することを確認した。Stanfordの"Lost in the Middle"論文では、長いプロンプトの中間に置かれた情報の精度が30%以上低下することを示している。トークンを増やすことは、適切な検索の代替にはならない。

コンテキストグラフとは何か

記事が提示する解決策は、コンテキストグラフをエージェントの外部に構築し、クエリ可能にすることだ。

コンテキストグラフの構造は「型付きエンティティ」と「型付きリレーションシップ」の集合体だ。Service X が Endpoint Y を公開し、Endpoint Y は Team Z が所有し、Team Z は Auth Scheme A を使う——こうした3要素の事実の連鎖がグラフを形成する。

実際のコードベースでエージェントが必要とするエンティティは以下のようなものだ：

リポジトリ、パッケージ、モジュール、関数
サービス、エンドポイント、OpenAPI仕様
チームとコードオーナーシップ
環境、デプロイ、ランタイム依存関係、フィーチャーフラグ
ガバナンスルール、廃止フラグ、承認ステータス
インシデント履歴とポストモーテム

エンドポイントのエンティティはたとえば以下のような形を取る：

{
  "id": "svc.payments.charges",
  "type": "service.endpoint",
  "method": "POST",
  "path": "/v2/charges",
  "spec_ref": "specs/payments/openapi.yaml#/paths/~1v2~1charges",
  "owner_team": "team.payments-core",
  "status": "active",
  "deprecates": "svc.payments.charges.v1",
  "auth": "oauth2:payments.write",
  "consumers": ["svc.checkout", "svc.subscriptions"],
  "last_incident": "INC-4821"
}

このレコードがあれば、エージェントは「同じ機能を持つエンドポイントはすでに存在するか」「変更の承認者は誰か」「レスポンスの形が変わると何が壊れるか」「このPRを誰に向けるべきか」を答えられる。これが、変更がマージされるか「Actually…」から始まるコメントで差し戻されるかの分岐点だ。

APIレイヤーはすでにグラフである

記事が面白い点を指摘している。すでにAPIを扱っているチームは、知らずしてグラフの部品を構築してきたという事実だ。

OpenAPI仕様は型付きエンティティ（パス、オペレーション、スキーマ）と型付きリレーションシップ（参照、セキュリティスキーム、タグ）の集合体だ。これにオーナーシップ、承認状態、ガバナンスポリシーを加えれば、エージェントがクエリできるグラフになる。

Postmanはこれを「インフラとして」扱う設計になっている。Private API Networkは組織が公開したいAPIを人間とエージェントが発見できる場所だ。Postman API GovernanceはAPIにルールを付与し、エージェントがPRを開く前にポリシー違反を検知できるようにする。Postman APIはそのグラフをプログラム的に走査できるよう公開されている。

さらにグラフは自社APIで止まらない。Stripe、Okta、Twilio、Salesforceといったサードパーティサービスとのインテグレーションも同様の失敗を引き起こす。エージェントが「アプリがv2エンドポイントを使っていてv1は廃止済み」という事実を知らなければ、誤ったバージョンのコードを生成し、その問題はレート制限や請求が発生するまで表面化しない。

エージェントがコードを1行も書く前に実行できるクエリの例として、記事は以下を示している：

curl -H "X-Api-Key: $POSTMAN_API_KEY" \
  "https://api.getpostman.com/apis?workspace=$WORKSPACE_ID" \
  | jq '.apis[] | {name, id, summary}'

これはワークスペースに公開されているAPIの一覧を返す。ファイル名でも文字列マッチでもなく、組織がすでに合意した契約のセットだ。

grepではなくグラフをクエリする

エージェントにモノリポをgrepさせる問題は、grepが「一致する文字列」を返すが「意味」を返さない点にある。ここで記事が解決策として挙げるのがModel Context Protocol（MCP）だ。MCPはAIエージェントにツールやデータソースをクエリ可能な形で公開するためのオープンプロトコルである。Postman MCP ServerはPostmanのグラフをMCPツールとして公開し、IDEで動作するエージェントがAPIの検索、コレクションの確認、ガバナンスルールのチェックを直接実行できるようにする。

グラフ検索がベクトル検索を補完することを示す研究として、記事はMicrosoft GraphRAGと、LLMがリポジトリのグラフデータベースをクエリすることで検索単体より優れた結果を示したCodexGraph（NAACL 2025）を挙げている。また、Googleが最近公開したAgentic Resource Discovery仕様も、インターネットスケールで同じパターンを適用しようとする動きだ。

運用上の注意点

記事が実際の運用で遭遇した注意点も整理されている：

グラフはすぐ陳腐化する。チームの組織変更でオーナーシップを更新しなければ、エージェントは誤った担当者に通知する。グラフの更新はコード変更のレビューワークフローに組み込むべきだ
強制力のないガバナンスは無いより悪い。廃止エンドポイントの情報があっても、エージェントがそれを参照しないまま実装すれば意味がない。CIでの強制が必要になる
エンティティ数の爆発に注意。8人チームで20サービスならモデルは容易だが、500サービス・40チーム・10年の歴史がある組織では重複や類似エンティティが複雑に絡み合う。まずは公開API、稼働中サービス、現オーナーから始めるべきだ
発見はループの半分に過ぎない。エンドポイントを見つけられても実際にテストできなければ意味がない。コレクションと環境を仕様と並べて公開することが、グラフを「実行可能なもの」に変える

今週から始める3ステップ

6ヶ月のプラットフォームプログラムを待たずに動ける具体的なステップとして、記事は以下を示している：

組織のAPIを実際のオーナーシップメタデータ付きでPrivate API Networkに公開する（部分的でもSlackスレッドよりはるかにマシ）
廃止フラグと必須認証のAPI Governanceルールを最低限有効にする
使用中のエージェント（Claude Code、Copilot系、社内ツールなど）をPostman MCP Serverに接続し、grepの代わりにグラフをクエリさせる

記事が示すポイントは明確だ。問題はモデルの能力ではなく知識の置き場所にある。エージェントにとって足りないのは推論能力ではなく、組織がすでに持っているはずの構造化された文脈への接続経路だ。

詳細はWhy AI coding agents need context graphsを参照していただきたい。