FoundryVTT/.claude/commands/explain.md

description, allowed-tools, argument-hint

description	allowed-tools	argument-hint
Explain code in detail - how it works, patterns used, and key concepts	Read(*), Grep(*), Glob(*), Bash(git log:*)	file-or-selection

Explain Command

Provide detailed, educational explanations of code.

Technology Adaptation

Configuration Source: 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

## 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