Legacy Refactoring with AI — It's Already Real

# "Legacy Refactoring with AI Is a Bad Idea": Bad Advice from People Who Don't Know How to Do Preliminary Work

## Bad Advice from a Lecture

https://youtu.be/Nm3MsnngCJg?si=4QWKn2MKNIyEsEGg

Sheiko says:

> "At first, when I joined this project, I thought: 'Wow, cool, we have the opportunity to compare our new solution with the old one.' But the downside is that there are a ton of workarounds in the old solution that the agent either replicates — and then completely destroys the architecture — or it tries to explain to them not to do it, but then it can't fully replicate the old front end. And the biggest downside is architectural work. Mistakes are expensive. Any problem we introduced at the architecture formulation stage will persist throughout the entire project's lifetime. And we have a bunch of vibe coders using Claude Code for the first time and starting to do this."

Sounds scary. Sounds like an expert warning. The audience nods. Everyone thinks: "Yes, refactoring legacy with AI is dangerous, better not to try."

This is **bad advice**. Because it confuses cause and effect. The problem isn't that "legacy refactoring with AI is a bad idea." The problem is that **nobody did the preliminary work before refactoring**. When you throw an agent at an unprepared codebase without analysis, without specs, without metrics — yes, it will make mistakes. But that doesn't mean the task is bad. It means **you don't know how to prepare for it**.

---

## Refactoring Is a Clear Task

Refactoring and migration are **not ambiguous tasks**. They are among the most well-defined and structured tasks in development. Why?

Because you have **two clear states**:

- **Old state**: the existing codebase that works (even with workarounds)

- **New state**: the target architecture/stack you're moving toward

And there's a **contract between them**: behavior that must be preserved. APIs that must not break. Data that must not be lost.

This isn't "create something new from scratch where it's unclear what's needed." This is **transitioning from known state A to known state B while preserving invariants**. This is the most well-defined task that exists.

The problem was never the ambiguity of the task. The problem was the **volume of preparatory work** needed to properly formulate the task.

---

## What Preliminary Work Is Needed

Before starting refactoring or migration, you need to do **four things**. This is not optional. This is **mandatory**. And it was always mandatory, even before AI.

**1. Full codebase analysis.**

Not "look at a couple of modules." A complete analysis:

- Which modules exist and how they're connected (dependency graph)

- What contracts exist between modules (APIs, interfaces, data formats)

- Where the business logic is vs. infrastructure code

- Where the "workarounds" are and why they exist (commit history, comments)

- What's covered by tests and what isn't

- Which parts are actively used and which are dead

**2. Specs and migration plan.**

Based on the analysis:

- Target architecture (where we're heading)

- Migration order (which modules first, to avoid breaking dependencies)

- What we migrate 1:1, what we rewrite, what we discard

- What we DO NOT touch (critical pieces that must not break)

- Readiness criteria for each module

**3. Metrics and verification criteria.**

How to know the migration is successful:

- Behavioral tests: old and new code must produce identical results on the same inputs

- API contracts: signatures and formats must not break

- Performance: must not degrade

- Coverage: which parts are verified, which aren't

**4. Rollback strategy.**

What to do if the migration goes wrong. How to return to the old state. This isn't paranoia. This is basics.

---

## Why This Was Obvious Even Without AI

Any experienced specialist knows: **before refactoring, you need to do analysis, write a plan, and define metrics**. This is nothing new. This isn't some revelation of the AI era. This is **engineering fundamentals** taught in the first years of work.

So why did everyone postpone refactoring? Not because they didn't know what needed to be done. But because it was **physically difficult**:

- **Analyzing the entire codebase manually** — that's weeks. Sit down, read code, build the dependency graph, document contracts. On a large codebase, this is unmanageable for one person.

- **Writing specs** — that's more weeks. Formalize what you understood into a document you can hand to the team.

- **Defining metrics** — is difficult because you need to understand exactly what to verify.

As a result, refactoring was postponed. "Later. When there's time. When we hire people. When the tech debt burns off." Because the preparatory work cost more than the expected benefit.

All specialists **knew** what needed to be done. But **they didn't do it** because it was too expensive.

---

## Why It's Now Solvable (August 2026)

Here's what changed. **AI does the preparatory work in hours instead of weeks.**

**Codebase analysis:** The agent parses the entire project, builds a dependency graph, finds contracts, isolates business logic, marks workarounds. What took a person weeks, the agent does in **hours**. You get a complete map of the codebase without reading it manually.

**Extracting implicit knowledge:** The agent analyzes commit history, comments, related files. Pulls out what was "in the team's heads" and undocumented. Workarounds that seemed random get explanations: "this is a fix for bug X, which only reproduces under condition Y."

**Generating specs and plan:** Based on the analysis, the agent drafts specs: target architecture, migration order, what to migrate/rewrite/discard. You don't write from scratch. You **verify and adjust** what the agent proposed.

**Formulating metrics:** The agent suggests what to verify: which tests to write, which API contracts to check, which scenarios to run. You supplement with domain expertise.

**Generating verification tests:** The agent writes behavioral tests based on the old code. This is what used to be unmanageable: "write tests for legacy code that nobody understands." Now the agent reads the code and generates tests that capture the current behavior.

All of this together — **the preparatory work that used to cost months now costs days**. And that's precisely why legacy refactoring with AI **has stopped being a bad idea**. It has become a **solvable task**.

---

## What Exactly to Do: Step-by-Step Plan

**Step 1: Full codebase analysis (1–2 days).**

Prompt for the agent:

```

Analyze the project codebase:

1. Build a graph of modules and their dependencies

2. Identify contracts between modules (APIs, interfaces, data formats)

3. Separate business logic from infrastructure code

4. Find all "workarounds" and explain their origin (from commits, comments)

5. Determine which parts are covered by tests and which aren't

6. Mark dead code that isn't used

Format: structured report + dependency map.

```

**Step 2: Formulate specs and migration plan (1 day).**

Based on the report:

```

Based on the analysis, formulate a migration plan for [target stack]:

1. Target architecture

2. Module migration order (accounting for dependencies)

3. What we migrate 1:1, what we rewrite, what we discard

4. What we DO NOT touch (critical pieces)

5. Readiness criteria for each module

6. Rollback strategy

```

You **verify** the plan. Adjust for domain knowledge. Approve.

**Step 3: Metrics and verification tests (1–2 days).**

```

For each module to be migrated:

1. Write behavioral tests capturing the current behavior

2. Identify API contracts that must not break

3. Set performance metrics that must not degrade

```

The agent generates tests. You verify they cover critical scenarios.

**Step 4: Module-by-module migration (main phase).**

Migrate **one module at a time**. After each module:

- Run behavioral tests: old vs. new

- Check API contracts

- If discrepancies — agent fixes BEFORE moving to the next module

No "migrate everything in one step." Iterative pipeline with verification at every step.

**Step 5: Final verification and stabilization.**

Full test run. Load testing. Audit for "agent brought patterns from the old stack that aren't needed in the new one."

---

## Why Sheiko Failed

Because he **skipped the preparatory work**. He took a live legacy front end and told the agent: "Migrate to the new stack." Without analysis. Without specs. Without metrics. Without a plan.

And then **was surprised** that:

- The agent replicates workarounds (because nobody told it which parts are workarounds and which are features)

- It breaks features during fixes (because there are no behavioral tests capturing the current behavior)

- It doesn't understand business logic (because nobody extracted and formalized it from the code)

- Architectural errors persist for months (because there's no architecture plan, just "migrate somehow")

This isn't "legacy refactoring is a bad idea." This is **"refactoring without preparation is a bad idea."** And that has always been true, even without AI.

---

## Conclusion

"Legacy refactoring with AI is a bad idea" is bad advice. It confuses cause and effect. Refactoring is a **clear, structured task**: transitioning from known state A to known state B while preserving invariants.

The problem was never the ambiguity of the task. The problem was the **volume of preparatory work**: codebase analysis, specs, metrics. This was physically difficult and expensive, so everyone postponed it. All specialists **knew** what needed to be done, but **they didn't do it** because it took months.

Now, in August 2026, AI does the preparatory work in days instead of months. Codebase analysis, implicit knowledge extraction, spec and test generation — all of it is automated. And that's precisely why legacy refactoring **has stopped being a bad idea**. It has become a solvable task.

Those who say "don't tackle legacy refactoring with AI" simply don't know how to do the preliminary work. And that's their problem. But they shouldn't project it onto a task that has always been well-understood.