claude-mods/commands/explain.md

---

description: "Deep explanation of complex code, files, or concepts. Breaks down architecture, data flow, and design decisions."

Explain - Deep Code Explanation

Get a comprehensive explanation of complex code, files, or architectural concepts.

Arguments

$ARGUMENTS

• File path: Explain specific file
• Function/class name: Explain specific component
• --depth <shallow|normal|deep>: Level of detail
• --focus <arch|flow|deps|api>: Specific focus area

What This Command Does

1. Identify Target

   • Parse file/function/concept
   • Gather related files if needed
   • Understand scope of explanation

2. Analyze Code

   • Parse structure and dependencies
   • Trace data flow
   • Identify patterns and design decisions

3. Generate Explanation

   • Architecture overview
   • Step-by-step breakdown
   • Visual diagrams (ASCII)
   • Related concepts

Execution Steps

Step 1: Parse Target

# If file path
cat <file>

# If function name, search for it
grep -rn "function <name>\|def <name>\|class <name>" .

# If directory
ls -la <dir>
tree <dir> -L 2

Step 2: Gather Context

For the target, collect:

• Imports/dependencies
• Exports/public API
• Related files (tests, types)
• Usage examples in codebase

Step 3: Analyze Structure

For Functions:

• Input parameters and types
• Return value and type
• Side effects
• Error handling
• Algorithm complexity

For Classes:

• Properties and methods
• Inheritance/composition
• Lifecycle
• Public vs private API

For Files/Modules:

• Purpose and responsibility
• Exports and imports
• Dependencies
• Integration points

For Directories:

• Module organization
• File relationships
• Naming conventions
• Architecture pattern

Step 4: Generate Explanation

# Explanation: <target>

## Overview
<1-2 sentence summary of what this does and why>

## Architecture
<ASCII diagram if helpful>

┌─────────────┐ ┌─────────────┐ │ Input │───▶│ Processor │ └─────────────┘ └──────┬──────┘

                      │
                      ▼
               ┌─────────────┐
               │   Output    │
               └─────────────┘

## How It Works

### Step 1: <phase name>
<explanation>

### Step 2: <phase name>
<explanation>

## Key Concepts

### <Concept 1>
<explanation>

### <Concept 2>
<explanation>

## Dependencies
- `<dep1>` - <purpose>
- `<dep2>` - <purpose>

## Usage Examples

```<language>
// Example usage

Design Decisions

Why ?

Related Code

• <file1> -
• <file2> -

Common Pitfalls

• ```

Usage Examples

# Explain a file
/explain src/auth/oauth.ts

# Explain a function
/explain validateToken

# Explain a class
/explain UserService

# Explain a directory
/explain src/services/

# Explain with deep detail
/explain src/core/engine.ts --depth deep

# Focus on data flow
/explain src/api/routes.ts --focus flow

# Architecture overview
/explain src/services/ --focus arch

Depth Levels

Level	Output
shallow	Quick overview, main purpose, key exports
normal	Full explanation with examples (default)
deep	Exhaustive breakdown, edge cases, internals

Focus Areas

Focus	Explains
arch	Architecture, structure, patterns
flow	Data flow, control flow, sequence
deps	Dependencies, imports, integrations
api	Public API, inputs, outputs, contracts

Explanation Styles by Target

Functions

• Input/Output: What goes in, what comes out
• Algorithm: Step-by-step logic
• Edge Cases: Boundary conditions
• Performance: Time/space complexity

Classes

• Purpose: Why this class exists
• State: What data it manages
• Behavior: What it can do
• Relationships: How it connects to others

Files

• Role: Where it fits in the system
• Exports: What it provides
• Imports: What it needs
• Patterns: Design patterns used

Directories

• Organization: How files are structured
• Conventions: Naming and patterns
• Boundaries: Module responsibilities
• Dependencies: Inter-module relationships

ASCII Diagrams

For complex systems, include ASCII diagrams:

Sequence Diagram

User          Service         Database
  │              │               │
  │──request───▶│               │
  │              │───query─────▶│
  │              │◀──result─────│
  │◀─response───│               │

Data Flow

[Input] → [Validate] → [Transform] → [Store] → [Output]
              │
              └──[Error]──▶ [Log]

Component Diagram

┌────────────────────────────────────┐
│            Application             │
├──────────┬──────────┬─────────────┤
│  Routes  │ Services │   Models    │
├──────────┴──────────┴─────────────┤
│            Database               │
└────────────────────────────────────┘

Flags

Flag	Effect
--depth <level>	Set detail level (shallow/normal/deep)
--focus <area>	Focus on specific aspect
--no-examples	Skip usage examples
--no-diagrams	Skip ASCII diagrams
--json	Output as structured JSON

Integration

Works well with:

• /review - Review after understanding
• /test - Generate tests for explained code
• /checkpoint - Save progress after learning

Notes

• Explanations are based on code analysis, not documentation
• Complex systems may need multiple explanations
• Use --depth deep for unfamiliar codebases
• Diagrams help visualize relationships