Prompt Engineering

Explain Code Prompt — the Understanding Contract

"Explain this code" gets line-by-line narration. The understanding contract gets strategy, audience-fit, design decisions, and inference labeled as inference.

Overview

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.

Workflow

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.

Why This Works

An educational objective replaces the narration reflex
Audience assumptions put the explanation at the level the reader actually needs
Labeled inference keeps plausible stories from masquerading as the code's history

Best for

Developers using chat AIs to understand unfamiliar code
Code whose context the model cannot guess
Teams standardizing how code gets explained

Not for

Judging the code's quality — that's the Code Review Prompt Generator
Writing the documentation itself — that's the Markdown Output Builder

Use cases

Getting understanding instead of line-by-line narration
Explaining a subsystem thoroughly enough to document it
Keeping inferred intent labeled instead of narrated as fact

Customize This Resource

Opens this setup in Code Explanation Prompt. Generate to get the full understanding contract — then adjust the mode, audience, and depth.

Open in Code Explanation Prompt

Prompt Template

EXPLANATION OBJECTIVE
Explain this payment retry subsystem thoroughly enough that its technical documentation could be written from the answer.
Explanation mode: high-level overview — what this code is for and how it fits the system.
The goal is understanding, not judgment: explain what this code does and why it is built this way — and clearly separate what the code shows from what you infer.

CODE CONTEXT
System context: Retries failed payment captures with exponential backoff; documentation does not exist yet.
Code to explain:
```
[Paste the code to explain here]
```

AUDIENCE PROFILE
Audience: a mid-level developer — fluent in the language and common patterns.
- Assume: language features and common patterns are known; this codebase's conventions and domain are not.
- Skip syntax explanations entirely; spend the depth on intent, structure, and domain meaning.

EXPLANATION STRATEGY
1. Lead with purpose: what problem this code solves and who or what calls it.
2. Map the major responsibilities — the three to five jobs this code actually performs.
3. Place it in the system: upstream callers, downstream dependencies, and its role between them.
4. Walk the important workflows end to end at the level of steps, not statements.
- Depth: deep dive — behavior, rationale, and the decisions behind the structure.
- For every significant design decision: the rationale, the tradeoffs accepted, and at least one alternative approach with why it likely lost.
- Surface the assumptions the design rests on — and what would break if each assumption stopped holding.
- Where rationale cannot be recovered from the code, say so explicitly — do not fabricate a design story.

KEY CONCEPTS
- Name the central concepts a reader must hold to reason about this code — the domain objects, the states, the contracts between parts.
- Order concepts by how load-bearing they are for understanding this code — not by where they appear in the file.

EXECUTION FLOW
- Describe the main workflows as numbered step sequences — what triggers each, what it produces, and what can short-circuit it.
- Where the flow depends on state or configuration, say which, and what each setting changes.

DESIGN DECISIONS
- Point out the structural decisions visible at this altitude: how responsibilities are divided, and what that division suggests about the system's priorities.
- Discuss only decisions actually visible in the code; rationale you cannot evidence belongs under ASSUMPTIONS, labeled as inference.

ASSUMPTIONS
- Separate what the code DOES (verifiable from the source) from why it might be that way (inference).
- Label every statement about intent, history, or rationale as an INFERENCE unless the code itself evidences it — a comment, a test, a telling name.
- Where behavior cannot be determined from the provided code, say "cannot be determined from this code" — never fill the gap with a plausible story.

TRADEOFFS
- For each significant tradeoff: what was gained, what was given up, and the alternative that would invert it.
- Evaluate whether each tradeoff still makes sense today, or whether the constraint that justified it has expired.

LEARNING NOTES
- Close with the three things to remember about this code — the summary a colleague would give at a whiteboard.

NON-GOALS
- Do not review code quality — no findings, no severities, no verdicts.
- Do not debug failures — explain the behavior that exists without diagnosing it.
- Do not refactor the code or propose rewrites.
- Do not generate tests.
- Do not invent requirements or unstated intentions.
- If something looks defective, note it as a question for the team — investigating or fixing it is out of scope.
- Clearly separate facts from assumptions throughout.

OUTPUT REQUIREMENTS
- Structure the explanation with headings that mirror the sections above — a reader should be able to navigate it without reading all of it.
- Anchor every claim about behavior in the code: name the function, branch, or line it comes from when precision matters.
- Calibrate every section to the stated audience — too basic wastes their time, too advanced loses them.
- End with the open questions: what could not be determined from the provided code, and who or what could answer it.

Related Resources

Explore more resources that work well with this one.

Used in Playbooks

Complete workflows that include this resource as a step.

AI Code Review Workflow Workflow · 5 steps AI Debugging Workflow Workflow · 5 steps AI Production Incident Workflow Workflow · 4 steps AI Code Documentation Workflow Workflow · 3 steps

Tip: Save time by exploring related resources and tools that integrate with this workflow.

Explore all resources