explain

Structured Code Explainer

Overview

Produce layered explanations of code — files, directories, functions, classes, or cross-cutting concepts. Designed for developers working in unfamiliar parts of a codebase.

Core principles:

1. Adaptive depth. A single function gets a focused deep-dive. A directory gets a map first, then the user picks where to zoom.
2. Project-aware. If the project has a CLAUDE.md, reference its Architecture section to ground explanations in the project's own terminology.
3. Conversation output. Explanations go to the conversation, not files. The user can ask to save if they want.

When to Use

User types /explain followed by:

• File path → explain that file
• Directory path → map the directory structure, then explain key components
• Function or class name → find the definition, explain it in context
• Natural language concept → search the codebase for relevant files and explain the concept/flow

Invocation Examples

/explain src/auth/middleware.ts
/explain the payment processing flow
/explain src/services/
/explain OrderProcessor.process
/explain how webhooks get dispatched

Workflow Order (MANDATORY)

You MUST follow this order. No skipping steps.

---

Step 1: Parse Input

Classify the argument:

Type	Detection	Example
File path	Has file extension or resolves to a file	src/auth/middleware.ts
Directory path	Resolves to a directory (or ends with /)	src/services/
Symbol name	Looks like a function, class, or method (CamelCase, dot notation, ::)	OrderProcessor.process
Concept	Natural language, doesn't resolve to a file or directory	the payment processing flow

If ambiguous (e.g., auth could be a directory or a concept), check the filesystem first. If it resolves to a file or directory, treat it as that. Otherwise, treat it as a concept.

---

Step 2: Gather Context

For a file path:

1. Read the target file
2. Identify imports/dependencies — read the most important ones (up to 5 files)
3. Search for callers — search for the filename or its key exports across source files in the codebase (filter to relevant file types like *.ts, *.py, *.go, etc. to avoid noise from docs, tests, and build output)
4. Limit total files read to ~10 to stay focused