Understanding code you didn't write

There’s a specific situation this page is for, and it’s more common than anyone admits in public. There is a system your organisation depends on. The people who built it have left, or moved on, or genuinely don’t remember. There’s no documentation worth the name. And every question about it — can we change this?, what would that break?, why does it do this? — currently costs a meeting, or a guess.

The reason that situation used to be so expensive is worth being precise about, because it explains why it’s different now. The knowledge was never actually lost. It’s all still there, written down exactly, in the code itself. What was lost was the institutional memory of how to navigate it — and the only tool for recovering that was a person with the time and the skill to read the whole thing. That person was expensive and usually didn’t exist.

Claude reads it directly. Not a summary of it, not a description someone wrote about it once — the actual files, as they are today. Which means the map can be rebuilt from the territory, by someone who couldn’t have read the territory themselves.

Start by reading, because reading is free

If you take nothing else from this page: reading is the safe half of this tool. Asking Claude to explain something changes nothing at all. No file is touched, nothing is saved, there is nothing to undo. The whole apparatus of review and permissions exists for the moment Claude proposes a change — and none of it is engaged when you’re only asking questions.

So the correct amount of caution when reading is very little, and the correct amount of curiosity is a great deal. This is the part of the tool where you can afford to be fearless, and where people are strangely reluctant to be.

Name a file. It’s the biggest upgrade available.

The instinct, faced with something large and frightening, is to ask the largest possible question: explain the codebase. It feels efficient. It’s the weakest thing you can ask.

That question forces a skim — list the files, sample a few, infer the shape, summarise broadly. You get something long, vague, and partly guessed, because the reading was spread too thin to be careful anywhere.

Now name one file:

explain server/index.js

One file gets opened and read properly, and what comes back is short, specific, and grounded in lines that actually exist. It’s also checkable — you can open the same file and see whether the description matches, which you cannot do with a summary of forty files.

This is how experienced people read code, and it’s worth knowing that, because it dissolves a bit of the intimidation: nobody reads a codebase. They read one file, with a goal, and then another. The scary thing was never a single object to be comprehended; it was always a pile of small ones.

Or name the thing inside the file

Scope one level finer and it gets better still. Most real curiosity isn’t about a file — it’s about a name. A colleague says the problem is in handleContact. An error mentions saveMessage. You’re reading something and hit a call to sendNotification you’ve never seen.

You don’t need to find the file first:

where is handleContact and what does it do?

You get the location and the explanation in one answer, because the name was enough to find it with.

The reason this matters more than it sounds is friction. Finding a function by name was never hard — open the editor, jump to symbol, scan the hits, try a couple of files. It was just slow enough that people stopped bothering, and skipped the question instead. When asking and answering take the same few seconds, you can afford to be curious about every name you don’t recognise, rather than rationing curiosity for the ones that look important. That change in what you can afford is the actual unlock.

Follow the wire

Once single things make sense, the questions worth asking are about connections — where a value came from, and what depends on it. Where does this come from? and where is this used? are the same question pointed in opposite directions, and the second one is the one people skip. It’s also the one that tells you whether changing something is safe.

That move has its own page: where does this come from, where is it used? The habit it turns on is asking for the list of callers rather than a yes — because a list is something you can spot-check, and a yes isn’t.

When it’s broken rather than unfamiliar

The other half of reading is the wall of red text. An error is not a verdict on you; it’s a machine stating, with total accuracy and no tact, the exact point where its instructions stopped making sense — and Claude reads that format fluently.

The whole move, plus the one mistake almost everybody makes (trimming the error before pasting it), is in reading errors and stack traces.

Read what it read

One honest caveat, because it applies to everything above. An explanation of code is still a generated explanation, and a fluent one is not automatically a correct one — the same trust-and-verify problem that applies everywhere else applies here.

The saving grace is that reading is unusually easy to check. Every claim points at a file and a line, so confirming one is a matter of opening it and looking. You don’t need to verify everything; you need to verify one link in the chain, and usually the one the rest of your decision rests on. Fifteen seconds of that is the difference between a map you can act on and a story that merely sounds right.

That’s also why the useful questions ask for specifics — a list of files, a named function, a line number. Specific answers are checkable answers. Vague ones aren’t, and the vagueness is where mistakes hide.