AI Code Migration: How Agent Loops Port Codebases Fast

AI code migration uses a closed LLM-agent feedback loop. The loop translates, compiles, tests, and repairs code because one-pass translation collapses under repository-scale dependencies. Research on repository-level translation found GPT-4 resolves 8.1% of full-project translations; every other tested model scored 0%.

Migration loops need four prerequisites before agents edit production files:

• A rulebook that encodes source-to-target patterns.
• A dependency map that sequences repository-scale work.
• Characterization tests that preserve current behavior.
• Parity gates that compare migrated outputs against the original system.

Those prerequisites replace one-pass translation with a repair workflow that checks edits through rules, tests, and review gates.

Why Migration Projects Stall Until the Loop Changes

Legacy migration projects stall when repository-scale dependencies, rewrite risk, and missing tests make manual modernization exceed budget and staffing limits. A legacy codebase consumes a growing share of the budget, a rewrite gets scoped, and the estimate comes back in engineering-years, so leaders defer the project again. The same backlog blocks platform upgrades, compliance fixes, and hiring plans. Agents change the mechanism by using a rulebook, running compilers and test suites as tools, and iterating until outputs match the original system.

At organizational scale, agentic migration becomes infrastructure work. Repositories can span hundreds of thousands of files, so cloud agents need repository context, controlled execution, and review checkpoints across repositories. Augment Cosmos, the unified cloud agents platform, runs agents with shared context and memory that compound across the software development lifecycle. Cosmos exposes three primitives that map directly to migration work: Environments define where agents run and what they can touch, Experts encode migration behavior and triggers, and Sessions turn one-off translation attempts into auditable, replayable workflows. The underlying Context Engine processes entire codebases and maps semantic dependencies before agents edit code. This guide defines AI code migration, quantifies why one-shot approaches fail, gives CTOs a migrate-or-maintain framework, and walks through the six-step loop used in documented migrations. For leaders comparing platforms before a migration, evaluation criteria for enterprise AI coding tools should include repository context, review gates, and validation workflows.

[ Meet Cosmos ]

Run your software agents at scale

Cosmos gives your agents the context, tools, and feedback loops they need to get better with every workflow.

Try it out

What Is AI Code Migration?

AI code migration covers "large-scale and systematic modifications across an entire codebase at the repository level," including API and dependency upgrades, framework modernization, language version evolution, and platform porting. A 2025 survey of LLMs in compilation identifies "Agentic & Iterative Workflows" as a distinct methodology. The survey states, "This advanced methodology treats the LLM as a reasoning engine within a larger loop. The 'agent' can plan, use external tools (like compilers, verifiers, or SMT solvers), and iteratively refine its output based on feedback from these tools." The distinction matters because migration success requires repository-level behavioral parity against the original system.

That definition separates three approaches with different track records. Rule-based transpilers rewrite syntax deterministically, but they leave runtime crashes and non-idiomatic output behind: C2Rust passes only 5 of 24 tests on real projects, and the ceiling is the syntactic subset the frontend accepts. One-shot LLM translation runs a single sequence-to-sequence rewrite and achieves 2.1%-47.3% success across models, with hallucinated APIs and silent semantic drift as the primary failure modes at function level. Agentic loops generate, verify with compiler and tests, then repair; a 79.3% one-shot baseline rises to 92.1% after 10 refinement cycles with Claude Code, though overfitting to the test suite without parity checks is the failure mode to plan for at repository level.

Transpilers fail on scale and idiom. Meta's Java-to-Kotlin migration found IDE-based conversion untenable: Meta reported that IDE-based conversion would have required engineers to run the conversion almost 100,000 times across the Android codebase. One-shot LLM translation fails on correctness; for PyTorch-to-JAX work, researchers found that without a reliable execution-based verification loop, LLMs tend to hallucinate incorrect mathematical and semantic judgements.

The agentic formulation, as PyMC Labs put it: "you put the AI into a loop where it writes code, compiles it, tests it against a reference implementation, and can't finish until everything matches."

Why One-Shot Translation Fails at Repository Scale

Repository-level translation defeats every tested model without a loop. The RepoTransBench authors conclude repository-level translation needs different methods than fine-grained translation because current LLM methods struggle with large-scale context management, complex dependency analysis, and full environment configuration; their own best method, RepoTransAgent, reaches only 32.8% success under repository conditions. Microsoft's TRANSREPO-BENCH found even state-of-the-art LLMs reach only 26.65% accuracy under realistic repository conditions.

Four failure modes have documented rates. A study of GPT-4 across 18 Java APIs recorded API misuse in 62% of cases, breaking correctness through hallucinated APIs and incorrect calls. A study of 16 models measured package hallucination at an average 19.6% of generated dependencies, which breaks environment configuration downstream. RustRepoTrans attributed 77.9% of all Rust translation errors to misunderstood language differences that create semantic drift. And a web API benchmark found only 30% of full completions were fully correct without validation.

A risky class of bugs compiles and runs. The modulo operator behaves differently across languages: Python retains the sign of the divisor, while Java and C retain the sign of the dividend. That difference produces wrong outputs with no runtime error. Java defines int arithmetic modulo 2³², but a naive C translation uses signed int where overflow is undefined behavior. Compilers then produce divergent hash function results. Only behavioral comparison against the original system will catch either bug.

When to Migrate: A Decision Framework for CTOs

The migrate-or-maintain decision shifts when AI-assisted repair loops reduce execution cost while legacy operations, staffing scarcity, and rewrite risk keep increasing. The US federal government spends $83 billion, 79% of planned FY 2025 IT spending on operations and maintenance of existing systems. GAO's 11 legacy systems most in need of modernization are 23 to 60 years old and cost roughly $754 million annually to run. In the private sector, McKinsey finds technical debt consumes 20 to 40 percent of technology budgets.

Talent risk compounds the cost. GAO warns that reliance on COBOL creates COBOL talent risk through "a decrease in the availability of individuals with the proper skill sets."

Historically, the counterweight was rewrite risk. A McKinsey/Oxford study of 5,400 projects found large IT projects run 45% over budget while delivering 56% less value than predicted. Deferral was often the rational choice.

For the framework itself, Forrester's REAP model scores each application on business fitness and technical fitness as a continuous assessment. Gartner's 2024 Market Guide names three primary drivers: "technical debt, lack of business fit and high costs." The research favors migration where test coverage is high, the task is well-bounded, and the codebase can stay relatively stable. Examples include a single version upgrade or one framework pair. Teams should hold back where they have not documented business logic and no characterization tests exist yet, because those tests are a prerequisite for the loop below. For teams prioritizing debt reduction before migration, a survey of code refactoring tools can identify modernization support for debt remediation work.

Teams can put the decision into practice with a migration-readiness table:

The table converts the migrate-or-maintain choice into prerequisites that the six-step migration loop can verify.

The Six-Step Migration Loop

The six-step AI migration loop applies the prerequisites to repository-scale code. Each step follows the same operating rule: when the output is wrong, update the loop that produced the code.

The loop runs in this order:

1. Build the rulebook and dependency map before translation starts.
2. Inventory language, API, and framework gaps that can cause semantic drift.
3. Stress-test the loop on a hard vertical slice before scale-out.
4. Translate bounded code units in parallel against shared validation gates.
5. Compile, run, and repair with compiler and test feedback.
6. Match migrated behavior against original outputs before cutover.

The following sections explain each step through its mechanism, failure mode, and validation signal.

Step 1: Build the Rulebook and Dependency Map

The rulebook and dependency map make AI migration deterministic by encoding source-to-target patterns and sequencing work before any translation runs. AWS describes its agents as building a deterministic app model, extracting "code structure, runtime behavior, and data relationships across the entire system" before LLMs enter the workflow. Google's migration tooling makes the same division of labor explicit: deterministic AST techniques handled change-location discovery and validation, while LLM edit generation produced the edits.

In Cosmos, Experts encode this rulebook-first migration work in the Expert Registry, defining agent behavior, tools, and triggers against the shared repository rulebook. For organizations formalizing review controls at the same time, a comparison of open source AI code review tools shows how repository context, policy enforcement, and CI integration differ across the category.

Step 2: Inventory the Gaps

The gap inventory makes semantic-drift risks explicit by cataloguing source constructs with no direct target equivalent before agents translate production code. In RustRepoTrans, misunderstood language differences caused 77.9% of all errors. The Context Engine can surface gap candidates from repository-wide dependency maps before agents translate production code. Berkeley's LLMLIFT work instead frames code migration around verified lifting, translating source programs into a higher-level intermediate representation (IR) that captures DSL operator semantics before generating target code. Teams convert every gap found here into an explicit rule, a flagged construct routed to a human, or a stress-test case for step 3, rather than a silent divergence discovered in production.

Step 3: Stress-Test with a Mini-Migration

A stress-test mini-migration exposes loop defects before parallel scale-out by running the full migration loop end to end on a deliberately hard vertical slice. Airbnb's Enzyme-to-React Testing Library migration shows loop-tuning economics: 75% of files migrated successfully within 4 hours, and four days of prompt refinement pushed that to 97%. The team used "sample, tune, sweep" with retry loops and dynamically expanded context, then re-ran the migration. Each fix to the rulebook or prompts corrects every file that failed for that reason, while a hand-edit corrects one.

By the end of the mini-migration, the program should have loop artifacts:

Those artifacts decide whether parallel scale-out is ready or whether the loop still needs tuning.

Step 4: Translate in Parallel

Parallel agentic translation scales migration by splitting bounded code units across agents that share validation gates, the mechanism used in documented work ranging from Google's 39 internal migrations to test-framework rewrites. Google's retrospective shows the human-to-agent ratio this allows: 3 developers drove 39 distinct migrations over 12 months. They submitted 595 code changes containing 93,574 edits, and the LLM generated 74.45% of changes. Parallel translation still needs shared repository state, because independent agents can otherwise make locally valid edits that conflict across package boundaries. Teams weighing scheduling, state sharing, review gates, and rollback behavior can compare AI workflow orchestration platforms side by side.

Cosmos runs cloud-agent sessions from the same repository state and pauses at review checkpoints before cross-file edits land, so parallel translation converges rather than diverges across packages.

Step 5: Compile, Run, Repair

The compile-run-repair migration step improves correctness by feeding syntax, compilation, and behavioral failures back into specialized repair agents. Agent4Decompile formalizes three validation levels where "L1 checks syntax, L2 checks compilation, and L3 checks behavioral equivalence. When validation fails at any level, a specialized LLM agent receives the error feedback and proposes targeted repairs." RustAssure implements the L2 loop concretely: when output fails to compile, it re-attempts by sending compiler error feedback with the original function back to the LLM.

Signal quality varies by feedback type. FeedbackEval measured repair success across feedback categories: mixed feedback leads at 63.6%, followed by LLM-Expert review at 62.9% and test feedback at 57.9%, while minimal feedback reaches 53.1% and compiler feedback trails at 49.2%, according to repair feedback results. Test feedback remains the strongest single structured signal because of its "explicit and structured nature, which directly pinpoints errors," and combining it with other signals outperforms any channel alone. That result argues for writing characterization tests before the migration starts, since they become the loop's most useful input, and for layering compiler and reviewer signals on top rather than relying on tests in isolation. The loop also needs guardrails against self-deception; TDAD's design reverts any change whose unit tests fail and checksums the evaluation script so agents cannot game it. Inside Cosmos, the Context Engine indexes and maps large codebases so repair agents have architectural context, and Prism routes each repair turn to the model best suited to the failure signal.

Repair gates separate failures by the feedback signal each agent can act on:

This separation keeps repair feedback specific enough for agents to fix the loop rather than masking semantic drift.

Step 6: Match Behavior Against Original Outputs

Behavioral parity verifies AI migration by comparing migrated outputs with original-system outputs across test and production-derived inputs. Because full semantic equivalence remains generally undecidable, production systems adopt behavioral equivalence: same outputs as the original on a defined input set. Michael Feathers' characterization testing rationale explains why the original system is the reference: "When a system goes into production, in a way, it becomes its own specification."

For live systems, parallel-run patterns extend the same idea to production traffic. Shopify ran Redis and MySQL inventory reservations in shadow-mode migration, writing every reservation to both systems. GitHub's Scientist library runs code paths in production, always returning the control result while recording differences. Test suites reflect the inputs someone thought to write down; production traffic adds the rest.

What Production Migrations Show

Production AI migration reports include vendor-reported and engineering-postmortem verification loops. Teams have applied those loops across tens of thousands of Amazon production applications, Airbnb's ~3,500 test-file migration, and Google's 39 internal migrations, with agents compiling, testing, repairing, or reviewing generated changes. These cases span runtime upgrades and test-framework migrations, with reported timelines ranging from 50 minutes for 10,000+ Java lines to a fleet-wide Java upgrade campaign that covered more than half of production applications within six months.

Amazon reported migrating tens of thousands of production applications from Java 8/11 to 17 with Amazon Q Developer, saving over 4,500 developer-years of work and delivering $260M in annual cost savings from performance improvements. In a separate internal write-up, AWS reported that Amazon's Java campaigns upgraded more than 50% of production applications in six months, with 79% of auto-generated code reviews applied without additional changes. Airbnb migrated roughly 3,500 test files from Enzyme to React Testing Library against a 1.5-year manual estimate, relying on retry loops with dynamic prompting and expanded context. Google's retrospective across 39 internal migrations, 93,574 edits, 12 months, and 3 developers estimated a 50% reduction in total migration time. And an AWS case study reports that Novacomp completed a Java 8 to 17 migration of 10,000+ lines in 50 minutes against a 3-week estimate, reducing technical debt by an average of 60%.

Google's papers surface the finding that should shape how leaders staff these programs: generation stopped being the constraint. A group of 306 reviewers across 149 teams, 37 offices, and 12 time zones reviewed those 595 changes, and the team reported that review bottlenecks remain because "code reviews and change rollouts still require a human operator and can quickly become bottlenecks in the larger code migration process." A JUnit3-to-JUnit4 migration of 5,359 files saw roughly 87% of AI-generated code committed without human modification, and the paper names human review as the main bottleneck.

Cosmos redesigns the review step around this reality. Deep Code Review, one of the Reference Experts that ships with Cosmos, uses cross-file dependency analysis to prioritize recall and route possible bugs and changed assumptions to humans before parity-gate review. Checkpoints concentrate human judgment at prioritization, spec review, and contextual review of how the code evolved. For migration work, that puts human attention on the rulebook and parity gates, where one correction fixes thousands of files.

Write the Rulebook Before You Translate a Single File

Rulebook-first migration replaces cheap translation with verified modernization by spending human effort on the controls that shape every generated edit. Teams that prompt an LLM to "rewrite this codebase" join the 0% column in repository-level benchmarks.

Start with the hardest vertical slice. Write characterization tests against current behavior, then run a stress-test mini-migration through the full six-step loop. Cosmos gives that mini-migration a shared repository state, review policies applied at cross-file checkpoints, and Experts that carry the rulebook forward into parallel scale-out, so ad hoc interruptions collapse into defined checkpoints where human judgment compounds across thousands of files.

FAQ

Related

• AI Tools for Large-Codebase Analysis: Enterprise Picks
• 6 AI Platforms for Safe Legacy Code Modernization
• 6 AI Tools for Cross-Repo Dependency Mapping at Scale
• 13 Best AI Coding Tools for Complex Codebases
• Best AI Coding Assistants for Every Team Size