Explain This Codebase: Understand Legacy Code in an Afternoon

The Problem: Code With No Owner

Every team has it. A script that quietly runs the month-end reconciliation. A tool a vendor handed over two years ago. A macro written by someone who left the company. It works — until you're the one who has to change it, debug it, or explain it to your reporting manager on a call you didn't expect to be on.

The instinct is to open the file and read top to bottom. For anyone without a deep coding background, that's an afternoon lost to dread — and you still don't trust your own understanding at the end of it.

The Real Reason It's Hard: The Theory Walked Out the Door

Here's the insight that changes how you approach this. In a famous 1985 essay, Programming as Theory Building, the computer scientist Peter Naur argued that the most valuable thing a programmer builds isn't the code — it's the theory: the mental model of why the system works the way it does, what trade-offs were made, and what the author was worried about. The source code is only a lossy snapshot of that theory. The real thing lived in the author's head.

So when someone leaves and hands you their code, the code is all that survived — the theory is gone. That's why legacy code feels impossible: you're not missing a programming skill, you're missing the reasoning that was never written down.

Which reframes the whole task. You're not trying to read the code. You're trying to rebuild the theory behind it — and that's a job of asking the right questions, not decoding syntax. It's exactly the kind of work AI is good at: turning dense logic back into the human reasoning it came from.

Why AI Is Good at This (Even If You Don't Code)

Summarizing and explaining is the single strongest thing a large language model does. A pricing rule buried in 200 lines of nested conditions is precisely what a human reads slowly and an AI reads instantly. Your job shifts from decoding to interrogating — and asking good questions is a skill you already have.

The goal isn't to become a developer. It's to walk into the next conversation able to say what the code does, where the risk is, and what you'd confirm before changing anything.

The 4 Questions That Rebuild the Theory

Each question below recovers one piece of the author's lost mental model: what it does, what they feared, what it's wired to, and what you still can't know. Notice the shape of each prompt — Role (who the AI should be), Task (what to do), Context (your code and situation), and an Example when the format matters. That structure is what turns a vague answer into a useful one. Work through them in order.

1. The Mechanism — what it actually does

Role: You are a patient senior engineer explaining code to a sharp colleague who does not write code.
Task: Walk through what the code below does, step by step, in plain English. Define every technical term the moment you use it. Finish with one line: "In plain words, this code's job is ___."
Context: I need to understand this well enough to explain it in a review. I am not editing it yet.
Code:
[PASTE THE CODE]

2. The Fears — what the author was worried about

Role: You are a meticulous code reviewer who has seen a lot of production incidents.
Task: List the 3 riskiest parts of this code — where it is most likely to fail, behave unexpectedly, or break if something outside it changes. For each, say WHY it's risky in one sentence.
Context: I'm trying to understand what the original author was probably careful about, so I don't break it.
Code:
[PASTE THE CODE]

3. The Wiring — what it's connected to

Role: You are a systems analyst mapping dependencies.
Task: List everything this code needs in order to run — inputs, files, databases, environment variables, and external services — and what happens if each one is missing or changes.
Context: I need to understand the blast radius before anyone touches this.
Example of the format I want:
- Depends on: [name] — used for: [what] — if it breaks: [effect]
Code:
[PASTE THE CODE]

4. The Gaps — what you still can't recover

Role: You are helping me reconstruct knowledge the original author never wrote down.
Task: Based only on this code, list the 5 most important questions I should ask the person or team who owns it before I change anything — the things the code itself can't tell me (intent, edge cases, history).
Context: The author has left; I want a checklist that protects me from a change I don't fully understand.
Code:
[PASTE THE CODE]

That fourth one is the honest part: some of the theory is genuinely unrecoverable from the code alone. Naming those gaps is how you avoid the trap of thinking you understand something you don't.

A Warning on Privacy (Read This First)

This matters more for code than for almost anything else, especially in Indian IT and financial-services environments:

Never paste proprietary, client, or production code into the free or public version of an AI tool. Source code can be a trade secret, and free tiers may use your input to train future models. Before you paste anything, confirm one of these is true: you're on a Team or Enterprise plan with a data-privacy guarantee, the code is non-sensitive, or you've stripped out anything identifying — credentials, client names, internal URLs. When in doubt, ask your security or compliance team first. One careless paste can become a real incident.

Where AI Stops and You Start

The theory you rebuild this way is a hypothesis, not gospel — AI can describe code confidently and still be wrong, especially about edge cases, the same hallucination risk that shows up in reports. So verify the parts that matter. When it tells you "this function does X," your follow-up is "show me the exact line where that happens." Then read those few lines yourself. You're verifying a summary, not decoding the whole file — and that's a job you can absolutely do. It's the same shift from reading to interviewing that powers the PDF Cruncher.

The Real World Story

I ran into this on my own office laptop. I was working with Claude, it produced a script for a task I was automating, and every time I tried to run it, our corporate security system blocked it cold.

I wanted to know why. Was the script doing something genuinely risky, or was this a false alarm I could safely raise with IT? The obvious move was to ask the AI directly: "why is my security tool blocking this?" So I did. But Claude has zero visibility into my company's security setup, and it showed. All it could offer was guesses — maybe it's this network call, maybe it's that file access. None of them matched what was actually happening. It was confidently speculating about an environment it simply couldn't see.

So I stopped asking the question it couldn't answer and asked the one it could. I told it to ignore my security system entirely and just explain, in pure logic, exactly what the script does step by step — what it reads, what it writes, and anything it reaches out to. Once I had that plain-English breakdown, I could see for myself which specific action my security software would flag, and I could explain it to our IT team in terms they trusted. The script was never the point; understanding it was. That's the whole trick: AI can't see your world, but it can explain the logic — and the understanding is what actually solves the problem.