Explain the code below as a patient senior engineer teaching me how it actually works. My background is: [MY EXPERIENCE LEVEL]. The language, runtime, and relevant framework are: [TECH STACK]. The code and any surrounding context are: [CODE TO EXPLAIN]. What I need to understand or change is: [GOAL OR CONFUSION]. Start with a 3-5 sentence plain-English overview: what this code is responsible for, what calls it, what it returns or changes, and its most important side effect. Then provide these sections: 1. Execution path: trace the normal path from input or entry point through key functions, branches, and output. 2. Data flow: identify important values, their type or shape if known, where they originate, and where they are transformed or persisted.
3. Line or block annotations: explain only the meaningful blocks in source order; group boilerplate rather than paraphrasing every token. 4. Assumptions and failure modes: include null or empty inputs, error handling, async behavior, state mutation, security or validation boundaries, and performance concerns when relevant. 5. A small worked example using invented, non-sensitive sample input and output. 6. Three comprehension questions for me, followed by one safe next experiment I can run. If context is absent, distinguish what the code proves from what you infer about the larger system. Do not invent APIs, database schemas, environment variables, callers, or behavior that is not shown. Before answering, self-check that you have explained control flow and data flow separately, and flag any line whose behavior depends on an unseen dependency. Ask up to 3 clarifying questions only if a required input is missing.
Fill in
| Placeholder | What to enter | Example |
|---|---|---|
| [MY EXPERIENCE LEVEL] | Describe your coding experience and any concepts you already understand or want explained without jargon. | Junior developer comfortable with JavaScript functions and arrays, but new to async code and Express middleware. |
| [TECH STACK] | Name the language, runtime, framework, and versions if they are relevant or known. | Node.js 22, TypeScript, Express 5, PostgreSQL through Prisma. |
| [CODE TO EXPLAIN] | Paste the smallest complete code excerpt plus nearby types, function signatures, or error output needed for context. | async function getOrder(req, res) { const order = await prisma.order.findUnique({ where: { id: req.params.id } }); if (!order) return res.sendStatus(404); res.json(order); } |
| [GOAL OR CONFUSION] | State what you are trying to learn, debug, modify, or verify in the code. | I need to understand what awaits, what happens on a missing order, and where authentication should be checked. |
How to use
- Paste the smallest runnable or coherent excerpt, including function signatures, types, and the exact error if one exists.
- State the behavior you expect and which part confuses you, so the explanation can focus on the relevant execution path.
- Verify claims about hidden dependencies by opening their definitions or running a small test in your own environment.
- Follow up with: “Now trace this request with `req.params.id = '42'`, then show the smallest test that proves the 404 branch works.”
Variations
Code review learning
Use when you want to understand risks in a pull request before commenting.
Review this code change for learning purposes: [CODE DIFF]. The surrounding system is [SYSTEM CONTEXT], and the intended behavior is [INTENDED BEHAVIOR]. Explain the change’s execution path, then list correctness risks, edge cases, security boundaries, test gaps, and maintainability concerns. Rank findings by impact and include evidence from the supplied code for each. Do not claim knowledge of files or APIs not shown. End with three specific review questions I could ask the author.
Debug an error
Use when an error occurs and you need a disciplined debugging path.
Help me debug [ERROR MESSAGE] in this code: [RELEVANT CODE]. Environment and reproduction steps: [ENVIRONMENT AND STEPS]. First separate observed facts from hypotheses. Then propose an ordered debugging plan with the exact log, breakpoint, test, or inspection for each hypothesis, what result would confirm or rule it out, and the smallest safe fix to try. Do not invent a root cause or recommend changing unrelated code.
Explain for interview
Use to prepare to explain your own code clearly in a technical interview.
Help me explain this project code in an interview: [CODE OR FEATURE]. The role is [TARGET ROLE], and my actual contribution was [MY CONTRIBUTION]. Produce a 90-second spoken explanation covering the user problem, architecture, control and data flow, one tradeoff, testing, and one improvement I would make. Keep claims limited to my input. Then give five likely follow-up questions and concise truthful answer outlines.
Tips
- Include the entry point and the caller when possible; a function body alone often cannot reveal who guarantees its inputs or handles its errors.
- Ask for a normal-path trace and a failure-path trace separately, because code that looks simple can behave differently across asynchronous or exceptional branches.
- Treat names as clues, not proof: inspect type definitions, schema models, tests, and dependency implementations before relying on inferred behavior.
- Use invented sample values only for explanation, and never paste production secrets, access tokens, customer data, or private source code into an unapproved tool.
FAQ
Can Claude explain a whole repository?
It can help, but begin with an entry point and a few linked files. Large codebases need staged explanations tied to a concrete feature or request path.
How do I stop an AI from making up missing context?
Tell it to label inference versus evidence and to flag unseen dependencies. Provide types, tests, error messages, and caller code where they matter.
Is line-by-line explanation always useful?
Not usually. Start with responsibilities, control flow, and data flow, then zoom into the blocks that affect the behavior you need to change.