Write a Framework Migration Prompt for a Staged Codebase Upgrade

A major-version framework bump is rarely one change. It's forty small ones scattered across services, and the failure mode is doing all forty in a single weekend PR that nobody can review or revert. A framework migration prompt turns that into a staged plan: inventory first, map each breaking change to an edit, ship in reversible increments.

The usual approach is to ask a model to "upgrade this file" one file at a time. That works until file twelve depends on an interface that changed in file three, and now you're debugging a migration you can't roll back. The problem isn't the model's code. It's that there was never a plan, just a pile of edits.

A reusable prompt encodes the plan. You describe the source and target once, and the same structure handles a React 18-to-19 jump or a Rails upgrade without you rewriting the workflow each time.

Why the "migrate this file" loop fails at scale

Migrating file by file feels like progress. Each file compiles, so you move on. The trap is interface drift: a signature you changed in an early file breaks callers you haven't reached yet, and you don't find out until the whole thing is half-converted.

Here's the stance worth defending. The hardest part of a framework migration isn't writing the new code. It's knowing the order. Get the sequence right and each step is boring. Get it wrong and you're holding a branch that's broken in both directions, too far along to revert and too incomplete to ship. A migration prompt's real output isn't code. It's a sequence.

What a framework migration prompt does

A framework migration prompt is a staged planner that reads your source and target framework versions and returns an inventory, a breaking-change map, a rollout sequence, and a rollback per stage. It plans before it touches a line.

Run it to:

• Catalog every place the source framework is used, per service
• Map each breaking change to the exact edit it requires
• Group edits into stages that ship and verify independently
• Define a go/no-go checkpoint between stages
• Produce a concrete rollback path for every stage
• Flag changes that can't be automated and need a human decision

The rollback-per-stage line is what separates a plan from a wish.

Anatomy of the prompt

Variables
  {{source_framework}}    → current framework + version
  {{target_framework}}    → target framework + version
  {{service_inventory}}   → services / packages in scope
  {{breaking_changes}}    → known breaking changes (or let the model derive)

Prompt
  Role: you are a staged migration planner.
  Task: plan the migration from {{source_framework}} to {{target_framework}}.
  Rules:
    - Inventory usage before proposing any edit.
    - Each stage must ship and verify independently.
    - Every stage needs a rollback path.

Output contract
  Return: inventory table + breaking-change map + staged plan + rollbacks.

1. Define source and target

Set {{source_framework}} and {{target_framework}} with versions. "React to React 19" is too vague; "React 18.2 to React 19.0" lets the model pull the right breaking-change set.

2. Scope the inventory

List the services in {{service_inventory}}. The inventory pass is the step people skip, and it's the one that catches the service nobody remembered was on the old version.

3. Read the staged plan

The output sequences edits into stages. Don't reorder them casually. The sequence exists because stage three assumes stage one already shipped.

4. Ship one stage at a time

Each stage is its own PR with its own rollback. Hit the go/no-go checkpoint, verify, then proceed.

Prompt-craft patterns for staged migrations

Inventory before edits, always. A prompt that proposes edits before it knows the full usage surface will miss callers. Force the inventory pass as a separate, earlier section so the model can't shortcut it.

Use variables for the stack, not hardcoded names. Hardcoding "React" makes the prompt single-use. The {{source_framework}} and {{target_framework}} variables make the same structure reusable across every migration you'll ever run.

Demand a rollback per stage. A migration plan with one rollback at the end is a plan with no rollback. Each stage's reversal has to be stated, or a mid-migration failure leaves you stranded.

Where Claude and ChatGPT diverge on staging

The two models plan migrations differently, and the difference shows up in how they stage. Claude tends to over-stage when you ask for safety: it'll split a migration into more, smaller steps than strictly needed, which is the right error to make. GPT-4o leans toward fewer, larger stages unless the "ship and verify independently" rule sits near the end of the prompt where it stays in attention.

Both models will quietly merge two breaking changes into one stage if the rule isn't explicit. So state it: each stage handles one breaking change or one cohesive group, never two unrelated ones bundled for convenience. Pin the model version too. A migration planner that subtly started batching more aggressively after an update is the kind of regression you won't catch until a stage you can't revert blows up. Restate the staging contract on the final line for GPT-4o; Claude holds it from a dedicated ## Staging rules heading. Neither model knows your deploy cadence, so the go/no-go checkpoint is where your judgment overrides the plan.

How this differs from a cross-language port

A framework migration stays in one language and changes the libraries around it. A cross-language port changes the language itself, which is a different prompt with different failure modes. If you're translating between languages rather than upgrading a framework, the cross-language refactor prompt handles the idiom-preservation problem that a framework bump doesn't have.

Variables you'll set

Getting started

1. Copy the staged structure into ChatGPT, Claude, or Gemini.
2. Set {{source_framework}} and {{target_framework}} with exact versions.
3. List your services in {{service_inventory}} so the inventory pass is complete.
4. Run it and read the staged plan before the breaking-change map.
5. Ship the stages in order, hitting the go/no-go checkpoint between each.
6. Keep the rollback for each stage handy until the next stage is verified.

For a migration spanning many services with go/no-go gates already wired in, the Framework Migration Harness Playbook runs the full sequence.

A framework upgrade often surfaces breaking API changes you'll need to communicate to consumers. The Breaking Change Detection Harness Agent Pack diffs two API surfaces and recommends the semver bump. For the database side of a major upgrade, the safe database migration prompt covers schema changes. New to buying packs versus rolling your own? Start with how to choose a reusable AI prompt pack.