Part 14 — Taming Legacy Code with AI: From Archaeology to Modern Architecture

AI Workflow · Module 14

Taming Legacy Code with AI

"The most valuable code you'll ever read is the code you didn't write."

3 Phases Understand → Document → Modernise

Zero Rewrites Incremental changes only

Days not Weeks to understand any codebase

Your team inherited a billing system built in 2019. The developer who wrote it left in 2022. There is no documentation. There are no tests. The code works — which is the only reason nobody has touched it. Until now, because the business needs a new pricing tier added next week.

Before AI, this scenario meant two weeks of archaeology, three wrong assumptions, one production incident, and a lot of apologetic Slack messages.

With AI and the right workflow, you can understand that billing system in a day, document it in an afternoon, and add the new feature safely — without breaking what works.

This is the most underrated use case for AI in development. Let's build the process.

The Golden Rule of Legacy Work

Before any AI interaction with legacy code, memorise this:

Understand Before You Touch

Never ask AI to modify legacy code you haven't read and understood. AI will confidently refactor code that has subtle side effects, undocumented business rules, or hidden dependencies — and it will break production. Use AI to understand first. Modify second.

Phase 1 — Comprehension: Understanding What You Inherited

The first hour with any legacy codebase has one goal: build a mental map. You are not changing anything. You are reading.

AI is an extraordinary reading partner for this phase. It can summarise, explain, trace call chains, and identify patterns in code that would take you days to trace manually.

The 5 Comprehension Prompts

Use these prompts in sequence. Each one builds on the previous. Paste the code directly into Claude Code or Claude.ai:

<div style="background: rgba(245,158,11,0.08); border: 1px solid rgba(245,158,11,0.3); border-radius: 10px; padding: 16px; display: flex; gap: 14px; align-items: flex-start;">
  <div style="background: #f59e0b; color: #000; font-weight: 900; font-size: 0.9rem; border-radius: 6px; padding: 6px 12px; flex-shrink: 0;">P1</div>
  <div>
    <div style="color: #fcd34d; font-weight: 600; margin-bottom: 6px;">The Overview Prompt</div>
    <div style="background: #0f172a; border-radius: 6px; padding: 10px; font-family: monospace; color: #94a3b8; font-size: 0.8rem; line-height: 1.7;">"Read this file. Explain in plain English: what problem does this code solve? What is its input and output? Are there any parts that look unusual or risky?"</div>
  </div>
</div>

<div style="background: rgba(245,158,11,0.08); border: 1px solid rgba(245,158,11,0.3); border-radius: 10px; padding: 16px; display: flex; gap: 14px; align-items: flex-start;">
  <div style="background: #f59e0b; color: #000; font-weight: 900; font-size: 0.9rem; border-radius: 6px; padding: 6px 12px; flex-shrink: 0;">P2</div>
  <div>
    <div style="color: #fcd34d; font-weight: 600; margin-bottom: 6px;">The Dependency Prompt</div>
    <div style="background: #0f172a; border-radius: 6px; padding: 10px; font-family: monospace; color: #94a3b8; font-size: 0.8rem; line-height: 1.7;">"What does this code depend on? What depends on it? List every import, every function called, and every place this function's output is used. Flag anything that looks like a hidden coupling."</div>
  </div>
</div>

<div style="background: rgba(245,158,11,0.08); border: 1px solid rgba(245,158,11,0.3); border-radius: 10px; padding: 16px; display: flex; gap: 14px; align-items: flex-start;">
  <div style="background: #f59e0b; color: #000; font-weight: 900; font-size: 0.9rem; border-radius: 6px; padding: 6px 12px; flex-shrink: 0;">P3</div>
  <div>
    <div style="color: #fcd34d; font-weight: 600; margin-bottom: 6px;">The Business Logic Prompt</div>
    <div style="background: #0f172a; border-radius: 6px; padding: 10px; font-family: monospace; color: #94a3b8; font-size: 0.8rem; line-height: 1.7;">"Identify every place in this code where a business decision is being made. List them as rules: 'IF [condition] THEN [business outcome].' Do not explain the code — only extract the business rules embedded in it."</div>
  </div>
</div>

<div style="background: rgba(245,158,11,0.08); border: 1px solid rgba(245,158,11,0.3); border-radius: 10px; padding: 16px; display: flex; gap: 14px; align-items: flex-start;">
  <div style="background: #f59e0b; color: #000; font-weight: 900; font-size: 0.9rem; border-radius: 6px; padding: 6px 12px; flex-shrink: 0;">P4</div>
  <div>
    <div style="color: #fcd34d; font-weight: 600; margin-bottom: 6px;">The Risk Prompt</div>
    <div style="background: #0f172a; border-radius: 6px; padding: 10px; font-family: monospace; color: #94a3b8; font-size: 0.8rem; line-height: 1.7;">"What are the three most dangerous things about this code? What would be most likely to break if I modified it? Are there any anti-patterns, race conditions, or silent failure modes I should know about before touching it?"</div>
  </div>
</div>

<div style="background: rgba(245,158,11,0.08); border: 1px solid rgba(245,158,11,0.3); border-radius: 10px; padding: 16px; display: flex; gap: 14px; align-items: flex-start;">
  <div style="background: #f59e0b; color: #000; font-weight: 900; font-size: 0.9rem; border-radius: 6px; padding: 6px 12px; flex-shrink: 0;">P5</div>
  <div>
    <div style="color: #fcd34d; font-weight: 600; margin-bottom: 6px;">The Change Impact Prompt</div>
    <div style="background: #0f172a; border-radius: 6px; padding: 10px; font-family: monospace; color: #94a3b8; font-size: 0.8rem; line-height: 1.7;">"I need to [describe your specific change]. Based on everything in this code, what would break? What should I test before and after? What is the safest sequence of changes to make?"</div>
  </div>
</div>

Verify everything AI tells you about legacy code. AI reads code accurately but can miss runtime behaviour, environment-specific configurations, and business context that lives outside the code file. Use P1–P5 as a starting map, then validate against actual behaviour before acting.

Phase 2 — Documentation: Writing What Should Have Been Written

Once you understand the code, document it — while the AI-assisted comprehension is fresh. This is the work that pays compounding dividends to every developer who touches this code after you.

<div style="display: flex; gap: 16px; align-items: flex-start; background: rgba(168,85,247,0.1); border: 1px solid rgba(168,85,247,0.4); border-radius: 12px; padding: 18px;">
  <div style="background: #a855f7; color: #fff; font-weight: 900; font-size: 1rem; border-radius: 8px; padding: 8px 14px; flex-shrink: 0; text-align: center;">D1</div>
  <div>
    <div style="color: #c084fc; font-weight: 700; font-size: 1rem; margin-bottom: 6px;">Function-Level JSDoc</div>
    <div style="color: #e9d5ff; font-size: 0.9rem; line-height: 1.7; margin-bottom: 10px;">Ask AI to generate JSDoc comments for every function. Then review each one against the actual code. Correct anything that doesn't match the true behaviour. Inaccurate documentation is worse than no documentation.</div>
    <div style="background: #0f172a; border-radius: 6px; padding: 10px; font-family: monospace; color: #94a3b8; font-size: 0.8rem; line-height: 1.7;">"Add JSDoc to every function in this file. For each function: describe what it does, document every parameter including its valid range/type, document the return value, and flag any side effects or known edge cases."</div>
  </div>
</div>

<div style="text-align: center; color: #334155; font-size: 1.2rem; padding: 2px 0;">↓</div>

<div style="display: flex; gap: 16px; align-items: flex-start; background: rgba(168,85,247,0.1); border: 1px solid rgba(168,85,247,0.4); border-radius: 12px; padding: 18px;">
  <div style="background: #a855f7; color: #fff; font-weight: 900; font-size: 1rem; border-radius: 8px; padding: 8px 14px; flex-shrink: 0; text-align: center;">D2</div>
  <div>
    <div style="color: #c084fc; font-weight: 700; font-size: 1rem; margin-bottom: 6px;">The Module README</div>
    <div style="color: #e9d5ff; font-size: 0.9rem; line-height: 1.7; margin-bottom: 10px;">For each major folder or module, generate a README that explains the purpose, the data flow, and the business rules. This becomes the onboarding document for the next developer — and your future self in 6 months.</div>
    <div style="background: #0f172a; border-radius: 6px; padding: 10px; font-family: monospace; color: #94a3b8; font-size: 0.8rem; line-height: 1.7;">"Based on all the files in this module, write a README.md that explains: what this module does, the key data flow, the main business rules it enforces, and what a developer must understand before modifying anything here."</div>
  </div>
</div>

<div style="text-align: center; color: #334155; font-size: 1.2rem; padding: 2px 0;">↓</div>

<div style="display: flex; gap: 16px; align-items: flex-start; background: rgba(168,85,247,0.1); border: 1px solid rgba(168,85,247,0.4); border-radius: 12px; padding: 18px;">
  <div style="background: #a855f7; color: #fff; font-weight: 900; font-size: 1rem; border-radius: 8px; padding: 8px 14px; flex-shrink: 0; text-align: center;">D3</div>
  <div>
    <div style="color: #c084fc; font-weight: 700; font-size: 1rem; margin-bottom: 6px;">The Business Rules Register</div>
    <div style="color: #e9d5ff; font-size: 0.9rem; line-height: 1.7; margin-bottom: 10px;">Extract all business rules from the code into a single document. This is gold. Most business rules in legacy systems exist only in the code — never in requirements docs. Extracting them prevents the same rule being re-implemented differently in a new service.</div>
    <div style="background: #0f172a; border-radius: 6px; padding: 10px; font-family: monospace; color: #94a3b8; font-size: 0.8rem; line-height: 1.7;">"Extract every business rule embedded in this codebase into a structured list. Format as: Rule ID | What triggers it | What it enforces | Where in the code it lives."</div>
  </div>
</div>

Phase 3 — Safe Refactoring: The Strangler Fig Pattern

The most dangerous thing you can do with legacy code is rewrite it from scratch. The second most dangerous is making large, sweeping refactors without a safety net. The safe path is incremental — and the Strangler Fig pattern is the most reliable incremental approach.

❌ The Big Rewrite

→ "We'll rewrite the whole thing properly"
→ Takes 3× longer than estimated
→ Misses 40% of the business rules
→ Can't run old and new side by side
→ Big bang release → big bang failure

Known as "the second system effect". Almost always a disaster.

✅ The Strangler Fig

→ Replace one small piece at a time
→ Old and new code run in parallel
→ Each piece is tested before the next
→ Roll back is always one piece
→ No big bang — gradual takeover

Named after the strangler fig vine that grows around a host tree. It works.

How to Apply the Strangler Fig with AI

The process is a 4-step loop you repeat for each piece of the codebase you want to modernise:

<div style="background: rgba(245,158,11,0.1); border: 1px solid rgba(245,158,11,0.35); border-radius: 10px; padding: 16px; display: flex; gap: 14px; align-items: flex-start;">
  <div style="background: #f59e0b; color: #000; font-weight: 900; font-size: 0.9rem; border-radius: 6px; padding: 6px 12px; flex-shrink: 0;">1 IDENTIFY</div>
  <div>
    <div style="color: #fcd34d; font-weight: 600; margin-bottom: 4px;">Find the smallest independently replaceable piece</div>
    <div style="color: #fde68a; font-size: 0.85rem; line-height: 1.6;">Ask AI: "Which part of this codebase is most self-contained and could be extracted and replaced without affecting the rest?" Start there. Never start with the core.</div>
  </div>
</div>

<div style="text-align: center; color: #334155; font-size: 1.2rem; padding: 2px 0;">↓</div>

<div style="background: rgba(34,197,94,0.1); border: 1px solid rgba(34,197,94,0.35); border-radius: 10px; padding: 16px; display: flex; gap: 14px; align-items: flex-start;">
  <div style="background: #22c55e; color: #000; font-weight: 900; font-size: 0.9rem; border-radius: 6px; padding: 6px 12px; flex-shrink: 0;">2 COVER</div>
  <div>
    <div style="color: #4ade80; font-weight: 600; margin-bottom: 4px;">Write characterisation tests before changing anything</div>
    <div style="color: #86efac; font-size: 0.85rem; line-height: 1.6;">Characterisation tests capture current behaviour — including bugs. Ask AI: "Write tests that document what this function currently does, including any edge case behaviour, even if it looks wrong." These tests protect you during the replacement.</div>
  </div>
</div>

<div style="text-align: center; color: #334155; font-size: 1.2rem; padding: 2px 0;">↓</div>

<div style="background: rgba(168,85,247,0.1); border: 1px solid rgba(168,85,247,0.35); border-radius: 10px; padding: 16px; display: flex; gap: 14px; align-items: flex-start;">
  <div style="background: #a855f7; color: #fff; font-weight: 900; font-size: 0.9rem; border-radius: 6px; padding: 6px 12px; flex-shrink: 0;">3 REPLACE</div>
  <div>
    <div style="color: #c084fc; font-weight: 600; margin-bottom: 4px;">AI rebuilds the piece to the same interface, modern standards</div>
    <div style="color: #e9d5ff; font-size: 0.85rem; line-height: 1.6;">Prompt: "Rewrite this function with the same interface (same inputs, same outputs, same business rules from the register) using modern TypeScript. Keep all characterisation tests passing." Review the new code against the business rules register.</div>
  </div>
</div>

<div style="text-align: center; color: #334155; font-size: 1.2rem; padding: 2px 0;">↓</div>

<div style="background: rgba(34,211,238,0.1); border: 1px solid rgba(34,211,238,0.35); border-radius: 10px; padding: 16px; display: flex; gap: 14px; align-items: flex-start;">
  <div style="background: #06b6d4; color: #000; font-weight: 900; font-size: 0.9rem; border-radius: 6px; padding: 6px 12px; flex-shrink: 0;">4 VALIDATE</div>
  <div>
    <div style="color: #22d3ee; font-weight: 600; margin-bottom: 4px;">All tests pass → deploy → repeat for the next piece</div>
    <div style="color: #cffafe; font-size: 0.85rem; line-height: 1.6;">Old piece is now gone. New piece is live. Characterisation tests are still running as your regression suite. Pick the next smallest replaceable piece and loop back to step 1.</div>
  </div>
</div>

What AI Is Bad at With Legacy Code

This is as important as knowing what AI is good at.

⚙️

Runtime Behaviour

AI reads the code, not the running system. Race conditions, memory leaks, and environment-specific bugs are invisible to static analysis.

🔍

Business Context

AI doesn't know WHY a rule exists. "If status === 7" could be a critical fraud check or a forgotten workaround. Always ask a domain expert before removing mysterious conditions.

📦

External Dependencies

AI sees the import but not the behaviour of the library at the version actually running in production. Version-specific bugs and deprecated API behaviour must be validated manually.

The Legacy Code Playbook — One Page

Everything in this article condensed into the sequence you follow on your first day with any unknown codebase:

<div style="display: flex; gap: 10px; align-items: flex-start; padding: 10px 14px; background: rgba(245,158,11,0.06); border-radius: 8px;">
  <span style="color: #f59e0b; font-weight: 700; min-width: 80px;">Hour 1</span>
  <span style="color: #e2e8f0;">Run P1–P3 comprehension prompts on the most critical files. Build your mental map. Take notes on the business rules you find.</span>
</div>

<div style="display: flex; gap: 10px; align-items: flex-start; padding: 10px 14px; background: rgba(245,158,11,0.06); border-radius: 8px;">
  <span style="color: #f59e0b; font-weight: 700; min-width: 80px;">Hour 2</span>
  <span style="color: #e2e8f0;">Run P4–P5 risk and change impact prompts. Identify the danger zones. Know what to stay away from for now.</span>
</div>

<div style="display: flex; gap: 10px; align-items: flex-start; padding: 10px 14px; background: rgba(168,85,247,0.06); border-radius: 8px;">
  <span style="color: #a855f7; font-weight: 700; min-width: 80px;">Day 1 PM</span>
  <span style="color: #e2e8f0;">Generate JSDoc with D1 prompt. Generate module README with D2. Build the business rules register with D3. Commit all documentation.</span>
</div>

<div style="display: flex; gap: 10px; align-items: flex-start; padding: 10px 14px; background: rgba(34,197,94,0.06); border-radius: 8px;">
  <span style="color: #22c55e; font-weight: 700; min-width: 80px;">Day 2</span>
  <span style="color: #e2e8f0;">Write characterisation tests for the area you need to change. All tests passing means you have a safety net. Now you're ready to modify.</span>
</div>

<div style="display: flex; gap: 10px; align-items: flex-start; padding: 10px 14px; background: rgba(34,211,238,0.06); border-radius: 8px;">
  <span style="color: #22d3ee; font-weight: 700; min-width: 80px;">Day 3+</span>
  <span style="color: #e2e8f0;">Make your change incrementally. Run characterisation tests after every step. If tests break — stop and understand why before continuing. Strangler Fig for anything that needs modernising.</span>
</div>

The meta-lesson: Legacy code is not a problem to be solved. It is a system to be understood. AI makes the understanding phase dramatically faster — but the understanding is still your job. Every developer who follows the comprehension-first principle is safer, faster, and less likely to cause a production incident than one who jumps straight to changing code.

Series Complete

You've completed the AI Workflow Series

From your first tool setup (Part 0) to the AI-first mindset, strategic delegation, prompt architecture, debugging, code review, design principles, quality gates, model selection, team standards, skill maintenance, ethics, testing, and legacy code — you now have the complete framework for working with AI as a professional developer. The developers who use these tools well don't just write more code. They build better systems, faster, with less risk, and compound their advantages over time. That is the point of all of it.

Part 0 — Toolkit Setup

Parts 1–12 — The Core Series

Part 13 — AI Testing

Part 14 — Legacy Code ✓