How long should a migration take?

For a roughly 50k-LOC app, plan 2–4 quarters in slices. Faster only if the scope is genuinely narrow (a single bounded context or one framework version bump).

Should we pause features during the migration?

No. A paused product churns users. Slice the migration so feature work keeps shipping alongside it.

When is a rewrite better than strangler fig?

Almost never. The honest case is a system that is provably abandoned, with no active users, where downtime is acceptable.

Should AI write the migration code itself?

Yes for mechanical transformations (a codemod scopes most framework upgrades). No for cut-over decisions and data-consistency logic — keep a human on those.

Which AI model is best for the plan itself?

One with a 1M-token window so it sees the whole dependency graph. As of June 2026 that is Claude Opus 4.7 for the hardest cross-file reasoning, with Sonnet 4.6 or Gemini 3.1 Pro for cheaper passes.

What's the single most common failure mode?

No phase exits and no kill criteria, so sunk cost carries a doomed migration forward. Define both before phase one.

Prompt Library

Migration Plan Prompts: 12 Templates for Framework / DB / Auth Moves

12 migration prompts that produce a real phased plan with rollback at every step, not "rewrite everything". Covers Next.js App Router, Postgres, auth swaps, monolith→service, monorepo.

Published: May 19, 2026 Updated: Jun 09, 2026 Author: AI Productivity Guide Team 🌐 查看中文版本

Most migration plans fail because they read like a Gantt chart instead of a strategy. A good migration prompt forces the AI to pick a pattern (strangler fig, shadow, or dual-write), name the rollback at every phase, set measurable phase exits, and treat the parts you do NOT migrate as first-class. The 12 templates below do exactly that. Paste one, fill the bracketed variables, and you get a plan you can defend in a review meeting.

TL;DR

Use these prompts to turn “we should migrate” into a sliced, reversible plan with kill criteria.
The non-negotiables every prompt enforces: a co-existence seam, a low-risk first slice, a rollback per phase, and a drift check on any dual-write.
Run them on a model with a 1M-token window (Claude Opus 4.7, Sonnet 4.6, or Gemini 3.1 Pro as of June 2026) so it reasons over the whole dependency graph instead of a chunked fragment.
Pair the plan with vendor codemods where they exist (for example npx @next/codemod@canary upgrade latest for Next.js) so the AI scopes the manual work, not the mechanical part.

Who this is for

Tech leads scoping a framework or database migration, founders weighing an auth-provider switch, and staff engineers stuck with a three-year-old codebase that has to move forward without freezing the feature pipeline.

When not to use these prompts

Skip them for a green-field rewrite. That is a fresh project, not a migration, and these prompts will fight you. Skip them when “we should migrate” has not been justified yet: the output will rationalize a bad call instead of questioning it. Decide WHY first, then plan the HOW here.

Which model to run these on

Migration reasoning lives or dies on whether the model can hold the whole dependency graph at once. Chunking a codebase fragments exactly the cross-file relationships the plan depends on, so a 1M-token context is the right tool here, not a nice-to-have. All three flagship models below ship 1M-token context as of June 2026.

Model	Context	SWE-bench Verified	Best fit for migration work
Claude Opus 4.7	1M tokens	87.6%	Deepest cross-file refactor reasoning; cut-over and data-consistency planning
Claude Sonnet 4.6	1M tokens	—	The everyday workhorse; cheaper passes over a large repo (API: $3/$15 per 1M)
Gemini 3.1 Pro	1M tokens	80.6%	Ingesting an entire monorepo plus docs in one prompt (API: $2/$12 per 1M)

For the heavy planning prompts (templates 1, 2, 4, 5), reach for Opus 4.7. For the mechanical conversions (7, 10) where a vendor codemod does most of the lifting, Sonnet 4.6 or Gemini 3.1 Pro is plenty. See the ChatGPT vs Claude vs Gemini comparison if you are choosing a default.

Prompt anatomy

Every migration-plan prompt below carries six elements. If a prompt of your own is producing mush, it is almost always missing one of them:

Role: who the AI plays (release captain, SRE, staff engineer).
Context: repo, framework, runtime version, branch, the diff or the failing logs.
Goal: one concrete deliverable (a phased plan, a risk register, a cut-over checklist).
Constraints: what the AI must NOT do (no big-bang, no silent version guesses, no auto-applied changes).
Output format: numbered phases, a markdown table, or a JSON risk register.
Signal: one example of good output, or a description of what bad output looks like.

Best for

Framework major upgrade (Next.js Pages Router → App Router, or 14 → 16)
Database engine swap (MySQL → Postgres)
Auth-provider migration (custom → Auth0 / Clerk / WorkOS)
Monolith → service split for one bounded context
Monorepo tooling migration (lerna → turborepo / nx / pnpm workspaces)

12 copy-ready prompt templates

Variables are written as [likeThis]. Swap the bracketed text for your real systems before sending.

1. Strangler fig plan

Design a strangler-fig migration from [oldSystem] to [newSystem].
Identify: (1) the seam (router / facade / proxy) where old and new run
side by side, (2) the first slice to migrate — low-risk, high-learning,
(3) the sequence of next slices, (4) the rollback at each slice. Use the
four phases: identify, transform, co-exist, eliminate. Stop at the seam;
do NOT propose a big-bang rewrite.

Swap: oldSystem, newSystem

2. Dual-write plan for a DB migration

Plan a dual-write migration from [oldDb] to [newDb]. Phases:
(1) write to both, read from old, (2) read from new but compare with old
to measure drift, (3) read from new only, (4) stop writing to old. For
each phase give: duration target, drift tolerance (as a %), and rollback.
Include a spec for the consistency-check job, and name the columns most
likely to drift (timestamps, JSON blobs, generated IDs).

Swap: oldDb, newDb

3. Next.js Pages Router → App Router migration

Plan an incremental Next.js Pages → App Router migration. Don't propose a
single rewrite. Order: (1) layout + leaf marketing pages, (2) data-fetch
utilities to the RSC pattern, (3) auth-gated pages, (4) dynamic routes
last. For each: which behaviors need a recheck (caching, headers,
redirects, async cookies()/headers()). Scope what the official
@next/codemod can do automatically vs what must be hand-migrated.

Run the vendor codemods first so the AI only plans the manual remainder. As of June 2026 the App Router migration tooling is automated via npx @next/codemod@canary upgrade latest, which updates Next.js, React, and React DOM and runs the bundled codemods (use --dry for a preview). From Next.js 16.1+, next upgrade works directly through your package manager. The async-API codemod is the big one: cookies(), headers(), and draftMode() are now async and must be awaited. See the official App Router migration guide.

4. Auth-provider swap

Plan a migration from [oldAuth] to [newAuth]: (1) user-table mapping
(id, email, hashed pw, sessions, MFA factors), (2) migration mode —
hard cutover vs gradual (verify against old on sign-in, then sync to new),
(3) session and refresh-token preservation, (4) rollback to old auth,
(5) user comms if a password reset or re-consent is needed. Flag every
place a token is read, minted, or verified.

Swap: oldAuth, newAuth

5. Monolith → service extraction

Extract [boundedContext] from a monolith into its own service. Plan:
(1) identify the schema tables owned by this context, (2) build an API in
the monolith for outside callers, (3) mirror to the new service,
(4) move callers, (5) remove monolith code last. For each step: data
ownership, transactional boundaries that break across the network, and
rollback. Call out any cross-context foreign key or join.

Swap: boundedContext — e.g., billing, search, notifications

6. ORM migration

Migrate from [oldOrm] to [newOrm]. Don't rewrite all models at once.
Plan: (1) read-only models first, (2) new writes use the new ORM, old
writes keep the old, (3) convert by domain, not file order. List the 5
most-used queries likely to behave differently between the two ORMs
(N+1 defaults, lazy vs eager loading, transaction semantics, raw SQL
escape hatches).

Swap: oldOrm, newOrm — e.g., sequelize → prisma

7. JS → TS migration

Plan a JS → TS migration: (1) add a tsconfig with allowJs: true,
(2) migrate files leaf-first (utilities before app code), (3) add real
per-file types — don't blanket-cast to any, (4) turn on strict
incrementally, one directory at a time. Don't propose a single rewrite.
Include a CI gate that fails the build on any new `any`.

8. Frontend state-management swap

Migrate from [oldState] to [newState]. Phases: (1) co-exist — new store
used only for new features, (2) move read-heavy slices, (3) move
write-heavy slices, (4) remove old. For each: how to keep the two stores
in sync during co-existence, and how to roll back per slice.

Swap: oldState, newState — e.g., redux → zustand

9. Cloud-provider lift-and-shift

Plan a migration of [service] from [oldCloud] to [newCloud]. Phases:
(1) replicate infra in the new cloud with IaC, (2) mirror traffic at 1%
to compare, (3) cut DNS over in a low-traffic window, (4) decommission
old. List the parity checks: p99 latency, monthly cost, data residency,
secrets, and IAM role mapping.

Swap: service, oldCloud, newCloud

10. Monorepo tooling migration

Migrate from [oldTool] to [newTool] (e.g., lerna → turborepo). Phases:
(1) run side by side — CI runs both, (2) migrate package by package,
(3) move root scripts last, (4) remove old. For each package: dependency
graph audit, cache keys, and build-script differences.

Swap: oldTool, newTool

11. Risk register for any migration

For this migration plan, build a risk register: each row = (risk,
probability L/M/H, impact L/M/H, owner, mitigation). Top risks must
include: data loss, downtime, performance regression, a security gap
during the transition, and stakeholder fatigue. Don't list trivial risks.
Output as a markdown table.

12. Migration kill criteria

Define KILL CRITERIA for this migration before we start: under what
conditions do we revert and call the migration unsuccessful? Examples:
(1) a phase takes more than 2x its budget, (2) drift exceeds 0.1% during
dual-write, (3) error rate stays more than +5% above baseline for 24h.
Name who has the authority to call it.

Common mistakes

Big-bang migration. One bug in production means a full rollback. Strangler fig ships value per slice instead.
No rollback at each phase. You commit further than you can safely retreat from.
No drift check during dual-write. The two stores silently diverge and you find out from a customer.
Migrating the hardest piece first. Burns the team and produces no early win to point at.
No kill criteria. Sunk cost keeps a failing migration alive long past the point it should have been called.
Skipping the shadow phase on critical data. You trust the new system without proof it agrees with the old one.
Doing the migration AND new features in one sprint. Neither finishes.

How to push results further

Default to strangler fig over a rewrite until a rewrite is proven necessary.
Make the first slice low-risk and high-learning: marketing pages, read-only models, low-traffic endpoints.
Treat dual-write as “write to both PLUS run a drift-check job”, never just “write to both”.
Write phase exits as measurable criteria, not “looks ok”.
Put the rollback in the same PR as the migration step, so reverting is one click.
Treat the plan as a living document and update it after every phase.
Over-communicate. Stakeholders read “no news” as “stuck”.

FAQ

How long should a migration take?: For a roughly 50k-LOC app, plan 2–4 quarters in slices. Faster only if the scope is genuinely narrow (a single bounded context or one framework version bump).
Should we pause features during the migration?: No. A paused product churns users. Slice the migration so feature work keeps shipping alongside it.
When is a rewrite better than strangler fig?: Almost never. The honest case is a system that is provably abandoned, with no active users, where downtime is acceptable.
Should AI write the migration code itself?: Yes for mechanical transformations (a codemod scopes most framework upgrades). No for cut-over decisions and data-consistency logic — keep a human on those.
Which AI model is best for the plan itself?: One with a 1M-token window so it sees the whole dependency graph. As of June 2026 that is Claude Opus 4.7 for the hardest cross-file reasoning, with Sonnet 4.6 or Gemini 3.1 Pro for cheaper passes.
What’s the single most common failure mode?: No phase exits and no kill criteria, so sunk cost carries a doomed migration forward. Define both before phase one.

Tags: #Prompt #Coding #Migration #Refactor