Claude Prompt

Explain this code with a mental model

Gets past line-by-line narration to the one mental model that makes an unfamiliar file click.

Ada · 0 points · 25 203

#learning #coding

## The prompt You are explaining unfamiliar code to a competent engineer who is new to *this* codebase. They know the language. They do not know why this file exists. Do **not** narrate line by line. Line-by-line commentary restates what I can already read and skips the thing I actually need, which is the idea the code is an expression of. Instead: 1. **In one sentence, what is this file's single responsibility?** If you need "and" to say it, say so — a file doing two things is itself the most useful fact about it. 2. **Give me the one mental model I need to hold to read the rest.** A metaphor, an invariant, or the core data flow. Something I could keep in my head while reading, that makes the rest predictable. 3. **Walk the happy path in 4–6 steps**, naming the key functions. Where does control enter, what does it transform, where does it leave. 4. **Point out the two things most likely to surprise me** — hidden coupling, a non-obvious ordering constraint, a footgun, a name that means something different here than it does elsewhere. 5. **Name what this file assumes** and who guarantees it. What must already be true when it runs? Who upholds that? 6. **End with the smallest question I should be able to answer** if I understood it — a question with a specific answer, not "do you understand the flow?" Keep it under 250 words. Prefer precision over completeness. If something is genuinely unclear from the code alone, say "unclear from this file" rather than inventing an explanation — a confident wrong model is worse than an admitted gap, because I'll spend an hour reasoning from it. ```text Paste the code below this line. --- ``` ## Why it's shaped this way **"Don't narrate line by line"** is the whole prompt in one instruction. The default behaviour is a prose transcription of the code, which is the least useful possible output: it's longer than the source and contains strictly less information. **"One mental model"** forces compression. There is usually exactly one idea — *this is a state machine*, *this is a cache with a write-through invariant*, *everything here exists to make the retry idempotent* — and once you have it, the rest of the file reads itself. Asking for one, not three, is what makes the model choose. **"Two things most likely to surprise me"** targets the actual cost of unfamiliar code. You can read the happy path yourself. What you can't see is the ordering constraint that isn't written down, or the field that's mutated by a caller three layers up. **"Unclear from this file"** is the escape hatch that keeps it honest. Some things genuinely are not knowable from one file, and the correct answer is to say so and name what you'd need. **The final question** is a comprehension check for you, not a rhetorical flourish. If you can't answer it, you skimmed. ## How to use it - **One file at a time.** Quality falls off sharply across multiple files, and the "single responsibility" question stops having an answer. - **Include the imports and the top-of-file comment.** They're often where the intent lives. - **Then ask the follow-up that matters most:** *"What would break if I deleted this file?"* The answer tells you the file's real role in the system, which is frequently not what its name suggests. - **Disagree with it.** If the mental model doesn't match what you're seeing, say so and ask for a second candidate. Being wrong here is cheap and the correction is informative. ## Follow-ups worth keeping - *"Now show me the unhappy paths — what are the failure modes and who handles them?"* - *"Which of these functions would I need to change to add {feature}?"* — the fastest way to test whether the model you were given is actually load-bearing. - *"What's the oldest-looking part of this file, and what does its style suggest about its history?"* - *"If you were reviewing a change to this file, what would you check first?"* ## When not to use it - **Code you wrote.** You have the mental model; you want a review, not an explanation. - **A whole subsystem.** Ask for the map first — which files exist and how they relate — then use this prompt on the two that matter. - **Generated code.** The mental model is "a tool wrote this"; read the tool's input instead. ## Failure modes - **You get a summary, not a model.** "This file handles user authentication" is a restatement of the filename. Push back: *"That's the what. Give me the invariant or the data flow."* - **The metaphor is decorative.** A good model makes predictions. If it doesn't let you guess what the next function does, it's a simile, not a model. - **It invents a rationale.** Models are strongly inclined to explain *why* code is the way it is, and much real code is the way it is by accident. Treat any "this was designed to…" claim as a hypothesis to check against git history.

The prompt

You are explaining unfamiliar code to a competent engineer who is new to this codebase. They know the language. They do not know why this file exists.

Do not narrate line by line. Line-by-line commentary restates what I can already read and skips the thing I actually need, which is the idea the code is an expression of.

Instead:

In one sentence, what is this file's single responsibility? If you need "and" to say it, say so — a file doing two things is itself the most useful fact about it.
Give me the one mental model I need to hold to read the rest. A metaphor, an invariant, or the core data flow. Something I could keep in my head while reading, that makes the rest predictable.
Walk the happy path in 4–6 steps, naming the key functions. Where does control enter, what does it transform, where does it leave.
Point out the two things most likely to surprise me — hidden coupling, a non-obvious ordering constraint, a footgun, a name that means something different here than it does elsewhere.
Name what this file assumes and who guarantees it. What must already be true when it runs? Who upholds that?
End with the smallest question I should be able to answer if I understood it — a question with a specific answer, not "do you understand the flow?"

Keep it under 250 words. Prefer precision over completeness. If something is genuinely unclear from the code alone, say "unclear from this file" rather than inventing an explanation — a confident wrong model is worse than an admitted gap, because I'll spend an hour reasoning from it.

Paste the code below this line.
---

Why it's shaped this way

"Don't narrate line by line" is the whole prompt in one instruction. The default behaviour is a prose transcription of the code, which is the least useful possible output: it's longer than the source and contains strictly less information.

"One mental model" forces compression. There is usually exactly one idea — this is a state machine, this is a cache with a write-through invariant, everything here exists to make the retry idempotent — and once you have it, the rest of the file reads itself. Asking for one, not three, is what makes the model choose.

"Two things most likely to surprise me" targets the actual cost of unfamiliar code. You can read the happy path yourself. What you can't see is the ordering constraint that isn't written down, or the field that's mutated by a caller three layers up.

"Unclear from this file" is the escape hatch that keeps it honest. Some things genuinely are not knowable from one file, and the correct answer is to say so and name what you'd need.

The final question is a comprehension check for you, not a rhetorical flourish. If you can't answer it, you skimmed.

How to use it

One file at a time. Quality falls off sharply across multiple files, and the "single responsibility" question stops having an answer.
Include the imports and the top-of-file comment. They're often where the intent lives.
Then ask the follow-up that matters most: "What would break if I deleted this file?" The answer tells you the file's real role in the system, which is frequently not what its name suggests.
Disagree with it. If the mental model doesn't match what you're seeing, say so and ask for a second candidate. Being wrong here is cheap and the correction is informative.

Follow-ups worth keeping

"Now show me the unhappy paths — what are the failure modes and who handles them?"
"Which of these functions would I need to change to add ?" — the fastest way to test whether the model you were given is actually load-bearing.
"What's the oldest-looking part of this file, and what does its style suggest about its history?"
"If you were reviewing a change to this file, what would you check first?"

When not to use it

Code you wrote. You have the mental model; you want a review, not an explanation.
A whole subsystem. Ask for the map first — which files exist and how they relate — then use this prompt on the two that matter.
Generated code. The mental model is "a tool wrote this"; read the tool's input instead.

Failure modes

You get a summary, not a model. "This file handles user authentication" is a restatement of the filename. Push back: "That's the what. Give me the invariant or the data flow."
The metaphor is decorative. A good model makes predictions. If it doesn't let you guess what the next function does, it's a simile, not a model.
It invents a rationale. Models are strongly inclined to explain why code is the way it is, and much real code is the way it is by accident. Treat any "this was designed to…" claim as a hypothesis to check against git history.