organizationL3 SystematicTech Debt & Modernization

OpenRewrite + agent = systematic refactoring

OpenRewrite combined with an AI agent is the L3 pattern where structured code transformation (OpenRewrite recipes) is orchestrated by an AI agent that selects which recipes to appl

·Continuous modernization: agents work on tech debt reduction in background (non-blocking to feature work)
·Library version bumps and dependency upgrades are automated via agent PRs
·OpenRewrite + agent combination is used for systematic refactoring campaigns

·Agent tech debt PRs follow the same review process as feature PRs
·Dependency freshness score is tracked (% of dependencies within N versions of latest)

Evidence

·Agent-authored tech debt reduction PRs in git history
·Automated dependency upgrade configuration (Renovate + agent, Dependabot + agent)
·OpenRewrite recipe configuration with agent integration

What It Is

OpenRewrite combined with an AI agent is the L3 pattern where structured code transformation (OpenRewrite recipes) is orchestrated by an AI agent that selects which recipes to apply, sequences them correctly, interprets test failures, handles the edge cases that recipes do not cover, and produces production-ready PRs with minimal human intervention. The combination is more powerful than either component alone: OpenRewrite provides reliable, semantically-correct mechanical transformation; the AI agent provides the judgment to apply it strategically and fix what the recipe could not.

OpenRewrite alone handles roughly 60-80% of a typical migration's mechanical work. The remaining 20-40% is edge cases: custom patterns that differ from what the recipe expects, test failures caused by behavioral differences in the new API, integration tests that relied on internal implementation details that changed. At L2, a human engineer handles this remaining fraction. At L3, the AI agent handles it - examining the test failures, reading the library changelog or documentation, writing targeted fixes, and re-running tests to validate.

The agent acts as an intelligent wrapper around OpenRewrite. It receives a migration task from the debt inventory ("migrate the payments service from Spring Boot 2.7 to Spring Boot 3.1"), selects the appropriate OpenRewrite recipe, runs it, interprets the results, identifies what the recipe did not handle, researches the fix using the library's documentation or changelog, implements the fix, runs the full test suite, and opens a PR. The human engineer reviews and merges. The entire execution happens asynchronously, often overnight.

This combination is what makes the L3 claim of "continuous modernization as background work" operational. Without the agent, running OpenRewrite is still a human-supervised process that requires engineering attention. With the agent, the process is largely autonomous - the human is in the review loop, not the execution loop.

Why It Matters

Closes the last-mile gap in automated migration - OpenRewrite recipes handle the pattern-based work; the agent handles the judgment-based remaining fraction; together they cover nearly all of a typical migration without human writing code
Scales to the full migration backlog - A human engineer can only run so many OpenRewrite recipes per week; an agent running continuously can process the entire migration backlog in parallel across all repositories simultaneously
Handles the long tail of custom patterns - Enterprise codebases accumulate custom patterns, internal abstractions, and non-standard usage that no public recipe covers; the AI agent generates targeted fixes for these cases on the fly
Produces high-quality, documented PRs - An AI agent can generate a PR description that explains what was migrated, why, what the test failures were, and how they were fixed - documentation quality that is often better than human-authored migration PRs
Creates a reusable recipe library - When an agent writes a fix for a custom pattern, that fix can be extracted as a custom OpenRewrite recipe for the next occurrence of the same pattern; the agent's output improves the recipe library

Getting Started

Select a well-supported migration as the first target - Choose a migration for which a production-quality OpenRewrite recipe already exists (Spring Boot 3 migration, JUnit 4 to 5, Java 11 to 17 APIs). The recipe handles the bulk of the work; the agent handles the residual. This is the easiest configuration to validate.
Configure the agent's tool access - The agent needs: the ability to run mvn rewrite:run (or equivalent), the ability to run the test suite, read access to the library's changelog and migration documentation (via MCP web access or pre-loaded context), and write access to create commits and open PRs.
Write a clear migration task specification - The task given to the agent should include: the recipe to run, the expected outcome, the repositories to target, the criteria for "done" (all tests pass, no compilation errors, PR opened), and the escalation path for issues the agent cannot resolve.
Run the first migration on a low-risk repository - Start with a repository that has good test coverage and is not on a critical path. Validate the full agent workflow: recipe execution, failure diagnosis, fix implementation, PR creation. Review the output carefully. Identify what the agent handled well and where it needed help.
Build a diagnosis prompt library - The agent's effectiveness at handling residual failures depends on the quality of the diagnosis prompt. Maintain a library of prompts for common failure types: "compilation error due to removed API," "test failure due to behavioral change in assertion library," "configuration file format change." These prompts improve over time as the library grows.
Expand to multiple repositories in parallel - Once the single-repository workflow is validated, the agent can run the same migration across multiple repositories simultaneously. This is where the scale advantage becomes obvious: the same migration that took two engineers four weeks runs across 20 repositories in one weekend.

Tip

The agent's ability to handle residual failures depends heavily on the quality of the library's migration documentation that is provided as context. Before running a migration, load the official migration guide, changelog, and any known breaking change documentation into the agent's context. The agent that cannot find the answer in its context will guess; the agent with good documentation will usually find the right answer.

6 steps to get from here to the next level

Common Pitfalls

Expecting the agent to handle major behavioral changes autonomously. The agent-plus-recipe combination handles mechanical and documented changes well. Behavioral changes that require understanding business logic - "should this endpoint's response format change, or should we maintain backward compatibility?" - require human judgment. The agent should escalate these cases, not make autonomous decisions.

Not reviewing the agent's custom fixes. When the recipe fails and the agent writes a custom fix, that fix may be correct but should always be reviewed. The agent's fix is often a reasonable first attempt that needs polish, not a production-ready change that can be merged blindly.

Running migrations on repositories without a staging environment. Even a correctly migrated codebase can have production issues that tests do not catch. For critical services, require a staging deployment and smoke test before merging agent-generated migration PRs.

Using the agent as a substitute for understanding the migration. Engineers who merge agent-generated migration PRs without understanding what changed lose the ability to debug issues when they arise in production. Review sessions should include understanding, not just approval.

Not extracting custom fixes as recipes. When the agent writes a fix for a custom pattern in one repository, that same fix is likely needed in similar repositories. Extract the fix as a custom OpenRewrite recipe. Over time, the custom recipe library reduces the agent's residual workload and improves its consistency.

Mistakes teams actually make at this stage - and how to avoid them

How Different Roles See It

BobHead of Engineering

Bob's team is running the Spring Boot 3 migration across 12 repositories using the agent-plus-recipe approach. The agent has been running for three days. It has processed 8 repositories, opened 8 PRs, and his team has merged 6 of them after quick reviews. Two PRs are in review because they touched configuration areas that required judgment about production deployment approach. The remaining 4 repositories are queued.

The speed is unlike anything Bob has seen for migration work. His estimate had been 18 weeks for two engineers. The agent processed 8 repositories in 3 days, with review taking perhaps 2 hours per PR. At this rate, all 12 repositories will be done in under two weeks, with total engineering time of approximately 24 review-hours. Bob needs to update his migration planning model. He also needs to communicate the approach to other teams, because the business case for investing in the agent setup is now demonstrated by concrete results.

SarahProductivity Lead

Sarah is tracking the migration metrics. The agent-plus-recipe approach has produced a productivity multiplier she is struggling to present credibly because the numbers seem implausible: 8 repositories migrated in 3 days vs. the 18-week estimate for manual migration. She wants to make sure the comparison is fair.

Sarah should document the methodology carefully: what did the recipe handle, what did the agent fix, and what did the humans review? The breakdown for these 8 repositories: recipe handled 72% of changes, agent fixed 23% of residual cases, humans reviewed and modified 5% during PR review. Total human engineering time: 16 hours of review across 8 PRs. Equivalent manual time estimate: 3 weeks per repository. The comparison is valid and the numbers are real. Sarah should present this with the methodology attached - it will be questioned, and having the detailed breakdown makes the case bulletproof.

VictorStaff Engineer - AI Champion

Victor designed the agent configuration, wrote the task specifications, and is the primary reviewer of agent-generated migration PRs. He has developed a detailed understanding of where the recipe plus agent combination succeeds and where it struggles. Success: standard Spring patterns, controller/service/repository layer changes, test annotations. Struggle: custom AOP aspects that use Spring internals, reactive programming patterns that changed behavior in WebFlux, integration tests that use Spring's test context in non-standard ways.

Victor is addressing the struggle areas by writing custom OpenRewrite recipes for the most common custom patterns. He has written three recipes so far, each taking about two hours to write and test. Each recipe eliminates one class of agent failure - the agent's test failure rate on the repositories processed after the recipes were added dropped from 23% to 8%. Victor's recipe-writing effort is a high-leverage investment: each recipe written once reduces the agent's residual work across every future migration that encounters that pattern. Victor should track which custom patterns are most common across the organization's codebase and prioritize recipe development accordingly.