Quick Explain Code

Get a plain-language explanation of any code file, function, or block, including its purpose, inputs, outputs, side effects, and how it fits into the larger system.

When to Use This Command

Run this command when...

• You are reading unfamiliar code and need to understand what a function or module does
• You want to explain a complex piece of code to a team member or in a PR description
• You need to understand how a component interacts with the rest of the system

Avoid this command when...

• The code is trivial and self-explanatory (e.g., a simple getter function)
• You need to modify the code, not just understand it

Quick Start

Copy
# .claude/commands/quick-explain-code.md
---
allowed-tools: ["Read", "Grep", "Glob"]
---
Read the specified file or function. Explain its purpose,
inputs, outputs, and side effects in plain language.
Show how it connects to the rest of the codebase.

Example usage:

/quick-explain-code src/services/billing/invoiceGenerator.ts
/quick-explain-code "the handleWebhook function in stripe.ts"

Example output:

Explanation: invoiceGenerator.ts
================================
Purpose: Generates PDF invoices from order data and sends
         them to customers via email.

Inputs:
  - orderId (string): The order to generate an invoice for
  - options.format: PDF or HTML output format

Outputs:
  - Returns a Buffer containing the rendered invoice

Side Effects:
  - Sends an email via the EmailService
  - Logs invoice generation to the audit table

Called By: orderController.ts (after payment confirmation)
Calls: PdfRenderer, EmailService, AuditLogger

Core Concepts

Concept	Description
Purpose analysis	Determines what the code is designed to accomplish
I/O mapping	Documents what goes in (parameters, config) and what comes out
Side effect detection	Identifies database writes, API calls, file system changes
Call graph	Shows what calls this code and what this code calls

Target Code --> Read Source --> Analyze
                                 |
                    +-----+------+------+
                    |     |      |      |
                Purpose  I/O   Side   Call
                              Effects  Graph
                    |     |      |      |
                    +-----+------+------+
                           |
                   Plain Language Summary

Configuration

Option	Default	Description
depth	medium	Explanation detail level (brief, medium, thorough)
audience	developer	Target audience (developer, junior, non-technical)
include-graph	true	Show the call graph (callers and callees)
include-examples	false	Add usage examples to the explanation
format	text	Output format (text, markdown, json)

Best Practices

1. Start with the entry point -- explain the main function first, then drill into its helpers.
2. Ask for the call graph -- understanding callers and callees reveals the code's role in the system.
3. Use for PR descriptions -- paste the explanation into your PR to help reviewers understand context.
4. Specify the audience -- a "non-technical" explanation removes jargon and focuses on business logic.
5. Pair with debug-error -- when debugging, explain the error site first to understand expected behavior.

Common Issues

1. Explanation too superficial -- set depth to thorough for complex algorithms or business logic.
2. Missing broader context -- if the function depends heavily on external state, the explanation may be incomplete. Provide the full file path.
3. Dynamic dispatch not resolved -- functions called via callbacks or dependency injection may not appear in the call graph. Mention the pattern explicitly.