社内システムを長く使っていると、どこかで必ず「ライブラリが古くなった」「フレームワークのサポートが切れる」という話が出てきます。更新の作業そのものは地味ですが、影響する範囲が読みにくく、動かしてみるまで何が壊れるか分かりません。そのため後回しにされやすく、気づいたときには大きな移行になっている、ということがよくあります。
Codex はこの種の作業を手伝えますが、「全部新しくして」と頼むと差分が大きくなりすぎて、人が確かめられなくなります。この記事では、ライブラリの更新やフレームワークの移行を Codex に任せるときの進め方を、手順の順番に整理します。製品の動きに関わる内容は、2026年11月19日に OpenAI の公式ユースケース(Run code migrations・Migrate a validation module・Refactor your codebase)で確かめた範囲に絞りました。
結論: 移行は「範囲を書いた指示書」から始めます。Codex にまず移行に関係する所を洗い出させ、1か所ずつ移し、区切りごとに更新の前と後で動きが同じかを比べた証拠を出させます。戻し方は最初から指示書に書き、移行が終わるまで消しません。マージと本番への反映は人が決めます。
なぜ「範囲」を先に決めるのか
ライブラリの更新は、変えた量に対して影響が見えにくい作業です。1行の版の変更が、画面の表示・データの読み書き・外部との連携のどこに効くかは、動かしてみないと分かりません。
公式のユースケース「Run code migrations」では、移行は古い仕組みから新しい仕組みへ、区切りを置きながら段階的に進めるものとして説明されています。向いているのは、フレームワーク・実行環境・ビルドの仕組みが変わる移行や、互換の層を挟んで少しずつ切り替える必要がある移行です。(出典: Run code migrations)
また「Refactor your codebase」では、コードの整理と依存関係の移行をはっきり分け、整理の途中で更新が必要になったら書き出して別の作業にするよう指示する例が示されています。(出典: Refactor your codebase)
つまり、人が最初にやるべきことは「どこまでを今回の作業にするか」を決めることです。
| 作業の種類 | 中身の例 | 1回の作業にまとめてよいか |
|---|---|---|
| コードの整理 | 使っていないコードの削除・大きいファイルの分割 | 1つの主題ごとに1回 |
| 1つのライブラリの更新 | 入力チェックに使うライブラリの版を上げる | 1つのモジュールずつ |
| フレームワークの移行 | 画面の仕組みや実行環境を入れ替える | 区切りを置いて段階的に |
| 外から見える動きの変更 | API の返す形を変える | 移行とは別の作業に分ける |
手順1: 指示書(ブリーフ)を書く
公式のユースケース「Migrate a validation module」では、最初の手順として指示書を書くことが挙げられています。書く項目は、対象のモジュール、そのモジュールを直接呼んでいる箇所、担当者、承認済みの移行先の版、動きを確かめるテスト、今回は触らないコード、戻し方です。さらに、もっと広い依存関係の更新や外から見える動きの変更が必要になったら止まるよう書いておくとされています。(出典: Migrate a validation module)
社内向けに書き直すと、次のような形になります。
対象: 受注システムの入力チェックのモジュール1つ
移行: 入力チェックのライブラリを今の固定の版から、社内で承認した版へ上げる
直接の呼び出し元: 受注登録の API と管理画面の取り込み処理
担当: 受注システムの開発担当
守ること:
- API の入出力の形とエラーの返し方は変えない
- 既存のテストの期待値を書き換えない・判定を緩めない
- 今回は他のモジュールに触らない
止まる条件:
- 他のライブラリの更新が必要になったとき
- 外から見える動きを変えないと移せないと分かったとき
→ その時点で作業を止めて理由を報告する
確かめ方:
- 更新の前と後で同じ入力を流し、返ってくる結果を比べて記録する
- lint・型の検査・関係するテストを実行し、コマンドと結果を報告する
戻し方:
- 版を元に戻す手順と、元に戻したあとに流す検査を書いて残す
公式のユースケースの例文にも「新しいスナップショットを承認しない」「外から見える違いをならして消さない」「判定を緩めない」という趣旨の制約が入っています。(出典: Migrate a validation module)テストを通すために期待値を書き換えてしまうと、移行で何が変わったのかが分からなくなります。この一文は必ず入れてください。
手順2: 移行に関係する所を洗い出させる
指示書ができたら、いきなり直させずに洗い出しから始めます。「Run code migrations」では、まず移行に関係する範囲を棚卸しするよう書かれています。対象は、パッケージ、フレームワークの決まりごと、画面の振り分け、データの読み書き、認証、設定、ビルドの道具、テスト、デプロイの前提、外部との取り決めです。続けて、古い仕組みの考え方を新しい仕組みのどれに当てはめるかを Codex に整理させ、そのまま対応するものが無い所に印を付けさせます。(出典: Run code migrations)
この段階で受け取るのは「変更」ではなく「一覧」です。人は一覧を見て、次の2つを決めます。
- 今回の作業に入れる所と、後回しにする所
- 対応するものが無い所をどう扱うか(互換の層で包むか・別の作業にするか)
一覧の時点で範囲が広すぎると分かれば、指示書の「対象」を狭めて書き直します。洗い出しの段階で計画を確かめたいときは、計画を先に出させるモードを使うと進めやすくなります。計画の出させ方は作業を途中で直す方法の記事で解説しています。
手順3: 今の動きを記録してから移す
移す前に、今の状態を記録させます。「Migrate a validation module」では、Codex に AGENTS.md・指示書・移行の案内・ロックファイル・呼び出し元・テストを読ませ、作業を始めたときのコミットと入っている版を記録させる手順が示されています。始める前から失敗している検査があれば、直すか理由を説明させてから「動きが同じ」と言うよう書かれています。(出典: Migrate a validation module)
ここで大事なのは、比べる元になる記録を先に作ることです。そもそも今の動きを確かめるテストが少ないシステムでは、移行の前にテストを足す作業を1回挟むと安心です。進め方は既存システムにテストを足す記事にまとめています。
ほかのモジュールと共有している依存関係があって、そのままでは1か所だけ移せない場合もあります。公式のユースケースでは、そうした準備(互換のための変更)を移行そのものとは別の変更として見直し、元の状態と準備後の状態で同じテストが通ることを示すよう書かれています。(出典: Migrate a validation module)
手順4: 1か所ずつ移して区切りごとに確かめる
準備ができたら、1か所ずつ移します。「Run code migrations」では、互換の層を挟む・モジュールごとに移す・抽象化の層を挟んで切り替える・古い部分を少しずつ置き換える、といった段階的なやり方から選び、境目を1つずつ扱うよう書かれています。移行のために外から見える動きを変えざるを得ないときは、その変更をはっきり名前を付けて書き出させます。(出典: Run code migrations)
区切りごとに流す検査は、動きが同じことを示せる最小のものにします。公式のユースケースでは、lint・型の検査・関係するテスト・取り決めのテスト・簡単な動作確認・古い経路との並べての比較などが挙げられ、失敗は次に進む前に直すとされています。(出典: Run code migrations)
| 区切りで見るもの | Codex に出させるもの | 人が判断すること |
|---|---|---|
| 検査の結果 | 実行したコマンドと終了コードと結果 | 失敗が残っていないか |
| 前後の比較 | 同じ入力に対する更新の前と後の結果 | 違いが意図したものか |
| 差分 | 今回の区切りで変えたファイル | 範囲の外に触れていないか |
| 残った課題 | まだ残る互換のコードと未解決の違い | 次の区切りに進むか止めるか |
「Migrate a validation module」では、成果として、絞った差分・前後の比較の記録(コマンド・終了コード・版・記録の置き場所)・未解決の違いと残った互換のコード・依存関係とロックファイルの変更・戻し方・Pull Request の説明の下書きを返す形が示されています。マージ・デプロイ・次の区切りの作業はレビューする人に任せる、とされています。(出典: Migrate a validation module)
手順5: 長い移行は目標と止まる条件を決めて回す
移行が何日にもわたるときは、1回ずつ頼み直すより、目標を決めて続けて進めさせるほうが楽です。「Run code migrations」では、長く続く作業には /goal で目標を設定し、終わりの状態・動きが同じかの確かめ方・戻し方の考え・止まる条件をはっきり書くよう案内されています。また、システムの部分ごとに実行計画(ExecPlan)を作り、決めたことや技術の選び方を記録して見直せるようにすることも勧められています。(出典: Run code migrations)
同じ条件で検査を何度も流すには、クラウドの環境を用意しておくと便利です。「Migrate a validation module」では、クラウドの環境で実行環境・依存関係・テスト用のサービスを準備させ、準備の結果を確かめてから公開し、依存関係やサービスを変えたら環境を直して公開し直し、新しい作業で確かめる手順が示されています。外部への通信先と認証情報は別に設定するとされています。(出典: Migrate a validation module)クラウドの使い方はクラウドタスクの基本の記事、通信先の決め方はネットワークアクセスの記事で解説しています。
チームで回すときに決めておくこと
移行は1回で終わる作業ではなく、毎年のように発生します。最初の1件で次の4つを決めておくと、次からの作業が早くなります。
- 指示書の型を共有する: 手順1の項目をリポジトリの手順書や AGENTS.md に置き、移行のたびに同じ形で書けるようにします。書き方はAGENTS.md の書き方の記事を参考にしてください
- マージ前の確認を決める: 公式のユースケースでは、依存関係の変更や危険を含む移行をマージ前に確かめるために Security Best Practices のスキルを使う例や、区切りごとの CI の失敗に対応するスキルが紹介されています。(出典: Run code migrations)社内のレビューと Codex のレビューの分担はコードレビューの記事にまとめています
- うまくいった型をスキルにする: 「Refactor your codebase」では、うまくいった進め方や確認の一覧をチームで使い回せるスキルにする例が紹介されています。(出典: Refactor your codebase)作り方はスキルを部門で作って共有する記事で解説しています
- 互換のコードに担当と期限を付ける: 一時的に残す互換のコードは、誰がいつ外すかを決めておかないと残り続けます。公式のユースケースでも、一時的な橋渡しのコードに担当者と外す条件を付けるよう指示書に書くとされています。(出典: Migrate a validation module)
まとめ
ライブラリの更新やフレームワークの移行を Codex に任せるときは、範囲・守ること・止まる条件・確かめ方・戻し方を書いた指示書から始めます。洗い出しの一覧を人が見て範囲を決め、今の動きを記録してから1か所ずつ移し、区切りごとに更新の前と後を比べた証拠を出させます。テストを通すために期待値を書き換えさせないこと、戻し方を最後まで残すこと、マージと本番への反映は人が決めることの3点を守れば、後回しにしがちな更新を少しずつ前に進められます。
この記事の内容は、2026年11月19日時点の OpenAI 公式ドキュメントの記載に基づいています。機能の名前や画面の操作は変わることがあるため、使う前に最新の記載をご確認ください。デジライズでは、社内システムの保守や更新の流れに Codex を組み込む手順づくりから、指示書の型・社内ルール・開発部門向けの研修までを含めた Codex の法人導入支援のご相談を承っています。「まず1つのライブラリの更新で試したい」という段階からでもお問い合わせください。
- https://learn.chatgpt.com/codex/use-cases/code-migrations
- https://learn.chatgpt.com/use-cases/migrate-a-validation-module
- https://learn.chatgpt.com/codex/use-cases/refactor-your-codebase
確認日:2026年11月19日。提供条件・機能・料金は変更されるため、最新情報は各公式ページをご確認ください。
デジライズの実績はデジライズ全体の社内集計値です。Codex の機能・対応環境・料金・提供条件は記事の公開・更新時点の OpenAI 公式情報に基づき、変更される場合があります。導入効果は企業や業務によって異なります。



