153 lines
4.2 KiB
Markdown
153 lines
4.2 KiB
Markdown
---
|
|
description: Explain code in detail - how it works, patterns used, and key concepts
|
|
allowed-tools: Read(*), Grep(*), Glob(*), Bash(git log:*)
|
|
argument-hint: [file-or-selection]
|
|
---
|
|
|
|
# Explain Command
|
|
|
|
Provide detailed, educational explanations of code.
|
|
|
|
## Technology Adaptation
|
|
|
|
**Configuration Source**: [CLAUDE.md](../../CLAUDE.md)
|
|
|
|
Consult CLAUDE.md for:
|
|
- **Language**: To explain syntax and language-specific features
|
|
- **Frameworks**: To identify framework patterns and conventions
|
|
- **Project Patterns**: To explain project-specific architectures
|
|
|
|
## Instructions
|
|
|
|
1. **Identify Target**
|
|
- If $ARGUMENTS provided: Explain that file/code
|
|
- If user has selection: Explain selected code
|
|
- Otherwise: Ask what needs explanation
|
|
|
|
2. **Analyze Code**
|
|
- Read CLAUDE.md to understand project context
|
|
- Use serena MCP to understand code structure
|
|
- Identify patterns, algorithms, and design choices
|
|
- Understand dependencies and relationships
|
|
|
|
3. **Provide Explanation**
|
|
Include these sections:
|
|
- **Purpose**: What this code does (high-level)
|
|
- **How It Works**: Step-by-step breakdown
|
|
- **Key Concepts**: Patterns, algorithms, principles used
|
|
- **Dependencies**: What it relies on
|
|
- **Important Details**: Edge cases, gotchas, considerations
|
|
- **In Context**: How it fits in the larger system
|
|
|
|
4. **Adapt Explanation Level**
|
|
- Use clear, educational language
|
|
- Explain technical terms when first used
|
|
- Provide examples where helpful
|
|
- Reference CLAUDE.md patterns when relevant
|
|
|
|
## MCP Server Usage
|
|
|
|
### Serena MCP
|
|
|
|
**Code Navigation**:
|
|
- `find_symbol` - Locate symbols to explain
|
|
- `find_referencing_symbols` - Understand usage and relationships
|
|
- `get_symbols_overview` - Get file structure and organization
|
|
- `search_for_pattern` - Find related patterns
|
|
|
|
**Persistent Memory** (stored in `.serena/memories/`):
|
|
- Use `write_memory` to store complex explanations for future reference:
|
|
- "explanation-algorithm-[name]"
|
|
- "explanation-pattern-[pattern-name]"
|
|
- "explanation-architecture-[component]"
|
|
- Use `read_memory` to recall past explanations of related code
|
|
- Use `list_memories` to find previous explanations
|
|
|
|
### Memory MCP (Knowledge Graph)
|
|
|
|
**Temporary Context** (in-memory, cleared after session):
|
|
- Use `create_entities` for code elements being explained
|
|
- Use `create_relations` to map relationships between components
|
|
- Use `add_observations` to document understanding
|
|
|
|
**Note**: After explanation, store reusable patterns in Serena memory.
|
|
|
|
### Context7 MCP
|
|
- Use `get-library-docs` for framework/library documentation and official explanations
|
|
|
|
## Output Format
|
|
|
|
```markdown
|
|
## Explanation: [Code/File Name]
|
|
|
|
### Purpose
|
|
[What this code accomplishes and why it exists]
|
|
|
|
### How It Works
|
|
|
|
#### Step 1: [High-level step]
|
|
[Detailed explanation]
|
|
|
|
```[language]
|
|
[Relevant code snippet]
|
|
```
|
|
|
|
#### Step 2: [Next step]
|
|
[Explanation]
|
|
|
|
### Key Concepts
|
|
|
|
#### [Concept 1]: [Name]
|
|
[Explanation of pattern/algorithm/principle]
|
|
|
|
#### [Concept 2]: [Name]
|
|
[Explanation]
|
|
|
|
### Dependencies
|
|
- **[Dependency 1]**: [What it provides and why needed]
|
|
- **[Dependency 2]**: [What it provides and why needed]
|
|
|
|
### Important Details
|
|
- **[Detail 1]**: [Edge case or consideration]
|
|
- **[Detail 2]**: [Gotcha or important note]
|
|
|
|
### In the Larger System
|
|
[How this fits into the project architecture from CLAUDE.md]
|
|
|
|
### Related Code
|
|
[Links to related files or functions]
|
|
|
|
### Further Reading
|
|
[References to documentation or patterns]
|
|
```
|
|
|
|
## Example Output Scenarios
|
|
|
|
### For a Function
|
|
- Explain algorithm and complexity
|
|
- Show input/output examples
|
|
- Highlight edge cases
|
|
- Explain why this approach was chosen
|
|
|
|
### For a Class
|
|
- Explain responsibility and role
|
|
- Show key methods and their purposes
|
|
- Explain relationships with other classes
|
|
- Highlight design patterns used
|
|
|
|
### For a Module
|
|
- Explain module's purpose in architecture
|
|
- Show public API and how to use it
|
|
- Explain internal organization
|
|
- Show integration points
|
|
|
|
## Guidelines
|
|
|
|
- Start with high-level understanding, then dive into details
|
|
- Use analogies when helpful
|
|
- Explain "why" not just "what"
|
|
- Reference CLAUDE.md patterns
|
|
- Be educational but concise
|
|
- Assume reader has basic programming knowledge
|
|
- Adapt detail level based on code complexity
|