AI AI Tools Guidebook
AI Tool Tutorials

AI Dependency Upgrade Workflow: CHANGELOG Mapping + No Drift

Upgrade a dependency that is several majors behind using Claude Code or Cursor, without subtle build breaks. CHANGELOG-mapped diffs, exact commands, June 2026.

Published: Updated: Author: AI Productivity Guide Team 🌐 查看中文版本

Dependency upgrades fail in the same four places: deprecated APIs the type checker can’t see, behavior changes inside functions whose signatures never moved, peer-dependency conflicts that resolve quietly into the wrong version, and runtime regressions no unit test catches. An AI coding agent handles all four well — but only if you give it the structure it needs: the official CHANGELOG, a breaking-change list mapped to your actual files, and a fix loop that refuses to drift into refactoring.

TL;DR

  • Branch from green main, then upgrade exactly one package per pull request. Never npm audit fix --force blind.
  • Ground the agent in the published CHANGELOG, not its training data. Make it return a table mapping each breaking change to file:line in your repo.
  • Catalog every test failure first, then match each one to a CHANGELOG entry. An unmatched failure means you missed a breaking change.
  • Fix with minimal diffs that adopt the new API; revert any stylistic refactor the agent slips in.
  • Type checks pass is not “done.” Run the app and smoke-test before you ship. Pin or overrides any transitive major you did not approve.

What this tutorial solves

You inherit a project where a critical dependency is twelve majors behind, or a security advisory drops at 5pm Friday and the patched version sits behind two breaking releases. CI is green but you do not trust the version pin. This workflow lets one developer plus an AI agent do the upgrade safely in a single focused session and ship a PR with a CHANGELOG-mapped diff a reviewer can actually verify line by line.

It fits npm/pnpm/yarn, pip, cargo, and gem equally: the CHANGELOG-grounding step is language-agnostic. Only the install command and test runner differ.

When to reach for it (and when not to)

Reach for it when a specific dependency is several majors behind, when CI passes but you don’t trust the pin, when a security advisory is forcing the bump, or when you pick up an abandoned internal tool whose lockfile predates the company’s current ESLint config. Run it before you touch anything else in that repo.

Do not reach for it on a full framework migration — Vue 2→3, Angular major-to-major, a Rails major jump. Those need a dedicated plan with codemods, phased rollout, and often a feature freeze, not a single upgrade run. (See the AI migration prompt workflow for those.) Also skip it on tiny prototype repos where re-scaffolding on current versions is faster than upgrading.

Before you start

  • Confirm CI is green on main. If main is red, fix that first; otherwise upgrade failures and pre-existing failures mix and you can’t tell them apart.
  • Write a smoke-test plan: the three or four manual paths that exercise the dependency. Type checks pass; smoke tests find the real runtime regressions.
  • Decide your upgrade boundary. Just this one package and its required peer-dep bumps, or adjacent packages too? Default to one package at a time.
  • Have a rollback plan. Keep the old lockfile on the branch and know your branch protections. git stash of package-lock.json is enough to revert a bad resolve in one command.

Step by step

  1. Branch from green main. Run npm ci (clean install from the lockfile, not npm install), then the full test suite. Confirm a green baseline. If you can’t, stop and fix the baseline first.
  2. Read the CHANGELOG with the agent. Ask it: “I want to upgrade [package] from [x] to [y]. Read its official CHANGELOG and migration guide for that range. List every breaking change that could affect a TypeScript codebase using these APIs: [list the ones you use].” Save the list.
  3. Map breaking changes to your code. For each item: “Find every file in this repo that uses the affected API. Give file:line references.” Click through and verify. An agent that lists files with no real matches is hallucinating — challenge it.
  4. Upgrade the one package. npm install package@y --save-exact (or your runner’s equivalent). Re-resolve the lockfile. Do not touch any other dependency in this commit.
  5. Run tests. Catalog failures. Do not fix yet. List every failure: which test file, which assertion, which source line.
  6. Cross-reference each failure with the breaking-change list. Every failure should match a list item. If one doesn’t, you missed a breaking change — go back to step 2 and re-prompt with the failing output as evidence.
  7. Fix failures one at a time. Each fix should be a minimal diff that adopts the new API, not a refactor of the surrounding code. Ask: “Is this the minimal change, or are you introducing a pattern that doesn’t match the rest of this codebase?”
  8. Run the full suite plus the manual smoke test. Start the app, walk the smoke paths, watch the network tab and console for new warnings. Type checks passing is not enough.
  9. Commit with CHANGELOG-mapped messages. Each commit names the breaking change it addresses, so the reviewer can diff your change against the CHANGELOG section directly.

Breaking-change mapping prompt

Paste this into Claude Code or Cursor with the repo open. It is the one template you reuse every time; only the first three lines change.

Package: [name]
Upgrade: [from-version] -> [to-version]
Codebase: TypeScript 5, Node 22, [framework]

Read the official CHANGELOG and migration guide for this range.

Return a markdown table:
| Breaking change | Affected API | file:line in this repo | Suggested fix |

Only include breaking changes that affect this codebase. Skip
changes to features we do not use. Cite the CHANGELOG section
for each row so I can verify it.

Worked example: React Router v6 to v7

This is the upgrade most React teams hit in 2026, and it shows why the future-flag path matters. React Router v7 ships no breaking changes if you have enabled all six v6 future flags first (per the official upgrade guide). The trap is treating it as a hard cutover.

The CHANGELOG-mapped run looks like this:

  1. First update to the latest v6.x minor so you get all future flags and console warnings.
  2. Have the agent map each flag to the behavior it changes — for example v7_relativeSplatPath, v7_normalizeFormMethod, v7_partialHydration. Enable them one at a time, fixing the console warnings each one surfaces, with the app running.
  3. Only after all six flags are true and tests stay green do you npm install react-router-dom@7 --save-exact. In v7 those flags are the defaults, so you delete them from your config.
Changev6 formv7 formRisk if you skip the flag
Relative splat pathslegacy resolutionv7_relativeSplatPathNested * routes resolve to the wrong URL silently
Form method casingmixedv7_normalizeFormMethodformMethod comparisons break in loaders/actions
Partial hydrationfull hydratev7_partialHydrationSSR apps hydrate differently than tested

Enabling flags incrementally turns silent behavior differences into visible console warnings you can fix one at a time. That is exactly the “catalog, then map, then fix” loop above, with the maintainer handing you the catalog for free.

If your app deploys to Firebase Hosting, run the AI Firebase deploy checks workflow right after a router major — these upgrades routinely break SPA rewrite rules that local tests never exercise.

Security-driven upgrades

npm audit links each finding to a GitHub Security Advisory (GHSA). Two things to know in 2026:

  • Don’t run npm audit fix --force and walk away. --force installs breaking major bumps (for example, pulling a <7 package up to 8.x) and the “fix” then breaks your app. Read the advisory, then run this workflow on the one affected package.
  • Most findings live in transitive dependencies with no entry in your package.json. You can’t npm install them directly. Use overrides (npm 8.3.0+) to force the patched version:
"overrides": {
  "vulnerable-pkg": "1.4.2"
}

Scope it to a single parent when you only want the override under one dependency: "overrides": { "loader-utils": { "ip-address": "9.0.5" } }. Always re-run the full suite after an override; forcing a nested version can introduce its own incompatibilities.

(Heads-up: npm’s legacy audit endpoints retire after July 15, 2026; pnpm and yarn users should confirm their audit tooling is on the current endpoint.)

AI workflow vs. automated bots

Use the bots for volume and this workflow for risk. They are complementary, not competing.

DependabotRenovateThis AI workflow
Best forPatch + minor bumpsPatch/minor at scale, groupedMajors, risky minors, security forcings
PR volume1 PR per dependency per day (default)Groups hundreds into one PROne package, one PR
Config surfaceSmall, GitHub-native400+ optionsA reusable prompt
CHANGELOG-to-failure traceNoNoYes — the whole point

Grouping in Renovate typically cuts PR volume three to five times versus ungrouped Dependabot. Let the bots clear the safe minor/patch churn so this manual loop is reserved for the upgrades that actually bite.

Quality check before you open the PR

  • Does every test failure in your catalog map to a known CHANGELOG entry? An unmatched failure means an undiscovered breaking change — go back to step 2.
  • Did you smoke-test in a running app, not just CI? Type checks miss runtime regressions, especially silent ones (a logging change, a default option flipped).
  • Did the agent add unrelated refactors? Revert them; they belong in a separate PR.
  • Did the lockfile resolve cleanly, or did it pull a new major of a transitive you didn’t approve? Diff package-lock.json and pin via overrides if so.

Common mistakes

  • Skipping the CHANGELOG step. The agent will guess breaking changes from training data, which may be wrong for your exact version range. Always ground it in the published CHANGELOG.
  • Letting the agent make stylistic refactors mid-upgrade. Every refactor adds risk to a PR that should be boring. Save them for separate work.
  • Upgrading multiple packages at once. When tests break you can’t attribute failures cleanly. One package per PR.
  • Not smoke-testing a running app. Type checks pass; the app loads blank because a default prop flipped. Manual smoke is non-optional.
  • Trusting transitive resolution. If the lockfile pulls a new transitive major, pin or override it until you’ve read its CHANGELOG too.
  • Calling it done at green CI. Production has runtime configuration CI doesn’t replicate. Deploy to staging first.

FAQ

  • Should I still use Dependabot or Renovate? Yes, for safe patch and minor bumps. This AI workflow shines on majors, risky minors, and packages with known migration pain. Let the bots clear the noise.
  • What about deprecation warnings? Treat them as homework, not a blocker. Schedule the cleanup as a separate PR within two to four weeks. Letting deprecations pile up is exactly how you end up “twelve majors behind.”
  • How do I handle transitive dependencies? Audit package-lock.json after the upgrade. If a transitive jumped a major you didn’t authorize, pin it with overrides (npm 8.3.0+), resolutions (yarn), or the pnpm equivalent.
  • What if the agent insists a breaking change is irrelevant when it isn’t? Show it the failing test output: “Reconcile this failure with the CHANGELOG entry you said didn’t apply.” Agents self-correct when handed the contradiction directly.
  • Can I parallelize across multiple agents? Run one agent at a time on the same branch. Parallel agents on one upgrade cause merge conflicts and destroy the CHANGELOG-to-failure trace that makes the PR reviewable.
  • Does this work for npm, pip, cargo, gem? Yes for all of them. Only the install command and test-framework details change; the CHANGELOG-grounding loop is identical.

Tags: #AI coding #Tutorial #Workflow

Related Articles