← Back to BlogEngineering

How to Upgrade a Major Version With Claude Code

Claude Code keeps writing the old API after an upgrade? Why it happens, and a staged plan: read the guide, run codemods, fail on deprecations.

If Claude Code keeps writing the old API after you bump a major version, the model is not ignoring you. Its training data often predates the version you installed, and the old code around every edit tends to pull it back toward the previous API. The fix is to change what it reads and what fails: put the target version's migration guide in the repo, run the vendor's codemods first, make deprecated APIs break a check, and move one major version at a time.

Disclosure: we build TLM Forge, a process layer for Claude Code, so weigh the product section accordingly. The upgrade plan below works with plain Claude Code.

Why the agent writes the old API mid-upgrade

Open-source code holds plenty of both the old and the new form of an API. A study of deprecated API usage in LLM code completion, accepted at ICSE 2025, counted 9,022 functions using deprecated APIs and 19,103 using their replacements in open-source repositories, so the old forms are far from rare. The authors note that model training data is primarily sourced from such repositories. They then tested seven models on 145 deprecated-to-replacement mappings from eight Python libraries, using 28,125 completion prompts. The deprecated usage rate in the paper counts only the completions that used either the deprecated API or its replacement, and it ran from 25% to 38% across the models. The split that matters for an upgrade is by context. When the prompt was cut from a function that used the deprecated API, that rate was 70% to 90%. When it was cut from a function that used the replacement, it fell to 9% to 18%.

Sources: Wang et al., LLMs Meet Library Evolution: Evaluating Deprecated API Usage in LLM-based Code Completion (arXiv:2406.09834), Same paper, full text (PDF)

Treat that as a mechanism, not a current benchmark. The models were CodeGen, DeepSeek-Coder, StarCoder2, CodeLlama and GPT-3.5, prompted for plain code completion, the language was Python, and none was an agent. The implication is ours, not the paper's: in the middle of an upgrade your repository is full of old-API code, and every file the agent opens works as a prompt that points at the old version.

Sources: Same paper, full text (PDF)

Framework vendors say this themselves. The Next.js documentation states: "AI coding agents may rely on training data that predates the Next.js version installed in a project." The AGENTS.md block that next dev writes into a project opens with the heading "This is NOT the Next.js you know." A post on Vercel's blog by a Next.js engineer adds that the error runs both ways: an agent working on an older version can suggest newer APIs that do not exist in your project yet, which matters in a half-migrated repo that contains both.

Sources: Next.js docs: How Next.js supports AI coding agents, Vercel: AGENTS.md outperforms skills in our agent evals

That post also put a number on the fix. On Next.js 16 APIs the post says are missing from model training data, an agent with no docs had a pass rate of 53%, and with a compressed docs index in AGENTS.md the pass rate was 100%. It is the vendor's own eval, the post names neither the model nor the number of cases, and its author works on Next.js and recommends a Next.js tool. The direction is still the useful part: version-matched docs in always-loaded context beat none.

Sources: Vercel: AGENTS.md outperforms skills in our agent evals

The second failure is quieter, because some breaking changes fail no build, and may fail no test you already have. The Next.js 16 upgrade guide lists changed image defaults: images.minimumCacheTTL moved from 60 seconds to 4 hours, the value 16 left the default imageSizes array, and images.qualities allows only 75 by default unless you list more. A passing build says nothing about whether any of the three applies to your app. Reading the guide is what surfaces them.

Sources: Next.js docs: How to upgrade to version 16

Both failures differ from an invented API. The old call is real, it just belongs to the previous version. Invented ones are covered in AI Hallucinated APIs: Why It Happens and How to Catch It.

Step 1: Get a green baseline and name both versions

Before the agent touches a dependency, commit a state where the full test suite passes on the old version, lockfile included. Everything after is measured against it. The Rails upgrade guide puts the reason bluntly: "Do yourself a favor and make sure your test coverage is good before you start an upgrade." Anthropic's guide to large migrations, written for language ports such as Bun's move from Zig to Rust, makes the same point. It says a strong judge must be in place before you start, or you have no exit condition or measure of success. Later it calls an existing test suite a built-in referee and says that if you can't inherit one, "have Claude build one." If coverage is thin, pin current behavior first, as described in How to Refactor With AI Without Breaking Things.

Sources: Rails Guides: Upgrading Ruby on Rails, Anthropic: How Anthropic runs large-scale code migrations with Claude Code

Then write the exact from and to versions into the prompt, and move one major version at a time. Official guides lean that way. The Rails guide says "it's best to move slowly, one minor version at a time, in order to make good use of the deprecation warnings." The Spring Boot 3.0 migration guide says to upgrade to the latest available 2.7.x version before you start. The React 19 upgrade guide recommends React 18.3 first, a release identical to 18.2 except that it adds warnings for deprecated APIs and other changes React 19 needs. And when the Next.js upgrade command hands a major jump to an agent, the task includes the guide for every major version crossed, so a multi-major leap multiplies what the agent has to read.

Sources: Rails Guides: Upgrading Ruby on Rails, Spring Boot 3.0 Migration Guide, React blog: React 19 Upgrade Guide, Next.js docs: Upgrade with a coding agent

Step 2: Put the guide in the repo and make the agent read it first

An agent cannot follow a changelog it never opened. Save the target version's migration guide as markdown inside the repo, then point at it from the prompt with an @ reference, which includes the file's content in the conversation. The docs add a limit: the file is included only when it fits the Read tool's token limit, 25,000 tokens by default, and a text file larger than 256KB is not included, so split a very long guide into parts. Some vendors make the first half easy. Every page on nextjs.org/docs has a plain Markdown version at its .md URL, and Next.js 16.2 and later bundle version-matched docs in node_modules/next/dist/docs/.

Sources: Next.js docs: How Next.js supports AI coding agents, Claude Code docs: Common workflows

``` mkdir -p docs/upgrade curl -sL https://nextjs.org/docs/app/guides/upgrading/version-16.md -o docs/upgrade/guide.md ```

Make the first pass read-only. This prompt asks for the breaking changes that touch your code before any edit, and for the changes that would not fail a build:

``` We are upgrading <package> from X.Y.Z to A.B.C. Do not edit any file yet. Read @docs/upgrade/guide.md in full, then: 1. List every breaking change in it that our code touches, with the files found by search. Skip the ones that do not apply. 2. List every change that alters behavior without failing a build or test (defaults, renamed config keys, changed return values) and how we would notice each one. 3. Say which items an official codemod covers and which stay manual. 4. Propose the order of work, one commit per step. Then stop and wait for my OK. ```

A prompt is a request, not a block. If you lean on plan mode for the read-only pass, check what it enforces first: Claude Code Ignores Plan Mode? What Enforces It.

Where the standing instruction lives matters too. Next.js writes its docs pointer into AGENTS.md. Claude Code's memory docs say it reads AGENTS.md by default only when there is no CLAUDE.md in the working directory or above, and that with both files present it reads the CLAUDE.md files only. So in a repo that has a CLAUDE.md, the Next.js block does not load by default. The docs show importing it with a line reading @AGENTS.md in the CLAUDE.md. The docs also note that reading AGENTS.md directly requires Claude Code v2.1.277 or later.

Sources: Claude Code docs: How Claude remembers your project, Next.js docs: How Next.js supports AI coding agents

Keep the standing instruction short. CLAUDE.md is context, not enforced configuration, and the memory docs suggest staying under 200 lines. This block is enough for the length of the upgrade. Delete it when the upgrade lands:

Sources: Claude Code docs: How Claude remembers your project

``` ## Mid-upgrade: <package> X.Y.Z to A.B.C Your training data likely describes the old version. Before writing code that touches <package>, read docs/upgrade/guide.md and docs/upgrade/RULES.md. Do not add compatibility shims without asking. When a check fails on a deprecated API, fix the call. Do not silence the check. ```

If the agent skips it mid-session, Why Your CLAUDE.md Gets Ignored covers why, and the Stop hook in step 4 is the enforced alternative.

The RULES.md file named in that block is an old-to-new rulebook. Anthropic's migration guide describes the habit for its ports: when a reviewer keeps catching the same mistake across files, the fix is not per file. You add one sentence to the rulebook and regenerate the batch. For an upgrade, it is a short list of old call to new call, such as cookies() becoming await cookies() and middleware.ts becoming proxy.ts in Next.js 16. Each time you correct the agent twice for the same thing, add a line.

Sources: Anthropic: How Anthropic runs large-scale code migrations with Claude Code, Next.js docs: How to upgrade to version 16

Step 3: Run the vendor codemods first, then hand over the leftovers

A codemod applies one rule the same way everywhere, and you can rerun it. An agent applies judgment, which varies from file to file. A Thoughtworks Technology Radar entry about a team upgrading its .NET framework version says that using AI alone for such upgrades "has often proven costly and prone to meandering conversations." The team combined traditional upgrade pipelines with agentic coding assistants, broken into smaller, verifiable steps, and Thoughtworks calls its results mixed in measurable time savings. Google's report on its int32-to-int64 ID migration has the same shape: engineers and scripts find the locations, a model writes the edits, builds and unit tests validate them, and people review. In that report 80% of the code modifications in the landed changes were fully AI-authored, and engineers estimated total migration time fell by 50%. The authors call it an experience report, not a research study.

Sources: Thoughtworks Technology Radar: AI for code migrations, Nikolov et al., How is Google using AI for internal code migrations? (arXiv:2501.06972)

UpgradeWhat the docs say about orderAutomated first passWhat stays with you
Next.js 15 to 16Version 15 introduced async request APIs with temporary synchronous compatibility. Version 16 removes it.npx @next/codemod@canary upgrade latestThe upgrade codemod does not run every migration codemod. The async request API codemod marks spots it cannot fix with @next-codemod-error comments and may add UnsafeUnwrapped casts.
React 18 to 19Upgrade to 18.3 first: identical to 18.2 plus warnings for deprecated APIs.npx codemod@latest react/19/migration-recipeTypeScript changes need a separate codemod, types-react-codemod.
Spring Boot 2 to 3Upgrade to the latest available 2.7.x first.OpenRewrite recipe UpgradeSpringBoot_3_5 (2.x to 3.5), plus spring-boot-properties-migrator for renamed or removed propertiesReview with git diff and fix what could not be migrated automatically. Items deprecated in 2.x are removed in 3.0.
Rails, minor to minorOne minor version at a time, after moving to the latest patch of your current version.bin/rails app:updateReview the generated diff for unexpected changes. Fix tests and deprecated features at each step.

Hand the agent only what is left: the codemod's own markers and the spots your checks flag. That keeps its work small enough to review, and it keeps the mechanical part deterministic.

One caveat on the Spring row: OpenRewrite's guide says its rewrite-spring recipe module is source-available, that compiled binaries are only available to Moderne customers, and that for non-commercial use you can compile and publish the module locally.

Sources: OpenRewrite docs: Migrate to Spring Boot 3

Step 4: Make the old API fail loudly

A test suite that passes on deprecated calls tells the agent it is finished. Change that, so the old API breaks a check.

Python hides library deprecations by default: the default warning filter ignores DeprecationWarning unless the code that triggers it is in __main__. pytest displays those warnings but does not fail on them. In a run on pytest 9.2.0 and Python 3.14.10, a test that called a function raising a DeprecationWarning passed with one warning in the summary, then failed when run with -W error::DeprecationWarning. The same effect from configuration:

Sources: Python docs: warnings, Warning control, pytest docs: How to capture warnings

``` [tool.pytest.ini_options] filterwarnings = [ "error::DeprecationWarning", "error::PendingDeprecationWarning", ] ```

If a dependency you do not control floods the run, add an ignore entry after the error lines, matched on the start of the warning message, such as ignore:<start of message>:DeprecationWarning. pytest applies the last matching entry. A module name in the filter matches where the warning is attributed, and a library that calls warnings.warn with stacklevel=2 attributes it to your calling code, so a filter naming the library module may not match. Rails has the equivalent: the generated test environment sets deprecation behavior to :stderr, and :raise is one of the documented behaviors, set with config.active_support.deprecation = :raise. In TypeScript projects, run the compiler as a check. The Next.js 16 guide notes, for one example, that the deprecated single-argument form of revalidateTag produces a TypeScript error.

Sources: pytest docs: How to capture warnings, Python docs: warnings, warn(), Rails Guides: Configuring Rails Applications, Rails API: ActiveSupport::Deprecation::Behavior, Next.js docs: How to upgrade to version 16

Then make the check run when the agent tries to stop. The Claude Code docs show a Stop hook that runs pnpm tsc --noEmit 1>&2 || exit 2: exit code 2 blocks the stop, and the output on stderr goes back to Claude as the reason it cannot finish. Claude Code overrides the block after eight stops in a row with no tool call between them. The same shape works for a tripwire on names your target version removed. Tested in a scratch repo on git 2.54.0, the command in this hook exits 0 on a clean tree and 2 when a removed name appears, with the matches printed to stderr. The hook wiring follows the docs example above:

Sources: Claude Code docs: Best practices

``` { "hooks": { "Stop": [ { "hooks": [ { "type": "command", "command": "! git grep --untracked -n -E 'serverRuntimeConfig|publicRuntimeConfig|next/amp' -- src 1>&2 || exit 2" } ] } ] } } ```

Pro Tip

Two details from that test. Without --untracked, git grep skips files the agent has just created, which is where new old-API code usually appears. And the check fails open: a path that matches nothing exits clean, and so does a git error such as running outside a repository, so confirm the path and the working directory are right. Keep the pattern list to names your target version removed, such as serverRuntimeConfig, publicRuntimeConfig and next/amp in Next.js 16, or the check will flag legitimate uses.

Step 5: Review what no check can see

Checks cover the loud failures. This list covers the rest:

  • Codemod markers: search for @next-codemod-error, UnsafeUnwrapped and @next-codemod-ignore (or your tool's equivalent). The docs say to complete the migration before removing the first two, and that @next-codemod-ignore is the way to dismiss a marker that does not apply, so read every explanation.
  • Silent defaults: walk the guide's list of changed defaults and renamed config keys against your own config, one entry at a time.
  • New shims: look for wrapper functions and aliases the agent added to keep an old call working. One practitioner guide warns about compatibility code that becomes permanent by accident.
  • Test edits: diff the test files on their own. A suite edited to pass is not a judge. How to Stop Claude Code Changing Tests to Pass covers the enforcement side.
  • Lockfile: confirm that only the intended packages, and their expected dependencies, moved.
  • Runtime: start the app and exercise it. The Next.js 16 checklist says: "A green build alone does not close runtime findings."

When the upgrade touches hundreds of files

Scale changes the mechanics, not the order. Airbnb's migration of nearly 3,500 test files from Enzyme to React Testing Library modeled each file as a state machine that advanced only after the previous step's validation passed, and retried failed steps with the errors fed back to the model. A first bulk run migrated 75% of files in four hours, a tuning loop reached 97%, and the remaining files took about another week by hand. Claude Code's best-practices page shows the plain version, a shell loop of claude -p calls with --allowedTools and --permission-mode dontAsk, tried on three files first. It also describes /batch, which splits a mechanical change into 5 to 30 units, shows you the plan, and gives each unit its own worktree. Anthropic's guide adds a design rule worth copying: keep the work queue mechanical and resumable, with done defined as something a script can check, such as an output file existing on disk.

Sources: Airbnb Engineering: Accelerating Large-Scale Test Migration with LLMs, Claude Code docs: Best practices, Anthropic: How Anthropic runs large-scale code migrations with Claude Code

Where TLM Forge fits

If TLM Forge sizes the upgrade Medium or Deep, you see a design for your OK before anything is built. That is the moment to check it against the migration guide you read. Deep also gets a spec audit, and the work is verified on a real running environment, which matters because a green build does not close runtime findings. See design sign-off and live verification.

The limit is the guide itself. The design and the spec audit are only as good as the migration notes the agent read, and the phase-auditor that checks the promised work was delivered is an LLM agent, so it can miss a default that changed silently. Someone still has to read the breaking-change notes.

Frequently asked questions

01Why does Claude Code write deprecated code?

Its training data often predates the version you installed, and old-API code is common in public code. During an upgrade, the files around each edit also use the old API, which pulls completions toward it. Putting the migration guide in front of the agent and failing checks on deprecated calls counters both.

02Should I use a codemod or let Claude Code migrate my code?

Use the codemod first. It applies one rule the same way everywhere and can be rerun. Then give Claude Code what it leaves behind, such as flagged call sites. Thoughtworks wrote that using AI alone for such upgrades has often proven costly and prone to meandering conversations, and one team paired agents with traditional upgrade pipelines.

03Can I jump several major versions at once with an AI agent?

You can, but it multiplies the reading. The Rails, Spring Boot and React guides each tell you to land on a specific release first, such as the latest 2.7.x or React 18.3. React 18.3 adds warnings for deprecated APIs. A single-major step gives the agent one guide, one baseline and one set of failures to fix per commit.

04Does Claude Code read AGENTS.md?

By default it reads AGENTS.md only when there is no CLAUDE.md in the working directory or above. If both exist, it reads CLAUDE.md only. To include AGENTS.md, add an @AGENTS.md import line to CLAUDE.md. Reading AGENTS.md directly requires Claude Code v2.1.277 or later, per the memory docs.

05How do I make deprecation warnings fail my tests?

In pytest, run with -W error::DeprecationWarning or add error::DeprecationWarning to filterwarnings in your config. In Rails, set the test environment deprecation behavior to raise. In TypeScript projects, run the compiler as a check. Keep any ignores narrow, matched on the message text, so real deprecations still fail.

Ship AI-written code you can trust

TLM Forge is the missing process layer for Claude Code: a spec audit, independent multi-agent review, enforced TDD, and an adversarial red-team gate.

Get TLM Forge