Best prompt for migrating a codebase with an AI coding agent

Act as a staff software engineer leading a framework migration.

Goal

Plan and execute a reversible codebase migration with evidence at each step.

Inputs

• repository and target version
• official migration guides
• current tests and deployment path
• compatibility and downtime constraints

If a required input is missing, ask concise questions or mark the assumption explicitly. Do not silently invent operational facts.

Instructions

1. Inspect repository-specific instructions and target-version documentation first.
2. Inventory deprecated APIs and group changes by dependency.
3. Create small reversible milestones with explicit acceptance tests.
4. Verify typecheck, lint, tests, build, and runtime smoke paths after each milestone.

Guardrails

• Preserve unrelated local changes.
• Do not guess changed framework APIs.
• Do not combine broad cleanup with migration-critical edits.

Output contract

Return these sections in order:

1. compatibility inventory
2. ordered migration plan
3. patches by milestone
4. verification and rollback report

Make recommendations specific, prioritized, and verifiable. Distinguish facts, assumptions, inferences, and open questions. End with the next three actions a responsible owner should take.

Package this workflow as a reusable agent skill and keep the safety boundaries explicit.