The prompt
Score 10 of 10, Excellent
Use it when You need a library or framework moved to a new major version, with breaking changes handled and the tests still passing.
- {{package}}
- {{current_version}}
- {{target_version}}
- {{reason}}
- {{usage_locations}}
- {{migration_notes}}
- {{related_packages}}
- {{check_commands}}
- {{max_files}}
- {{off_limits}}
Full prompt and why it works
Prompt
Goal: Upgrade {{package}} from {{current_version}} to {{target_version}} in this repository, so that we get {{reason}}, with no change in behavior for users. Context: - Where it is used, as far as I know: {{usage_locations}} - The official migration guide or changelog for this upgrade: {{migration_notes}} - Packages that depend on it or must move with it, as far as I know: {{related_packages}} - Test, build and type-check commands: {{check_commands}} Constraints: - Before editing, read the migration guide and search the codebase for every use of the APIs it lists as changed or removed. Reply with a plan: the breaking changes that affect us, the files each one touches, and any other package that must be upgraded with it. Wait for my go-ahead if the plan touches more than {{max_files}} files or needs another major upgrade. For example, the form of one plan line: "[old API] is removed in [version] and replaced by [new API] (guide section: [name]); used in 6 files under src/routes/." - Upgrade only {{package}} and what it strictly requires. Do not upgrade other dependencies along the way, and do not refactor or reformat code the upgrade does not need. - Base every code change on the migration guide or the library's own documentation, not on memory, because APIs change between versions. If neither covers a change you need, stop and ask. - Update the lockfile with the project's package manager. Do not edit the lockfile by hand. - Do not touch {{off_limits}}. Do not change, skip or delete tests to make them pass; if a test fails because the library behaves differently, report it. - Replace deprecated calls only where the new version removes them, and list the remaining deprecation warnings instead of fixing them all. Done when: - The manifest (package.json, requirements.txt, go.mod or equivalent) and the lockfile show {{target_version}}. - {{check_commands}} pass, with no new warnings from {{package}} other than the deprecations you listed. Verify: run the commands, read the output and iterate until they pass. Then report: each breaking change you handled with the file and the guide section it came from, files changed, the commands you ran with the last 20 lines of their output, and remaining deprecation warnings. If a change would alter behavior that a user could notice, stop and describe it before going further.
Variables
- {{package}}
- The library or framework, for example react-router or Django.
- {{current_version}}
- The version you are on now.
- {{target_version}}
- The version to move to.
- {{reason}}
- Why you are upgrading, for example "security fixes and support for Node 22".
- {{usage_locations}}
- Folders or files that use it heavily, or "not sure".
- {{migration_notes}}
- A link to the official migration guide, or the relevant section pasted in.
- {{related_packages}}
- Plugins or packages tied to it, or "not sure".
- {{check_commands}}
- The commands for tests, build and types, for example npm test && npm run build && npx tsc --noEmit.
- {{max_files}}
- The number of files above which the agent must check with you first, for example 15.
- {{off_limits}}
- Files, folders or systems that must not change, for example migrations or generated code.
Why it works
- Background facts. Changes come from the migration guide, not the agent's memory of the library, which is often a version or two out of date.
- What to avoid. Only this package moves, the lockfile is regenerated rather than hand-edited, and tests stay as they are, which keeps the diff reviewable.
- What good looks like. Done means the manifest shows the new version and the full checks pass, with each breaking change traced to a section of the guide.