Verified against Claude Code · 2026-08-04
Map a major dependency upgrade before Claude Code touches the lockfile
A pre-upgrade research prompt that has Claude Code cross-reference every breaking change in a dependency's release notes against real usage sites in the repo, catching the silent behavior changes a live-fire upgrade-and-fix-what-breaks approach reliably misses.
The prompt
Ready to copy — highlighted parts are example details you can swap.
You are planning an upgrade of Next.js from 15.4.2 to 16.2.12. Do not modify the lockfile, the package manifest, or any application code during this pass — this is research and mapping only, using the repository search and read access you already have, not a live upgrade attempt. CRITICAL PATHS THAT MUST NOT REGRESS The prompt library detail pages and the tool directory search must keep rendering exactly as they do today — these are the highest-traffic routes on the site. HOW THIS DEPENDENCY IS ACTUALLY USED HERE App Router throughout, no legacy pages directory; server components by default with a handful of explicit client components for interactive tools. PROCESS 1. Read the official changelog, release notes, or migration guide for every version between 15.4.2 and 16.2.12, not only the final target — a breaking change introduced in an intermediate minor version is still a breaking change this repo will pass through. 2. List every breaking change, deprecation, and default-behavior change found, each tagged with the version it landed in, in plain language a reviewer who has not read the release notes can follow. 3. For every item from step two, search this codebase for every usage site touching the changed API, prop, config key, or behavior. Cite exact files and line numbers — do not estimate or generalize to a whole module when a specific line is what actually matters. 4. Classify each usage site as SAFE, NEEDS CHANGE, or UNCERTAIN. UNCERTAIN means the static read alone cannot settle it and an actual test run against the new version would be needed to confirm — this is a legitimate answer, not a placeholder for more effort later. 5. Weight silent behavior and default-value changes more heavily than removals or renames in this analysis, specifically because a rename fails loudly at the type checker or build step, while a shifted default or a subtly different timing assumption passes every automated check and only surfaces as a production bug days or weeks later. 6. Propose a staged plan: whether the version jump should happen in one step or several, whether an official codemod exists and should run before any manual fix, and the order NEEDS CHANGE sites should be addressed in so each stage is independently testable rather than one large simultaneous change. OUTPUT A table of breaking change, affected usage sites, classification, and planned action. Then the staged plan as a numbered list. End with an honest confidence statement about the completeness of this mapping and specifically what would raise that confidence, such as running the existing suite against the new version on a disposable branch before touching the main codebase. Do not begin making any change until this plan is reviewed and approved.
Customize
Optional — swap in your own details for the highlighted parts above.
Why this works
The default failure mode for 'upgrade X to Y' is a live-fire approach: bump the version, run the build or type checker, and fix whatever complains, iterating until it is green — which works fine for changes that throw, but is structurally blind to changes that do not, like a default option flipping, a hook's timing shifting, or a prop silently being ignored instead of rejected. Forcing the changelog read and the usage-site mapping before any edit converts those silent risks into a named list before the upgrade starts, rather than relying on the test suite to happen to exercise every changed default by luck. The SAFE, NEEDS CHANGE, UNCERTAIN classification specifically creates a category for 'cannot know this without running it', rather than forcing a binary safe-or-not call the model is not actually in a position to make from static reading alone — an uncertain classification is honest, where a model pressured into a yes-or-no answer will often guess safe for a code path it did not fully trace, and that guess is exactly where a silent regression later hides. Requiring exact file and line citations rather than a general 'this affects the router' claim exploits the same repo-wide search capability that distinguishes an agentic coding assistant from a chat-only one reading pasted code — Claude Code can actually search the entire codebase for every call site of a changed API, which is the step that makes the difference between a plausible-sounding migration plan and one that is actually complete for this specific repository's real usage. Weighting silent default changes above loud removals reorders the plan's own attention against the model's natural instinct to lead with whatever the changelog itself lists first or most prominently, which is very often the headline removal, not the quieter default-value change buried three bullets down that a live-fire upgrade would never surface until it reached production. Requiring a staged plan, rather than one large simultaneous jump, also matters for a version range spanning several minors: it turns an all-or-nothing upgrade into a sequence of independently testable checkpoints, so a regression discovered at stage two is attributable to a small, known set of changes rather than to the entire multi-version jump at once.
What you get back
Breaking change table, excerpt: - useEffect cleanup timing changed (16.0) -> hooks/useSocketConnection.ts:34 -> NEEDS CHANGE, cleanup now fires before the next effect runs in an edge case this hook relies on the old ordering for. - forwardRef no longer required for function components accepting ref (16.0) -> components/ui/Input.tsx:1, Button.tsx:1 -> SAFE to simplify, not required. Staged plan: run the official codemod first, fix useSocketConnection.ts manually since no codemod covers it, then re-run the full suite plus a manual pass on the reports pages. Confidence: moderate on the hooks-timing change specifically — recommend running the reports integration tests against a 16.2 branch before merging.
Verified against
Claude Code Sonnet 4.6 · 2026-08-04
Cursor 2.1 · 2026-08-04
Changelog
- 2026-08-04 — Initial publish, verified against Claude Code (Sonnet 4.6) and Cursor 2.1.
Building this for real?
This is a free starting point. If you'd rather have custom software built and running for your business, that's Scult's day job.
EXPLORE CUSTOM SOFTWARE
