How to prepare for AI-driven code modernization projects

來源原標題

How to prepare for AI-driven code modernization projects

機構

Anthropic

原始標籤

Enterprise AI

原始連結

https://claude.com/blog/how-to-prepare-for-ai-driven-code-modernization-projects

摘要原文

How to prepare for AI-driven code modernization projects How to organize AI-driven modernization projects for critical systems and regulated enterprises. Category Enterprise AI Claude Code Product Claude Code Date September 23, 2026 Reading time 5 min Share Copy link https://claude.com/blog/how-to-prepare-for-ai-driven-code-modernization-projects Author(s) Jonah Ezekiel Lexie Tonelli In our Notes from the Field series, Anthropic forward deployed engineers share best practices inspired by real customer deployments. In this article, we share our experience managing large code modernization projects. Code modernizations once scoped as multi-year, all-hands efforts can now finish in months (or weeks ), but the organizational work on either side often remains the same. For example, every change to a critical banking system must go through change management, review, and approval. It is a robust process because regulators, auditors, and the business require it. Those processes are what make critical systems trustworthy, and they were built on the assumption that a human wrote each change and a human would review each diff. Once agents accelerate writing the changes, the bottleneck shifts from producing changes to mobilizing the organization around them. This article covers the work enterprises must do before the modernization takes place: defining what done means, what evidence a change must carry, how certified changes will reach production, and what has to be staged so the run can start. We break this process into six steps: Define the target: the tech stack and behavior the modernized code must have. Create the certificate: the conditions that the changes must meet to be considered correct in the target state. Set the promotion policy: the path by which certified changes get into production at the rate they’re produced. Put the prerequisites in place: environment, CI/CD, review capacity, and approvals. Build and refine the agentic workflow: the custom Claude Code dynamic workflow that distributes the modernization across many smaller parallel subagent workstreams that produce the changes. This is built around the target, certificate, and promotion policy. Run the modernization: prove the workflow end to end on a small partition of the codebase, then scale. Step 1: Define the target The target is the end state of the modernization. The desired end state determines which of the three kinds of modernization you are doing, detailed in the table below. Determine the modernization type Type What it is Choose when The target is Uplift Same-stack version bump (e.g., C++11 → C++20). The stack is fine but the version has fallen behind: end-of-life runtimes, unpatched security issues, dependencies you can no longer upgrade. A runtime version and package set. Transform Cross-stack rewrite that keeps behavior fixed (e.g., COBOL → Java). The stack is the problem to resolve and the behavior is trusted. Everything needed for an uplift, plus the language, frameworks, and architectural conventions the new code must follow. Reimagine Greenfield rebuild on a new architecture with modified behavior. The behavior needs to be changed alongside the code. Everything needed for a transform, plus a written behavioral spec for the new system. Determining which type of modernization to do is often debated inside an organization. In our experience, the people closest to production want the stack swapped with behavior held constant to contain risk (transform modernization). On the other side are often the engineers who have lived with the codebase and want the modernization to pay down tech debt, plus other business stakeholders who want to take the opportunity to name new requirements (reimagine modernization). Both positions are reasonable, but if the question is left unresolved it resurfaces later as an argument over whether a given change is “correct.” Building consensus on which path to take adds initial friction, but streamlines the project as a whole. Map the codebase and create the behavioral spec Understanding the current system is often a good first step for defining the target. Extracting what the old code actually does and creating an inventory of current behavior makes it easy to decide if parts should be changed or dropped, and so whether the modernization is a transform or a reimagine. This also often reveals unknown business logic and edge cases. Claude can do much of that discovery by mapping dependencies and documenting workflows that nobody remembers building . The code modernization plugin ’s assess, map, and extract-rules commands mine business rules with source citations that engineers can then review. However, Claude’s discovery alone may not capture how a legacy system fully behaves. Interviews with business users and developers, and internal documentation, can fill those gaps. Context gathering may take some time upfront, but the quality of that context shapes every decision the workflow makes later. For a reimagine, defining the target requires additional work: a detailed behavioral spec should be written down and agreed with user groups. An interactive dependency map example from the code modernization plugin. Establish the project’s justification and goals Alongside defining the target, the organization should consider why the modernization is worth undertaking at all. Modernizing legacy systems can reduce ongoing maintenance and operational costs, however, in our experience, cost reduction has not been the driving goal of most modernization projects. Risk reduction is often the most important modernization benefit. Consider the risk of not doing the modernization when debating whether or not to undergo the project. For example, a system carrying unpatched vulnerabilities can mean a cyber breach or an outage severe enough to put the business itself at risk. An unsupported runtime or a shrinking pool of engineers who understand the system exacerbates the risk. Agentic coding tools like Claude Code have shortened modernization timelines, but budgets are still hard to estimate, which leads to inertia. We have released the costs of some of our large-scale modernizations as have others . These can serve as a rough baseline, and we have additional guidance on budget projections at the bottom of this guide. The main challenge in initiating these projects is usually building the internal consensus and commitment from the teams that own the system, and the teams that depend on it. Building the business case and setting the goals of the project, often at the leadership level, make this part of the process easier. This also helps anchor the tradeoffs in the certificate and promotion policy that follow. When stakeholders disagree over how much risk a change can carry, the risk of not modernizing is the counterweight. Step 2: Define the certificate The certificate is the set of conditions or tests that every modernization change must meet. Pick the conditions that give the strongest cumulative evidence that the change is correct against the target. Each condition should be checkable without a human in the loop, so the agentic workflow can iterate on a change until it meets the certificate or flag it for human review if it can’t.