explore

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Explore - Internal Codebase Exploration

探索 - 内部代码库探索

Meta-skill for exploring an internal codebase at varying depths. READ-ONLY workflow - no code changes.

用于不同深度探索内部代码库的元技能。只读工作流——不修改任何代码。

Usage

使用方法

/explore <depth> [options]

/explore <depth> [options]

Question Flow (No Arguments)

提问流程（无参数）

If the user types just

/explore

with no or partial arguments, guide them through this question flow. Use AskUserQuestion for each phase.

如果用户仅输入

/explore

而未提供参数或参数不完整，将引导用户完成以下提问流程。每个阶段使用AskUserQuestion工具。

Phase 0: Workflow Selection

阶段0：工作流选择

yaml

question: "How would you like to explore?"
header: "Explore"
options:
  - label: "Help me choose (Recommended)"
    description: "I'll ask questions to pick the right exploration depth"
  - label: "Quick - fast overview"
    description: "Chain: tldr tree → tldr structure (~1 min)"
  - label: "Deep - comprehensive analysis"
    description: "Chain: onboard → tldr → research → document (~5 min)"
  - label: "Architecture - layers & dependencies"
    description: "Chain: tldr arch → call graph → layer mapping (~3 min)"

Mapping:

"Help me choose" → Continue to Phase 1-4 questions
"Quick" → Set depth=quick, skip to Phase 2 (scope)
"Deep" → Set depth=deep, skip to Phase 2 (scope)
"Architecture" → Set depth=architecture, skip to Phase 2 (scope)

If Answer is Unclear (via "Other"):

yaml

question: "I want to understand how deep you want to explore. Did you mean..."
header: "Clarify"
options:
  - label: "Help me choose"
    description: "Not sure - guide me through questions"
  - label: "Quick - fast overview"
    description: "Just want to see what's here"
  - label: "Deep - comprehensive analysis"
    description: "Need thorough understanding"
  - label: "Neither - let me explain differently"
    description: "I'll describe what I need"

yaml

question: "你希望以何种方式进行探索？"
header: "探索"
options:
  - label: "帮我选择（推荐）"
    description: "我会通过提问帮你选择合适的探索深度"
  - label: "快速 - 快速概览"
    description: "执行链：tldr tree → tldr structure（约1分钟）"
  - label: "深入 - 全面分析"
    description: "执行链：onboard → tldr → research → document（约5分钟）"
  - label: "架构 - 层级与依赖关系"
    description: "执行链：tldr arch → 调用图 → 层级映射（约3分钟）"

映射关系：

"帮我选择" → 继续执行阶段1-4的提问
"快速" → 设置depth=quick，跳过至阶段2（探索范围）
"深入" → 设置depth=deep，跳过至阶段2（探索范围）
"架构" → 设置depth=architecture，跳过至阶段2（探索范围）

若回答不明确（选择“其他”）：

yaml

question: "我需要明确你希望的探索深度。你是指..."
header: "确认"
options:
  - label: "帮我选择"
    description: "不确定 - 请通过提问引导我"
  - label: "快速 - 快速概览"
    description: "仅需了解代码库大致内容"
  - label: "深入 - 全面分析"
    description: "需要对代码库有透彻理解"
  - label: "都不是 - 我换种方式说明"
    description: "我会描述具体需求"

Phase 1: Exploration Goal

阶段1：探索目标

yaml

question: "What are you trying to understand?"
header: "Goal"
options:
  - label: "Get oriented in the codebase"
    description: "Quick overview of structure"
  - label: "Understand how something works"
    description: "Deep dive into specific area"
  - label: "Map the architecture"
    description: "Layers, dependencies, patterns"
  - label: "Find where something is"
    description: "Locate specific code/functionality"

Mapping:

"Get oriented" → quick depth
"Understand how" → deep depth
"Map architecture" → architecture depth
"Find where" → quick with --focus

yaml

question: "你希望了解哪方面内容？"
header: "目标"
options:
  - label: "熟悉代码库整体情况"
    description: "快速了解代码结构"
  - label: "理解特定功能的工作原理"
    description: "深入研究特定领域"
  - label: "梳理系统架构"
    description: "层级结构、依赖关系、设计模式"
  - label: "定位特定代码/功能"
    description: "找到特定代码或功能的位置"

映射关系：

"熟悉代码库整体情况" → 快速探索深度
"理解特定功能的工作原理" → 深入探索深度
"梳理系统架构" → 架构级探索深度
"定位特定代码/功能" → 快速探索+--focus参数

Phase 2: Scope

阶段2：探索范围

yaml

question: "What area should I focus on?"
header: "Focus"
options:
  - label: "Entire codebase"
    description: "Explore everything"
  - label: "Specific directory or module"
    description: "I'll specify the path"
  - label: "Specific concept/feature"
    description: "e.g., 'authentication', 'API routes'"

If "Specific directory" or "Specific concept" → ask follow-up for the path/keyword.

yaml

question: "我应该聚焦于哪个范围？"
header: "聚焦范围"
options:
  - label: "整个代码库"
    description: "探索全部内容"
  - label: "特定目录或模块"
    description: "我会指定路径"
  - label: "特定概念/功能"
    description: "例如：'authentication'、'API routes'"

若选择“特定目录”或“特定概念” → 继续提问获取具体路径/关键词。

Phase 3: Output Format

阶段3：输出格式

yaml

question: "What should I produce?"
header: "Output"
options:
  - label: "Just tell me what you find"
    description: "Interactive summary in chat"
  - label: "Create a documentation file"
    description: "Write to thoughts/shared/docs/"
  - label: "Create handoff for implementation"
    description: "Prepare context for coding agent"

Mapping:

"Documentation file" → --output doc
"Handoff for implementation" → --output handoff

yaml

question: "我应该生成什么格式的输出？"
header: "输出"
options:
  - label: "直接告知探索结果"
    description: "在聊天中生成交互式摘要"
  - label: "创建文档文件"
    description: "写入到thoughts/shared/docs/目录"
  - label: "生成开发交接文档"
    description: "为编码Agent准备上下文信息"

映射关系：

"创建文档文件" → --output doc
"生成开发交接文档" → --output handoff

Phase 4: Entry Point (Architecture only)

阶段4：入口点（仅架构级探索）

If architecture depth selected:

yaml

question: "Where should I start the analysis?"
header: "Entry point"
options:
  - label: "Auto-detect (main, cli, app)"
    description: "Find common entry points"
  - label: "Specific function/file"
    description: "I'll specify the entry point"

若选择架构级探索深度：

yaml

question: "我应该从哪里开始分析？"
header: "入口点"
options:
  - label: "自动检测（main、cli、app）"
    description: "查找常见的入口点"
  - label: "特定函数/文件"
    description: "我会指定入口点"

Summary Before Execution

执行前汇总

Based on your answers, I'll run:

**Depth:** deep
**Focus:** "authentication"
**Output:** handoff
**Path:** src/

Proceed? [Yes / Adjust settings]

根据你的回答，我将执行：

**探索深度：** deep
**聚焦范围：** "authentication"
**输出格式：** handoff
**路径：** src/

是否继续？[是 / 调整设置]

Depths

探索深度说明

Depth	Time	What it does
`quick`	~1 min	tldr-explorer only - fast structure overview
`deep`	~5 min	onboard + tldr-explorer + research-codebase + write doc
`architecture`	~3 min	tldr arch + call graph + layer mapping + circular dep detection

深度	耗时	功能说明
`quick`	~1分钟	仅使用tldr-explorer - 快速生成结构概览
`deep`	~5分钟	onboard + tldr-explorer + research-codebase + 生成文档
`architecture`	~3分钟	tldr arch + 调用图 + 层级映射 + 循环依赖检测

Options

可选参数

Option	Description	Example
`--focus "area"`	Focus on specific area	`--focus "auth"` , `--focus "api"`
`--output handoff`	Create handoff for next agent	`--output handoff`
`--output doc`	Create documentation file	`--output doc`
`--entry "func"`	Start from specific entry point	`--entry "main"` , `--entry "process_request"`

参数	说明	示例
`--focus "area"`	聚焦于特定领域	`--focus "auth"` , `--focus "api"`
`--output handoff`	为下一个Agent生成交接文档	`--output handoff`
`--output doc`	创建文档文件	`--output doc`
`--entry "func"`	从特定入口点开始分析	`--entry "main"` , `--entry "process_request"`

Examples

使用示例

bash

undefined

bash

undefined

Quick structure overview

快速结构概览

/explore quick

Deep exploration focused on auth

聚焦于认证模块的深入探索

/explore deep --focus "auth" --output doc

Architecture analysis from specific entry

从特定入口点开始的架构分析

/explore architecture --entry "cli" --output handoff

Quick focused exploration

聚焦于hooks模块的快速探索

/explore quick --focus "hooks"

undefined

/explore quick --focus "hooks"

undefined

Workflow Details

工作流详情

Quick Depth

快速探索深度

Fast structure overview using tldr-explorer. Best for:

Initial orientation
Quick questions about structure
Finding where things are

Steps:

Run
```
tldr tree
```
for file structure
Run
```
tldr structure
```
for codemaps
If
```
--focus
```
provided, run
```
tldr search
```
for targeted results
Return summary

Commands:

bash

undefined

仅使用tldr-explorer生成快速结构概览。适用于：

初次接触代码库时熟悉整体情况
快速了解代码结构
定位特定内容的位置

步骤：

执行
```
tldr tree
```
获取文件结构
执行
```
tldr structure
```
获取代码映射
若提供
```
--focus
```
参数，执行
```
tldr search
```
获取针对性结果
返回摘要

命令：

bash

undefined

1. File tree

1. 文件树

tldr tree ${PATH:-src/} --ext .py

2. Code structure

2. 代码结构

tldr structure ${PATH:-src/} --lang python

3. Focused search (if --focus provided)

3. 聚焦搜索（若提供--focus参数）

tldr search "${FOCUS}" ${PATH:-src/}

undefined

tldr search "${FOCUS}" ${PATH:-src/}

undefined

Deep Depth

深入探索深度

Comprehensive exploration with documentation output. Best for:

First time in a codebase
Preparing for major work
Creating reference documentation

Steps:

Check if onboarded (look for
```
.claude/cache/tldr/
```
), if not run onboard
Run tldr-explorer for structure
Spawn research-codebase agent for patterns
Write findings to doc or handoff

Subprocess:

undefined

生成全面的探索结果并输出文档。适用于：

首次接触代码库
准备进行重大开发工作前
创建参考文档

步骤：

检查是否已完成初始化（查找
```
.claude/cache/tldr/
```
目录），若未完成则执行onboard
执行tldr-explorer分析结构
启动research-codebase Agent分析设计模式
将探索结果写入文档或交接文档

子流程：

undefined

1. Onboard check

1. 初始化检查

if [ ! -f .claude/cache/tldr/arch.json ]; then # Spawn onboard agent fi

if [ ! -f .claude/cache/tldr/arch.json ]; then # 启动onboard Agent fi

2. Structure analysis

2. 结构分析

tldr structure src/ --lang python tldr calls src/

3. Research patterns (via scout agent)

3. 分析设计模式（通过scout Agent）

Task: research-codebase → "Document existing patterns in ${FOCUS:-codebase}"

Task: research-codebase → "记录${FOCUS:-代码库}中已有的设计模式"

4. Write output

4. 写入输出

→ thoughts/shared/research/YYYY-MM-DD-explore-{focus}.md → OR thoughts/shared/handoffs/{session}/explore-{focus}.yaml

undefined

→ thoughts/shared/research/YYYY-MM-DD-explore-{focus}.md → 或 thoughts/shared/handoffs/{session}/explore-{focus}.yaml

undefined

Architecture Depth

架构级探索深度

Architecture-focused analysis with layer detection. Best for:

Understanding system boundaries
Preparing for refactoring
Identifying coupling issues

Steps:

Run
```
tldr arch
```
for layer detection
Run
```
tldr calls
```
for cross-file call graph
Analyze entry/middle/leaf layers
Detect circular dependencies
Map architectural boundaries

Commands:

bash

undefined

聚焦于系统架构的分析，包含层级检测。适用于：

理解系统边界
准备进行代码重构
识别耦合问题

步骤：

执行
```
tldr arch
```
检测层级结构
执行
```
tldr calls
```
生成跨文件调用图
分析入口层/中间层/叶子层
检测循环依赖
梳理系统架构边界

命令：

bash

undefined

1. Architecture detection

1. 架构检测

tldr arch ${PATH:-src/}

Returns: entry_layer, middle_layer, leaf_layer, circular_deps

返回结果：entry_layer, middle_layer, leaf_layer, circular_deps

2. Call graph

2. 调用图

tldr calls ${PATH:-src/}

Returns: edges, nodes

返回结果：edges, nodes

3. Impact analysis from entry point (if --entry provided)

3. 入口点影响分析（若提供--entry参数）

tldr impact ${ENTRY} ${PATH:-src/} --depth 3


**Output Structure:**
```yaml
layers:
  entry: [routes.py, cli.py, main.py]  # Controllers/handlers
  middle: [services.py, auth.py]        # Business logic
  leaf: [utils.py, helpers.py]          # Utilities

call_graph:
  total_edges: 142
  hot_paths: [process_request → validate → authorize]

circular_deps:
  - [module_a, module_b]  # A imports B, B imports A

boundaries:
  - name: API layer
    files: [src/api/*]
    calls_to: [src/services/*]

tldr impact ${ENTRY} ${PATH:-src/} --depth 3


**输出结构：**
```yaml
layers:
  entry: [routes.py, cli.py, main.py]  # 控制器/处理器
  middle: [services.py, auth.py]        # 业务逻辑层
  leaf: [utils.py, helpers.py]          # 工具类

call_graph:
  total_edges: 142
  hot_paths: [process_request → validate → authorize]

circular_deps:
  - [module_a, module_b]  # A导入B，B导入A

boundaries:
  - name: API层
    files: [src/api/*]
    calls_to: [src/services/*]

Output Formats

输出格式

--output doc

Creates:

thoughts/shared/research/YYYY-MM-DD-explore-{focus}.md

markdown

---
date: {ISO timestamp}
type: exploration
depth: {quick|deep|architecture}
focus: {focus area or "full"}
commit: {git hash}
---

生成文件：

thoughts/shared/research/YYYY-MM-DD-explore-{focus}.md

markdown

---
date: {ISO时间戳}
type: exploration
depth: {quick|deep|architecture}
focus: {聚焦范围或"full"}
commit: {git哈希值}
---

Codebase Exploration: {focus}

代码库探索：{聚焦范围}

Summary

摘要

{High-level findings}

{高层级探索结果}

Structure

结构

{File tree / codemaps}

{文件树/代码映射}

Architecture

架构

{Layer analysis - for architecture depth}

{层级分析 - 仅架构级深度}

Key Components

关键组件

{Important files and their roles}

{重要文件及其作用}

Patterns Found

发现的设计模式

{Existing patterns - for deep depth}

{已有的设计模式 - 仅深入探索深度}

References

参考

```
path/to/file.py:line
```
- Description

undefined

```
path/to/file.py:line
```
- 说明

undefined

--output handoff

Creates:

thoughts/shared/handoffs/{session}/explore-{focus}.yaml

yaml

---
type: exploration
ts: {ISO timestamp}
depth: {quick|deep|architecture}
focus: {focus area}
commit: {git hash}
---

summary: {One-line summary of findings}

structure:
  entry_points: [{main.py}, {cli.py}]
  key_modules: [{auth.py}, {routes.py}]
  test_coverage: [{tests/}]

architecture:
  layers:
    entry: [{files}]
    middle: [{files}]
    leaf: [{files}]
  circular_deps: [{pairs}]

findings:
  - {key finding with file:line}

next_steps:
  - {Recommended action based on exploration}

refs:
  - path: {file.py}
    role: {what it does}

生成文件：

thoughts/shared/handoffs/{session}/explore-{focus}.yaml

yaml

---
type: exploration
ts: {ISO时间戳}
depth: {quick|deep|architecture}
focus: {聚焦范围}
commit: {git哈希值}
---

summary: {探索结果的单行摘要}

structure:
  entry_points: [{main.py}, {cli.py}]
  key_modules: [{auth.py}, {routes.py}]
  test_coverage: [{tests/}]

architecture:
  layers:
    entry: [{files}]
    middle: [{files}]
    leaf: [{files}]
  circular_deps: [{pairs}]

findings:
  - {带文件行号的关键发现}

next_steps:
  - {基于探索结果的推荐操作}

refs:
  - path: {file.py}
    role: {文件作用}

Integration with /build

与/build的集成

The explore skill is designed to feed into

/build brownfield

bash

undefined

探索技能专为与

/build brownfield

配合使用而设计：

bash

undefined

Step 1: Explore to understand

步骤1：通过探索了解代码库

/explore architecture --output handoff

Step 2: Build with context from exploration

步骤2：利用探索的上下文进行开发

/build brownfield --from-handoff thoughts/shared/handoffs/session/explore-full.yaml

undefined

/build brownfield --from-handoff thoughts/shared/handoffs/session/explore-full.yaml

undefined

Implementation

实现逻辑

When user invokes

/explore <depth> [options]

当用户调用

/explore <depth> [options]

时：

Parse Arguments

解析参数

python

depth = args[0]  # quick | deep | architecture
focus = extract_option(args, "--focus")
output = extract_option(args, "--output")  # handoff | doc
entry = extract_option(args, "--entry")

python

depth = args[0]  # quick | deep | architecture
focus = extract_option(args, "--focus")
output = extract_option(args, "--output")  # handoff | doc
entry = extract_option(args, "--entry")

Execute Based on Depth

根据探索深度执行

Quick:

bash

undefined

快速探索：

bash

undefined

Just tldr commands, no agents

仅执行tldr命令，不启动Agent

tldr tree ${src_dir} --ext .py tldr structure ${src_dir} --lang python if [ -n "$focus" ]; then tldr search "$focus" ${src_dir} fi


**Deep:**
```bash

tldr tree ${src_dir} --ext .py tldr structure ${src_dir} --lang python if [ -n "$focus" ]; then tldr search "$focus" ${src_dir} fi


**深入探索：**
```bash

1. Check/run onboard

1. 检查/执行初始化

if [ ! -f .claude/cache/tldr/meta.json ]; then # Spawn onboard agent via Task tool fi

if [ ! -f .claude/cache/tldr/meta.json ]; then # 通过Task工具启动onboard Agent fi

2. Structure

2. 结构分析

tldr structure src/ --lang python

3. Research (spawn scout agent)

3. 分析设计模式（启动scout Agent）

Task tool with subagent_type: "scout"

Task工具，subagent_type: "scout"

Prompt: "Research patterns in ${focus:-codebase}"

提示："研究${focus:-代码库}中的设计模式"

4. Write output

4. 写入输出

→ doc or handoff based on --output

→ 根据--output参数生成doc或handoff


**Architecture:**
```bash


**架构级探索：**
```bash

1. Arch detection

1. 架构检测

arch_output=$(tldr arch ${src_dir})

2. Call graph

2. 调用图

calls_output=$(tldr calls ${src_dir})

3. Impact from entry (if provided)

3. 入口点影响分析（若提供参数）

if [ -n "$entry" ]; then impact_output=$(tldr impact $entry ${src_dir} --depth 3) fi

4. Synthesize and write output

4. 合成结果并写入输出

undefined

undefined

Key Principles

核心原则

READ-ONLY - This skill never modifies code
Uses scout, not Explore - Per project rules, scout (Sonnet) over Explore (Haiku)
Token-efficient - Uses tldr commands (95% savings over raw reads)
Outputs to shared locations -
```
thoughts/shared/research/
```
or handoff directory
Entry point to /build - Exploration handoffs feed into brownfield builds

只读模式 - 本技能绝不会修改代码
使用scout而非Explore - 遵循项目规则，使用scout（Sonnet）而非Explore（Haiku）
高效token利用 - 使用tldr命令（相比直接读取代码节省95%的token）
输出到共享位置 -
```
thoughts/shared/research/
```
或交接文档目录
/build的前置步骤 - 探索生成的交接文档可用于brownfield开发

Related Skills

Skill	When to Use
tldr-explorer	Direct tldr commands (used internally by explore)
tldr-code	Specific analysis commands (cfg, dfg, slice)
onboard	First-time project setup (used by deep depth)
research-codebase	Pattern documentation (used by deep depth)
create_handoff	Handoff format (used by --output handoff)

技能	使用场景
tldr-explorer	直接执行tldr命令（被探索技能内部调用）
tldr-code	特定分析命令（cfg、dfg、slice）
onboard	首次项目初始化（被深入探索深度调用）
research-codebase	设计模式文档生成（被深入探索深度调用）
create_handoff	交接文档格式生成（被--output handoff调用）

Troubleshooting

故障排除

tldr not found:

bash

undefined

未找到tldr：

bash

undefined

Check if installed

检查是否已安装

which tldr

Install if missing

若未安装则执行

uv tool install llm-tldr

or: pip install llm-tldr

或：pip install llm-tldr


**No Python files found:**
```bash


**未找到Python文件：**
```bash

Check language, adjust --lang

检查语言类型，调整--lang参数

tldr structure src/ --lang typescript # or go, rust


**Empty architecture output:**
```bash

tldr structure src/ --lang typescript # 或go、rust


**架构输出为空：**
```bash

May need to specify src directory

可能需要指定src目录

tldr arch ./ # Current directory tldr arch src/ # Explicit src

undefined

tldr arch ./ # 当前目录 tldr arch src/ # 明确指定src目录

undefined