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 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.

• 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

1. 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.
2. 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.
3. 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.
4. 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.
5. 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.
6. 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.

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.