use-cases/code-migrations.md +90 −0 added
1---
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].
30
31
32 Requirements:
33
34 - Start by inventorying the legacy assumptions: routing, data models, auth,
35 configuration, build tooling, tests, deployment, and external contracts.
36
37 - Map the old stack to the new one and call out anything that has no direct
38 equivalent.
39
40 - Propose an incremental migration plan with compatibility layers or
41 checkpoints instead of one big rewrite.
42
43 - Keep behavior unchanged unless the migration explicitly requires a
44 user-visible change.
45
46 - Work in milestones and run lint, type-check, and focused tests after each
47 milestone.
48
49 - Keep rollback or fallback options visible until the transition is
50 complete.
51
52 - If validation fails, fix it before continuing.
53
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---
63
64## Introduction
65
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.
67
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.
69
70## How to use
71
72
73
741. 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.
752. Ask Codex to map the legacy concepts to the target stack and call out what has no direct match.
763. Choose an incremental strategy: compatibility layer, module-by-module port, branch-by-abstraction, or a strangler-style replacement around one boundary at a time.
774. Keep behavior stable until the migration itself forces a visible change, and name those exceptions explicitly.
785. 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.
796. Review the diff and the remaining transition risk after each checkpoint instead of waiting for the full rewrite.
80
81
82
83## Leverage ExecPlans
84
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.
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.
87
88## Combine with a goal
89
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.