"Explain this code" gets line-by-line narration. The understanding contract gets strategy, audience-fit, design decisions, and inference labeled as inference.
Most explanation prompts produce a restatement of what the code visibly does — no business context, no rationale, no learning value. The understanding contract structures the explanation instead: an explanation strategy with a real educational objective, an audience profile that sets what can be assumed known, key concepts ordered by load, execution flow, design decisions — and the honesty discipline that separates trustworthy explanations from smooth stories: intent and rationale are labeled as INFERENCE unless the code evidences them, and gaps are answered with "cannot be determined from this code". This setup loads a deep-dive overview thorough enough to write documentation from.
Give the context the prompt always loses
Two sentences of business context outperform a thousand lines of pasted code without them.
Hold the strategy
Purpose, responsibilities, system role, workflows — an educational objective, not a narration order.
Check the inference labels
Every claim about intent arrives labeled FACT-from-code or INFERENCE — the open questions list what the code alone cannot answer.
Paste the code into the CODE CONTEXT block plus two things the model can't guess: the system context (like 'retries failed payment captures with exponential backoff') and the AUDIENCE PROFILE. The default profile targets a mid-level developer — fluent in the language, so syntax gets skipped and depth goes to intent, structure, and domain meaning instead.
It returns a headed deep-dive built from an EXPLANATION STRATEGY: it leads with purpose, maps the three-to-five responsibilities, places the code in its system, and walks workflows as numbered steps. Separate sections cover KEY CONCEPTS ordered by load, EXECUTION FLOW, DESIGN DECISIONS, TRADEOFFS with the alternative that would invert each, and LEARNING NOTES — the three things a colleague would give at a whiteboard.
No — it produces a structured, audience-calibrated explanation and marks what it can't verify, but it doesn't confirm the AI understood anything. Every claim about intent or rationale arrives labeled INFERENCE unless the code evidences it via a comment, test, or telling name, and gaps get 'cannot be determined from this code'. You run it in your own AI tool and confirm behavior against the code and tests.
Yes, as raw material — the EXPLANATION OBJECTIVE loads an overview thorough enough that documentation could be written from it, headings mirror each section, and every behavior claim names the function, branch, or line. But this prompt explains rather than writes docs; hand the labeled facts, inferences, and closing open-questions list to the Markdown Output Builder to draft the actual documentation.
For code whose authors are gone: reconstruct likely intent as labeled inference, hunt undocumented assumptions, and end with a maintenance brief — what's safe to touch.
Explain the idea before the implementation: numbered steps with their contribution, honest best/worst-case complexity, and the alternatives each decision point rejected.
Explain a system's shape, not its statements: layers and their owners, boundary contracts, dependency direction, and one request traced through every handoff.
"Review this code" gets shallow comments. The review contract gets findings with severities, a checklist, and a verdict.
"Refactor this code" invites silent behavior changes. The refactoring contract preserves business rules, outputs, and side effects — and flags uncertainty instead of deciding it.
"Fix this error" gets guesses. The investigation contract gets a ten-stage diagnosis: facts separated from assumptions, alternatives weighed, fixes justified.
Build code explanation prompts — mode, audience, and depth turn into an understanding contract that teaches, not narrates.
A complete AI-assisted review pass — not one prompt — that ends with ranked findings, tests guarding behavior, and a refactor plan when one is warranted.
The order that actually finds bugs instead of guessing at them — so you end with a verified fix, not a plausible one that quietly returns next week.
Work a live production incident in the right order — triage and stabilize first, then find the cause, then write the summary and postmortem — so the fire is out before the writeup begins.
Generate documentation that matches the code instead of drifting from it — have AI explain what the code really does, write it up as structured docs, then validate the format holds.