Legacy code modernization

Using AI to modernize a legacy system

AI can significantly accelerate legacy system modernization by helping your team understand existing code, identify technical debt, refactor components, migrate to newer frameworks, generate tests, and validate changes. The most effective approach is to use AI as a modernization copilot throughout the software lifecycle, with developers and architects retaining control over design decisions and production releases.

Modernization-specific tools now support structured workflows for application assessment, migration planning, code transformation, build validation, and deployment. For example, GitHub Copilot modernization supports upgrades and migration scenarios for Java and .NET, while AWS provides AI-assisted approaches for mainframe modernization and legacy code decomposition.learn.microsoft.com+2

1. Where AI can help

• 

1. Discover and understand the legacy system

Use AI to analyze source code, configuration files, database schemas, API contracts, and existing documentation.

• Generate documentation for undocumented modules.
• Identify dependencies, business rules, and integration points.
• Map call chains and data flows.
• Highlight outdated libraries and potential security issues.

Deliverable: a system inventory, dependency map, and list of modernization risks.

---

• 

2. Refactor legacy code

Ask AI to improve maintainability while preserving existing behavior.

• Break large functions into smaller, cohesive units.
• Reduce duplication and simplify complex conditional logic.
• Introduce interfaces, dependency injection, and clearer boundaries.
• Replace deprecated APIs and obsolete design patterns.
• Extract business logic from UI, database, or infrastructure code.

Deliverable: smaller, reviewable changes with tests proving behavioral equivalence.

---

• 

3. Migrate to newer technologies

Use AI to plan and assist with transformations such as:

• Older Java to a supported Java release and modern frameworks.
• .NET Framework applications to modern .NET.
• Legacy APIs to REST or event-driven interfaces.
• On-premises deployments to containers or cloud infrastructure.
• Legacy database access layers to modern data-access technologies.

Deliverable: a migration plan, transformed code, dependency updates, and deployment configuration.

---

• 

4. Generate tests and validate changes

AI can help create unit tests, integration tests, regression tests, test data, and edge-case scenarios.

• Characterize existing behavior before changing code.
• Compare old and new implementations.
• Identify missing test coverage.
• Diagnose build failures and test regressions.
• Review generated code for security and performance issues.

Deliverable: automated quality gates that reduce migration risk.

These uses align with the capabilities described in the AWS and Microsoft modernization guidance.docs.aws.amazon.com+2

2. A practical modernization workflow

I recommend an incremental, AI-assisted approach rather than asking an AI tool to rewrite the entire legacy system in one step. AWS's wave-based approach similarly emphasizes discovery, analysis, and implementation in manageable phases.docs.aws.amazon.com+1

1. Phase 1 — Assess the existing system

   Inventory applications, languages, frameworks, databases, interfaces, dependencies, and deployment environments. Ask AI to produce architecture documentation and identify unsupported technologies.

2. Phase 2 — Define the target architecture

   Choose supported runtimes, frameworks, APIs, data platforms, and deployment models. Have AI compare options, estimate complexity, and identify compatibility risks.

3. Phase 3 — Establish a safety net

   Create a reliable baseline of regression tests, integration tests, performance measurements, and security checks before changing business logic.

4. Phase 4 — Refactor in small increments

   Select one module or business capability. Have AI propose changes, implement them on a branch, run tests, and submit a pull request for review.

5. Phase 5 — Migrate and integrate

   Update dependencies, frameworks, APIs, database access, configuration, and deployment assets. Run old and new implementations side by side where practical.

6. Phase 6 — Release and measure

   Use staging deployments, canary releases or feature flags, monitoring, and rollback procedures. Expand to the next module only after meeting defined quality criteria.

Example: modernizing a legacy application

Suppose you have an older Java application using Java 8, Spring Boot 2, and a relational database, and want to move to Java 21, a supported Spring Boot release, and a containerized deployment.

For supported Java and .NET projects, GitHub Copilot modernization is one option for orchestrating assessment, framework upgrades, code transformations, and validation.learn.microsoft.com+3

3. Tools worth evaluating

• 

GitHub Copilot modernization

Best suited to supported Java and .NET modernization workflows, including framework upgrades, migration planning, code changes, and build validation.

Official documentation

---

• 

Amazon Q Developer

Worth evaluating for AI-assisted code understanding, development, and modernization tasks in AWS-oriented environments.

Official website

---

• 

AWS Transform

Particularly relevant for mainframe modernization, including COBOL analysis, business-rule extraction, decomposition, and transformation planning.

Mainframe modernization example

These products have different language and platform coverage, so validate their current support against your actual source code, framework versions, deployment environment, and organizational security requirements.learn.microsoft.com+2

4. Reusable AI prompts for your modernization project

You can use these with a code-aware AI assistant that has authorized access to your repository.

Prompt A — Analyze legacy code

Goal: understand the system before modifying it.

Analyze this legacy application without modifying any files.

Identify: 1. Architecture and major modules. 2. Business rules and critical execution paths. 3. External systems, databases, and APIs. 4. Deprecated dependencies and unsupported runtimes. 5. Tight coupling, duplication, and security risks. 6. Missing tests and high-risk modernization areas.

For every finding, provide evidence from the code, the affected files, confidence, and recommended next steps. Do not invent behavior when evidence is missing.

[Copy prompt]

---

Prompt B — Refactor a module safely

Refactor the selected module to improve maintainability without changing externally observable behavior.

Before editing: - Explain the current behavior and dependencies. - Identify edge cases and compatibility constraints. - Propose the smallest safe change.

Then: - Implement the refactoring on the current branch. - Add or update regression tests. - Run relevant tests and report the results. - Explain any behavior changes or unresolved risks.

Do not modify unrelated modules or remove existing functionality without explicit approval.

[Copy prompt]

---

Prompt C — Create a migration plan

Evaluate migration from CURRENT TECHNOLOGY to TARGET TECHNOLOGY.

Produce: 1. A compatibility and dependency assessment. 2. Required code, configuration, and database changes. 3. A phased migration plan with dependencies. 4. Automated tests and validation criteria for each phase. 5. Security, performance, and operational risks. 6. Rollback and coexistence strategies. 7. Effort estimates with assumptions and uncertainty.

Do not begin implementation until the plan is reviewed.

[Copy prompt]

5. Controls that make AI-assisted modernization safer

AI-generated code is a proposal, not proof of correctness. Legacy systems often contain undocumented behavior, unusual data dependencies, and business rules that are easy to accidentally change.

Build these safeguards into your process:

• Preserve behavior: create characterization tests for existing behavior before refactoring.
• Require evidence: ask the AI to cite relevant files, functions, tests, and dependency declarations for its findings.
• Keep changes small: use isolated branches and reviewable pull requests rather than bulk rewrites.
• Automate quality gates: run builds, regression tests, static analysis, dependency scanning, and security checks in CI/CD.
• Protect sensitive data: use approved tools and environments; don't upload production secrets, credentials, or sensitive customer data to unapproved services.
• Keep human approval: require engineers to review architectural decisions, database changes, security-sensitive code, and production deployments.

Track results using measurable indicators such as regression defect rate, test coverage, build success rate, migration lead time, escaped defects, and the percentage of AI-generated changes accepted after review.

6. Tailor the approach to your legacy system

The best strategy depends heavily on the source technology and the target platform. Tell me a little about your system and I can outline a more concrete modernization roadmap.

What are you modernizing?

Current technology

Java / Spring

.NET / C#

COBOL / mainframe

PHP, Python, or another technology

---

Target modernization

Upgrade framework and runtime

Migrate to cloud

Decompose a monolith into services

Rewrite in a different technology

---

Current architecture

Monolith

Service-oriented / microservices

Mainframe

Multiple interconnected applications

---

Primary goal

Refactoring and maintainability

Migration speed and cost reduction

Performance and scalability

Security and technology support

Important constraints (optional)

[Textarea placeholder: e.g., limited testing, strict compliance, minimal downtime] (Current value unavailable.)

[Build my modernization roadmap]

AI tools and workflows for legacy code modernization

The most effective approach is to combine AI coding agents with deterministic refactoring tools, automated tests, and incremental migration. AI is particularly useful for understanding unfamiliar code, tracing dependencies, proposing architectural changes, and translating business logic. Rule-based tools are generally better for repetitive, predictable transformations across thousands of files.

For example, if you're migrating a legacy Java application to Spring Boot 3, modernizing a .NET monolith, or moving an older web app to a newer framework, I would not rely on a single AI tool to rewrite the entire application. I'd use a staged workflow in which every change can be tested and reviewed.

1. AI tools worth evaluating

• 

OpenRewrite

(Best for repeatable migrations)

Best for Java and JVM modernization, framework upgrades, dependency changes, and large-scale source transformations. Its composable recipes can update code, build files, and configuration in a repeatable way. Use it before asking an AI agent to perform thousands of similar edits.

Website: Documentation and migration recipes.docs.openrewrite.org+2

---

• 

GitHub Copilot

Best for repository-aware coding assistance, explaining unfamiliar modules, generating tests, proposing refactors, and implementing changes in small batches. Particularly useful when a developer needs to stay in control of each pull request.

Website: GitHub Copilot.

---

• 

Claude Code

Best for complex, multi-file refactors: tracing call chains, mapping implicit dependencies, extracting services, and reasoning about changes spanning modules. Give it a bounded task and explicit verification criteria rather than an unrestricted rewrite.

Website: Claude Code.

---

• 

AWS Transform

Best for enterprise modernization involving legacy platforms, cloud migration, dependency analysis, and large portfolios of applications. It supports specialized transformation workflows rather than only interactive code completion.docs.aws.amazon.com+1

Website: AWS Transform.

---

• 

Gemini Code Assist

Worth evaluating for code explanation, test generation, repository-level assistance, and teams already invested in Google Cloud. Validate how well its available features handle your repository size and migration tasks before standardizing on it.

Website: Gemini Code Assist.

These tools serve different purposes, so they are not direct substitutes. In particular, OpenRewrite is a transformation engine, while coding agents are better suited to tasks requiring contextual reasoning. For .NET, TypeScript, Python, or frontend framework migrations, select language-aware codemods and analyzers alongside the AI agent.

2. The workflow that works best in practice

I recommend a six-stage process that keeps the AI focused on bounded tasks and uses automated checks as the safety net.

1. Inventory and understand the legacy system

   Use a coding agent to map modules, entry points, dependencies, database access, external integrations, and business rules. Generate an architecture summary and identify the riskiest areas before changing code.

2. Build a safety net

   Add characterization tests that capture what the existing application actually does. Record representative API responses, database behavior, and important edge cases. Establish a baseline for builds, tests, performance, and security.

3. Automate mechanical transformations

   Use AST-aware codemods, migration recipes, framework upgrade tools, and linters for predictable changes. For Java, OpenRewrite is a strong option. For .NET, use the current GitHub Copilot modernization agent in supported Visual Studio versions.docs.openrewrite.org+2

4. Use AI for semantic changes

   Have the agent handle tasks such as extracting business logic from controllers, replacing deprecated patterns with modern equivalents, introducing dependency injection, and separating persistence from application logic.

5. Migrate incrementally

The key principle is to separate understanding, transformation, and verification. Let AI accelerate the first two, but never let AI-generated explanations substitute for executable tests.

3. Choose tools based on your migration

For .NET specifically, note that Microsoft's documentation now marks the standalone .NET Upgrade Assistant as deprecated in favor of the GitHub Copilot modernization chat agent in supported Visual Studio releases.learn.microsoft.com+1

For Java migrations, OpenRewrite has documented recipes for Spring Boot, Java versions, JUnit, and Jakarta EE, making it particularly useful for repeatable framework changes.docs.openrewrite.org+2

4. Give the AI agent a migration contract

One of the most useful practices is to provide repository-level instructions and require the agent to follow them. GitHub documents repository-specific instructions for guiding coding agents and code reviews.github.com+1

Here is a reusable prompt:

:::writing{variant="document" id="58321"}

Legacy Code Modernization Task

Act as a senior software modernization engineer.

Objective

Analyze the existing application and propose a safe, incremental migration to [target framework and version].

Phase 1 — Analyze

• Map the architecture, modules, dependencies, entry points, and external integrations.
• Identify deprecated APIs, unsupported dependencies, framework incompatibilities, and security risks.
• Document important business rules and implicit behavior.
• Do not modify code during this phase.

Phase 2 — Plan

• Propose small, independently testable migration steps.
• Identify breaking changes, compatibility risks, and required configuration or database changes.
• Prioritize changes by risk and dependency order.
• Identify missing tests before proposing high-impact refactors.

Phase 3 — Implement

• Change one bounded module or concern at a time.
• Preserve existing behavior unless a behavior change is explicitly approved.
• Prefer framework-supported APIs and established project conventions.
• Avoid unrelated refactoring and unnecessary dependency additions.
• Explain any change that cannot be automated safely.

Phase 4 — Verify

• Run the relevant build, unit tests, integration tests, and static analysis.
• Add regression tests for changed behavior.
• Report failures honestly; never claim a test passed unless it was executed successfully.
• Review security, performance, configuration, and backward compatibility.

Deliverables

For each batch, provide:

1. Files changed and the reason for each change.
2. Tests added and commands executed.
3. Results and unresolved failures.
4. Risks, assumptions, and rollback instructions.
5. The next recommended migration step.

Do not proceed to a broad rewrite without an approved plan and a working verification strategy. :::

5. Common failure modes to avoid

• Rewriting everything at once: produces large diffs that are difficult to debug and review.
• Trusting generated tests without checking them: tests can reproduce the new implementation's assumptions rather than protect existing behavior.
• Migrating frameworks and architecture simultaneously: makes it difficult to determine which change caused a regression.
• Ignoring hidden dependencies: reflection, dynamic configuration, stored procedures, scheduled jobs, and undocumented integrations can break even when the project compiles.
• Optimizing for lines of code changed: a successful migration is measured by behavioral correctness, maintainability, reliability, and delivery risk—not code volume.

My recommendation

Start with one AI coding agent plus deterministic migration tooling plus a CI test pipeline. Add enterprise migration tooling if you have many applications, complex infrastructure dependencies, or a mainframe estate.

The best combination depends on what you are modernizing. Which describes your project most closely?

Primary language or platform

Java / Spring

.NET / C#

JavaScript / TypeScript

Python

COBOL / Mainframe

Other or polyglot

---

Main modernization goal

Framework or runtime upgrade

Architectural refactoring

Monolith to microservices

Cloud migration

Full rewrite or replatform

---

Application scale

Small application or single repository

Large legacy application or monolith

Enterprise portfolio of applications

[Get a tailored modernization plan]

AI tools and workflows for modernizing a legacy codebase

The most effective way to modernize a legacy application is to combine AI coding agents, automated refactoring tools, architecture analysis, and test-driven migration. Rather than asking an AI to rewrite the entire application in one go, use it to understand the system, plan incremental changes, automate repetitive transformations, and verify behavior after every step.

The right toolset depends on whether you're upgrading an existing framework, moving to a different language, breaking a monolith into services, or replacing an obsolete platform.

1. The tools worth evaluating

• 

OpenRewrite — automated refactoring

(Best for repeatable migrations)

Ideal for Java and JVM modernization, dependency upgrades, API changes, framework migrations, and bulk source transformations. Its recipes can combine many small changes into a repeatable migration. It also supports several other languages and configuration formats.docs.openrewrite.org+2

Start here for Spring, Java, dependency, and build-file migrations.

Documentation and recipes

---

• 

GitHub Copilot — repository-aware coding assistance

Useful for explaining unfamiliar code, generating characterization tests, proposing refactors, making changes across related files, and helping developers work through migration tasks.

Best for developer-led migrations with frequent code review.

GitHub Copilot

---

• 

Claude Code — agentic repository refactoring

Useful for tracing behavior across files, understanding complex control flow, proposing a migration plan, implementing a bounded change, running tests, and iterating on failures.

Best for cross-cutting changes that require understanding business logic.

Claude Code

---

• 

Amazon Q Developer — cloud and enterprise modernization

Worth evaluating for AWS-oriented application modernization, legacy-language analysis, code transformations, and cloud migration planning.

Best when the destination architecture is AWS-centric.

Amazon Q Developer

---

• 

Sourcery — code quality and smaller refactors

Useful for identifying maintainability issues, simplifying functions, and making code easier to review before or during migration.

Best as a supporting tool, not as the main migration engine.

Sourcery

One important distinction: OpenRewrite is primarily a deterministic transformation engine, whereas coding agents are better at interpreting context and handling changes that require judgment. These approaches complement each other.

For a more migration-focused option, also evaluate Microsoft's GitHub Copilot modernization tooling. Its modernization workflows cover assessment, planning, and execution, with support for Java, .NET, C++, and JavaScript/TypeScript use cases.github.com+1

Official modernization documentation

2. Match the tool to your migration

OpenRewrite is particularly attractive for repeatable framework migrations, while Amazon Q has dedicated Java and .NET transformation workflows.docs.openrewrite.org+3

3. A practical end-to-end AI modernization workflow

Phase 1 — Assess and understand

Inventory languages, dependencies, entry points, database access, integrations, deployment infrastructure, and critical business workflows. Have an AI agent map module dependencies and identify unsupported libraries and architectural risks.

Deliverable: system map, risk register, and prioritized migration backlog.

---

Phase 2 — Establish behavioral safety nets

Generate characterization tests around existing behavior before refactoring. Add integration tests for databases, APIs, authentication, and important business rules. Capture representative production inputs and outputs where safe and appropriate.

Deliverable: baseline test suite and known-good behavior.

---

Phase 3 — Automate mechanical changes

Use codemods and migration recipes for API replacements, dependency updates, package renames, configuration changes, and framework upgrades. Run the transformations on a branch and inspect the diffs.

Deliverable: small, reproducible transformation commits.

---

Phase 4 — Refactor architectural boundaries

Use a coding agent to extract domain logic from UI, database, or framework-specific code; define interfaces; separate modules; and migrate one bounded capability at a time.

Prefer a modular monolith first unless independent deployment or scaling justifies microservices.

Deliverable: a modernized slice with clear boundaries and preserved behavior.

---

Phase 5 — Validate continuously

Require automated builds, unit and integration tests, linting, dependency and security scans, and code review for every pull request. Use the AI agent to diagnose failures, but require evidence that the fix works.

Deliverable: independently reviewable, deployable increments.

4. Make the AI agent work from a migration specification

A strong workflow uses a persistent set of instructions, an architecture decision record, and a task list rather than relying on one giant prompt.

Here is a starter prompt you can use with a repository-aware coding agent:

COPY-READY PROMPT

Act as a senior software modernization engineer.

Goal: Migrate this legacy application from its current stack to the target stack described below.

Rules: 1. Do not rewrite the entire application at once. 2. First inspect the repository, build system, dependencies, tests, entry points, and deployment configuration. 3. Document the architecture and critical business workflows. 4. Identify unsupported dependencies and migration risks. 5. Propose a phased migration plan with independently testable milestones and rollback strategies. 6. Establish characterization tests before changing behavior. 7. Automate mechanical changes where reliable tooling exists. 8. Make one bounded change at a time. 9. Run relevant tests and builds after every change. 10. Never silently change business rules, data semantics, authentication, or public API contracts. 11. Report assumptions, failed tests, and unresolved risks. 12. Do not deploy or perform destructive operations.

Start with assessment only. Do not edit production code yet.

Current stack: describe languages, frameworks, database Target stack: describe desired languages, frameworks, database Constraints: uptime, budget, deadlines, compliance, integrations

[Copy prompt]

5. Common mistakes to avoid

• Rewriting everything at once. This makes regressions harder to isolate and increases the chance of losing undocumented behavior.
• Trusting generated tests blindly. AI-generated tests can encode the same incorrect assumptions as the generated implementation. Review them against business requirements and observed behavior.
• Mixing migrations together. Separate language upgrades, framework changes, database migrations, and architectural refactoring when possible.
• Allowing unrestricted agent access. Use version control, isolated branches or worktrees, restricted credentials, and human approval for sensitive operations.
• Measuring progress by lines rewritten. Track test coverage of critical paths, migration completion, defect rates, build reliability, deployment safety, and operational performance instead.

My recommendation

For most teams, start with one coding agent + automated migration tooling + a strong CI test suite. Add specialized modernization platforms only where the language, framework, or scale justifies them.

To narrow this to a concrete toolchain, tell me one thing: what is your current stack, and what do you want to migrate to?

For example, Java/Spring to modern Spring Boot, PHP to Node.js/TypeScript, .NET Framework to modern .NET, or a monolith to modular services. I can then recommend the most suitable tools and a migration plan for that specific codebase.