Codexでコード移行を進める前に決めること

3行まとめ

Target

対象。

Checkpoint

到達点。

Compat

互換性。

Rollback

戻す。

Review

確認。

migrationは一括rewriteではなく、戻せる単位で進めます。

• Codexにcode migrationを任せる時は、一括rewriteではなく、対象、checkpoint、互換性test、rollback、PR分割を先に決めます。
• legacy stack、framework、API、dependency、runtime、data migrationは同じriskではないため、移行単位を分けます。
• migrationは速く変える作業ではなく、戻せる単位で進め、各checkpointでreviewできる状態へ戻す作業です。

この記事では、OpenAI公式のCodex use cases、Codex app Features、Worktrees、Goals、Permissions、AGENTS.md docsを確認し、2026年6月1日時点の情報として整理しています。Codex app、Worktrees、Goal、migration系use caseは更新され得るため、導入前に最新docsと自社のrelease運用を確認してください。

この記事でわかること

Scope

範囲。

Tests

確認。

PRs

分割。

Owner

承認者。

速さより、確認できる単位と戻せる単位を優先します。

• Codexへ任せるmigration対象の分け方
• checkpointとPR分割の考え方
• 互換性testと観測できる証拠の作り方
• rollbackと停止条件を先に決める理由
• Codexに調査、実装、reviewを分けて渡す方法
• 初週に試す小さなmigration導入例

OpenAIのCodex use casesでは、Run code migrationsとして、legacy stacksをcontrolled checkpointsで移行する使い方が紹介されています。migrationは、Codexが得意な「広く読んで、局所的に直し、testで確認する」作業に見えます。

ただし、migrationは大きくなりがちです。古いframeworkを新しくする、runtimeを変える、API clientを差し替える、dependencyを上げる。どれも一括で進めると、review不能なPRや戻せない差分になります。Codexに任せる前に、checkpointとrollbackを設計します。

長期作業としてmigrationを進める場合は、公開済み記事のCodexでGoalを立てる前に決めることも参考になります。この記事では、migrationそのものの分割と検証に絞ります。

前提知識

項目	内容	見方
Use cases		migration用途。
Features		app機能。
Worktrees		独立作業。
Goals		長期作業。
Permissions		権限。

migrationはGoalやWorktreeと組み合わせると管理しやすくなります。

OpenAI公式のCodex use casesでは、Run code migrationsがlegacy stacksをcontrolled checkpointsで移行する用途として示されています。Codex app Featuresでは、Codex appがproject、thread、worktree、skillsなどを扱う開発作業の入口として説明されています。

Worktrees docsでは、Git repositoryで独立した作業場所を作り、background作業やHandoffへ使えることが説明されています。migrationは既存作業を壊しやすいため、Worktreeで調査や小さな差分を分けると扱いやすくなります。

Permissions docsでは、filesystemやnetworkの境界をprofileとして決める考え方が説明されています。migrationでは、read-only調査、限定write、dependency install、外部docs確認、CI実行を分けます。

公式情報で確認する範囲

確認先	見ること
Codex use cases	code migrationの位置づけ
Codex app Features	project、thread、worktree
Worktrees	独立作業、Handoff
Goal	長期作業の管理
Permissions	read/write/networkの境界
AGENTS.md	repo固有の作業契約

注意点

この記事は、Codexに大規模rewriteを丸投げする話ではありません。migrationは、対象を小さく分け、testで守り、rollbackできる単位で進めます。

また、testがない範囲を暗黙に変えないようにします。testがないなら、先に観測できる証拠を作ります。snapshot、fixture、manual QA、golden outputなど、今の挙動を守る材料を置きます。

まずmigration対象を分ける

項目	内容	見方
Framework		基盤。
API		契約。
Dependency		依存。
Runtime		実行環境。
Data		データ。

対象を分けると、testとrollbackの設計が変わります。

migration対象は、種類ごとにriskが違います。

対象	例	主なrisk
framework	Rails、Next.js、React major update	behavior差分
API	client、endpoint、schema	契約破壊
dependency	library major update	hidden behavior
runtime	Node、Python、Java version	build/test差分
data	DB migration、format change	rollback困難

framework

framework migrationは、影響範囲が広いです。routing、rendering、build、test、runtime、plugin、middlewareが一緒に変わることがあります。

Codexへ渡す時は、最初に影響mapを作らせます。どのdirectory、entrypoint、test、build configが関係するかを調べ、PR単位へ分けます。

API

API migrationでは、契約を守ることが重要です。request/response、auth、error code、pagination、rate limit、retry、timeoutを確認します。

API docsやschemaとあわせて確認する場合は、公開済み記事のCodexにドキュメント更新を任せる前に決めることの考え方も使えます。

dependency

dependency migrationでは、changelog、breaking changes、lockfile、test、transitive dependencyを確認します。security updateと絡む場合は、Codexにセキュリティ調査を任せる前に決めることのように、findingとregression evidenceを分けます。

data migrationは別扱い

DB migrationやdata format変更は、別扱いにします。rollback、backup、dual-write、read compatibility、migration window、monitoringが必要です。Codexに実装補助をさせる場合でも、人間承認と運用手順を必須にします。

checkpointを設計する

1. 1Map

   棚卸し。

2. 2Slice

   分割。

3. 3Migrate

   移行。

4. 4Verify

   確認。

5. 5Merge

   統合。

checkpointごとに、mergeできる状態へ戻します。

checkpointは、migrationの小さな到達点です。各checkpointで、buildできる、testできる、reviewできる、rollbackできる状態へ戻します。

checkpoint	例
調査	影響範囲とrisk map
準備	test追加、fixture作成
小移行	1 directoryだけ移す
互換層	old/new両対応
cleanup	旧コード削除

小さな到達点

小さな到達点は、「mergeできる状態」で定義します。大きなmigration branchの途中状態を何週間も持つと、mainとの差分が広がり、reviewが難しくなります。

Codexには、checkpointごとに完了条件を渡します。

完了条件	例
build	npm run build が通る
test	変更範囲のtestが通る
behavior	fixture出力が一致する
docs	変更点がREADMEに反映
review	ownerが確認

PR分割

PRは、reviewできる単位で分けます。

PR	内容
PR 1	test追加と現状固定
PR 2	互換層追加
PR 3	1領域を移行
PR 4	旧経路を削除
PR 5	docsとcleanup

分割しすぎの注意

分割しすぎると、全体像が見えなくなります。各PRには、migration planへのリンク、現在のcheckpoint、次のcheckpointを入れます。

互換性とtestを固定する

項目	内容	見方
Unit		小さい挙動。
Integration		結合。
Snapshot		出力。
Fixture		入力。
Manual		手動QA。

testがない範囲は、先に観測できる証拠を作ります。

migrationで守るべきは、見た目のdiffだけではありません。挙動の互換性です。

test	見ること
unit	小さな関数やcomponent
integration	module間の連携
snapshot	出力やUI構造
fixture	入力と期待出力
manual QA	人間が見るflow

behavior test

behavior testは、移行前後で守りたい挙動を固定します。Codexに実装を変えさせる前に、現状挙動をtest化します。

testがないままmigrationすると、「正しく変わった」のか「壊れた」のかが分かりません。

snapshotやfixture

snapshotやfixtureは、migration前後の出力を比較するのに向いています。ただし、snapshotを盲目的に更新しないようにします。変化が意図したものか、reviewで見ます。

testがない範囲の扱い

testがない範囲では、先に観測します。

方法	例
golden output	既存出力を保存
fixture	代表入力を用意
manual checklist	画面flowを固定
logging	一時的に挙動を確認
read-only調査	変更前に構造を把握

rollbackと停止条件を決める

Revert PR

差分単位。

Feature flag

切替。

Fallback

旧経路。

Stop

人間確認。

戻せないmigrationは、進める前に分割し直します。

migrationは、戻せることが大事です。

rollback	使う場面
revert PR	小さな差分を戻す
feature flag	old/newを切り替える
compatibility layer	旧APIを一時維持
data backup	data migration前
release toggle	段階反映

戻す単位

戻す単位は、PR単位が基本です。巨大PRは戻しにくいため、migration PRは小さくします。

feature flagやcompatibility layerを使う場合は、いつ削除するかも決めます。互換層を置いたままにすると、次の負債になります。

人間確認

次の条件では、人間確認へ戻します。

条件	理由
testが不足	壊れたか判断できない
data migration	rollbackが難しい
authやbilling	影響が大きい
public API変更	利用者影響がある
performance悪化	指標確認が必要

Codexへ渡す作業を分ける

項目	内容	見方
Research		影響調査。
Plan		checkpoint。
Patch		限定変更。
Review		risk確認。

同じ依頼で調査と実装とreviewを混ぜないようにします。

Codexへ渡す作業は、調査、計画、実装、reviewに分けます。

役割	依頼
調査	影響範囲、依存、testを読む
計画	checkpointとPR分割を出す
実装	1 checkpointだけ変更する
review	risk、test gap、rollbackを確認

調査

調査では、read-onlyで構造を見ます。entrypoint、dependency、test、build config、docs、release手順を確認し、migration mapを作ります。

実装

実装では、1 checkpointだけを渡します。Codexに「全部移行して」と頼むのではなく、「このdirectoryを新APIへ移し、既存testを通し、docsはこの1箇所だけ更新する」といった形にします。

review

reviewは実装と分けます。migration PRでは、behavior差分、test gap、rollback、compatibility、docs更新を見ます。

導入初週の進め方

1. 1日目

   棚卸し。

2. 2日目

   test確認。

3. 3日目

   小PR。

4. 5日目

   rollback確認。

5. 7日目

   次checkpoint。

最初はmigrationそのものより、観測と戻し方を固めます。

最初の1週間は、migration前の観測と小さなPRに集中します。

日	やること	見ること
1日目	影響範囲を棚卸し	対象が広すぎないか
2日目	testとfixtureを確認	守れる挙動があるか
3日目	小さな準備PR	reviewできるか
5日目	rollbackを確認	戻せるか
7日目	次checkpointを決める	継続可能か

初週の成功条件は、大量に移すことではありません。migration plan、test、rollback、PR分割が見えることです。

小さく始める例

作業	理由
1 helperのAPI差し替え	影響が狭い
test追加だけのPR	挙動を先に固定
docsの移行方針作成	合意を取りやすい
compatibility layer追加	段階移行しやすい
deprecated importの置換	機械的に確認しやすい

FAQ

Big bang?

避ける。

No tests?

先に作る。

Worktree?

独立作業。

Goal?

長期管理。

迷ったら、reviewできるPR単位へ戻します。

Codexに全部一括で移行してもらってよいですか？

おすすめしません。migrationはcheckpointとPR分割を作り、戻せる単位で進めます。

testがない場合はどうしますか？

先に観測できる証拠を作ります。fixture、snapshot、manual checklist、golden outputなどで現状を固定します。

Worktreeは使うべきですか？

Localの作業を汚したくない調査や試作には向いています。採用する差分はHandoffやbranch化でreviewしやすい形にします。

Goalにしたほうがよいですか？

複数checkpointにまたがるmigrationならGoalが向きます。単発の小さな置換なら通常threadで十分です。

rollbackはいつ考えますか？

最初に考えます。戻せないmigrationは、進める前に分割し直します。

次に読むなら

参照した主な情報源

• Codex use cases – OpenAI Developers
• Codex app features – OpenAI Developers
• Worktrees – Codex app – OpenAI Developers
• Permissions – Codex – OpenAI Developers
• Custom instructions with AGENTS.md – Codex – OpenAI Developers

更新履歴

1. 2026年6月1日

   OpenAI公式Codex docsを確認して初版を作成しました。

導入時には最新のCodex use casesとproject設定を確認してください。

• 2026年6月1日: OpenAI公式Codex use cases、Codex app docs、Worktrees、Permissions、AGENTS.mdを確認し、初版を作成しました。