explain

Explain - コードの詳細な解説

コード、ファイル、ディレクトリ、またはアーキテクチャの概念について、包括的な説明を得られます。最も関連性の高い -ops スキルをあらかじめ読み込んだ汎用エージェントを自動的に起動し、最新の 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：コンテキストを収集

可能な場合、以下を並行して実行します：

使用箇所を検索（structural-search スキル）：

# 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：解説エージェントに振り分け

振り分けではスキルを優先します。汎用の general-purpose サブエージェントが、ファイルの拡張子と内容に基づいて、関連する -ops スキルをあらかじめ読み込みます：

パターン	振り分け先	事前読み込み	条件
.ts	general-purpose	skills/typescript-ops/SKILL.md	JSX／React の import がない
.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：解説を生成

振り分けられたエージェントが、構造化された解説を生成します：

# 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

出力：1 段落とエクスポートの一覧。

詳細な解説の例

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

出力：内部処理全般、アルゴリズム分析、パフォーマンスに関する注記、エッジケース。

トレースの例

/explain handleLogin --trace

出力：エントリーポイントからデータベースを経てレスポンスに至るまでのデータフローを追跡します。

重点領域モード

モード	分析内容
--focus arch	モジュール境界、レイヤー分離、依存関係
--focus flow	データフロー、制御フロー、状態の変化
--focus deps	import、外部依存関係、統合
--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 スキルにより、フレームワーク固有の知見が得られます