explain

解释 - 深入讲解代码

全面讲解代码、文件、目录或架构概念。自动分派预先加载了最相关 -ops 技能的通用 Agent，并使用现代 CLI 工具进行分析。

参数

$ARGUMENTS

• <target> - 文件路径、函数名、类名、目录或概念
• --depth <shallow|normal|deep|trace> - 详细程度（默认：normal）
• --focus <arch|flow|deps|api|perf> - 特定关注领域

架构

/explain <target> [--depth] [--focus]
    |
    +-> Step 1: Detect & Classify Target
    |     +- File exists? -> Read it
    |     +- Function/class? -> ast-grep to find definition
    |     +- Directory? -> tokei for overview
    |     +- Concept? -> rg search codebase
    |
    +-> Step 2: Gather Context (parallel)
    |     +- structural-search skill -> find usages
    |     +- code-stats skill -> assess scope
    |     +- Find related: tests, types, docs
    |     +- Load: AGENTS.md, CLAUDE.md conventions
    |
    +-> Step 3: Route to Explainer (general-purpose + skill preload)
    |     +- .ts/.tsx -> general-purpose, preload typescript-ops or react-ops
    |     +- .py -> general-purpose, preload python-* skill by topic
    |     +- .vue -> general-purpose, preload vue-ops
    |     +- .sql/migrations -> general-purpose, preload postgres-ops
    |     +- agents/skills/commands -> general-purpose, preload claude-code-ops
    |     +- Default -> general-purpose
    |     +- All explainers preload: debug-ops (systematic analysis)
    |
    +-> Step 4: Generate Explanation
    |     +- Structured markdown with sections
    |     +- Mermaid diagrams (flowchart/sequence/class)
    |     +- Related code paths as file:line refs
    |     +- Design decisions and rationale
    |
    +-> Step 5: Integrate
          +- Offer to save to ARCHITECTURE.md (if significant)
          +- Link to /save if working on related task

执行步骤

步骤 1：检测目标类型

# Check if target is a file
test -f "$TARGET" && echo "FILE" && exit

# Check if target is a directory
test -d "$TARGET" && echo "DIRECTORY" && exit

# Otherwise, search for it as a symbol

对于文件： 使用 bat（语法高亮）或 Read 工具直接读取。

对于目录： 使用 tokei（如果可用）获取概览：

command -v tokei >/dev/null 2>&1 && tokei "$TARGET" --compact || echo "tokei unavailable"

对于符号（函数/类）： 使用 ast-grep 查找定义：

# Try ast-grep first (structural)
command -v ast-grep >/dev/null 2>&1 && ast-grep -p "function $TARGET" -p "class $TARGET" -p "def $TARGET"

# Fallback to ripgrep
rg "(?:function|class|def|const|let|var)\s+$TARGET" --type-add 'code:*.{ts,tsx,js,jsx,py,vue}' -t code

步骤 2：收集上下文

尽可能并行运行以下操作：

查找用法（结构化搜索技能）：

# With ast-grep
ast-grep -p "$TARGET($_)" --json 2>/dev/null | head -20

# Fallback
rg "$TARGET" --type-add 'code:*.{ts,tsx,js,jsx,py,vue}' -t code -l

查找相关文件：

# Tests
fd -e test.ts -e spec.ts -e test.py -e spec.py | xargs rg -l "$TARGET" 2>/dev/null

# Types/interfaces
fd -e d.ts -e types.ts | xargs rg -l "$TARGET" 2>/dev/null

加载项目约定：

• 如果存在，读取 AGENTS.md
• 如果存在，读取 CLAUDE.md
• 检查是否有特定于框架的模式

步骤 3：分派给讲解 Agent

分派优先使用技能：通用 general-purpose 子 Agent 会根据文件扩展名和内容预加载相关的 -ops 技能：

模式	分派	预加载	条件
.ts	general-purpose	skills/typescript-ops/SKILL.md	不包含 JSX/React 导入
.tsx	general-purpose	skills/react-ops/SKILL.md	存在 JSX
.js、.jsx	general-purpose	skills/javascript-ops/SKILL.md	-
.py	general-purpose	根据主题选择相关的 skills/python-*/SKILL.md	-
.vue	general-purpose	skills/vue-ops/SKILL.md	-
.sql、migrations/*	general-purpose	skills/postgres-ops/SKILL.md	-
agents/*.md、skills/*、commands/*	general-purpose	skills/claude-code-ops/SKILL.md	Claude 扩展
*.test.*、*.spec.*	general-purpose	（根据文件类型选择框架技能）	-
其他	general-purpose	-	回退

通过 Agent 工具调用：

Agent tool with subagent_type: "general-purpose" (preload claude-code-ops for Claude extensions)
model: "sonnet"
Prompt includes:
  - Skill preloading (domain knowledge):
    "First, read these files for analysis context:
     - Read: skills/debug-ops/SKILL.md
     - Read: [Preload column for the matched pattern]"
  - File content
  - Related files found
  - Project conventions
  - Requested depth and focus

步骤 4：生成讲解

分派的 Agent 会生成结构化讲解：

# Explanation: [target]

## Overview
[1-2 sentence summary of purpose and role in the system]

## Architecture

[Mermaid diagram - choose appropriate type]

### Flowchart (for control flow)
` ` `mermaid
flowchart TD
    A[Input] --> B{Validate}
    B -->|Valid| C[Process]
    B -->|Invalid| D[Error]
    C --> E[Output]
` ` `

### Sequence (for interactions)
` ` `mermaid
sequenceDiagram
    participant Client
    participant Server
    participant Database
    Client->>Server: Request
    Server->>Database: Query
    Database-->>Server: Result
    Server-->>Client: Response
` ` `

### Class (for structures)
` ` `mermaid
classDiagram
    class Component {
        +props: Props
        +state: State
        +render(): JSX
    }
` ` `

## How It Works

### Step 1: [Phase Name]
[Explanation with code references]

See: `src/module.ts:42`

### Step 2: [Phase Name]
[Explanation]

## Key Concepts

### [Concept 1]
[Explanation]

### [Concept 2]
[Explanation]

## Dependencies

| Import | Purpose |
|--------|---------|
| `package` | [why it's used] |

## Design Decisions

### Why [decision]?
[Rationale and tradeoffs considered]

## Related Code

| File | Relationship |
|------|--------------|
| `path/to/file.ts:123` | [how it relates] |

## See Also

- `/explain path/to/related` - [description]
- [External docs link] - [description]

详细程度模式

模式	输出
--shallow	概述段落、关键导出项，不含图表
--normal	完整讲解，包含 1 张图表和主要概念（默认）
--deep	详尽内容：所有内部细节、边缘情况、历史背景、多张图表
--trace	跟踪整个系统中的数据流，包含时序图

浅层示例

/explain src/auth/token.ts --shallow

输出：单个段落 + 导出项列表。

深入示例

/explain src/core/engine.ts --deep

输出：完整内部细节、算法分析、性能说明、边缘情况。

跟踪示例

/explain handleLogin --trace

输出：跟踪从入口到数据库再到响应的数据流。

关注模式

模式	分析内容
--focus arch	模块边界、分层、依赖关系
--focus flow	数据流、控制流、状态变化
--focus deps	导入项、外部依赖、集成
--focus api	公共接口、输入/输出、契约
--focus perf	复杂度、瓶颈、优化机会

CLI 工具集成

命令使用现代 CLI 工具，并提供平滑的回退方案：

工具	用途	回退方案
tokei	代码统计	跳过统计
ast-grep	结构化搜索	使用带模式的 rg
bat	语法高亮	Read 工具
rg	内容搜索	Grep 工具
fd	文件查找	Glob 工具

检查是否可用：

command -v tokei >/dev/null 2>&1 || echo "tokei not installed - skipping stats"

使用示例

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

# Explain a function (finds it automatically)
/explain validateToken

# Explain a directory
/explain src/services/

# Deep dive with architecture focus
/explain src/core/engine.ts --deep --focus arch

# Trace data flow
/explain handleUserLogin --trace

# Quick overview
/explain src/utils/helpers.ts --shallow

# Focus on dependencies
/explain package.json --focus deps

集成

技能/命令	关联方式
/review	理解后进行审查
/testgen	为讲解过的代码生成测试
/save	处理相关任务时保存进度

持久化

在进行重要说明后，系统可能会提示你：

Would you like to save this explanation?
  1. Append to ARCHITECTURE.md
  2. Append to AGENTS.md (if conventions-related)
  3. Don't save (output only)

这样可以将有价值的架构知识保存在由 git 跟踪的文档中。

备注

• 说明基于代码分析，而非文档
• 复杂系统可能需要多次调用 /explain
• 对不熟悉的代码库使用 --deep
• Mermaid 图表可在 GitHub、GitLab、VSCode 和大多数 Markdown 查看器中渲染
• 预加载的 -ops 技能可提供特定于框架的见解