code-explanation

Code Explanation

Overview

Understanding code is a prerequisite to improving it. Rushed explanations create misunderstanding that compounds over time.

Core principle: Explain at the right level of abstraction. Start high, drill down only when needed.

Iron Law:

READ BEFORE EXPLAINING. UNDERSTAND BEFORE SIMPLIFYING.

Never explain code you haven't fully read. Never simplify what you haven't fully understood.

When to Use

• Onboarding new team members to a codebase
• Code review: explaining design decisions
• Understanding legacy code before modifying it
• Explaining an AI agent's recommendations
• Documenting complex algorithms or patterns
• Understanding error stack traces

The Five Levels of Explanation

Choose the level based on your audience and purpose:

Level	Audience	Goal	Depth
L1: Bird's Eye	Non-technical stakeholders	What does this system do?	Architecture diagram
L2: Module	New developers	How is this organized?	Module/file structure
L3: Function	Developers onboarding	What does this code do?	Function by function
L4: Line	Debugging partners	Why is this written this way?	Line by line
L5: Algorithm	Algorithm review	How does this work mathematically?	Proof-level

The Explanation Process

Phase 1: Read First

1. Read the entire file/function before explaining anything
2. Identify the core purpose (what problem does this solve?)
3. Note dependencies (what does this require?)
4. Note side effects (what does this change?)
5. Note error handling (what can go wrong?)

Phase 2: Bird's Eye View (Always Start Here)

**What this is:** One sentence describing purpose
**What problem it solves:** The business/technical need
**How it fits:** Where it sits in the larger system
**Key dependencies:** What it relies on
**Key outputs:** What it produces or modifies

Example:

**What this is:** RulesService — file system reader for AI coding rules
**What problem it solves:** Provides a unified interface for reading and searching
  .ai-rules files regardless of directory structure
**How it fits:** Used by McpModule to serve rules via MCP protocol
**Key dependencies:** Node.js fs/promises, glob patterns
**Key outputs:** Array of Rule objects with name, content, and metadata