use-cases/code-migrations.md Codex Docs, 2026-04-24 18:20 UTC → 2026-05-07 20:02 UTC

1# Run code migrations | Codex use cases1---

2name: Run code migrations

3tagline: Migrate legacy stacks in controlled checkpoints.

4summary: Use Codex to map a legacy system to a new stack, land the move in

5 milestones, and validate parity before each transition.

6skills:

7 - token: $security-best-practices

8 url: https://github.com/openai/skills/tree/main/skills/.curated/security-best-practices

9 description: Check risky migrations, dependency changes, and exposed surfaces

10 before you merge.

11 - token: $gh-fix-ci

12 url: https://github.com/openai/skills/tree/main/skills/.curated/gh-fix-ci

13 description: Work through failing CI after each migration milestone instead of

14 leaving cleanup until the end.

15 - token: $aspnet-core

16 url: https://github.com/openai/skills/tree/main/skills/.curated/aspnet-core

17 description: Use framework-specific guidance when a migration touches ASP.NET

18 Core app models, `Program.cs`, middleware, testing, performance, or

19 version upgrades.

20bestFor:

21 - Legacy-to-modern stack moves where frameworks, runtimes, build systems, or

22 platform conventions need to change.

23 - Teams that need compatibility layers, phased transitions, and explicit

24 validation at each migration checkpoint.

25starterPrompt:

26 title: Migrate With Guardrails

27 body: >-

28 Migrate this codebase from [legacy stack or system] to [target stack or

29 system].

2 30 

3Codex use cases

4 31 

5![](/assets/OpenAI-black-wordmark.svg)32 Requirements:

6 

7![Codex](/assets/OAI_Codex-Lockup_Fallback_Black.svg)

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 33 

49- [Security Best Practices](https://github.com/openai/skills/tree/main/skills/.curated/security-best-practices)34 - Start by inventorying the legacy assumptions: routing, data models, auth,

35 configuration, build tooling, tests, deployment, and external contracts.

50 36 

51 Check risky migrations, dependency changes, and exposed surfaces before you merge.37 - Map the old stack to the new one and call out anything that has no direct

52- [Gh Fix Ci](https://github.com/openai/skills/tree/main/skills/.curated/gh-fix-ci)38 equivalent.

53 39 

54 Work through failing CI after each migration milestone instead of leaving cleanup until the end.40 - Propose an incremental migration plan with compatibility layers or

55- [Aspnet Core](https://github.com/openai/skills/tree/main/skills/.curated/aspnet-core)41 checkpoints instead of one big rewrite.

56 42 

57 Use framework-specific guidance when a migration touches ASP.NET Core app models, `Program.cs`, middleware, testing, performance, or version upgrades.43 - Keep behavior unchanged unless the migration explicitly requires a

44 user-visible change.

58 45 

59| Skill | Why use it |46 - Work in milestones and run lint, type-check, and focused tests after each

60| --- | --- |47 milestone.

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 48 

65## Starter prompt49 - Keep rollback or fallback options visible until the transition is

50 complete.

66 51 

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.52 - If validation fails, fix it before continuing.

76 - Start by mapping the migration surface and proposing the checkpoint plan.

77 53 

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.54 - Start by mapping the migration surface and proposing the checkpoint plan.

55relatedLinks:

56 - label: Modernizing your Codebase with Codex

57 url: /cookbook/examples/codex/code_modernization

58 - label: Follow a goal

59 url: /codex/use-cases/follow-goals

60 - label: Worktrees in the Codex app

61 url: /codex/app/worktrees

62---

90 63 

91## Introduction64## Introduction

92 65 

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.66When 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 67 

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.68Codex 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 69 

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.85In 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.86When 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 87 

111## Related use cases88## Combine with a goal

112 

113[![](/images/codex/codex-wallpaper-2.webp)

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)[![](/images/codex/codex-wallpaper-1.webp)

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)[![](/images/codex/codex-wallpaper-2.webp)

126 

127### Refactor your codebase

128 

129Use Codex to remove dead code, untangle large files, collapse duplicated logic, and...

130 89 

131Engineering Code](https://developers.openai.com/codex/use-cases/refactor-your-codebase)90For long-running migration slices, use a [goal](https://developers.openai.com/codex/use-cases/follow-goals) to guide Codex through the work. Set the goal with a clear end state, parity checks, rollback expectations, and a stopping condition.