To plan a code migration with AI, freeze a verified inventory of the current and target systems, map dependencies and compatibility boundaries, and ask AI to organize candidate migration waves with entry gates, exit gates, observations, rollback triggers, and owners. Humans must choose the target architecture, approve irreversible decisions, and verify every stage. The model can draft a migration blueprint; it must not rewrite code or report a migration as complete.

This is more specific than a general AI project plan. A migration changes a live technical contract while old and new states may coexist. The general guide to using AI covers safe context and approval. Use this workflow to reason about sequence and evidence, not to delegate architecture authority.

Key Takeaways

Define the outcome and non-goals before selecting a migration technique.

Inventory runtime paths, data, state, dependencies, and owners.

Turn compatibility assumptions into explicit tests and gates.

Prefer reversible, observable waves where the system permits them.

Write rollback triggers and actions before cutover.

Stop at a human-approved blueprint; execution is a separate change workflow.

What should the migration achieve, and what is out of scope?

“Migrate the codebase” does not say what must change or why. Name the driver: unsupported runtime, library replacement, service decomposition, language transition, framework upgrade, deployment-platform change, contract consolidation, or security requirement. Define measurable outcomes without choosing an implementation prematurely.

Write a one-page charter:

Field	Question
Outcome	What capability or risk changes?
Non-goals	What must remain untouched?
Scope	Which repositories, services, clients, jobs, and data?
Constraints	Compatibility window, budget, freeze periods, regulation
Success	What observable conditions prove the outcome?
Authority	Who chooses architecture and approves cutover?

NIST's Secure Software Development Framework frames secure practices as risk-based activities that organizations adapt to their context.［1］ Use that mindset: rank migration risks by impact and evidence, rather than asking a model for a universal sequence.

Do not upload private repositories, credentials, production dumps, customer information, internal network details, or undisclosed vulnerabilities to an unapproved tool. Use minimal sanitized inventories, public interfaces, synthetic schemas, and controlled environments.

Freeze current and target inventories

Inventory the current system as it actually operates, not as an old diagram claims. Include executable entry points, libraries, build and deployment jobs, configuration, data stores, queues, scheduled tasks, external providers, clients, observability, access controls, and ownership. Attach source locations and versions.

Create a separate target inventory that distinguishes approved design from candidates. An item is not “target state” merely because AI suggested it. Use statuses such as current-confirmed, target-approved, candidate, unknown, and out-of-scope.

Item ID	Current	Target	Evidence	Owner	Status
R-01	Runtime A version x	Runtime B version y	Build files, release manifest	Platform	Target approved
Q-03	Queue consumer v1	Unknown	Deployment config	Service team	Unknown

Compare inventories to identify additions, removals, retained contracts, and ambiguous ownership. Do not let a generated summary erase an orphaned cron job or a rarely used client.

Which dependencies widen the blast radius?

Dependencies include more than package imports. Map synchronous calls, events, queues, shared schemas, database reads and writes, file formats, caches, feature flags, identity and authorization, deployment order, operational runbooks, and human processes. Record direction and evidence.

Ask AI to create candidate dependency edges only when each edge cites a file, configuration entry, contract test, or approved operational record. Unknown runtime discovery belongs in a separate validation plan. An import graph cannot prove every network or data dependency.

Rank consumers by migration risk:

contract sensitivity and release independence;
data ownership and statefulness;
traffic or business criticality;
ability to test in parallel;
ability to roll back independently;
owner availability and external coordination.

The output should reveal where a supposedly local library upgrade is actually coupled to serialization, database, or client behavior.

Build a migration compatibility matrix

A migration often fails at boundaries rather than in rewritten internals. List old producer/new consumer and new producer/old consumer combinations for API versions, events, schemas, files, caches, CLI flags, and persisted state.

Boundary	Old → old	Old → new	New → old	New → new	Evidence / test
Event schema	Baseline	Candidate	Candidate	Target	Contract test IDs
Stored record	Baseline	Read check	Rollback read	Target	Fixture IDs

Never mark a cell compatible from type similarity alone. Define the fixture, test, environment, expected result, and owner. Include semantic changes such as defaults, ordering, timeout, retries, error mapping, permission checks, and locale handling.

If backward compatibility is impossible, make the coordinated cutover and outage risk explicit. Do not hide it inside a generic task called “update consumers.”

Which migration pattern fits your constraints?

AWS describes the strangler fig pattern as gradually replacing functionality in a legacy system while old and new paths coexist, then decommissioning the old system after migration.［2］ It can reduce risk when routing and bounded capabilities permit gradual transfer; it is not automatically suitable for tightly coupled state or atomic consistency requirements.

Evaluate candidate patterns against the evidence:

in-place upgrade with compatibility shims;
branch by abstraction;
incremental routing or strangler approach;
shadow traffic or read-only comparison;
dual read, dual write, or event replication;
offline conversion with a maintenance window;
coordinated big-bang cutover when partial coexistence is unsafe.

Ask AI to compare prerequisites, reversible steps, state divergence risk, operational cost, and exit conditions. A human architecture owner selects the pattern and records the rationale. Dual write, for example, can improve transition flexibility but introduces ordering, partial-failure, reconciliation, and rollback complexity.

How should data and state be planned explicitly?

Code can be redeployed; state may not be reversible. Inventory schema changes, backfills, identifiers, timestamps, encodings, indexes, constraints, retention, event offsets, cache keys, sessions, and derived data. Define the source of truth during every phase.

For each transformation, document:

input and output schema versions;
deterministic conversion rule;
validation sample or reconciliation query;
handling of invalid or late-arriving records;
checkpoint and restart behavior;
forward compatibility and rollback-read behavior;
backup, retention, and restoration evidence;
owner and approval.

Do not claim a backup is usable until restoration has been tested in an appropriate environment. Do not place real production data in the model context; use schema-only or synthetic samples unless an approved private workflow explicitly allows otherwise.

Plan a code migration with AI in gated waves

Microsoft's migration planning guidance emphasizes dependency discovery, migration sequencing, workload grouping, rollback planning, and migration waves rather than treating all workloads identically.［3］ Create waves small enough to observe and reverse, while respecting dependencies.

Each wave needs:

Field	Purpose
Scope	Exact components, consumers, and data
Entry gate	Evidence required before starting
Change	Approved technical action, not generated code
Observation	Metrics, logs, traces, contract tests, reconciliation
Hold period	Time or sample required before expansion
Exit gate	Conditions for proceeding
Rollback trigger	Measurable condition that stops the wave
Owner	Person authorized to decide

Begin with infrastructure and test capabilities that reduce uncertainty when appropriate: contract tests, telemetry, routing control, data reconciliation, or compatibility adapters. Do not call a wave “low risk” without explaining the evidence and remaining blast radius.

Design parallel runs and comparisons

When the system permits it, shadow execution or dual runs can compare outputs before transferring authority. Define which side is authoritative, how side effects are suppressed, how requests are sampled, and how nondeterministic fields are normalized. Never send production writes to an unapproved shadow path.

Create comparison classes:

exact equality for identifiers or canonical serialization;
tolerance bands for numerical or timing output;
set or order-insensitive comparison where contract permits;
semantic equivalence approved by a domain owner;
manual review for cases that cannot be automated.

Record mismatch categories and ownership. A high aggregate match rate can conceal a critical authorization or money-handling mismatch, so define severity gates rather than one headline percentage.

Make observability part of the plan

Choose signals before migration: availability, latency, error classes, resource use, queue delay, data reconciliation, authorization denials, client versions, and business invariants. Establish a known baseline and distinguish migration-specific telemetry from normal monitoring.

Every signal needs a query or dashboard reference, expected range, collection interval, retention, owner, and action threshold. AI can help format the catalog or propose missing categories; it cannot invent baseline values or assert that a dashboard exists.

Include negative evidence. If a legacy path should receive no traffic after a wave, measure that. If old-format records should no longer be created, query for them. Exit criteria should prove both that the target works and that the retired path is no longer authoritative.

What must the migration rollback plan cover before cutover?

Rollback is a tested transition, not the phrase “revert if needed.” Define triggers, decision authority, maximum decision time, routing action, deploy action, state handling, client communication, and verification. Separate code rollback from data rollback: the old binary may not understand records written by the new version.

Use a rollback table:

Trigger	Threshold	Decision owner	Action	State treatment	Verification
Contract mismatch	Any critical class	API owner	Route to old path	Stop new writes, reconcile	Contract suite + counters

Test the mechanism before relying on it. If a change is irreversible, say so and define prevention, backup, compensating action, and higher approval. Do not let the model soften “irreversible” to “difficult to revert.”

When is a migration actually complete?

Microsoft's modernization guidance recommends logical phases aligned to business value, technical dependencies, success criteria, and rollback planning.［4］ Migration completion should include retirement, not merely target deployment.

Define exit conditions such as:

compatibility and contract suites pass for the frozen scope;
reconciliation meets per-class thresholds;
required hold period completes without a rollback trigger;
all supported clients have moved or received an approved exception;
new state is authoritative and backup/restore evidence is current;
legacy traffic, jobs, credentials, flags, and writes are removed;
documentation, ownership, alerts, and runbooks match the target;
the named decision authority approves retirement.

Archive the evidence bundle and unresolved exceptions. A migration with a permanent “temporary” adapter is not necessarily failed, but its owner, cost, and review date must be explicit.

Use a copyable migration blueprint

# Code migration blueprint
- Outcome:
- Non-goals:
- Frozen evidence reference:
- Current inventory:
- Approved target inventory:
- Unknowns:
- Architecture decision owner:

## Boundary
- Consumer / producer:
- Current contract:
- Target contract:
- Compatibility tests:
- Data / state impact:

## Wave
- Scope:
- Dependencies:
- Entry gate:
- Approved change:
- Parallel-run method:
- Observations and thresholds:
- Hold period:
- Exit gate:
- Rollback trigger and action:
- Owner:

## Completion
- Reconciliation:
- Legacy retirement:
- Documentation / runbooks:
- Exceptions:
- Human approval:

Prompt AI to find empty fields, unsupported assumptions, cycles, missing owners, and rollback gaps. Do not ask it to generate and apply the migration in the same approval. Before executing any generated change, review it with the AI-generated code checklist and your repository's change process.

FAQ

Can AI choose the target architecture?

It can compare documented options and constraints. Accountable engineers must choose and approve the architecture because the decision includes context, risk, and ownership outside the prompt.

Is an incremental migration always safer?

No. Coexistence can create routing, compatibility, and state-divergence risk. Choose the pattern from system constraints and tested rollback options.

How should database migrations be handled?

Plan schema compatibility, backfill, invalid records, checkpoints, reconciliation, backup, restore, and rollback-read behavior separately from code deployment.

What is the difference between a project plan and migration blueprint?

A project plan coordinates work broadly. A migration blueprint models technical coexistence, compatibility, state authority, gated cutover, and retirement.

When is a big-bang cutover reasonable?

When partial coexistence is impossible or riskier, and the team has an approved window, complete rehearsal, strong verification, recovery options, and clear authority.

Can AI generate migration code from this plan?

That should be a separate, scoped change with code review and tests. Approval of the blueprint is not approval of generated implementation.

What if an unknown dependency appears during a wave?

Stop at the relevant gate, record evidence, reassess blast radius and compatibility, and obtain approval before changing the wave.

When is the migration finished?

When target behavior and state meet approved gates, clients have transitioned, exceptions are owned, legacy authority is removed, and retirement is approved.

Sources

Sources checked 29 August 2026.

NIST, “Secure Software Development Framework” — https://csrc.nist.gov/projects/ssdf
AWS Prescriptive Guidance, “Strangler fig pattern” — https://docs.aws.amazon.com/prescriptive-guidance/latest/cloud-design-patterns/strangler-fig.html
Microsoft Cloud Adoption Framework, “Plan a cloud migration” — https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/migrate/plan-migration
Microsoft Cloud Adoption Framework, “Plan cloud modernization” — https://learn.microsoft.com/en-us/azure/cloud-adoption-framework/modernize/plan-cloud-modernization

How to Plan a Code Migration with AI