Migrations and dependency upgrades are tasks nobody wants to do but everyone must do. They are repetitive, error-prone, and often involve dozens of files. A coding agent is perfect for this: it can apply the same pattern to hundreds of files with surgical precision. But beware — “surgical” does not mean “error-free.” A poorly done migration breaks more than it updates.

The agent is an excellent migrator only when the pattern is clear and the success criteria are deterministic.

When to use the agent for this case 🎯

• Dependency upgrade — updating a library with breaking changes.
• Schema/API migration — changing data formats or exposed interfaces.
• Boilerplate generation — configuration files, templates, repeated scaffolding.
• Chore tasks across many files — renaming, moving, restructuring uniformly.
• CI automation — scriptable and verifiable migrations.

When NOT to use the agent ⛔

• The migration is critical and you have no tests — without a safety net, every modification is a gamble.
• Breaking changes are ambiguous — if the library documentation is unclear, the agent will interpret on its own.
• The boilerplate requires domain knowledge — business-specific configurations cannot be generated from code.

Opening prompt 📝

“Update [dependency/pattern] in [area]. Purpose: [version upgrade / API migration / boilerplate]. Constraints: [do not break X]. Criteria: [green build/tests, updated changelog].”

Concrete example:

“Update github.com/gin-gonic/gin from v1.9 to v1.10 across the project. Purpose: version upgrade with breaking changes in the middleware package. Constraints: do not break existing endpoints, maintain compatibility with Go 1.22. Criteria: all tests pass, go build without errors, CHANGELOG updated.”

Context setup 🔧

1. Document current state — current dependency version, involved files, existing tests.
2. Indicate breaking changes — if you know them, list them. If you do not, ask the agent to identify them before proceeding.
3. Define success criteria — green build? Green tests? Updated changelog? Specify everything.

Workflow 💡

1. Analyze: the agent identifies involved files and necessary changes.
2. Plan: proposes an application order (base dependencies first, then those that depend on them).
3. Apply in micro-increments: after each change, verify build and tests.
4. Verify the diff: the change should be minimal and free of collateral modifications.
5. Update documentation: changelog, README, migration notes.

The “minimal diff” is the key criterion: a good migration changes only what needs to change. If the agent modifies 50 files for a single dependency upgrade, something is wrong.

For large-scale migrations, consider delegating to parallel sub-agents — each handles an independent area, reducing duration and context consumption.

Deterministic codemods + LLM: the hybrid approach 🔄

Migrations with breaking changes have high failure rates when relying solely on probabilistic LLM output. The modern architecture combines deterministic codemods (AST rewrite engines) with LLM agents for edge cases.

Tool	Type	Function
OpenRewrite	Deterministic AST	Type-aware transformations across thousands of files, preserving formatting and comments
jscodeshift	AST codemod	JavaScript/TypeScript transformations with TypeScript support
golangci-lint	Static analysis	Go compliance verification post-migration

The LLM agent acts as a high-level orchestrator: analyzes build logs to identify broken transitive dependencies, selects and configures the appropriate AST recipe from a catalog, and executes it systematically across thousands of files. Deterministic transformations guarantee structural correctness; the LLM handles complex business logic that rule-based engines cannot process.

Migration paths table

Migration Path	Legacy Pattern	Modern Target	Agent Strategy
React Class → Hooks	Class components, lifecycle methods	useState, useEffect, custom hooks	jscodeshift AST scripts + AI to extract state logic
Python 2 → Python 3	Implicit text/bytes, print statements	asyncio/httpx, typed data models	Mechanical 2-to-3 transformations + type hints
Go generics	interface{}, manual error handling	[T any], slog, context propagation	AST rewrite with parametric type constraints
Java Spring Boot	XML config, Spring Fox, Java 8	Java 21/25 records, Spring Doc, OpenRewrite	OpenRewrite recipes on Lossless Semantic Trees

The rule: use deterministic codemods for mechanical transformations (90% of the work), and reserve the LLM for edge cases that require business logic understanding.

Multi-agent architecture for complex migrations 🏗️

For migrations spanning multiple services or repositories, the optimal architecture separates three roles:

Role	Responsibility	Output
Planner Agent	Queries package registries, assesses compatibility, generates upgrade sequence with risk assessment	Step-by-step plan with priorities
Migrator Agent	Transforms code preserving business logic, updates API calls and config	PR with changes + tests
Validator Agent	Runs multi-stage validation: static analysis, tests, security check, performance	Conformance report

Real-world data (Elastic Cloud Control Plane): with 500 actively updated dependencies via Renovate, Claude analyzes failed Gradle build logs and iterates edit-compile-test cycles — in the first month, 24 broken PRs were fixed, 22 commits made by Claude, ~20 days of developer work saved.

The two-layer pattern is the 2026 standard: a deterministic bot (Renovate/Dependabot) opens version-bump PRs, and the agent picks up where the bot fails — specifically for breaking changes that require code modifications.

Confidence-scored automation 🎯

An advanced pattern for balancing speed and safety: the agent runs each dependency upgrade in a sandbox, and if everything passes, assigns confidence 1.0 and reports immediately — but below a configurable threshold (default 0.7), it delegates to an isolated sub-agent that re-runs the test suite with only that one package bumped.

This keeps the fast path for simple upgrades and the accurate path for complex ones, without slowing down the 80% of routine migrations.

The key insight is that rollback itself needs to be tested — via a monthly chaos drill that deliberately deploys a broken version to staging. The worst time to discover rollback does not work is during a real incident.

Acceptance criteria ✅

• Green build and tests after each increment.
• Minimal diff free of collateral modifications.
• Updated changelog and documentation.
• No dependencies removed or added without approval.

Further reading 📚

• Costs and tokens — how to manage token consumption during long migrations.
• Surviving sessions — error handling and loops during repetitive tasks.
• Testing and TDD — the safety net before every migration.