Dependency Upgrade Protocol
Claude CodeSKILL.mdCoding
Upgrade dependencies without surprises: changelogs before commands, one major at a time, lockfile diff review, and smoke tests per step.
Use when: Use when bumping dependencies — routine maintenance, a security advisory, or a major-version migration — rather than running a blanket update command.
Get this skill
Add the skill file with the CLI, by hand, or over MCP.Save this to your project or home directory so Claude Code can load it.
npx goodprompts add dependency-upgrade-protocolSaves to
~/.claude/skills/dependency-upgrade-protocol/SKILL.mdnpx goodprompts add dependency-upgrade-protocolSaves to
~/.claude/skills/dependency-upgrade-protocol/SKILL.mdSkill file
SKILL.md3,615 characters# Dependency Upgrade Protocol
A dependency upgrade is a code change written by strangers. Read what changed before running anything, and upgrade in steps small enough to bisect.
## Step 0 — Inventory and triage
1. List outdated packages (`npm outdated`, `pip list --outdated`, `cargo outdated`, etc.) and any security advisories (`npm audit`, Dependabot alerts).
2. Triage into three buckets and handle them in this order:
- **Security patches** — do first, separately, smallest possible scope.
- **Patch/minor bumps** — batch is acceptable, but only within one ecosystem area at a time (e.g. all eslint plugins together, not eslint + the ORM).
- **Major bumps** — one package per branch/PR. No exceptions. A PR with two majors and a regression is unbisectable.
## Step 1 — Read before you run
For each package being bumped (mandatory for majors, skim for minors):
- Read the changelog/release notes for *every version between current and target*, not just the target. Breaking changes hide in the minors you skipped.
- Specifically hunt for: removed/renamed APIs you use (grep your codebase for each), changed defaults, new peer-dependency or engine requirements (Node/Python version), license changes.
- Check the migration guide if one exists; majors with codemods (`npx @lib/codemod`) — plan to use them.
- Note the release date. A major released last week has undiscovered bugs; unless you need it, let it bake or pin the previous major.
## Step 2 — Upgrade and review the lockfile
- Bump the manifest explicitly to the intended version — avoid wildcard "update everything" commands, which hide unrelated transitive jumps.
- **Read the lockfile diff.** It is part of the code review, not noise:
- Expected package moved to the expected version? Any *other* top-level packages moved that you didn't ask for?
- New transitive dependencies appearing — what are they, who pulls them in? A bump that adds 40 packages deserves a raised eyebrow and a look at the heaviest additions.
- Integrity hashes changed for packages whose versions didn't — that's wrong; investigate.
- Resolved URLs still point at your expected registry (catches registry/typosquat substitution).
- Install with the lockfile-respecting command (`npm ci`, `pip-sync`, frozen lockfile) in a clean state, so what you test is what CI and prod will get.
## Step 3 — Verify in widening circles
1. Typecheck + lint + full unit/integration suite. Type errors after a bump are the cheap gift — fix them, they're the documented breakage.
2. Run the package's own surface deliberately: if you bumped the ORM, run the migration and a few real queries; HTTP client → exercise a request with retries/timeouts; build tool → compare production build output size and run the built artifact, not just the dev server.
3. Smoke test the app end to end: boot it, click through (or run e2e for) the two or three critical flows. Runtime behavior changes — changed defaults, stricter parsing — don't show up in unit tests with mocks.
## Step 4 — Land it bisectably
- One commit per package (or tightly-related group), message naming old → new version and any code changes the bump forced: `chore(deps): zod 3.24 → 4.0; migrate .nonempty() to .min(1)`.
- Code adaptations go in the *same* commit as the bump that requires them — a commit where the suite fails until the next one breaks bisect.
- In the PR description: link the changelog, list the breaking changes that applied to you, state what you smoke-tested.
- After deploy, watch error rates for the affected paths; know the revert is a one-commit revert because you kept it atomic.