How to Use 'Claude' to Explain Complex Legacy Code

Why Legacy Code Is a Good Fit for AI Explanation

Legacy code is hard to read not because the logic is inherently complex, but because the context that made it make sense — the business rule it was encoding, the bug it was working around, the convention of the era it was written in — has been lost. Claude's large context window and strong reasoning on unfamiliar syntax make it well suited to this specific problem: you can hand it a whole file (or several related files) and ask it to reconstruct the "why," not just restate the "what" in different words.

Getting the Most Out of a Single File

Paste the full source file rather than a fragment when you can. Claude's ability to reason about control flow and data dependencies improves significantly when it can see the whole picture — a function that looks pointless in isolation often makes sense once you can see every caller.

Here is a COBOL program from a 1990s billing system. Walk through it
section by section:
1. What is the overall purpose of this program?
2. What does each PARAGRAPH do, in plain English?
3. Are there any implicit business rules encoded in the logic (e.g.,
   hardcoded thresholds, special-case handling) that I should flag for
   the current team?
4. Are there any patterns here that suggest a workaround for a bug or
   limitation, rather than intentional business logic?

[paste code]

Asking explicitly for "implicit business rules" and "workarounds vs. intentional logic" is the difference between a generic paraphrase and something actually useful for a modernization effort — it directs Claude to flag the parts that matter most when legacy code gets rewritten.

Handling Files Too Large for One Prompt

For a sprawling legacy module too large to paste in one go, work top-down instead of dumping everything at once:

1. Paste just the function/procedure signatures and top-level structure first, and ask Claude to map out the overall architecture and identify which sections look most critical or most convoluted.
2. Paste the specific sections it flagged as complex, one at a time, and ask for a deep explanation of just that piece.
3. Ask it to describe data flow between the sections you've now covered — what gets passed in, what gets mutated, what gets returned — since that's usually where legacy bugs hide.

Explaining Dense Regular Expressions

Legacy regex patterns are a common pain point — a 200-character pattern with no comments, written years ago, that nobody dares touch. Ask Claude to break it down token by token:

Explain this regex piece by piece, and tell me what kind of input string
it's designed to match and reject:

^(?=.*[A-Z])(?=.*[a-z])(?=.*\d)(?=.*[@$!%*?&])[A-Za-z\d@$!%*?&]{8,}$

Claude will typically decompose this into its lookahead assertions (at least one uppercase, one lowercase, one digit, one special character) and the final character class plus length requirement — turning an opaque wall of symbols into a plain-English password policy statement you can document inline.

Explaining Assembly or Low-Level Code

For assembly, provide the target architecture explicitly (x86, ARM, MIPS) since mnemonics and calling conventions differ, and ask for a higher-level pseudocode translation alongside the line-by-line explanation:

This is x86-64 assembly (AT&T syntax) from a disassembled binary. For each
block:
1. Explain what the instructions do in plain English.
2. Translate the block into equivalent C-like pseudocode.
3. Identify the calling convention being used and what's happening to the
   stack/registers at function boundaries.

[paste code]

Turning Explanations into Documentation

Once Claude has explained a section, ask it to generate documentation you can actually commit to the repo — a docstring, a README section, or inline comments matching the surrounding style:

Based on your explanation above, write inline comments for this function
in the same commenting style already used in the file (don't introduce a
new comment convention), plus a 3-sentence summary I can put at the top
of the file.

Verify Before You Trust It

A good verification habit: after getting an explanation, ask Claude to also identify what it's uncertain about ("what parts of this explanation are you least confident in?"). This surfaces the exact spots where you should double-check against the original system's behavior or actual test output rather than trusting the paraphrase.

Wrap-Up

Claude is most useful on legacy code when you ask it to do more than restate syntax — push it to identify implicit business rules, distinguish intentional logic from bug workarounds, and flag its own uncertainty. Combined with working top-down on large files and verifying against real test behavior, this turns a multi-day archaeology exercise into a task you can complete in an afternoon.