Prompt · Code
Code explanation prompt
Landing in a codebase you did not write and needing to understand a file well enough to change it safely.
Explain the code below to a competent developer who has not seen this codebase.
<code language="{{language}}">
{{code}}
</code>
Answer, in this order:
1. What it does, in two sentences. Its purpose in the system, not a description of its syntax.
2. The flow — inputs, the transformation, outputs, and where it hands off.
3. Anything surprising: a workaround, a non-obvious ordering constraint, a defensive check that implies a bug elsewhere, a name that does not match behaviour.
4. What would break it — the inputs, state or timing this code assumes and does not verify.
Do not narrate line by line. Assume the reader can read {{language}}; explain what they cannot see from the code alone.
If a section's purpose is genuinely unclear from the code, say so and state what you would need to see — a caller, a schema, a config file. Do not fill the gap with a plausible guess.What to fill in
{{language}}- Sets the assumed baseline so the explanation skips syntax.
{{code}}- A file or a function. Include imports — they reveal the dependencies the explanation should mention.
Why it is written this way
Every rule in the prompt is there because of a specific failure it prevents. Knowing which is which is what lets you adapt it instead of only pasting it.
Line-by-line is banned
It is the default output and the least useful one. A competent reader can already see that line 14 assigns a variable; what they cannot see is why the assignment happens before the validation.
Surprises get their own section
This is where the value is. Workarounds, ordering constraints and defensive checks are archaeology — they record a bug someone hit once, and they are the parts most likely to break when a newcomer "cleans up" the code.
"What would break it" is the safety section
Unstated assumptions are what make a small change into an incident. Asking for them explicitly is the difference between understanding code and being able to modify it.
Guessing is forbidden
A confident explanation of a function whose purpose is not derivable from the code is the worst possible output, because it is exactly as fluent as a correct one.
The version most people write, and what it costs
Explain this code:
{{code}}Three hundred words restating the code in English. "The function first checks if the input is null, then iterates over the array..." The reader learns nothing they could not read directly, and the retry loop that exists because a downstream API returns 200 on failure goes unmentioned.
What it still gets wrong
- It explains what the code does, not what it was supposed to do. A bug is explained as intended behaviour.
- Without callers and configuration, the explanation of purpose is inference. The prompt asks it to admit that; it will not always.
- On very large files the explanation flattens — everything gets equal weight and the important parts stop standing out.
Check it before you ship it
- LLM Token CounterReal BPE tokenization, not characters ÷ 4. Shows which counts are exact and which are estimates.
- Text Splitter for RAG and EmbeddingsToken-accurate chunking with configurable overlap. Respects sentence and paragraph boundaries.
- AI Skill GeneratorThree skill shapes — review, generate, diagnose — each producing a complete file.
To build one of these from scratch for a task not covered here, the prompt generator assembles the same structure — delimiters, output contract, edge cases — from an expert-authored blueprint, and the prompt review checklist is what to run over the result.