エージェント型コンテキストエンジニアリングの実践ガイド

The practical guide to agentic context engineeringの意訳です。

コンテキストエンジニアリングは、AIコードレビューエージェントがバグを見つけるか、そのままリリースしてしまうかを決めます。コンテキストエンジニアリングとは、モデルが回答する前に参照するコード、チケット、規約、過去の意思決定を選ぶことです。エージェント型ワークフローを運用するチームに例えて言えば、レビュー品質は、シニアエンジニアが気づくことをエージェントも見られるかどうかに左右されるということです。

エージェント型コンテキストエンジニアリングとは、単一のプロンプトではなく、自律的なエージェントのためにその情報を組み立てる実践です。レビューのワークフローでは、より良い指示を書くことから、適切な入力を組み立てることへ作業の中心が移ります。Philipp Schmidが述べたように、「エージェントの失敗はモデルだけの失敗ではなく、コンテキストの失敗でもあります」。そのため、AIレビュアーが競合状態を見落としたり、誤検知を出したりしたときは、モデルを責める前に、そのレビュアーが受け取ったコンテキストを確認してください。

良いレビューには差分以上のコンテキストが必要です

差分（diff）だけを見てレビューするAIエージェントは、人間のレビュアーが持っている情報の一部しか見ていません。差分は何が変わったかを示します。しかし、なぜ変わったのか、そのコードが他に何へ触れるのか、どの制約が適用されるのか、チームの規約が何を求めているのかは示しません。縫合跡だけを見て手術を評価するようなものです。

SWE-PRBenchベンチマーク研究によれば、現在の最良モデルでさえ、人間のレビュアーが見つける問題の多くをまだ見落としています。

人間のようにレビューするには、エージェントに差分には含まれない4つの入力が必要です。

• コードの構造は差分には現れません。 関数境界や制御フローは、コードを解析した構造である抽象構文木（AST）に存在します。Ericssonの経験レポートでは、変更行を含むメソッドを取り出し、構造としてレビュアーへ渡す手法が説明されています。
• コールグラフは、その変更に何が依存しているかをエージェントに伝えます。 差分は関数が変更されたことを示しますが、コードベース全体のすべての呼び出し元を示すわけではありません。
• チームの規約はモデルの学習データには含まれていません。 Chalmers Universityの研究では、LLMが変更ファイルの外にあるアーキテクチャを見られない場合、提案は不正確になり、本当の設計上の問題がすり抜けると指摘しています。CodeRabbitのState of AIレポートのデータセットでは、AIによるPRで可読性の問題が3.15倍多く見られました。これは、レビュアーがチームの規約を知らないときに起きることです。
• チケットには、コードを評価する基準となる意図が含まれています。 O'Reillyの分析は、要件がなければ、AIレビュアーはコードがうまく作られているかは判断できても、本来すべきことをしているかは判断できないと述べています。

Common Appでは、.NET Core、Node.js、Angular、Pythonを横断して作業する20人の開発チームが、コードレビュー時間を35%削減し、以前のチェックでは見逃していた競合状態を発見しました。レビュアーがより広いコードベースを見られるようになると、一見きれいな変更の裏に隠れていた微妙なバグが見つかるようになります。

コンテキスト崩壊は静かな本番障害モードです

エージェントが重要な詳細を圧縮して失うと、エッジケースを見つけられなくなります。そして、その欠陥が本番環境に届くまで、あなたはそれに気づきません。

ACE論文（Agentic Context Engineeringの略）は、コンテキストが失われる1つの形を説明し、それを簡潔性バイアスと呼んでいます。これは、処理が指示を短く汎用的なものへと縮め続ける現象です。同論文では、こうした手法が「メソッドが期待どおりに動作することを保証するユニットテストを作成する」のような、ほぼ同じ指示を大量に生成し、ドメイン固有の詳細を落としてしまうことを示しています。LLMは短いプロンプトではなく、長く詳細なコンテキストで最もよく機能します。

コンテキスト崩壊は、エージェントの実行中に起きます。システムが各ターンでコンテキスト全体を書き換え、追記しない場合、書き換えるたびに前回より短く曖昧になり、以前のターンにあった詳細が消えていきます。

Microsoft ResearchとSalesforceの研究が示したように、コンテキストを多くのターンに分散させると精度が低下します。より大きなモデルを使っても解決しません。会話が積み上がるにつれて、モデルは話の本筋を見失います。

同じデータセットでは、エラー処理と例外処理の問題がAIによるPRで約2倍多いことも示されています。これは、薄いコンテキストが見落としやすいエッジケースそのものです。

ACEフレームワークは、コンテキストを上書きするのではなく追加し、新しい変更をすべて記録します。すべてを再要約しないことで、要約によって削ぎ落とされる詳細を保ちます。

CodeRabbitのLearningsも同じ原則で機能します。エンジニアがレビューコメントを修正すると、それはエージェントが将来のレビューへ持ち越す学習になります。

生成と検証には異なるコンテキストが必要です

生成エージェントと検証エージェントには、それぞれの仕事に合わせて整理されたコンテキストが必要です。エージェント型コンテキストエンジニアリングとは、1つのコンテキストを両方に使い回すのではなく、それぞれを意図的に構築することです。両者を交換可能なものとして扱うと、チームは適切に検証されていない出力を信頼することになります。

Martin Fowlerのドキュメントは重要な点を指摘しています。エージェントは、コンテキストが多すぎると効果が下がります。生成用のコンテキストは、意図、仕様、制約に絞って軽く保つべきです。検証用のコンテキストには、元の意図、生成されたコード、周辺のコードベースが必要です。

コードベースのコンテキストが多すぎると、生成に悪影響を与えることがあります。エージェントが仕様の求めるものを作る代わりに、既存パターンをコピーしてしまうからです。一方で、検証コンテキストが少なすぎると、レビュアーはサービス横断の問題、重複ロジック、意図した設計からの逸脱を見落とします。1つのエージェントが両方の仕事を担うと、そのエージェントがコードを書くときに置いた前提がレビューにも持ち込まれるため、死角が検証されないまま残ります。AIによるPRは全体としても欠陥が多く、人間によるPRが6.45件であるのに対し、AIによるPRでは1件あたり10.83件の問題があります。別個の検証なしに高速に生成すると、その差は未検証の作業のバックログになります。

チームはすでに、AIの出力を確認するために追加の時間を使っています。別個のレビューエージェントを用意すれば、それを避けられます。そのエージェントは、出力を生み出した前提ではなく、元々の意図と完成したコードからレビューを始めるからです。

より良いコンテキストが本当に効いたかをどう判断するのか

それは、どれだけ速くリリースできたかではなく、レビューをすり抜けたものからわかります。DORA（DevOps Research and Assessment）の2025年データは、AI導入が進むにつれて、チームがより多くのコードをリリースし、同時により頻繁に壊すようになっていることを示しています。

Faros AIは、コード行数のような活動指標は進捗の錯覚を生む一方で、流出バグ、インシデント、失敗した変更、手戻りといった品質シグナルこそが本当の状況を示すと主張しています。

freeeでは、ボトルネックはコーディング速度ではなく、レビュアーのキャパシティでした。同チームは過去6か月で32.8週分のレビュアー時間を節約しながら、数百のリポジトリにまたがるより多くのPRを扱いました。品質を落とさずにレビュアーの時間を解放できているかを測ってください。AI導入でアウトプットだけが増えているなら、単に速く進んでいるだけです。レビュアー時間が解放され、品質も維持されているなら、検証は機能しています。

4つの数値を追跡してください。流出欠陥、失敗した変更、レビュー遅延、見逃された指摘です。

1. 欠陥流出率は、早い段階で検出されず、本番環境に到達した欠陥の割合です。健全に見える活動統計が最もよく隠してしまう数値です。
2. 変更失敗率（DORA）は、障害を引き起こしたデプロイの割合です。今でも有用ですが、単独ではなく、流出欠陥やレビュー品質と並べて読むべきです。
3. レビューサイクルタイムは、DXのPRメトリクスの定義では、PRを開いてからマージするまでの時間です。AIがこれを短縮するかどうかについては研究によって意見が分かれるため、短くなると決めつけないでください。
4. 偽陰性率は、AIレビュアーが見逃し、後に本番環境へ到達した問題の割合です。CR-Benchベンチマークは、レビューエージェントについて、どれだけの指摘が本物で、どれだけの本物の問題を捕捉できるかを評価します。誤警告は高くつくからです。この指標は、エージェントが持っていたコンテキスト量と最も直接的に結びつきます。

活動チャートではなく、流出欠陥と偽陰性を見てください。コンテキストを追加したときにそれらが下がるなら、それが答えです。

エージェントのコンテキストウィンドウに入るものを管理する

エージェントがあなたのコードベースに対して行動した瞬間、何を見ることを許可され、何をできるのかは、セキュリティと監査の問題になります。従来のIAM（Identity and Access Management）は、予測可能なアクセス権を持つ人間のユーザーを前提にしています。AIエージェントはそのモデルを壊します。エージェントの役割はタスクの途中で変わることがあり、多くのシステムを機械の速度で横断し、標準的なログには何が起きたかは記録されても、なぜ起きたかは記録されません。

AIガバナンス研究は、コンテキストと権限が適切に管理されていない場合、エージェントがAPIキーや認証情報などのシークレットを漏えいさせる可能性があると警告しています。セキュリティ関連の指摘はAIによるPRで1.57倍多く見られます。そのため、エージェントが何へアクセスできるかを制御することは、レビューを正しく行うための一部です。

エージェントが見られるものと、それを使ってできることを制限してください。

• まずシークレットをフィルタリングする: コードがエージェントに届く前に認証情報をスキャンし、取り除きます。
• 期限付きの権限を与える: タスクのためにアクセスを付与し、タスクが終わったら取り消します。
• エージェントを開発者のアクセス権に合わせる: シングルサインオン（SSO）とロールベースアクセス制御（RBAC）を通じてリポジトリアクセスをスコープし、エージェントには開発者と同じアクセス権だけを与えます。スーパーユーザー権限は決して与えません。
• エージェントが見たものをログに残す: エージェントのコンテキストに何が入り、それがどこから来て、どのポリシーで許可されたのかを記録します。そうすれば、すべての意思決定を追跡できます。

エージェントが見るものを制御し、そのすべてをログに残してください。そうすれば、すべてのレビューは説明可能なコンテキストに基づいて実行されます。

コンテキストレイヤーを自作するか購入するか

自前のコンテキストレイヤーを構築するには、それを恒久的に担当する専任のプラットフォームチームが必要ですが、ほとんどの組織はその人員を確保できません。

コストはリリース時点では終わりません。コンテキストを取り込むシステムを動かし続け、コードベースグラフを最新に保ち、規約の変更に合わせてエージェントの指示を更新しなければなりません。これはコンテキストドリフトであり、継続的なコストです。チームがJestからVitestへ移行したのにAIへの指示を更新しなければ、エージェントはJestのテストを書き続けます。そして古くなった指示はすべてレビュー品質を下げます。

自作すればカスタマイズできますが、恒久的なエンジニアリングプロジェクトになります。購入すれば速く始められますが、他社のロードマップに依存します。多くのチームにとって、判断は1つの問いに集約されます。コンテキストレイヤーを自分たちが所有する問題にするのか、それとも任せる問題にするのか、です。

コンテキストを理解するレビューのテスト

コードレビューにおいて、エージェント型コンテキストエンジニアリングには具体的なテストがあります。レビュアーはコメントする前に、コードベースグラフ、チームの規約、リンクされたチケット、過去のレビュー判断を見られるでしょうか。CodeRabbitのコンテキストエンジンは、週あたり200万件以上のPRを300万以上のリポジトリでレビューしながら、コードグラフ、蓄積されたLearnings、MCP（Model Context Protocol）接続を通じて、すべてのPRに対してそれを自動的に組み立てます。差分だけを見るレビュアーは、変更行を指摘できます。コンテキストを理解するレビュアーは、その変更がそこに属しているかを判断できます。

コードレビュー時間を削減し、より多くのバグを見つけましょう。 無料の14日間トライアルを始めてください。