The Engineering of Intent 第37章:コンテキストスケーリング──100万行のコードベースのためのジャストインタイム検索

本記事は、私の著書The Engineering of Intent(英語版)を1章ずつ読み解くシリーズの第37回です。前回の記事では、長期的な視点を取り上げました。第37章からは、本書の上級トピックのセクションが始まります──中核となる実践を、より難しい領域へと広げる4つの章です。最初のテーマは、コードベースが大きすぎて人の手ではキュレーションしきれなくなったときのコンテキストパックです。


手書きのコンテキストパックはスケールしない

第9章「アドバンスト・コンテキストエンジニアリング」と第23章「コンテキストパックのレシピ」は、扱いきれる規模のコードベースを前提にしていました。500万行、30チーム、700サービスとなると、その前提は崩れます。3つの限界が同時にやってきます。

  • 広さ。 チェックアウトのバグは、価格設定、税、在庫、フルフィルメントにまで及ぶかもしれません。ありうるすべてのチケットについて、どのファイルが重要かを列挙できるAGENTS.mdなど存在しません。
  • ドリフト。 マージのたびにファイルは動きます。半年前には完璧だったパックが、今日は微妙に間違っていて、来年には壊滅的に間違っています。人の手によるメンテナンスでは追いつきません。
  • 特異性。 「チェックアウトのnullポインタを直して」と「チェックアウトに割引コードを追加して」では、必要なコンテキストが違います。単一のパックでは、どちらにもうまく応えられません。

解決策は、パックを手で書くのをやめることです。代わりに、クエリで取得するようにしてください。


ジャストインタイム・コンテキストのパターン

ジャストインタイム・コンテキスト(JIT Context)とは、エージェントが見るものを事前に指定する代わりに、タスクの実行時に動いて最も関連性の高いサブセットを取得する検索関数を指定するやり方です。4つのステップからなります。

  1. エージェントに、タスクと、小さく永続的なコアパック(10K〜20Kトークン:AGENTS.md、規約、トップレベルのアーキテクチャ)を与える。
  2. エージェント(または検索用のサイドカー)が、コードベースのベクトルインデックスに対してクエリを発行し、最も関連性の高いファイルやスニペットを10〜50件取得する。
  3. 取得した資料を、このタスクに限ってコンテキストに追加する。
  4. タスクが完了したら、取得したコンテキストは破棄する。次のタスクは、自分のコンテキストを自分で取得する。
💡 鍵となる規律: ステップ3──このタスクに限って追加すること。タスクをまたいで残り続けるコンテキストはドリフトします。タスクごとに作り直されるコンテキストは新鮮なままです。これは、エージェントが「時間とともにより多くを知る」ように、その「記憶」に物を足し続けたくなる素朴な直感とは正反対です。記憶には古さが積もっていきます。検索は常に最新を保ちます。

配信メカニズムとしてのMCP

検索レイヤーは、3〜4個のツールを公開するMCPサーバーの背後に置きます。セマンティック検索、あるパスに関連するファイルの検索、チームごとのファイル検索、ディレクトリ内の最近の変更の検索です。エージェントはタスクの途中でこれらを呼び出し、そのレスポンスがその場でコンテキストに注入されます。

独自のつなぎ込みではなくMCPでこれを行う利点は2つあります。ひとつは、何を取得するかをエージェントが決めること(計画をタスクの本当の形に合わせられます。その形はチケットごとに違います)。もうひとつは、検索サーバーがエージェント、フレームワーク、IDEをまたいで共有されることです。共有された検索は、共有された真実です。ばらばらの検索は、ばらばらの現実です。

「検索用のMCPサーバーは、1つのチームが所有します。プロダクトチームはそれを利用します。各チームに独自のものを作らせてはいけません──ランキングが微妙に異なる7つの検索システムができあがり、チームをまたぐコンテキストの問題をデバッグすることが不可能になります。」


必要になる3つのガバナー

JITコンテキストには、静的なパックにはない失敗モードがあります。検索の暴走です。検索ツールを持ったエージェントは、調整しないままにしておくと、もっともらしいけれどほとんど役に立たない資料でコンテキストが埋まるまで検索し続けます。そこで、3つのガバナーを設けます。

  1. タスクごとのトークン予算のハードリミット(クエリの数にかかわらず約60K)。選別を強制し、「すべてを取得して、何も読まない」状態を防ぎます。
  2. 関連性のしきい値。 注入する前に、類似度スコアが約0.7未満のものを捨てます。ラベル付きの評価セットを使って調整します。
  3. 可観測性。 すべてのクエリ、取得したすべてのファイル、すべてのタスクの結果をログに残します。毎月、結果に照らして検索を改善します。結果に照らして調整されない検索システムは、四半期もしないうちに凡庸へと流れていきます。

具体的なパイプライン(380万行のコードベースから)

  • mainへのマージのたびに、ワーカーが変更されたファイルを1536次元のモデルで埋め込みます。全体の再埋め込みは毎週。HNSW付きのpgvectorに保存します。コストは週20ドル未満です。
  • タスク開始時、エージェントは14Kトークンのコアパックを受け取り、続いて3つのクエリでMCPサーバーを呼び出します。セマンティック検索、git blameでの近さ、シンボル名の抽出です。
  • サーバーは、リランキングした候補を最大30件返します。エージェントはそこから8〜12件を選び、「主要」「関連」「可能性あり」のラベルを付けます。コンテキストの合計は通常40K〜60Kです。
  • 取得したコンテキストでタスクを完了できない場合、エージェントは最初のファイルを読んだあとで再クエリします。たいていはそれで成功します。
  • タスクの結果をログに記録します。毎月、取得したファイルのうち実際にエージェントの出力で参照されたものを見直します。使われなかったものは、ランクを下げる候補。参照されたのに取得されなかったものは、新しい検索戦略の候補です。
⚠ JITコンテキストが過剰になるとき: 5万行のコードベースのために検索インフラを作ってはいけません。3〜4個のAGENTS.mdファイルと第23章「コンテキストパックのレシピ」のレシピがあれば、運用コストゼロでもっとうまくいきます。JITコンテキストが割に合うようになるおおよそのしきい値は、アクティブなコードが約50万行、アクティブなエンジニアが約15人、またはサービスが20以上です。50万行から200万行までの過渡期は、チームが「賢いgrep」でなんとかしのごうとしがちな段階です──しばらくは驚くほどうまくいきますが、ある日突然うまくいかなくなります。たいていはインシデントの最中に。

次回 ── 第38章「マルチエージェント・コンフリクト解決──エージェント同士の対立を裁くプロトコル」 複数のエージェントが同じコードベースで協働するようになると、問いは「彼らは一緒に働けるか」から「どうやって決着をつけるか」に変わります。第38章では、エージェント同士の対立に決着をつけるためのプロトコルを見ていきます。


📖 さらに詳しく知りたい方へ

本章では、インデックス/クエリ/昇格のパイプラインの全体像、MCPサーバーの設計、調整のガイダンス付きの3つのガバナー、数値を交えた380万行のコードベースでの具体的なパイプライン、そして規模のしきい値を判断するためのチャートを解説しています。

The Engineering of Intent をAmazonで購入する →(英語版)

2026-05-23

下田 昌平

開発に関するインプットをアウトプットしています。