受注アプリに「出荷拠点」を必須項目として追加する依頼が届いたとします。既存の注文を失わず、アプリを段階的に更新しながら移行することが条件です。保守担当者は、エディターで受注登録処理を追い、マイグレーション管理ツールで変更履歴を確認し、開発用データベースで既存データの状態を調べます。SQLのひな型や既存テストが整っていても、列を追加する変更だけで依頼を完了にはできません。

この記事では、架空の受注アプリを使い、Codexに調査と変更案の作成を補助してもらう進め方を提案します。成果物は、段階ごとのマイグレーション、関連コードの変更、互換性テスト、移行判断に使う検証記録です。SQL、Git、アプリのデータアクセス層、マイグレーションの適用履歴を読める開発者を想定しています。実際に移行を実行した報告ではなく、業務に合わせて調整する実践例です。

例の受注テーブルには注文IDと店舗IDがあり、新たに出荷拠点IDを追加します。既存注文の出荷拠点は、業務担当者が承認した店舗と拠点の対応表から補う設計とします。ただし、対応先が見つからない店舗や複数候補を持つ店舗は、自動で決めません。新規注文にも正しい拠点が保存され、最終的に未設定を許さない状態を目指します。

ここで問題になるのが旧アプリです。新しい列を知らない旧版が稼働している間に必須制約を付けると、登録処理が失敗する可能性があります。本例では、未設定を許す期間を設け、旧版を含む書き込み元を切り替えてから制約を適用します。「必須にする」という依頼を、移行途中の状態まで設計する課題として扱うことが出発点です。

AIを使わない場合、担当者はスキーマ定義、過去の移行ファイル、受注モデル、登録API、バッチ、インポート処理、テストデータを順に確認します。検索で列名を見つけるだけでは不十分です。共通の保存関数を経由する処理もあれば、SQLを直接組み立てる処理もあるため、呼び出し元までたどる必要があります。定例処理や別リポジトリの連携プログラムが書き込んでいる場合は、アプリ本体の調査だけでは漏れます。

資料探しの後には、見つけた情報を移行計画へ転記し、読み取りと書き込みに分類する工程があります。例えば、画面表示は未設定の出荷拠点を扱えるか、CSV取込は拠点を指定できるか、テスト用データの生成処理は新しい必須条件を満たすか、といった確認です。関連箇所を見落とすと、SQL自体が正しくても、後段のテストやリリース準備で手戻りが発生します。

既存データの補完には別の判断が必要です。店舗と出荷拠点が現在は一対一でも、過去の注文に同じ対応を適用してよいとは限りません。本例では、対応表が既存注文にも適用できることを業務担当者に確認する前提です。適用できない注文があるなら、注文日時などを含む別ルールが必要になります。Codexに曖昧な対応関係を推測させても、業務上の正解は確定しません。

調査結果は「参照したファイル」「該当する処理」「移行への影響」「未確認事項」を対応させて残すと、レビューしやすくなります。リポジトリ内で確認できない外部の書き込み元は、存在しないと結論付けず、運用担当者への確認事項にします。調査の終了条件は検索結果が出そろうことではなく、移行中にどのプログラムがどの状態のデータを扱うか説明できることです。

OpenAIの公式Cookbookでは、Codexに継続的なリポジトリの指針を渡す任意のファイルとしてAGENTS.mdが説明されています。また、計画や段階別の作業ファイルを使う進め方が紹介されていますが、これらはCodexの必須ファイルではなく、調整可能なワークフロー上の慣例とされています。（出典: OpenAI Cookbook）

この考え方を移行作業に応用し、調査、計画、実装、検証を小さく区切る方法を提案します。Codexには関連コードを調べて根拠付きの一覧を作り、その一覧から移行案とテスト案を組み立てるよう依頼します。担当者が検索結果を何度も読み直して計画へ書き写す負担は減らせる可能性があります。ただし、調査範囲の網羅性と業務ルールの正しさは、人が確かめる必要があります。

比較するときは、AIの有無で完成条件を変えないことが大切です。どちらも同じコード、同じ架空データ、同じ対応表を入力とし、旧版との共存、補完の正確さ、失敗後の再開を確認した成果物を求めます。

| 工程 | AIを使わない場合 | Codexを使う場合 | 人が残す判断 |
| --- | --- | --- | --- |
| 影響調査 | 検索結果を読み、関連処理を一覧化します | 根拠付き一覧の下書きを依頼します | 調査漏れと外部連携を確認します |
| 移行設計 | 変更順序と停止条件を組み立てます | 段階案と矛盾の指摘を依頼します | 共存条件と業務ルールを決めます |
| 実装 | SQLと関連コードを作成します | 承認した段階の変更案を依頼します | データ更新条件と差分を審査します |
| 検証 | ケースを設計し、結果を記録します | テスト案と検証記録の整理を依頼します | 観測結果から適用可否を判断します |

Codexの出力を、そのまま調査完了や検証成功の証拠にはしません。計画は予定、生成されたテストは検証手段、実行ログは観測結果として区別します。本記事が参照する資料の取得日は2026年11月9日であり、資料の公開日を示すものではありません。紹介する進め方も、同日に発表された新機能として扱うものではありません。

準備するものは、対象リポジトリ、機密情報を除いた開発用DB、承認済みの店舗と拠点の対応表、旧版と新版を切り替えて動かせる検証環境です。DB製品とバージョン、ORM、既存のマイグレーション方式も確認します。ロックの発生条件やトランザクションの扱いは環境によって異なるため、本記事では共通の実行SQLを提示しません。以下のファイル名や作業区分は提案例であり、Codexの必須設定ではありません。

第1段階は、変更を伴わない調査です。利用中のCodexの入力欄へ、次のお願い文を渡します。対象パスや対応表の場所は、自分の環境で確認した内容に置き換えてください。既存のAGENTS.mdがある場合は、その指針も確認対象に含めます。

コピーして使う調査用のお願い文です。

受注に出荷拠点IDを追加する移行を計画してください。
今回は調査だけを行い、ファイル変更とDB更新は行わないでください。

既存のリポジトリ指針、スキーマ、移行履歴、受注の読み書き、
バッチ、インポート、テストと実際の検証方法を確認してください。
関連箇所はファイルパスと根拠を添えて整理してください。

既存注文の補完には、指定した承認済み対応表だけを使います。
対応なし・複数候補は未解決として扱ってください。
旧アプリとの共存期間を設け、全書き込み元の切替後に必須制約を適用します。

未確認事項、段階案、各段階の開始条件・停止条件、
失敗後の再開方法を提示してください。
リポジトリ外の書き込み元の有無は断定しないでください。

第2段階は、列の追加と共存対応です。人が調査結果を確認してから、未設定を許す列の追加と、新版が未設定を読み取れるための変更を依頼します。新版の書き込みでは出荷拠点を設定する設計にし、旧版による登録が続いても直ちに失敗しない状態を検証します。列追加の負荷や適用方法は、実際のDB環境で別途確認しなければなりません。

第3段階は、既存データの補完です。対象を出荷拠点が未設定の注文に限定し、承認済み対応表で一意に決まる注文だけを更新する案を作ります。大量のデータを扱う場合は、分割単位、進捗の記録方法、中断後の再開条件を設計します。補完中にも旧版が未設定の注文を作る可能性があるため、一度の補完で完了したとは判断できません。

第4段階で全書き込み元を切り替え、残った未設定を再確認してから必須制約へ進みます。旧版を残す必要があるなら、この段階を保留します。無条件の既定値で登録を通す案は、正しい出荷拠点を保存するという品質条件を満たすか、人が判断する必要があります。

コピーして使う段階別の実装依頼例です。

確認済み計画の第2段階だけを実装してください。
既存の移行方式とテストの慣例に合わせてください。
必須制約の適用と既存データの補完は今回の対象外です。

変更前に対象ファイルと検証方法を示してください。
旧版の登録と、新版による未設定データの読み取りを確認する
テストを用意してください。
実行した検証と実行していない検証を分けて報告し、
この段階で止めてください。本番DBへの接続・更新は行わないでください。

Codexから受け取る成果物は、SQLの差分だけでは不十分です。対象ファイル、変更理由、テスト結果、未解決事項を同じ段階にひも付けます。例えば、検証記録には「旧版で追加列を指定せず注文登録」「新版で未設定の注文を表示」「補完後に既存の出荷拠点を保持」といったケースを記載できます。ただし、これらは記録項目の例です。実際に動かしていないケースへ成功と書いてはいけません。

架空データには、一意に拠点が決まる注文、対応表に店舗がない注文、複数候補がある注文、すでに拠点が入力されている注文を用意します。補完前後で注文の総件数が変わらないことに加え、対象注文が正しい拠点へ結び付いたかを照合します。未設定件数が減るだけでは、誤った拠点への一括更新を見逃すためです。更新対象外の注文についても値が変わっていないことを確かめます。

互換性は、アプリとDBの組み合わせで確認します。旧版と列追加後のDB、新版と未補完データ、新版と補完済みデータを動かし、登録、更新、読み取りを検証します。最終的な必須制約の適用後には、正常な登録が成功することと、不正な未設定データが拒否されることの両方を確認します。別の制約や参照整合性がある場合は、それらも検証範囲に加える必要があります。

途中失敗への備えでは、補完を中断して再開し、重複更新や値の上書きが起きないかを調べます。複数の更新処理が同時に走る場合、処理開始時の抽出条件だけでなく、実際の更新時にも未設定という条件が守られるかをレビューします。また、アプリを旧版へ戻すことと、データを元へ戻すことは別の作業です。列の削除で復旧できると決め付けず、どの状態からどう回復するかを定めます。

差分レビューと検証記録をそろえた後、開発責任者と業務担当者が適用可否を判断します。未解決の対応関係、残存する旧版の書き込み、未検証の復旧方法があれば、次段階へ進む条件を満たしていません。Codexには不足の整理を依頼できますが、承認そのものを置き換えることはできません。

この使い方で負担を減らせる可能性があるのは、関連コードの探索、影響一覧の下書き、計画から変更案への展開、検証ケースのたたき台作成です。既存の移行ファイルやテストに一貫した慣例があるほど、担当者が繰り返し説明する内容を絞りやすくなると考えられます。ただし、調査漏れの修正や誤った補完条件の発見に時間がかかれば、その分だけ期待した効果は小さくなります。本記事では作業時間や削減率を実測していません。

自社で確かめる場合は、同じ開始状態のコードと開発用データを用意し、同じ移行要件、成果物、合格条件で比較します。記録する区分は、準備、調査、設計、実装、実行待ち、レビュー、修正です。Codexへ渡す資料の整理や追加説明も準備・修正に含めます。生成が速かったことだけを成果にせず、人が確認できる状態まで整える負担を見ることが必要です。

品質面では、見落とした書き込み元、対応表の誤解、更新対象の誤り、検証漏れ、差し戻し理由を残します。同じ課題を同じ担当者が二度行うと、二回目には知識が増えているため、時間差をそのままAIの効果と解釈できません。過去の類似案件との比較にも条件差があるので、数値を出す場合は比較方法と限界を添えます。最初は、どの工程で読み直しや転記が減り、どの確認が増えたかを把握するだけでも改善材料になるでしょう。

着手するなら、本番への移行一式ではなく、一つの受注登録経路を対象にした読み取り専用の影響調査から始めてください。人が把握しているコードとCodexの一覧を照合し、根拠の示し方や見落としを評価します。その調査結果を使って開発用DBの共存テストまで進めれば、実装を任せる範囲を判断できます。最初の合格条件を「SQLができること」ではなく、「旧版が動く期間と必須制約を付けられる条件を説明できること」に置くと、移行の目的に沿って試せます。

- Iterating Development Workflows with Codex