Code Explanation for Beginners
Step 0: Execution Mode (MANDATORY)
Before doing ANY work, ask the user:
"Want me to delegate this to the architect-explainer agent (guided explanation with diagrams), or proceed inline in this chat?"
- If user chooses agent → launch the architect-explainer agent with the target and context. STOP here — do not continue with the steps below.
- If user chooses inline → proceed with the methodology below.
- If user doesn't respond clearly → default to agent.
Step 1: Clarify Scope and Depth (MANDATORY)
Before explaining anything, ask the user these questions (skip any already answered in their request):
- What to explain? — specific file, function, module/directory, or full project?
- How deep?
- Overview — high-level summary, architecture, purpose (2-3 minutes read)
- Moderate — key logic explained, data flows traced, patterns identified (5-7 minutes read)
- Deep dive — line-by-line for key logic, edge cases, framework internals (10+ minutes read)
- What aspect interests you most?
- How it works (mechanics)
- Why it's built this way (design decisions)
- How data flows through it (inputs → outputs)
- How to modify or extend it (practical next steps)
- Your experience level with this stack? — helps calibrate terminology and analogies
If the user gives a vague request like "explain this", default to: the file/module they're looking at, moderate depth, "how it works" aspect. Confirm before proceeding.
Step 2: Read and Analyze Code (before explaining)
Follow this reading strategy based on scope:
For a function
- Read the function and its docstring/comments
- Read the file it's in — understand surrounding context
- Grep for callers: who calls this function and with what arguments?
- Check imports: what dependencies does it use?
For a file
- Read the full file
- Read the project's entry point or config to understand where this file fits
- Check imports to map dependencies
- Grep for references to this file from other files
For a module/directory
- List all files in the directory
- Read the module's index/init file if it exists
- Read 2-3 key files (entry points, models, main logic)
- Read the project root (package.json, requirements.txt, README) for stack context
- Map internal file dependencies via imports
For full project
- Read root files: README, CLAUDE.md, main config (package.json / requirements.txt / go.mod)
- List top-level directories and identify their roles
- Find entry points: main app file, route definitions, CLI commands
- Trace one complete request path through the system
After reading, identify: the main abstraction (what concept does this code represent?), the key decision (what's the most important choice made here?), and the surprise (what would a newcomer not expect?).
Step 3: Explain Using the 4-Layer Model
Adjust depth based on the user's answer in Step 1. Skip or compress layers that don't match the requested aspect.
Layer 1: Context (always start here)
Answer: What problem does this solve? Where does it fit in the project?
- One sentence: what this code does in plain language
- Where it sits in the architecture (data layer? route handler? utility?)
- Who calls it / what triggers it (incoming request, cron job, user action, another module)
- What would break if this didn't exist
For beginners, use an analogy: relate the code's role to something familiar. See ${CLAUDE_PLUGIN_ROOT}/skills/codemap-explain/references/explanation-patterns.md for common analogies per pattern.
Layer 2: Data Flow
Answer: What goes in, what comes out, what happens in between?
- Inputs: what data this code receives (parameters, request data, database queries)
- Processing: the main transformations, validations, or decisions
- Outputs: what it returns or produces (response, database write, side effect)
- Dependencies: what external services or modules it relies on
Show concrete values flowing through — not abstract descriptions. Use a mini-trace:
Form data {email, password}
→ validate(email) → check DB for user
→ bcrypt.compare(password, hash)
→ if match: create session → redirect /dashboard
→ if no match: flash error → redirect /login
Layer 3: Details
Answer: How does each part work?
- Walk through key sections of the code (not every line — focus on logic, not boilerplate)
- Explain non-obvious patterns or framework-specific conventions
- Define technical terms on first use: "Blueprint (Flask's way of organizing related routes into a module)"
- Show connections: "this function is called by X on line Y in file Z"
Adjust depth to user's request:
- Overview → skip this layer or give 1-2 sentences per section
- Moderate → explain key functions/blocks, skip boilerplate
- Deep dive → line-by-line for important logic, annotate decisions
Layer 4: Pitfalls
Answer: What can go wrong? What's non-obvious?
- Edge cases the code handles (or doesn't)
- Common mistakes when modifying this code
- Framework gotchas relevant to this code
- Performance considerations if applicable
- Security implications if applicable
Only include pitfalls proportional to depth requested. Overview = 1-2 biggest risks. Deep dive = comprehensive.
Step 4: Verify Your Explanation
Before presenting the explanation, cross-check:
- Every claim references real code — don't say "this function calls X" without confirming it in the source
- Names match the code — use actual variable names, function names, file paths from the codebase
- Flow matches reality — if you described a data flow, trace it one more time in the code to confirm
- No hallucinated features — don't attribute behavior that isn't in the code
If you discover something contradicts your initial analysis during verification, correct the explanation before presenting it.
Step 5: Suggest Next Steps
End every explanation with actionable next steps tailored to the user's interest:
- "How it works" → "Want me to explain [related module] next?" or "Want a diagram of this flow?"
- "Design decisions" → "Want me to review alternative approaches?" or "Want to understand the tradeoffs?"
- "Data flow" → "Want me to trace [another endpoint/feature]?" or "Want an ERD of the data models?"
- "How to modify" → "Want me to walk through adding [specific feature]?" or "Want a review of your changes after?"
Always suggest 2-3 specific next steps, not generic ones.
Output Format
Structure explanations consistently:
## [Target Name] — [one-line summary]
**Scope:** [function / file / module] · **Depth:** [overview / moderate / deep dive]
**Stack:** [detected framework, language, key libraries]
### Context
[Layer 1 content — 1-3 paragraphs depending on depth]
### Data Flow
[Layer 2 content — trace with concrete values, mini-diagram if helpful]
### How It Works
[Layer 3 content — adjusted to requested depth]
### Pitfalls
[Layer 4 content — proportional to depth]
### Next Steps
- [Suggestion 1]
- [Suggestion 2]
- [Suggestion 3]
For overview depth: Context + Data Flow + Next Steps (skip Details and Pitfalls).
For moderate depth: all sections, Details compressed.
For deep dive depth: all sections expanded, line-by-line annotations in Details.
Mini-Diagram Decision
Generate a mini-diagram (via codemap-diagram skill at ${CLAUDE_PLUGIN_ROOT}/skills/codemap-diagram/SKILL.md) when:
- 3+ components interact in the explanation
- Data flows through multiple files/services
- The user is confused about how pieces connect
- A visual would save 200+ words of text
Do NOT generate a diagram for:
- Single-function explanations
- Simple CRUD with obvious flow
- When the user just wants a quick answer
Scope-Specific Adjustments
For a single function
- Context: 1-2 sentences — what it does, who calls it
- Data Flow: parameter → processing → return value trace with concrete values
- Details: line-by-line for key logic, skip boilerplate (imports, type declarations)
- Pitfalls: edge cases and error paths — what inputs break it?
- Format: inline explanation, no headers needed for overview depth
For a file
- Context: file's role in the project, what module it belongs to
- Data Flow: list public API (exports, route handlers, model definitions) with one-line descriptions
- Details: explain each key function/class — skip helpers unless non-obvious
- Pitfalls: common modification mistakes, implicit dependencies
- Format: use headers per function/class for moderate+ depth
For a module/directory
- Context: module's purpose, boundaries, what it owns
- Data Flow: file listing with one-line role descriptions, dependency map
- Details: key files explained in depth, others summarized
- Pitfalls: architectural decisions and their tradeoffs, coupling risks
- Format: start with file map, then drill into key files
For full project
- Context: what the project does, who it's for, deployment model
- Data Flow: one complete request traced end-to-end
- Details: layer-by-layer architecture overview (routes → services → data)
- Pitfalls: key architectural decisions, tech debt, scaling concerns
- Format: start with architecture overview, then offer to drill into any layer
Tone Rules
- Define terms on first use — "Blueprint (Flask's way of organizing related routes into a module)"
- Use concrete examples — show actual values flowing through, not abstract descriptions
- Relate to familiar concepts — see
${CLAUDE_PLUGIN_ROOT}/skills/codemap-explain/references/explanation-patterns.md for analogies
- Progressive complexity — start simple, add nuance layer by layer
- Honest about complexity — "this part is genuinely tricky because..." is better than oversimplifying
- Match the user's level — use framework jargon only if user confirmed familiarity; otherwise define everything
Do NOT:
- Use filler phrases ("Let's dive in!", "Great question!")
- Explain obvious things (what a for-loop is, what imports do) unless user is a complete beginner
- Hedge excessively ("it seems like", "it appears to") — be direct about what the code does
- Skip to code without context — always start with Layer 1
Error Handling
- File not found → ask the user to verify the path. Suggest: "Want me to search for similar filenames with Glob?"
- Symbol not found → grep broader patterns (partial name, related terms). Ask for clarification if still not found
- Module too large (>20 files) → explain top-level structure first, then ask: "Which part should I drill into?"
- Minified/generated code → warn the user this is generated code, offer to find the source instead
- Binary/non-text files → explain what the file type is and where it's likely configured or generated from
1---2name: codemap-explain-23description: Use when the user wants existing code explained as a learner - what a file, function or module does, how a request or data flows through the project, why it was built that way, or a tour of a codebase. Gives a structured step-by-step explanation (context, data flow, details, pitfalls) pitched at the user's level, preferred to an ad-hoc answer when the user is learning the code. Not for code review (codemap-review) or diagrams (codemap-diagram).4metadata:5 source: https://skillmd.com/skills/agents-store/codemap-explain-26---78# Code Explanation for Beginners910## Step 0: Execution Mode (MANDATORY)1112Before doing ANY work, ask the user:1314> "Want me to delegate this to the **architect-explainer** agent (guided explanation with diagrams), or proceed inline in this chat?"1516- If user chooses agent → launch the **architect-explainer** agent with the target and context. STOP here — do not continue with the steps below.17- If user chooses inline → proceed with the methodology below.18- If user doesn't respond clearly → default to agent.1920---2122## Step 1: Clarify Scope and Depth (MANDATORY)2324Before explaining anything, ask the user these questions (skip any already answered in their request):25261. **What to explain?** — specific file, function, module/directory, or full project?272. **How deep?**28 - **Overview** — high-level summary, architecture, purpose (2-3 minutes read)29 - **Moderate** — key logic explained, data flows traced, patterns identified (5-7 minutes read)30 - **Deep dive** — line-by-line for key logic, edge cases, framework internals (10+ minutes read)313. **What aspect interests you most?**32 - How it works (mechanics)33 - Why it's built this way (design decisions)34 - How data flows through it (inputs → outputs)35 - How to modify or extend it (practical next steps)364. **Your experience level with this stack?** — helps calibrate terminology and analogies3738If the user gives a vague request like "explain this", default to: the file/module they're looking at, moderate depth, "how it works" aspect. Confirm before proceeding.3940<example>41User: "Explain the auth system"42Agent: "I'll explain the auth system. A few quick questions:43- Should I cover the whole auth module or a specific file (e.g., login handler, middleware)?44- Do you want a high-level overview or a deep dive into the internals?45- Are you more interested in how it works, or how to modify it?46- How familiar are you with [detected framework, e.g., Express/Passport]?"47</example>4849---5051## Step 2: Read and Analyze Code (before explaining)5253Follow this reading strategy based on scope:5455### For a function561. Read the function and its docstring/comments572. Read the file it's in — understand surrounding context583. Grep for callers: who calls this function and with what arguments?594. Check imports: what dependencies does it use?6061### For a file621. Read the full file632. Read the project's entry point or config to understand where this file fits643. Check imports to map dependencies654. Grep for references to this file from other files6667### For a module/directory681. List all files in the directory692. Read the module's index/init file if it exists703. Read 2-3 key files (entry points, models, main logic)714. Read the project root (package.json, requirements.txt, README) for stack context725. Map internal file dependencies via imports7374### For full project751. Read root files: README, CLAUDE.md, main config (package.json / requirements.txt / go.mod)762. List top-level directories and identify their roles773. Find entry points: main app file, route definitions, CLI commands784. Trace one complete request path through the system7980After reading, identify: **the main abstraction** (what concept does this code represent?), **the key decision** (what's the most important choice made here?), and **the surprise** (what would a newcomer not expect?).8182---8384## Step 3: Explain Using the 4-Layer Model8586Adjust depth based on the user's answer in Step 1. Skip or compress layers that don't match the requested aspect.8788### Layer 1: Context (always start here)8990Answer: **What problem does this solve? Where does it fit in the project?**9192- One sentence: what this code does in plain language93- Where it sits in the architecture (data layer? route handler? utility?)94- Who calls it / what triggers it (incoming request, cron job, user action, another module)95- What would break if this didn't exist9697For beginners, use an analogy: relate the code's role to something familiar. See `${CLAUDE_PLUGIN_ROOT}/skills/codemap-explain/references/explanation-patterns.md` for common analogies per pattern.9899### Layer 2: Data Flow100101Answer: **What goes in, what comes out, what happens in between?**102103- Inputs: what data this code receives (parameters, request data, database queries)104- Processing: the main transformations, validations, or decisions105- Outputs: what it returns or produces (response, database write, side effect)106- Dependencies: what external services or modules it relies on107108Show concrete values flowing through — not abstract descriptions. Use a mini-trace:109110```111Form data {email, password}112 → validate(email) → check DB for user113 → bcrypt.compare(password, hash)114 → if match: create session → redirect /dashboard115 → if no match: flash error → redirect /login116```117118### Layer 3: Details119120Answer: **How does each part work?**121122- Walk through key sections of the code (not every line — focus on logic, not boilerplate)123- Explain non-obvious patterns or framework-specific conventions124- Define technical terms on first use: "Blueprint (Flask's way of organizing related routes into a module)"125- Show connections: "this function is called by X on line Y in file Z"126127Adjust depth to user's request:128- **Overview** → skip this layer or give 1-2 sentences per section129- **Moderate** → explain key functions/blocks, skip boilerplate130- **Deep dive** → line-by-line for important logic, annotate decisions131132### Layer 4: Pitfalls133134Answer: **What can go wrong? What's non-obvious?**135136- Edge cases the code handles (or doesn't)137- Common mistakes when modifying this code138- Framework gotchas relevant to this code139- Performance considerations if applicable140- Security implications if applicable141142Only include pitfalls proportional to depth requested. Overview = 1-2 biggest risks. Deep dive = comprehensive.143144---145146## Step 4: Verify Your Explanation147148Before presenting the explanation, cross-check:1491501. **Every claim references real code** — don't say "this function calls X" without confirming it in the source1512. **Names match the code** — use actual variable names, function names, file paths from the codebase1523. **Flow matches reality** — if you described a data flow, trace it one more time in the code to confirm1534. **No hallucinated features** — don't attribute behavior that isn't in the code154155If you discover something contradicts your initial analysis during verification, correct the explanation before presenting it.156157---158159## Step 5: Suggest Next Steps160161End every explanation with actionable next steps tailored to the user's interest:162163- **"How it works"** → "Want me to explain [related module] next?" or "Want a diagram of this flow?"164- **"Design decisions"** → "Want me to review alternative approaches?" or "Want to understand the tradeoffs?"165- **"Data flow"** → "Want me to trace [another endpoint/feature]?" or "Want an ERD of the data models?"166- **"How to modify"** → "Want me to walk through adding [specific feature]?" or "Want a review of your changes after?"167168Always suggest 2-3 specific next steps, not generic ones.169170---171172## Output Format173174Structure explanations consistently:175176```177## [Target Name] — [one-line summary]178179**Scope:** [function / file / module] · **Depth:** [overview / moderate / deep dive]180**Stack:** [detected framework, language, key libraries]181182### Context183[Layer 1 content — 1-3 paragraphs depending on depth]184185### Data Flow186[Layer 2 content — trace with concrete values, mini-diagram if helpful]187188### How It Works189[Layer 3 content — adjusted to requested depth]190191### Pitfalls192[Layer 4 content — proportional to depth]193194### Next Steps195- [Suggestion 1]196- [Suggestion 2]197- [Suggestion 3]198```199200For **overview** depth: Context + Data Flow + Next Steps (skip Details and Pitfalls).201For **moderate** depth: all sections, Details compressed.202For **deep dive** depth: all sections expanded, line-by-line annotations in Details.203204---205206## Mini-Diagram Decision207208Generate a mini-diagram (via `codemap-diagram` skill at `${CLAUDE_PLUGIN_ROOT}/skills/codemap-diagram/SKILL.md`) when:209- 3+ components interact in the explanation210- Data flows through multiple files/services211- The user is confused about how pieces connect212- A visual would save 200+ words of text213214Do NOT generate a diagram for:215- Single-function explanations216- Simple CRUD with obvious flow217- When the user just wants a quick answer218219---220221## Scope-Specific Adjustments222223### For a single function224- **Context:** 1-2 sentences — what it does, who calls it225- **Data Flow:** parameter → processing → return value trace with concrete values226- **Details:** line-by-line for key logic, skip boilerplate (imports, type declarations)227- **Pitfalls:** edge cases and error paths — what inputs break it?228- **Format:** inline explanation, no headers needed for overview depth229230### For a file231- **Context:** file's role in the project, what module it belongs to232- **Data Flow:** list public API (exports, route handlers, model definitions) with one-line descriptions233- **Details:** explain each key function/class — skip helpers unless non-obvious234- **Pitfalls:** common modification mistakes, implicit dependencies235- **Format:** use headers per function/class for moderate+ depth236237### For a module/directory238- **Context:** module's purpose, boundaries, what it owns239- **Data Flow:** file listing with one-line role descriptions, dependency map240- **Details:** key files explained in depth, others summarized241- **Pitfalls:** architectural decisions and their tradeoffs, coupling risks242- **Format:** start with file map, then drill into key files243244### For full project245- **Context:** what the project does, who it's for, deployment model246- **Data Flow:** one complete request traced end-to-end247- **Details:** layer-by-layer architecture overview (routes → services → data)248- **Pitfalls:** key architectural decisions, tech debt, scaling concerns249- **Format:** start with architecture overview, then offer to drill into any layer250251---252253## Tone Rules254255- **Define terms on first use** — "Blueprint (Flask's way of organizing related routes into a module)"256- **Use concrete examples** — show actual values flowing through, not abstract descriptions257- **Relate to familiar concepts** — see `${CLAUDE_PLUGIN_ROOT}/skills/codemap-explain/references/explanation-patterns.md` for analogies258- **Progressive complexity** — start simple, add nuance layer by layer259- **Honest about complexity** — "this part is genuinely tricky because..." is better than oversimplifying260- **Match the user's level** — use framework jargon only if user confirmed familiarity; otherwise define everything261262Do NOT:263- Use filler phrases ("Let's dive in!", "Great question!")264- Explain obvious things (what a for-loop is, what imports do) unless user is a complete beginner265- Hedge excessively ("it seems like", "it appears to") — be direct about what the code does266- Skip to code without context — always start with Layer 1267268---269270## Error Handling271272- **File not found** → ask the user to verify the path. Suggest: "Want me to search for similar filenames with Glob?"273- **Symbol not found** → grep broader patterns (partial name, related terms). Ask for clarification if still not found274- **Module too large (>20 files)** → explain top-level structure first, then ask: "Which part should I drill into?"275- **Minified/generated code** → warn the user this is generated code, offer to find the source instead276- **Binary/non-text files** → explain what the file type is and where it's likely configured or generated from