月曜の朝、開発チームに「基幹APIで使っているライブラリを次のメジャーバージョンへ更新したい」という依頼が届いたとします。担当するのは保守リーダーと数名の開発者です。普段はGitリポジトリ、課題管理システム、CI、ライブラリの公式移行資料を使っており、更新作業そのものは珍しくありません。それでも、メジャー更新となると単にバージョン番号を書き換えるだけでは終わりません。

AIを利用しない場合、担当者はマニフェストとロックファイルを確認し、直接依存と間接依存を整理します。続いて公式の変更履歴や移行資料を読み、廃止されたAPI、設定形式の変更、実行環境の要件をリポジトリ内の実装と照合します。その結果から更新計画を作り、コード変更、単体テスト、結合テスト、CI確認を進め、レビュー担当者に経緯を説明できるよう記録を残します。既存の検索機能やIDE、CIを活用していても、資料とコードの対応付けは人の頭の中に集まりがちです。



成果物として必要なのは、更新済みの依存定義だけではありません。互換性変更に対応したコード、回帰テスト、実行結果、残存リスク、ロールバック判断に使える情報までそろって、ようやくレビュー可能になります。途中で想定外の修正が増えると、計画と実際の差が見えにくくなり、変更理由を後から復元する負担も生じます。

ここでCodexに任せたいのは、更新可否の最終判断ではなく、リポジトリの調査結果を計画へ落とし込み、承認済みの範囲だけを段階的に実行する部分です。本稿では、架空の業務用APIにおける依存ライブラリ更新を例にします。プログラミング、テスト設計、Gitによる差分確認、使用言語のパッケージ管理を理解している開発者を対象とし、同じ入力資料、成果物、品質条件のもとで従来工程をどう組み替えるかに焦点を当てます。

負担の出発点は影響範囲の調査です。マニフェストに対象ライブラリが一行だけ記載されていても、実装側にはインポート、初期化処理、設定値、型定義、テスト用のモックが散在している可能性があります。文字列検索だけでは、ラッパー経由の利用や間接依存の影響を見落とすこともあります。担当者は検索結果を読み、更新に関係する箇所と無関係な箇所を分類しなければなりません。

計画作成では、公式移行資料の項目を自社コードへ対応付けます。「廃止APIへの対応」という一般的な記述を、変更対象ファイル、期待動作、テスト条件へ変換する作業です。判断根拠が課題票、個人メモ、レビューコメントに分散すると、後から計画を修正する際に転記が発生します。実装中に未確認の互換性変更が見つかれば、完了したつもりの工程へ戻ることにもなります。



実装後の確認にも別の負担があります。単体テストが通っても、対象ライブラリを使う主要経路、エラー処理、起動設定、ビルド成果物まで確認できたとは限りません。担当者は実行すべきコマンドを既存ドキュメントやCI設定から探し、結果をレビュー用に要約します。失敗したテストが更新によるものか、元から存在したものかを区別するには、変更前の基準結果も必要でしょう。

工程を分けると、手間は「資料探し」「コードとの対応付け」「計画への転記」「反復的な修正」「証跡の整理」に集中しています。Codexを使う狙いは、これらを無条件に消すことではありません。調査結果を一つの計画に集約し、フェーズごとの入力と終了条件を固定することで、同じ調査や説明を繰り返す範囲を狭めることです。互換性の許容範囲、セキュリティ上の採否、リリース可能性は、引き続き人が判断します。

OpenAIの開発者向け資料では、`AGENTS.md`をリポジトリ固有の継続的な指針として利用でき、`PLANS.md`を計画の基準点とする構成が紹介されています。どちらも一律に必須となる仕組みではなく、`AGENTS.md`はCodexが認識する任意のファイル、`PLANS.md`やフェーズ別ファイルはワークフロー上の推奨例です。小さなフェーズファイルに分ける方法は、人が途中で品質を確認するゲートと、後から読める作業履歴を作るうえで役立つと説明されています（出典: OpenAI Developers）。



|工程|AIを使わない場合|Codexを組み込む場合|人が残す判断|
|---|---|---|---|
|影響調査|検索結果と資料を手作業で突合します|読み取り専用の調査を依頼し、根拠ファイルと不明点を一覧化します|調査範囲と公式資料の妥当性を確認します|
|更新計画|担当者が課題票やメモへ転記します|`PLANS.md`から承認可能なフェーズ案を作らせます|順序、非対象、停止条件を承認します|
|実装|変更とテストをまとめて進めます|承認済みの一フェーズだけを実行させます|差分が承認範囲内か判断します|
|検証|コマンドを探して結果を要約します|既存設定から検証方法を特定させ、観測結果を記録させます|失敗の許容可否と追加試験を決めます|
|完了判定|レビュー時に経緯を再構成します|計画、差分、テスト証跡を対応付けます|セキュリティ、互換性、ロールバック可否を承認します|

比較条件をそろえることが大切です。入力は同じリポジトリ、同じ公式移行資料、同じ更新対象バージョンとし、成果物も更新差分、テスト、検証記録、未解決事項まで同じにします。Codex側だけ品質条件を減らせば、短く見えても公平な比較にはなりません。

工程上の変化は、実装を丸ごと委任することではなく、調査、計画、変更、検証の境界を明示できる点にあります。Codexが提示した内容に根拠ファイルがなければ、推測として分離させます。公式移行資料に記載のない互換性やセキュリティ情報は断定させず、人が一次資料を追加して再調査する運用が必要です。

準備する情報は、対象バージョンだけでは足りません。更新前の動作基準、対応する実行環境、CIで使う検証方法、変更してはいけない領域、公開APIの互換性方針を明らかにします。ライブラリの公式移行資料やセキュリティ情報も、人が信頼できる一次資料を選んでリポジトリ内の参照可能な場所へ用意します。Codexに外部情報を探させる前提にはせず、渡していない資料の内容を補わせないことが安全です。

`AGENTS.md`には、リポジトリの目的、コーディング規約、テスト基準、参照すべき資料、対象外の操作などを記載できます。OpenAIの資料でも、目的や概要、規約、テスト標準、境界といった継続的な知識の置き場所として紹介されています（出典: OpenAI Developers）。ただし既存の指針がある場合は、更新作業の都合だけで上書きせず、チームで管理している内容を優先します。



以下は本記事で提案する構成例です。Codexが必須とする固定構成ではありません。

AGENTS.md
PLANS.md
harness/
  build/
    phase-00-baseline-and-impact.md
    phase-01-dependency-definition.md
    phase-02-compatibility-changes.md
    phase-03-regression-verification.md
  context/
  build-log.md

`PLANS.md`には、更新の目的、対象バージョン、非対象、フェーズ順序、受け入れ条件、ロールバック方針、未決事項を置きます。フェーズ別ファイルには、その段階で変更可能なファイル、必要な事前条件、確認コマンド、終了条件を絞って記載します。たとえばフェーズ00は読み取り専用の基準確認、フェーズ01は依存定義の更新、フェーズ02は互換性修正、フェーズ03は広範な回帰検証という分け方が考えられます。

実行前には作業ツリーの状態と既存失敗を確認し、対象外のユーザー変更を区別できるようにします。認証情報、デプロイ、外部システムへの書き込み、コミットやプッシュは、依存更新とは別の承認対象にします。この分離が曖昧なままでは、フェーズを作っても安全な停止点になりません。

最初のフェーズではコードを変更させません。Codexにリポジトリ指針、依存定義、ロックファイル、対象ライブラリの利用箇所、既存テスト、CI設定を読ませ、確認できた事実と不明点を分けて報告させます。検証コマンドについても一般論から作らせず、リポジトリ内のスクリプト、README、CI設定から特定させるのが要点です。

コピーして使う調査・計画用のお願い文は次のとおりです。山括弧の部分を自分の案件に合わせて置き換え、公式移行資料の保存場所も明示してください。

このリポジトリの依存ライブラリ更新について、読み取り専用の調査を行ってください。
対象は <対象ライブラリ> の <現在版> から <更新候補版> への更新です。

最初に、適用される AGENTS.md、PLANS.md、依存定義、ロックファイル、
CI設定、既存テスト、<公式移行資料のパス> を読んでください。

次の項目を、根拠となるファイルと行または設定項目を添えて報告してください。
- 現在の依存関係と実行環境の制約
- 対象ライブラリを利用する実装、設定、テスト
- 公式移行資料の各変更点に対応する影響候補
- 変更前に実行すべき既存の検証コマンド
- 不足資料、矛盾、推測を含む項目
- 小さく独立して確認できるフェーズ案

この段階ではファイルを変更しないでください。
書き込み前に、変更候補の正確なパス、非対象、受け入れ条件、
停止条件をまとめ、承認を待ってください。

返答では、単なるファイル一覧ではなく「移行資料の変更項目―該当コード―必要なテスト」の対応が作られているかを確認します。利用箇所が見つからない項目も削除せず、該当なしと判断した検索範囲を残させます。間接依存や実行時にだけ読み込まれる設定など、静的な検索で断定できないものは未解決事項として扱います。

調査結果を承認した後に、フェーズ別作業ファイルを作成させます。OpenAIの資料では、各ファイルに目的、必要な文脈、受け入れ条件、境界を持たせ、実装を始める前に人が確認できる形が提案されています（出典: OpenAI Developers）。フェーズの順序や対象が資料から確定できない場合、Codexに推測で書き進めさせず、案の提示で停止させることが承認ゲートとして機能します。

計画が承認されたら、一度に一つのフェーズだけを実行します。依存定義の更新と互換性修正、全体テストを同時に行うと、失敗原因の切り分けが難しくなります。フェーズ01でマニフェストとロックファイルだけを扱い、フェーズ02で利用コードを変更するなど、観測可能な単位に区切ります。更新直後にビルドできないことが予想される場合は、その状態をフェーズの終了条件にせず、依存関係を壊さない分割へ計画を修正します。

実装時のお願い文には、対象フェーズ、許可されたファイル、テスト方法、禁止操作、停止条件を含めます。次は提案例であり、実際のコマンドは調査フェーズでリポジトリから確認したものへ置き換えます。

承認済みの <フェーズ番号と名称> だけを実行してください。
開始前に AGENTS.md、PLANS.md、対象のフェーズファイル、
直前フェーズの記録を読み、現在の作業ツリーを確認してください。

実装前に次を短く報告し、承認済み内容との一致を確認してください。
- このフェーズの目的
- 変更予定ファイル
- 明示的な非対象
- 実行する検証
- 途中で停止すべき条件

実装では、既存動作を示す最小の確認を行い、必要最小限の変更を加え、
承認済みの検証を実行してください。範囲外の問題を発見した場合は修正せず、
根拠と影響を記録して停止してください。

完了時には、変更ファイル、差分の目的、実行したコマンド、観測した結果、
失敗と未解決事項、ロールバックに必要な情報を報告してください。
次のフェーズ、コミット、プッシュ、デプロイは開始しないでください。

OpenAIのワークフロー例では、フェーズ用の指示に読み取り専用の事前確認、書き込み前の承認要約、red・green・refactor・verification、観測したテスト証跡、次段階へ自動的に進まない停止条件を含める方法が示されています（出典: OpenAI Developers）。ここでいうredは、更新で守るべき動作や既存の失敗状態を確認する工程です。必ず新規テストを作るという意味ではなく、リポジトリの状況に応じて最小の観測可能な確認を選びます。

テスト記録には、コマンド名だけでなく実行環境、終了状態、失敗した対象、結果の要約を残します。テストを実行できなかった場合は、未実行を成功扱いにせず、必要な認証情報や外部サービスを明記させます。これにより、レビュー担当者はCodexの説明を信頼するだけでなく、差分と観測結果を照合できます。

Codexがコードとテストを整理しても、メジャー更新を採用してよいかは人が決めます。最初の確認対象は互換性です。公開API、データ形式、設定項目、例外処理、性能上の前提が変わっていないかを、公式移行資料と実際の差分で突き合わせます。テストが通ったという事実だけでは、利用者との契約や運用上の期待まで維持されたとは限りません。

セキュリティ確認では、更新候補版と残存する間接依存をチームの基準に照らします。Codexに脆弱性の有無を推測させず、組織が採用しているスキャナーや公式アドバイザリの結果を証跡として追加します。認証、暗号化、入力検証などに関係する差分は、通常のコードレビューとは別に担当者を割り当てる判断も必要でしょう。



レビュー時には、少なくとも次の項目を確認します。

- 計画した変更項目と実際の差分が一対一で対応しているか
- 対象外の整形、リファクタリング、設定変更が混入していないか
- 変更前の基準結果と変更後のテスト結果を比較できるか
- 未実行の検証や既知の失敗が明示されているか
- 旧版へ戻す手順と、戻した際のデータ互換性を説明できるか
- コミット、公開、デプロイに別の承認が必要か

ロールバックは、依存定義を元に戻せるという説明だけでは不十分です。更新後に生成されるデータ、キャッシュ、設定、外部サービスとの通信形式が旧版でも扱えるかを確認します。戻せない変更が含まれる場合は、移行前のバックアップや段階リリースを別の作業として計画します。

Codexの役割は、判断材料を同じ形式でそろえ、欠落を見つけやすくすることです。レビュー担当者は根拠ファイル、公式資料、差分、実行ログを直接読み、説明と一致しているかを確かめます。説明が明快でも証跡がなければ承認せず、追加調査を新しいフェーズとして切り出す運用が適しています。

導入効果は、作業時間だけで評価すると見誤ります。Codexへ渡す指針の整備、計画レビュー、結果の修正にも手間がかかるためです。従来方式と試行方式で同程度の依存更新を選び、影響調査、計画作成、実装、テスト、証跡整理、レビュー修正に分けて記録します。更新対象の規模やテスト環境が違う場合は、その条件も併記し、単純な時間比較を避けます。

観測項目としては、同じ情報を再調査した回数、計画外の変更数、レビューで根拠を追加した件数、テスト失敗の原因特定に必要だった往復、未解決事項の見落としなどが使えます。Codexによる下書きを人が大幅に修正した場合、その修正もコストに含めます。反対に、フェーズファイルや証跡を次回の保守で再利用できた場合は、継続的な効果として別に記録すると実態を捉えやすくなります。



期待できる変化は、資料探索や転記が完全になくなることではありません。リポジトリ内の根拠を計画へ結び付け、承認済み範囲だけを反復できれば、調査のやり直しやレビュー時の経緯復元を減らせると考えられます。ただし、指針が古い、テストが不足している、公式資料を渡していないといった条件では、整理された誤りが作られる可能性もあります。効果は準備の品質と人の確認を含めて判断する必要があります。

最初の試行では、直ちに本番へ影響する中核依存を選ばず、テスト環境で完結し、戻しやすい一件を候補にします。実装まで自動化する必要もありません。`AGENTS.md`の既存指針を確認し、読み取り専用の影響調査とフェーズ案だけをCodexへ依頼して、人が作った計画との差を比べるところから始められます。その結果がレビューに使える水準なら、一つの承認済みフェーズへ進み、証跡の残し方まで含めて自社の標準手順にできるか判断してください。

- Iterating Development Workflows with Codex