AI AI Tools Guidebook
Prompt Library

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

Migration prompts that produce a real phased plan — not "rewrite everything in Rust". 12 templates for Next.js, React Router, Postgres, auth provider, monorepo, monolith→service.

Published: Author: AI Productivity Guide Team 🌐 查看中文版本

Most migration plans fail because they’re a Gantt chart, not a strategy. A good migration prompt forces phasing (strangler? shadow? dual-write?), names the rollback at each phase, and treats the parts you DON’T migrate as first-class.

Who this is for

Tech leads scoping a framework or DB migration, founders evaluating an auth provider switch, staff engineers stuck with a 3-year-old codebase that needs to move forward without halting features.

When not to use these prompts

Don’t use these to plan a green-field rewrite — that’s a fresh project, not a migration. Don’t use them when “we should migrate” hasn’t been justified — output will rationalise a bad call.

Prompt anatomy / structure formula

Every migration plan prompt should carry six elements:

  • Role: who the AI plays (release captain / QA lead / SRE / staff engineer).
  • Context: repo / framework / runtime / branch / diff / failing logs.
  • Goal: one concrete deliverable — checklist, plan, test file, review notes, root cause, ticket list.
  • Constraints: what AI MUST NOT do (don’t auto-fix, don’t silently rewrite, don’t guess versions).
  • Output format: numbered findings, markdown table, JSON schema, unified diff, or runnable code.
  • Examples / signal: 1-2 examples of “good” output, or what bad output looks like.

Best for

  • Framework version major upgrade (Next 12 → 14)
  • Database engine swap (MySQL → Postgres)
  • Auth provider migration (custom → Auth0 / Clerk)
  • Monolith → service split for one bounded context
  • Monorepo migration (lerna → turbo / nx / pnpm workspaces)

12 copy-ready prompt templates

1. Strangler pattern plan

Design a strangler-pattern migration from `{oldSystem}` to `{newSystem}`. Identify (1) the seam (router / facade / proxy) where old and new live side by side, (2) the first slice to migrate (low-risk, high-learning), (3) sequence of next slices, (4) rollback at each slice. Stop at the seam — don't propose big-bang.

Variables to swap: oldSystem, newSystem

2. Dual-write plan for 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 for drift, (3) Read from new only, (4) Stop writing to old. For each phase: duration target, drift tolerance, rollback. Include consistency-check job spec.

Variables to swap: oldDb, newDb

3. Next.js / Pages → App Router migration

Plan an incremental Next.js Pages → App Router migration. Don't propose a single rewrite. Order: (1) Convert layout + leaf marketing pages, (2) Move data-fetch utilities to RSC pattern, (3) Migrate auth-gated pages, (4) Migrate dynamic routes last. For each: which features need recheck (caching, headers, redirects).

4. Auth provider swap

Plan a migration from `{oldAuth}` to `{newAuth}`: (1) User-table mapping (id, email, hashed pw, sessions), (2) Migration mode: hard cutover vs gradual (sign-in with old, sync to new), (3) Session preservation, (4) Rollback to old auth, (5) Comms to users (if email needed). Flag every place tokens are read.

Variables to swap: oldAuth, newAuth

5. Monolith → service extraction

Extract `{boundedContext}` from a monolith into its own service. Plan: (1) Identify schema rows owned by this context, (2) Build an API in the monolith for outside callers, (3) Mirror to new service, (4) Move callers, (5) Remove monolith code last. For each: data ownership, transactional boundaries, rollback.

Variables to 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 new ORM, old writes keep old, (3) Convert by domain, not file order. List the 5 most-used queries that are likely to behave differently between ORMs.

Variables to swap: oldOrm, newOrm — e.g., sequelize → prisma

7. JS → TS migration

Plan a JS → TS migration: (1) Add tsconfig with `allowJs: true`, (2) Migrate files leaf-first (utilities), (3) Add per-file types, don't make everything `any`, (4) Turn on `strict` incrementally per directory. Don't propose a single rewrite. Include CI gates for "no new `any`".

8. Frontend state-management swap

Migrate from `{oldState}` to `{newState}`. Phases: (1) Co-exist, new state used only for new features, (2) Move read-heavy slices, (3) Move write-heavy slices, (4) Remove old. For each: how to keep them in sync, how to roll back per slice.

Variables to 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 new cloud with IaC, (2) Mirror traffic at 1% to compare, (3) Cut over DNS at low-traffic window, (4) Decommission old. List parity checks: latency, costs, data residency, secrets, IAM mapping.

Variables to 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, build script differences.

Variables to swap: oldTool, newTool

11. Risk table 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 should include: data loss, downtime, performance regression, security gap during transition, stakeholder fatigue. Don't list trivial risks.

12. Migration kill criteria

Define KILL CRITERIA for this migration before starting: under what conditions do we revert and consider the migration unsuccessful? Examples: (1) Phase X takes > 2x budget, (2) Drift > 0.1% in dual-write, (3) Error rate sustained > +5%. Document who has authority to call it.

Common mistakes

  • Big-bang migration — one bug in production = full rollback.
  • No rollback at each phase — you commit further than you should.
  • No data drift check during dual-write — silently diverges.
  • Migrating the hardest piece first — burns the team, no early wins.
  • No kill criteria — sunk-cost keeps a failing migration alive.
  • Skipping a write-shadow phase on critical data — you trust the new system without proof.
  • Doing the migration AND new features in one sprint — neither finishes.

How to push results further

  • Strangler > rewrite — always, until proven otherwise.
  • First slice should be low-risk, high-learning. Marketing pages, read-only models, low-traffic endpoints.
  • Dual-write means a drift-check job, not just “write to both”.
  • Define phase exits with measurable criteria, not “looks ok”.
  • Build the rollback into the same PR as the migration step.
  • Migration plans are living docs. Update after each phase.
  • Communicate often — stakeholders mistake “no news” for “stuck”.

FAQ

  • How long should a migration take?: For a 50k LOC app: 2-4 quarters in slices. Less only if scope is narrow.
  • Should we pause features during migration?: No — paused product = churned users. Slice the migration so features can still ship.
  • When is rewrite better than strangler?: Almost never. Maybe if the old system is provably abandoned and downtime is acceptable.
  • Should AI write the migration code?: Yes for boilerplate transformations. No for cut-over decisions and data consistency code.
  • How do I know when to stop?: Define exit criteria up-front. Common one: “no production read still hits the old system for 14 days.”
  • What’s the most common migration failure mode?: No phase exits, no kill criteria, sunk-cost continuation.

Tags: #Prompt #Coding #Migration #Refactor

Related Articles