organizationL2 GuidedTech Debt & Modernization

OpenRewrite basic recipes

OpenRewrite is an open-source automated refactoring tool for Java and other JVM languages that executes structured code transformations called "recipes." A recipe is a reusable, te

·Tech debt is categorized and prioritized (severity, impact, effort)
·At least one manual migration attempt has been completed or is in progress
·OpenRewrite or equivalent automated refactoring tool has been evaluated or adopted for basic recipes

·Tech debt reduction is allocated time in sprint planning (even if small)
·Migration attempts are documented with lessons learned

Evidence

·Categorized tech debt backlog with priority ratings
·Completed or in-progress migration project documentation
·OpenRewrite configuration or evaluation report

What It Is

OpenRewrite is an open-source automated refactoring tool for Java and other JVM languages that executes structured code transformations called "recipes." A recipe is a reusable, tested refactoring operation that transforms source code from one pattern to another - replacing a deprecated API call with its modern equivalent, migrating from one framework version's conventions to another's, or applying a security fix across all usages of a vulnerable pattern in a codebase.

The key characteristic of OpenRewrite that distinguishes it from text-based find-and-replace is that it operates on the abstract syntax tree (AST) of the code, not on raw text. This means it understands the code's structure, handles edge cases correctly (variable shadowing, type inference, import deduplication), and produces transformations that are syntactically and semantically valid. A recipe that replaces org.junit.Assert.assertEquals with org.junit.jupiter.api.Assertions.assertEquals will also correctly update the import, remove the old import if it is no longer needed, and handle cases where the same class is used for different assertion types.

At L2, "basic recipes" means applying the existing recipe catalog to known debt items without writing custom recipes. The OpenRewrite recipe catalog includes hundreds of pre-built recipes for common migrations: Java version upgrades, Spring framework migrations, JUnit 4 to 5, Log4j to SLF4J, and many others. An organization at L2 can execute a significant portion of its migration backlog using these catalog recipes with minimal configuration - often just adding a Maven or Gradle plugin and specifying which recipe to run.

The L2 adoption pattern is: identify a migration on the debt backlog, search the OpenRewrite recipe catalog for a matching recipe, run the recipe on the codebase, review the diff, run tests, and commit. This is still a supervised, human-initiated process - the engineer decides when to run the recipe, reviews every change, and handles the edge cases that the recipe does not cover. But the mechanical transformation work that previously took weeks now takes minutes, and the engineer's effort shifts to review and validation.

Why It Matters

Dramatically reduces migration cost - A JUnit 4 to JUnit 5 migration that takes an engineer two weeks manually can be executed by an OpenRewrite recipe in an afternoon, with the engineer's effort limited to reviewing the diff and handling the edge cases
Produces consistent transformations - Manual migrations are inconsistent: different engineers make different choices about how to handle the same pattern, producing heterogeneous output that is harder to maintain; recipes produce identical transformations for every instance of a pattern
Enables migrations at scale - A recipe that works on one class works on 10,000 classes with the same effort; OpenRewrite makes large-scale migrations feasible that would be effectively impossible manually
Builds toward AI agent integration - At L3, AI agents run OpenRewrite recipes as part of their toolchain; adopting OpenRewrite at L2 is the prerequisite for this integration and builds team familiarity with the tool before automation is added
Lowers the barrier to consistent code standards - Recipes can encode style standards and architectural patterns and apply them across the entire codebase; what previously required a team-wide manual effort can be executed and re-executed automatically

Getting Started

Install the OpenRewrite Maven or Gradle plugin - Add the rewrite-maven-plugin or rewrite-gradle-plugin to your build configuration. The installation takes less than 10 minutes and makes every recipe in the catalog available to run against your codebase.
Run ./mvnw rewrite:discover (or equivalent) - This command lists all available recipes from the configured dependencies. Browsing the output will reveal migrations you did not know were automated - many teams are surprised to find their specific migration is already covered by a catalog recipe.
Pick one migration from your debt backlog and find its recipe - Search the OpenRewrite recipe catalog at docs.openrewrite.org/recipes for the migration. Common starting points: org.openrewrite.java.migrate.JavaVersion17, org.openrewrite.java.testing.junit5.JUnit4to5Migration, org.openrewrite.java.spring.boot3.UpgradeSpringBoot_3_0.
Run the recipe in dry-run mode first - Use ./mvnw rewrite:dryRun to see what changes the recipe would make without applying them. Review the diff. Identify anything unexpected. This review step is what keeps the engineer in control of the transformation.
Apply the recipe and run your test suite - Run ./mvnw rewrite:run to apply the changes, then run the full test suite. Fix any failures that require judgment (the recipe may have correctly transformed the code but a test may be testing an implementation detail that changed). Commit.
Add the recipe to your CI pipeline - For ongoing maintenance, add relevant recipes to your CI configuration so that they run automatically. A recipe that flags deprecated API usage in new code is a lint rule encoded as an OpenRewrite recipe.

Tip

The first time you run a major migration recipe on a large codebase, the diff will be large - potentially thousands of files. Do not let the size of the diff discourage you. Each change in the diff is a mechanical transformation that OpenRewrite made correctly. Your job is to look for the changes it did not make (missing edge cases) and the changes that affect behavior (not just syntax), which will be a small subset of the total diff.

6 steps to get from here to the next level

Common Pitfalls

Assuming recipes handle 100% of the migration. OpenRewrite recipes handle the mechanical, pattern-based parts of a migration. Every significant migration has edge cases that require engineering judgment. Treat the recipe output as the starting point, not the final product - you still need to run tests and handle the remaining cases manually.

Not reviewing the diff before committing. The AST-based approach makes OpenRewrite transformations highly accurate, but not infallible. Custom code patterns that the recipe authors did not anticipate may be transformed incorrectly. Always review the diff before committing, especially for the first time you run a new recipe.

Running the recipe without adequate test coverage. If your test coverage is low, you cannot verify that the recipe's transformations preserved behavior. The recipe may be syntactically correct but introduce a behavioral regression that your tests cannot catch. Test coverage is a prerequisite for safe recipe execution.

Ignoring the remaining 20% of the migration. Teams sometimes run a recipe, see that it addressed most of the migration, and declare the migration complete when 10-20% of cases remain. Partial migrations can be worse than no migration if they create inconsistency - some code using the old pattern, some using the new pattern. Finish the migration.

Not exploring the full recipe catalog. Most teams discover OpenRewrite because of one specific migration need and apply only that one recipe. The catalog contains hundreds of recipes for common patterns. A periodic catalog review will reveal additional migrations that can be automated.

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

How Different Roles See It

BobHead of Engineering

Bob's team just discovered OpenRewrite while researching how to execute the Spring Boot 3 migration. One of his engineers ran the UpgradeSpringBoot_3_0 recipe on a branch and produced a PR with 1,200 file changes in two hours - work that Bob had estimated at six weeks for two engineers. Bob is simultaneously impressed and unsettled: if this is real, his entire migration estimate framework is wrong.

It is real, with caveats. Bob needs to understand that the recipe produced the mechanical part of the migration, not the complete migration. There are edge cases that the recipe did not handle, tests that need to be fixed because they were testing implementation details, and configuration changes that require engineering judgment. But the 6-week estimate has collapsed to perhaps 2-3 weeks, and a significant fraction of those remaining weeks is review and validation rather than writing code. Bob should update his migration roadmap to reflect OpenRewrite as a standard tool in the migration process, and should brief his tech leads on the recipe catalog so they can identify other backlog items that can be automated.

SarahProductivity Lead

Sarah has been tracking migration velocity - hours per migration, complexity-adjusted. The first time her team uses OpenRewrite, the numbers will look anomalous: a migration that she expected to take 6 weeks completes in 2 weeks. Her first instinct will be to assume the migration was simpler than estimated.

Sarah should instrument the comparison properly. Record the number of files changed, the number of individual transformations, and the number of edge cases that required manual handling. Compare these to a previous manual migration of similar scope. The data will show that the recipe did in two hours what manual work would have done in three weeks, and the two weeks of elapsed time were spent on review, edge case handling, and validation - the engineering judgment that automation cannot replace. This breakdown is the most precise characterization of the OpenRewrite value proposition Sarah can produce, and it will be the foundation for the business case for AI-assisted migration at L3.

VictorStaff Engineer - AI Champion

Victor ran the recipe, reviewed the diff, fixed the edge cases, and has a working opinion on what the recipe handled well and what it missed. The recipe nailed the import replacements, the deprecated API calls, and the configuration file migrations. It missed two custom Spring interceptors that used internal APIs that changed behavior, and one integration test that relied on a Spring Boot 2 behavior that no longer exists in Spring Boot 3.

Victor should document this breakdown: recipe covered X%, manual cleanup required Y%. He should also write a custom OpenRewrite recipe for one of the patterns the catalog recipe missed. Writing a recipe requires understanding the OpenRewrite visitor API, but it is not prohibitively difficult, and a custom recipe that handles an internal pattern is reusable across every repository in the organization that uses that pattern. At L3, Victor's custom recipes are the tools that AI agents will use when they run migrations autonomously - the quality of Victor's recipe library directly determines the quality of AI-assisted migration at the next level.