use-cases/code-migrations.md +131 −0 added
1# Run code migrations | Codex use cases
2
3Codex use cases
4
5
6
7
8
9Codex use case
10
11# Run code migrations
12
13Migrate legacy stacks in controlled checkpoints.
14
15Difficulty **Advanced**
16
17Time horizon **1h**
18
19Use Codex to map a legacy system to a new stack, land the move in milestones, and validate parity before each transition.
20
21## Best for
22
23- Legacy-to-modern stack moves where frameworks, runtimes, build systems, or platform conventions need to change.
24- Teams that need compatibility layers, phased transitions, and explicit validation at each migration checkpoint.
25
26# Contents
27
28[← All use cases](https://developers.openai.com/codex/use-cases)
29
30Copy page [Export as PDF](https://developers.openai.com/codex/use-cases/code-migrations/?export=pdf)
31
32Use Codex to map a legacy system to a new stack, land the move in milestones, and validate parity before each transition.
33
34Advanced
35
361h
37
38Related links
39
40[Modernizing your Codebase with Codex](https://developers.openai.com/cookbook/examples/codex/code_modernization) [Worktrees in the Codex app](https://developers.openai.com/codex/app/worktrees)
41
42## Best for
43
44- Legacy-to-modern stack moves where frameworks, runtimes, build systems, or platform conventions need to change.
45- Teams that need compatibility layers, phased transitions, and explicit validation at each migration checkpoint.
46
47## Skills & Plugins
48
49- [Security Best Practices](https://github.com/openai/skills/tree/main/skills/.curated/security-best-practices)
50
51 Check risky migrations, dependency changes, and exposed surfaces before you merge.
52- [Gh Fix Ci](https://github.com/openai/skills/tree/main/skills/.curated/gh-fix-ci)
53
54 Work through failing CI after each migration milestone instead of leaving cleanup until the end.
55- [Aspnet Core](https://github.com/openai/skills/tree/main/skills/.curated/aspnet-core)
56
57 Use framework-specific guidance when a migration touches ASP.NET Core app models, `Program.cs`, middleware, testing, performance, or version upgrades.
58
59| Skill | Why use it |
60| --- | --- |
61| [Security Best Practices](https://github.com/openai/skills/tree/main/skills/.curated/security-best-practices) | Check risky migrations, dependency changes, and exposed surfaces before you merge. |
62| [Gh Fix Ci](https://github.com/openai/skills/tree/main/skills/.curated/gh-fix-ci) | Work through failing CI after each migration milestone instead of leaving cleanup until the end. |
63| [Aspnet Core](https://github.com/openai/skills/tree/main/skills/.curated/aspnet-core) | Use framework-specific guidance when a migration touches ASP.NET Core app models, `Program.cs`, middleware, testing, performance, or version upgrades. |
64
65## Starter prompt
66
67Migrate this codebase from [legacy stack or system] to [target stack or system].
68 Requirements:
69- Start by inventorying the legacy assumptions: routing, data models, auth, configuration, build tooling, tests, deployment, and external contracts.
70- Map the old stack to the new one and call out anything that has no direct equivalent.
71- Propose an incremental migration plan with compatibility layers or checkpoints instead of one big rewrite.
72- Keep behavior unchanged unless the migration explicitly requires a user-visible change.
73- Work in milestones and run lint, type-check, and focused tests after each milestone.
74- Keep rollback or fallback options visible until the transition is complete.
75 - If validation fails, fix it before continuing.
76 - Start by mapping the migration surface and proposing the checkpoint plan.
77
78[Open in the Codex app](codex://new?prompt=Migrate+this+codebase+from+%5Blegacy+stack+or+system%5D+to+%5Btarget+stack+or+system%5D.%0A%0ARequirements%3A%0A-+Start+by+inventorying+the+legacy+assumptions%3A+routing%2C+data+models%2C+auth%2C+configuration%2C+build+tooling%2C+tests%2C+deployment%2C+and+external+contracts.%0A-+Map+the+old+stack+to+the+new+one+and+call+out+anything+that+has+no+direct+equivalent.%0A-+Propose+an+incremental+migration+plan+with+compatibility+layers+or+checkpoints+instead+of+one+big+rewrite.%0A-+Keep+behavior+unchanged+unless+the+migration+explicitly+requires+a+user-visible+change.%0A-+Work+in+milestones+and+run+lint%2C+type-check%2C+and+focused+tests+after+each+milestone.%0A-+Keep+rollback+or+fallback+options+visible+until+the+transition+is+complete.%0A-+If+validation+fails%2C+fix+it+before+continuing.%0A-+Start+by+mapping+the+migration+surface+and+proposing+the+checkpoint+plan. "Open in the Codex app")
79
80Migrate this codebase from [legacy stack or system] to [target stack or system].
81 Requirements:
82- Start by inventorying the legacy assumptions: routing, data models, auth, configuration, build tooling, tests, deployment, and external contracts.
83- Map the old stack to the new one and call out anything that has no direct equivalent.
84- Propose an incremental migration plan with compatibility layers or checkpoints instead of one big rewrite.
85- Keep behavior unchanged unless the migration explicitly requires a user-visible change.
86- Work in milestones and run lint, type-check, and focused tests after each milestone.
87- Keep rollback or fallback options visible until the transition is complete.
88 - If validation fails, fix it before continuing.
89 - Start by mapping the migration surface and proposing the checkpoint plan.
90
91## Introduction
92
93When you are moving from one stack to another, you can leverage codex to map and execute a controlled migration: routing, data models, configuration, auth, background jobs, build tooling, deployment, tests, or even the language and framework conventions themselves.
94
95Codex is useful here because it can inventory the legacy system, map old concepts to new ones, and land the change in checkpoints instead of one giant rewrite. That matters when you are moving off a legacy framework, porting to a new runtime, or incrementally replacing one stack with another while the product still has to keep working.
96
97## How to use
98
991. Start by inventorying the migration surface: legacy packages, framework conventions, routing, data access, auth, configuration, build tooling, tests, deployment assumptions, and any external contracts that must survive the move.
1002. Ask Codex to map the legacy concepts to the target stack and call out what has no direct match.
1013. Choose an incremental strategy: compatibility layer, module-by-module port, branch-by-abstraction, or a strangler-style replacement around one boundary at a time.
1024. Keep behavior stable until the migration itself forces a visible change, and name those exceptions explicitly.
1035. After each milestone, run the smallest validation that proves parity: lint, type-check, focused tests, contract tests, smoke tests, or a side-by-side check against the legacy path.
1046. Review the diff and the remaining transition risk after each checkpoint instead of waiting for the full rewrite.
105
106## Leverage ExecPlans
107
108In our [code modernization cookbook](https://developers.openai.com/cookbook/examples/codex/code_modernization), we introduce ExecPlans: documents that let Codex keep an overview of the cleanup, spell out the intended end state, and log validation after each pass.
109When you ask Codex to run a complex migration, ask it to create an ExecPlan for each part of the system to make sure every decision and tech stack choice is recorded and can be reviewed later.
110
111## Related use cases
112
113[
114
115### Create a CLI Codex can use
116
117Ask Codex to create a composable CLI it can run from any folder, combine with repo scripts...
118
119Engineering Code](https://developers.openai.com/codex/use-cases/agent-friendly-clis)[
120
121### Create browser-based games
122
123Use Codex to turn a game brief into first a well-defined plan, and then a real browser-based...
124
125Engineering Code](https://developers.openai.com/codex/use-cases/browser-games)[
126
127### Refactor your codebase
128
129Use Codex to remove dead code, untangle large files, collapse duplicated logic, and...
130
131Engineering Code](https://developers.openai.com/codex/use-cases/refactor-your-codebase)