18.5 Migrating frameworks or libraries with AI help

Goal: migrate safely in chunks

Migrations (frameworks, libraries, major versions) are high-risk because they touch many files and can break behavior subtly.

Your goal is to use AI to:

• plan a safe migration path,
• split work into reviewable chunks,
• keep the system working throughout,
• avoid “big bang” rewrites.

Why migrations are hard (even with AI)

• behavioral differences between versions,
• API surface changes,
• test brittleness,
• dependency conflicts,
• hidden assumptions in production usage.

AI may confidently propose changes that compile but break runtime behavior. That’s why verification gates matter.

A migration strategy that works

1. Baseline: make sure tests pass on current system.
2. Map: identify impacted modules and entrypoints (system map).
3. Plan: write a stepwise plan with intermediate “green” states.
4. Chunk: migrate one area at a time with diff-only changes.
5. Verify: tests + runtime smoke checks after each chunk.
6. Rollout: feature flags or toggles if needed.

This strategy keeps the system working while you migrate.

Chunking: how to split the migration

Good chunking strategies:

• by module boundary (migrate module A, then B)
• by entrypoint (CLI first, then worker, then server)
• by compatibility layer (introduce adapter that supports old + new, then remove old)
• by feature flag (route some paths to new implementation)

Bad chunking strategy: “change everything everywhere.”

Verification gates (tests, lint, runtime checks)

Define your gates before the migration starts:

• unit tests must pass
• integration tests must pass
• lint/typecheck (if applicable)
• one or two runtime smoke checks

Gates are how you keep the migration from silently breaking behavior.

Copy-paste migration prompts

Prompt A: migration plan only

We are migrating from [old] to [new].

Context:
- System map: (paste)
- Constraints: no big bang rewrites; keep system working; diff-only changes

Task:
Propose a stepwise migration plan with 5–15 steps.
For each step:
- files/modules in scope
- verification gate (tests/commands)
- rollback strategy if it fails

Stop after the plan.

Prompt B: implement one migration step

Implement step N only from the approved plan.

Constraints:
- Diff-only changes
- Only touch files in scope for this step
- Do not refactor unrelated code
- After the diff, restate how to verify

Common migration risks (and mitigations)

• Hidden behavior differences: add characterization tests before changing.
• Dependency conflicts: resolve in small steps; avoid upgrading everything at once.
• Large diffs: enforce scope caps and line budgets; split steps.
• Runtime-only failures: add smoke checks; run a small staging rollout.

Where to go next

• 19. Debugging & incident response
• Back to 18.3 (safe refactors)