What this prompt does
This turns an upgrade you've been avoiding into an ordered, verifiable plan. You give Claude Code the move you want — [project_type] from [current_version] to [target_version] — plus the context that actually changes the risk profile: project [project_size], key [dependencies], your [test_coverage], and any [known_breaking_changes]. It runs an impact analysis across the codebase, audits dependency compatibility, then produces migration steps grouped into safe (mechanical find-and-replace), medium-risk (logic with a clear path), and high-risk (behavioral changes needing real testing).
It works because it refuses to treat a migration as one big diff. Every change comes back with the files affected, before/after code, why it changed, and how to verify it — so you're reviewing decisions, not guessing. The plan also covers the parts people skip and then get burned by: deprecation cleanup, config-file updates, test changes, and a rollback procedure.
The load-bearing instruction is the last line: apply changes incrementally, leave the project working after each step, run tests between steps. That single constraint is what keeps you from a half-migrated codebase you can't bisect.
When to use it
- Stepping a framework up a major version (Laravel 10→11, Symfony, Rails, Django) where deprecations and config moved.
- A language runtime bump — PHP 8.1→8.3, Node 18→22 — where syntax and stdlib behavior shift under you.
- Swapping a library for a maintained replacement (Guzzle for an HTTP client, Moment for Day.js, a deprecated SDK).
- Inheriting a legacy or low-coverage codebase where you need the risk grouping before touching anything.
- Planning the migration before you start, so you can size the work and sequence it across PRs.
Example output
## Impact Analysis — Laravel 10 → 11 (medium app, 58% coverage)
Affected patterns found: 23 files
- Http/Kernel.php middleware registration (moved to bootstrap/app.php)
- 4 config files with renamed keys
- 9 deprecated Str:: helper calls
## Migration Steps
### Safe (automated)
1. Replace `$this->faker` → `fake()` — 6 test files
Verify: php artisan test --testsuite=Unit
### Medium-risk
2. Migrate Kernel.php → bootstrap/app.php
File: app/Http/Kernel.php → bootstrap/app.php
Why: L11 removed the HTTP kernel; middleware now registered fluently
Verify: php artisan route:list renders; auth middleware still applies
### High-risk
3. Carbon 3 upgrade: diffIn* now returns floats and can be negative
Why: direction-aware, fractional results break any code comparing diffs as ints
Verify: write a test pinning each diffIn* call site, then run it
## Rollback Plan
git revert per step; restore config/*.php from the pre-migration tag.
Pro tips
- Be honest in
[test_coverage]. Low coverage doesn't disqualify you — it tells the model to lean on manual verification steps and characterization tests instead of trusting a green suite that doesn't exist. - Front-load
[known_breaking_changes]with the upgrade guide's headline items. It stops Claude rediscovering documented breaks and frees its attention for the breaks your code introduces. - Run it once read-only for the plan, commit that plan, then execute step by step. Pair it with my "Dependency Audit & Cleanup" prompt first so you migrate a clean dependency tree, not a tangled one.
- Treat each risk tier as its own PR. Safe changes merge same-day; high-risk gets its own review. The grouping is the natural seam for splitting the work.
- Tag your repo before step one. The rollback plan assumes a clean point to revert to — give it one.
