【ITニュース解説】Blind Replay Before Merge: Keep Only the Agent Diff a Clean Environment Recreates

システムエンジニアを目指す皆さんへ。

最近、AIアシスタントを活用したプログラミングが一般的になりつつある。しかし、この便利なツールがもたらす新たな課題も浮上している。「チャットセッション内にしか存在しないコード変更」の問題だ。AIアシスタントとの会話を通して生まれたコードは、その会話の文脈や制約に深く依存してしまうことがある。例えば、チャット中にモデルが提示した解決策のうち、採用されなかったアイデアや、特定のファイル名、非公開のサービス名、曖昧なアーキテクチャの記述などが、会話の中に埋もれてしまう。これらは後からコードを見る人や、別の開発者が同じ変更を再現しようとした際に、全くわからない「隠れた文脈」となってしまうのだ。

この「隠れた文脈」は、まるでコードに忍び込む「汚染物質」のようなものだ。この汚染されたコードをそのままリポジトリにマージしてしまうと、将来的にバグの原因になったり、他の開発者が理解できなかったり、最悪の場合、本番環境で予期せぬ問題を引き起こしたりするリスクがある。コードは、いつでも誰でも、リポジトリ（ソースコードの管理場所）から同じように生成・再現できるべきだという原則に反してしまうのだ。

そこで提唱されているのが、「ブラインドリプレイ（Blind Replay）」という考え方である。これは、AIアシスタントを使って生成されたコードを本番環境にマージする前に、そのコードが「クリーンな環境」と「短い指示書（ブリーフ）」だけで「再現可能であること」を厳しく検証する手法だ。つまり、チャットの履歴や会話の流れに一切頼らず、純粋にコードと、そのコードが満たすべき要件だけを基に、同じ変更がもう一度作り出せるかを確かめる。

この検証プロセスでは、主に二つの役割が登場する。一つは「ドライバー」で、AIアシスタントの助けを借りてコードの変更を試みる開発者だ。もう一つは「シニア」で、この変更が安全かつ再現可能であるかを厳しくチェックする経験豊富な開発者を指す。作業は、まずドライバーがAIアシスタントと共に、問題のあるテストが合格するようなコード変更を試みる。この最初の試みは、あくまで「使い捨てのブランチ」で行われ、その内容がどれほど完璧に見えても、すぐにマージされることはない。

次に重要なのは、「清潔な第二環境」を用意することだ。これは、最初のチャットセッションで使われた環境とは完全に隔離された、履歴や設定が一切残っていない状態の作業環境を意味する。この第二環境では、ドライバーとシニアが事前に作成した「brief.md」という指示書と、「replay_manifest.yaml」というマニフェストファイル、そしてリポジトリにある既存のコードだけを使って、同じ変更をもう一度AIアシスタントに生成させる。この時、最初のチャットのやり取りや、モデルが提案して却下されたアイデアなどは、一切参照しない。

「brief.md」（指示書）には、このタスクで達成すべき目標、現在の失敗状況、変更を許可するファイルパスと禁止するファイルパス、そして「完了」と見なすための具体的なテストコマンドなどが明確に記される。この指示書は、あたかも全く面識のない人が読んでも、タスクを正確に理解し、実行できるレベルでなければならない。チャットでの会話のトーンや、以前却下されたファイル名など、余計な情報は一切含めない。もし第二環境でタスクが完了できない場合は、その指示書自体が不完全であると判断し、指示書を修正する。

「replay_manifest.yaml」（再現マニフェスト）は、テストコマンド、許可されたパス、禁止されたパス、さらにはモデルが試行できる回数（最大ラウンド数）など、再現に必要な条件を機械的に読み取れる形で定義する。これにより、テストの実行方法や変更範囲が固定され、再現性が確保される。

そして、この第二環境で生成されたコードが、指示書とマニフェストの要件を満たしているかを自動でチェックするための「replay_gate.py」（再現ゲート）というスクリプトが導入される。このスクリプトは、変更されたファイルが許可されたパス内にあるか、禁止されたパスに触れていないか、そして指定されたテストコマンドが正常に終了するかを検証する。このスクリプトがゼロ（成功）を返した場合に初めて、その変更がマージの議論の対象となる。

これまでの経験から、いくつかの「デッドエンド（行き止まり）」が見つかっている。例えば、AIに最初のチャット内容を要約させても、その要約自体がまだ「汚染されたスレッド」の一部であり、正確なエラーコードやテストコマンドが抜け落ちることが判明した。また、チャットの全履歴をエクスポートして「指示書」とすることは、モデルが却下されたアイデアを再利用してしまう原因となり、逆効果だった。さらに、二つのパッチを目視で比較しても、人間の記憶は当てにならず、見落としが生じることがわかった。これらの失敗から、「機械的な検証」と「安定した契約（指示書とマニフェスト）」の重要性が強く認識されたのである。

ブラインドリプレイの最大の利点は、将来的なコードの理解とメンテナンスの容易さにある。チャット履歴に依存しない再現可能なコードは、他の開発者にとっても理解しやすく、長期的なプロジェクトの健全性を保つ上で非常に重要だ。たとえ最初のAIアシスタントによる変更が素早く見えたとしても、その再現性がなければ、後から本番環境で問題が発生した場合のデバッグは非常に困難になる。

しかし、このプロトコルにも限界がある。ブラインドリプレイは、コードの「アーキテクチャの良さ」や「製品としての判断の妥当性」を証明するものではない。既存のテストが貧弱であれば、不格好なパッチでもゲートを通過してしまう可能性がある。また、最初のチャットでAIが生成したテストは、自己整合性を証明するだけなので、リプレイの前に必ず破棄する必要がある。機密情報がbriefに紛れ込まないよう、厳重な注意も必要だ。そして最も重要なのは、このゲートは「デザインレビュー」や「コードレビュー」を代替するものではないということだ。人間による最終的なレビューは依然として不可欠であり、ゲートはあくまで契約（要件）の遵守を機械的にチェックする役割を担う。

このアプローチは、人手によるパッチ作成を既に義務付けているチームや、厳格な規制下でサードパーティの実行が禁じられているコードベースでは不要かもしれない。また、テストコマンドすらまだ明確にできないような状況では、まずテストを書くことから始めるべきである。

最終的に、このペアリング（開発者二人の協業）が保持したのは、指示書、マニフェスト、ゲートスクリプト、そして「ゲートを通過した第二環境のパッチ」だけだった。編集画面でどれほど似て見えても、最初のチャットで生成されたパッチは破棄された。なぜなら、「再現性なしの類似性」は、後から誰かがリポジトリだけで同じ変更を再現できる証拠にはならないからだ。マージの議論は、クリーンな環境でreplay_gate.pyがゼロを返した後に初めて開始される。これが、このペアリングが堅持し、コードツリーに残すべき唯一の「お土産」なのである。