explore

探索 - 内部代码库探索

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

用法

/explore <depth> [options]

问题流程（无参数）

如果用户只输入 /explore，或输入的参数不完整，请引导用户完成以下问题流程。每个阶段都使用 AskUserQuestion。

阶段 0：工作流选择

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)"

映射：

• “帮助我选择” → 继续回答阶段 1-4 的问题
• “快速” → 设置 depth=quick，跳到阶段 2（范围）
• “深入” → 设置 depth=deep，跳到阶段 2（范围）
• “架构” → 设置 depth=architecture，跳到阶段 2（范围）

如果答案不明确（通过“其他”）：

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"

阶段 1：探索目标

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"

映射：

• “熟悉代码库” → quick 深度
• “了解其工作方式” → deep 深度
• “梳理架构” → architecture 深度
• “查找位置” → quick 并附带 --focus

阶段 2：范围

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'"

如果选择“特定目录”或“特定概念” → 追问路径或关键词。

阶段 3：输出格式

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"

映射：

• “文档文件” → --output doc
• “实现交接” → --output handoff

阶段 4：入口点（仅限架构）

如果选择了 architecture 深度：

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"

执行前摘要

Based on your answers, I'll run:

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

Proceed? [Yes / Adjust settings]

深度

深度	时间	功能
quick	~1 分钟	仅使用 tldr-explorer——快速了解结构
deep	~5 分钟	onboard + tldr-explorer + research-codebase + 编写文档
architecture	~3 分钟	tldr arch + 调用图 + 层级映射 + 循环依赖检测

选项

选项	说明	示例
--focus "area"	聚焦于特定区域	--focus "auth"、--focus "api"
--output handoff	为下一个 Agent 创建交接内容	--output handoff
--output doc	创建文档文件	--output doc
--entry "func"	从特定入口点开始	--entry "main"、--entry "process_request"

示例

# 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
/explore quick --focus "hooks"

工作流详情

快速深度

使用 tldr-explorer 快速了解结构。适用于：

• 初步熟悉代码库
• 快速了解结构
• 查找内容所在位置

步骤：

1. 运行 tldr tree 查看文件结构
2. 运行 tldr structure 查看代码映射
3. 如果提供了 --focus，运行 tldr search 获取针对性结果
4. 返回摘要

命令：

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

# 2. Code structure
tldr structure ${PATH:-src/} --lang python

# 3. Focused search (if --focus provided)
tldr search "${FOCUS}" ${PATH:-src/}

深入深度

全面探索并输出文档。适用于：

• 首次接触代码库
• 为重要工作做准备
• 创建参考文档

步骤：

1. 检查是否已完成 onboard（查找 .claude/cache/tldr/），如果没有则运行 onboard
2. 运行 tldr-explorer 了解结构
3. 启动 research-codebase Agent，了解代码模式
4. 将发现写入文档或交接内容

子进程：

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

# 2. Structure analysis
tldr structure src/ --lang python
tldr calls src/

# 3. Research patterns (via scout agent)
Task: research-codebase → "Document existing patterns in ${FOCUS:-codebase}"

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

架构深度

聚焦架构的分析，并检测层级。适用于：

• 了解系统边界
• 为重构做准备
• 识别耦合问题

步骤：

1. 运行 tldr arch 检测层级
2. 运行 tldr calls 生成跨文件调用图
3. 分析入口层、中间层和叶子层
4. 检测循环依赖
5. 映射架构边界

命令：

# 1. Architecture detection
tldr arch ${PATH:-src/}
# Returns: entry_layer, middle_layer, leaf_layer, circular_deps

# 2. Call graph
tldr calls ${PATH:-src/}
# Returns: edges, nodes

# 3. Impact analysis from entry point (if --entry provided)
tldr impact ${ENTRY} ${PATH:-src/} --depth 3

输出结构：

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/*]

输出格式

--output doc

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

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

# 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

--output handoff

创建：thoughts/shared/handoffs/{session}/explore-{focus}.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}

与 /build 集成

explore 技能旨在为 /build brownfield 提供输入：

# Step 1: Explore to understand
/explore architecture --output handoff

# Step 2: Build with context from exploration
/build brownfield --from-handoff thoughts/shared/handoffs/session/explore-full.yaml

实现

当用户调用 /explore <depth> [options] 时：

解析参数

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

根据深度执行

快速：

# Just tldr commands, no agents
tldr tree ${src_dir} --ext .py
tldr structure ${src_dir} --lang python
if [ -n "$focus" ]; then
    tldr search "$focus" ${src_dir}
fi

深入：

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

# 2. Structure
tldr structure src/ --lang python

# 3. Research (spawn scout agent)
# Task tool with subagent_type: "scout"
# Prompt: "Research patterns in ${focus:-codebase}"

# 4. Write output
# → doc or handoff based on --output

架构：

# 1. Arch detection
arch_output=$(tldr arch ${src_dir})

# 2. Call graph
calls_output=$(tldr calls ${src_dir})

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

# 4. Synthesize and write output

核心原则

1. 只读 - 此技能绝不会修改代码
2. 使用 scout，而非 Explore - 根据项目规则，使用 scout（Sonnet）而非 Explore（Haiku）
3. 节省令牌 - 使用 tldr 命令（相比直接读取原始内容可节省 95%）
4. 输出到共享位置 - thoughts/shared/research/ 或交接目录
5. 作为 /build 的入口 - 探索交接内容将用于棕地构建

相关技能

技能	适用场景
tldr-explorer	直接使用 tldr 命令（explore 内部使用）
tldr-code	特定分析命令（cfg、dfg、slice）
onboard	首次设置项目（deep depth 使用）
research-codebase	模式文档（deep depth 使用）
create_handoff	交接格式（使用 --output handoff 时）

故障排除

找不到 tldr：

# Check if installed
which tldr
# Install if missing
uv tool install llm-tldr
# or: pip install llm-tldr

未找到 Python 文件：

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

架构输出为空：

# May need to specify src directory
tldr arch ./  # Current directory
tldr arch src/  # Explicit src