Home › Agent workflows › Dependency upgrade workflow AGENTS.md

Dependency upgrade workflow AGENTS.md

AGENTS.md workflow for upgrading dependencies and frameworks safely: one at a time, changelogs, codemods, and verification.

AGENTS.mdAgent workflows

Copy AGENTS.md

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

Note: Review and test before use. Provided as is, without warranty. See Terms.

# AGENTS.md: Dependency and framework upgrades

## Before
- Record the baseline: current versions, and test/lint/build results (`npm test`, etc.). Note pre-existing failures.
- Read the changelog and migration guide for every major version you cross. List the breaking changes that affect this codebase (search for the affected APIs with `rg`).

## Doing the upgrade
- One package (or one tightly coupled group, e.g. `react` + `react-dom` + `@types/react`) per step and per commit.
- Use the package manager, not manual edits: `pnpm up <pkg>@<version>`, `uv add <pkg>==<version>`, `go get <mod>@<version>`, `cargo update -p <crate>`. Commit the lockfile.
- Run official codemods where they exist (e.g. `npx @next/codemod`, `npx storybook upgrade`) and review their diff.
- Fix deprecations as you go; don't silence warnings.
- Don't jump multiple majors at once if the guide recommends stepping through each.

## Verify each step
- Install from clean, then typecheck, lint, tests, and build. Smoke-test the app's main flows.
- If something breaks and the fix is unclear, revert that step and report rather than piling on workarounds (patches, `--legacy-peer-deps`, `overrides`).

## Report
A table of package, from, to, breaking changes handled, and follow-ups. Flag anything requiring runtime/environment changes (Node/Python version, env vars, infrastructure).