【ITニュース解説】If You Cannot Replay the Agent, Do Not Merge

システムエンジニアを目指す初心者にとって、プログラミングアシスタント（AIエージェント）が生成したコードを開発プロセスに安全に組み込む方法は、重要な考慮事項である。この記事は、エージェントが提案するコードの変更をマージする際に、「再現性」が不可欠であると強く主張している。

まず、再現性とは何かについて説明する。エージェントが生成したコードの変更（パッチ）をプロジェクトに組み込むかどうかの判断は、その変更がどのようなプロセスを経て生成されたかを後から正確に再現できるかどうかによる。単に同じプロンプトをエージェントに与えて、同じ結果が得られることを期待するだけでは不十分だ。再現性とは、エージェントが行った一連の操作を、保存された情報に基づいていつでも再構築できる状態を指す。これは、人間が書いたコードに対してログやテスト結果の証拠を求めるのと同様に、エージェントの作業履歴にも詳細な証拠を求めるべきだという考え方に基づいている。

再現性を確保するためには、具体的な六つの情報を記録する必要がある。一つ目は、エージェントに与えたタスクのプロンプトと、添付された全てのファイルのハッシュ値である。二つ目は、エージェントが呼び出すことを許可されたツールのスキーマ情報である。三つ目は、エージェントが行った各ツール呼び出しの引数と、その結果のハッシュ値である。四つ目は、利用したモデルの識別子を特定するための文字列である。五つ目は、エージェントが生成したコードの差分（パッチファイル）を特定するハッシュ値である。最後に六つ目は、その結果に対する人間の判断（マージ、拒否、隔離）である。これら全ての情報が揃っていなければ、それは単なる個人的なメモに過ぎず、プロジェクトのメインブランチにマージされるべきではない。

再現性を軽視することには大きなリスクが伴う。例えば、安価または無料で利用できるAIトークンは、エージェントが何度も試行錯誤を繰り返すコストを隠してしまうことがある。その結果、たまたま成功したプロセスを記録せず、どのようにしてその結果が得られたのかが不明なままになってしまう。これにより、チーム内で「エージェントはリポジトリの内容を理解している」といった誤解が生じることがあるが、実際にはエージェントがたまたま成功したパスを見つけただけであり、その具体的な手順が記録されていないため、数週間後には誰もその変更を再現できなくなり、デバッグや引き継ぎ作業が極めて困難になる。

再現性を確保するためには、具体的な「再現契約」を定めて実践する必要がある。これは、エージェントの活動履歴を記録するためのJSON形式のスキーマとして表現できる。このスキーマには、タスクID、タスクプロンプトのハッシュ、使用モデルのID、ベースとなるコードのバージョン、許可されたツールリスト、各ツール呼び出しの詳細（シーケンス番号、ツール名、引数のハッシュ、結果のハッシュ）、生成されたパッチのハッシュ、そして人間の判断などが含まれる。特に、ツール呼び出しの引数や結果は、その内容を直接記録するのではなく、ハッシュ値として記録することで、履歴の改ざんを防ぎ、セキュリティを保つことができる。また、エージェントが使用できるツールは、許可リスト（allowlist）によって厳しく制限し、許可されていないツール名が使われた場合は実行を失敗させるべきである。

この再現契約は、コードの差分（diff）について議論する前に、継続的インテグレーション（CI）パイプラインで検証される必要がある。この検証は、再現ファイルに必須のキーが全て含まれているか、秘密情報が適切に処理されているか、人間の判断が許容される値であるか、生成されたパッチのハッシュ値が正確であるかなどをチェックする。この検証がパスしたとしても、それがエージェントが生成したコードの品質を保証するものではない。あくまで「再現可能であること」を確認するものであり、コードの正確性は人間が書いたテストによって検証されるべきである。

マージのプロセスにおいても、エージェントによる自動評価ではなく、人間が介入する明確なルールを設定する。再現ファイルがプルリクエストに含まれていない場合、許可されていないツールが使用されている場合、記録されたハッシュ値と実際のバイト列が一致しない場合など、再現性に関わる問題があれば、そのプルリクエストはブロックされる。また、最終的なマージ判断はエージェントではなく人間が行うべきであり、「review（レビュー）」「reject（拒否）」「isolate（隔離）」のみが許容される判断であり、「merge（マージ）」は許可されない。これにより、再現性のない変更がシステムに組み込まれることを防ぐ。

この再現性のチェックは、CIパイプラインに自動的に組み込むべきである。再現ファイルと生成されたパッチをプルリクエストに含め、チェックが失敗した場合はプルリクエストを拒否する。パッチのハッシュ値が記録と一致しない場合も同様である。このチェックツール自体は、エージェントに作成させるのではなく、人間が責任を持って作成し管理する必要がある。

再現チェックが失敗した場合のデバッグワークフローも重要である。まず、コード生成を一時停止し、問題の原因を特定するフォレンジック（鑑識）作業に移行する。このとき、replay.jsonファイルが正しく解析できるか、タスクハッシュがプロンプトファイルと一致するか、ツール名が許可リストに存在するか、結果のハッシュが保存されたデータと一致するか、パッチのハッシュがGitの差分と一致するかを順番に確認する。これらの確認後も再現しない場合は、エージェントが使用するツールの非決定性や、実行環境が固定されていないことが原因である可能性が高い。ネットワーク時間、ランダムなファイル、現在の時刻といった要素は、予測不能な動作を引き起こすため、これらのツールはスタブ化（代替処理）するか、その正確な出力バイトを記録する必要がある。

ただし、このアプローチにも限界がある。再現性は、エージェントが生成したパッチの正しさや、モデル自体の性能を保証するものではない。コードの正確性は、依然として人間が書いたテストで確認する必要がある。また、GPUの非決定性や、プロンプトに秘密情報を詰め込んでしまった場合の漏洩、レビューを怠った場合の潜在的な問題などは防げない。浮動小数点演算を行うツール、ネットワーク呼び出し、システム時刻を利用するツールなどは、単純な方法では再現性を破壊するため、これらもスタブ化するか、その出力を厳密に記録する必要がある。

このアプローチは、無人での本番環境への書き込み、厳しく規制されたシステムでの使用、生成されたテストの盲目的な承認には適さない。また、エージェントがツールを全く呼び出さないような単一の編集作業には、このような複雑な記録は不要であり、通常のコードレビューで十分である。最も重要なのは、もしエージェントの活動履歴（トランスクリプト）を安全に保存できないのであれば、このアプローチ自体を始めるべきではないということである。プロンプトには顧客名やプライベートなURLなどの秘密情報が含まれる可能性があり、共有サンドボックスに送る前にそれらの情報を適切に匿名化する手順が不可欠である。

最終的に、より「賢い」エージェントを求めるよりも、コールドスタート後も再現可能な実行履歴を記録できるシステムを構築することの方が、安全なコード変更をプロジェクトに組み込む上で遥かに重要である。エージェントが生成したコードが再現できないのであれば、その変更をマージしてはならないという原則は、開発プロセスの信頼性を確保するための基盤となる。