【ITニュース解説】The Context Packet: The Right Architectural Coding Agents

システムエンジニアを目指す初心者の皆さん、AIを使った開発ツールが注目を集める中、ただAIに大量のコードを渡すだけでは、必ずしもシステム全体を深く理解できるわけではないという課題が生まれています。今回は、AIを活用した開発をより賢く、安全に進めるための新しい考え方、「コンテキストパケット」について解説する。

大規模なコードリポジトリ全体をAIに渡しても、古いコードや文書化されていない決定が含まれるため、AIがシステムを正しく理解し、適切な提案をすることは難しい場合がある。大量の情報を読み込ませても、本当に重要なルールや制約がノイズの中に埋もれてしまい、AIの判断を誤らせる原因となる。

例えば、「支払い通知の処理に、エラー時の再試行機能を追加してほしい」とAIに依頼する場面を想像してみる。AIは関連コードを見つけ、修正案を提示するかもしれないが、安全な実装にはコードだけでは分からない情報が必要になる。メッセージが確実に一度だけ届けられるのか、支払いプロバイダーは同じ要求を複数回受けても問題ないか（冪等性）、どのようなエラーが一時的なものなのか、といった疑問に対する答えは、コードリポジトリの中には明確な「契約」として存在しないことがほとんどである。

AIが依頼内容と周辺ファイルしか見ていない場合、これらの情報の不足を「たぶんこうだろう」という仮定で埋めてしまう。一方、リポジトリ全体を渡された場合、重要なルールが何千もの関係ない情報や古い情報の中に埋もれてしまい、見つけ出すのが困難になる。この問題は、「コンテキスト（文脈）」のデザインの仕方に起因する。

AIコーディングシステムは、一度に処理できる情報量に限りがあり、これを「コンテキスト予算」と呼ぶ。さらに、提供された情報のうち有用な制約やルールの割合を示す「シグナル密度」が低いと、AIは誤った推論をしやすくなる。大量の入力は、矛盾する例や古くなった実装パターン、不正確な依存関係の推測を招く可能性を高める。AIへの指示文（プロンプト）を改善する試みもあるが、プロンプトはバージョン管理や検証が難しいため、システムの設計思想を保存する場所としては不適切である。

そこで提唱されるのが「コンテキストパケット」である。これは、個別の変更や作業フローに対して、システムに関する必要最小限の情報を、小さく、バージョン管理され、機械が読みやすい形式で記述したものである。ソースコードだけでは表現しきれない、システムの「契約」や「設計上の決定事項」を補完する役割を果たす。このパケットは、フォルダ構造ではなく、コードの「依存関係グラフ」に基づいて、本当に必要な情報だけを集めて作られる。

コンテキストパケットに情報を含めるかどうかは、以下の3つの質問で判断される。

1. この変更は、その情報に影響を与える可能性があるか？
2. その情報は、守るべき契約を定義しているか？
3. その情報は、現在の状況に対して最新のものか？ このように、コンテキストの選択を明確なルールとして定義することで、後から内容を検証したり改善したりできるようになる。

有用なコンテキストパケットには、以下のような情報が含まれる。

• 目的: この作業で達成したい結果。
• 範囲: この作業が影響を与えるサービス、モジュール、ファイル、データ。
• 契約: 他のシステムとのインターフェース（API）、データの形式（スキーマ）、責任範囲、互換性など。
• 制約: セキュリティ要件、信頼性、パフォーマンス、法的規制など。
• 証拠: 正しい動作を証明するテストコード、実行ログ、過去の問題、性能指標、使用例など。
• 実行ポリシー: 変更を行う際に許可されるツールや必要な承認プロセス。 これらの情報は、コードと同じようにバージョン管理され、レビューされるべきであり、また、エンジニアが容易に読み更新できるくらいに、小さい規模に保つことが重要である。

実際の利用例として、「プロバイダーのタイムアウト後に支払い通知を再試行する」というプルリクエスト（PR）を作成するケースを考える。AIエージェントは、リポジトリ全体のコピーではなく、その変更が安全かどうかを判断するために必要最小限の事実の集合を必要とする。

「コンテキストアセンブラ」と呼ばれる仕組みが、変更されるワーカー（処理を行うプログラム）の依存関係グラフをたどり、短いパケットを作成する。このパケットには、変更内容、担当チーム、目的、読み取り対象となるファイル、編集対象となるファイル、維持すべき特定の振る舞い、そして実行すべきチェックの項目が含まれる。

例えば、「読み取り対象」には支払い通知ワーカーのコード、プロバイダー連携コード、データ形式定義、関連する設計決定記録などが指定される。「編集対象」にはワーカー本体のコードと、それを検証するテストコードが含まれる。「維持すべき振る舞い」には、全ての再試行で通知IDが安定していることや、アダプターがプロバイダーの失敗を分類することなどが明記される。「実行するチェック」には、特定のテストが挙げられる。

AIエージェントは、このパケットを使って、指定された範囲内で変更を加える。コードを読んだり編集したり、テストを再実行したりは可能だが、インフラの設定やユーザー認証情報の変更はできない。継続的インテグレーション・継続的デプロイメント（CI/CD）のパイプラインは、パケットで指定されたチェックを実行し、もしAIが指定範囲外のファイルを変更したり、必要な証拠が不十分だったりすれば、PRを拒否する。

このように、パケットの各フィールドには明確な役割がある。「read」は関連する実装やアーキテクチャの決定をAIに提供し、「edit」は提案されるコードの変更範囲を制限し、「must_preserve」はソースコードだけでは説明できない維持すべき振る舞いを記録し、「checks」はパケットと開発・デプロイのパイプラインを結びつける。コンテキストパケットは、リポジトリ全体の要約ではなく、あくまで「変更の概要」として機能する。

コンテキストアセンブラは、プルリクエストで変更されるファイルから出発し、そのファイルが依存している他のコードや設定をたどって必要な情報を収集する。直接変更されるもの、その依存関係にあるもの、あるいはその依存関係が運用上の契約を定義しているものがパケットに含まれる。関係のないサービスや古い実装例は収集範囲外とされる。アセンブラは、リポジトリの所有者情報、アーキテクチャ上の決定記録、APIやイベントのスキーマ定義など、管理された情報源から必要な情報を集め、関連性に応じてランク付けする。

このコンテキストパケットが本当に役立っているかは、以下の指標で評価できる。

• 手戻り: AIエージェントが同じ制約について、繰り返し修正を必要としたか。
• 境界違反: AIの提案が、宣言されたスコープ外のファイルやツールに触れたか。
• 証拠カバレッジ: 必要なチェックが適切に定義され、実際に実行されたか。
• レビュー工数: レビュアーが、システムのコンテキストを再構築するのに費やす時間が減ったか。

もちろん、コンテキストパケットの導入には、いくつかの考慮すべき点や運用上の限界がある。

まず、コンテキストを整備するにはメンテナンスコストがかかる。システムの所有者は、契約、スキーマ、サービスメタデータなどを常に最新の状態に保つ必要がある。これは労力のいる作業だが、文書化されていない知識に依存するよりも、長期的に見てはるかに望ましい選択である。

次に、狭すぎるコンテキストは、重要な依存関係を見落とす危険性がある。パケットの範囲が狭すぎると、誤った安心感を生む可能性がある。そのため、依存関係の証拠を含めたり、AIエージェントがパケットの範囲拡大を要求できる仕組みが必要である。範囲拡大の要求は記録され、特に重要な境界を越える場合は承認プロセスが必要となるべきである。

また、バージョン管理には追加の手間がかかる。パケットのバージョン、元のコードのリビジョン、情報の鮮度などを記録することは、作業を伴う。しかし、この手間は、デバッグや問題発生時のロールバックが高価になるような変更において、その価値を大きく発揮する。

セキュリティに関する承認は、実際のコード実行時に行われるべきである。パケットの中でAIエージェントが特定のパスを編集しても良いと書かれていても、その権限はシステムが実際にコードを実行する段階で厳密に強制されなければならない。AIへの指示文やJSONフィールドだけでセキュリティ境界を定義することは安全ではない。

最後に、アーキテクチャの最終的な所有権は、人間のエンジニアにある。システムの契約を定義し、どの振る舞いが意図的なものかを決定し、トレードオフを受け入れるのは、やはり人間の仕事である。コンテキストパケットは、その作業をより明確にし、再利用可能にするためのツールに過ぎない。

結論として、コンテキストパケットの価値は、AIエージェントが「システムを支配する重要なルール」と「たまたま近くにある関係のないコード」を区別できるように助ける点にある。AIを活用した開発がより信頼性の高いものになるためには、コンテキストをシステムの設計の一部として計画し、継続的に管理していくことが非常に重要だと言えるだろう。