name: explore description: 用于内部代码库在不同深度（快速/深度/架构）探索的元技能 allowed-tools: [Bash, Task, Read, Glob, Grep, Write] keywords: [探索, 代码库, 架构, 理解, 分析, 层, 调用图, 棕地]

Explore - 内部代码库探索

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

用法

/explore <depth> [options]

问题流（无参数）

如果用户只输入/explore没有或部分参数，通过此问题流引导他们。对每个阶段使用AskUserQuestion。

阶段0：工作流选择

question: "您希望如何探索？"
header: "探索"
options:
  - label: "帮我选择（推荐）"
    description: "我会通过提问来选择正确的探索深度"
  - label: "快速 - 快速概览"
    description: "链：tldr tree → tldr structure（约1分钟）"
  - label: "深度 - 全面分析"
    description: "链：onboard → tldr → research → document（约5分钟）"
  - label: "架构 - 层和依赖"
    description: "链：tldr arch → call graph → layer mapping（约3分钟）"

映射：

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

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

question: "我想了解您希望探索的深度。您的意思是..."
header: "澄清"
options:
  - label: "帮我选择"
    description: "不确定 - 引导我通过问题"
  - label: "快速 - 快速概览"
    description: "只想看看这里有什么"
  - label: "深度 - 全面分析"
    description: "需要彻底理解"
  - label: "都不是 - 让我用不同方式解释"
    description: "我会描述我需要什么"

阶段1：探索目标

question: "您想理解什么？"
header: "目标"
options:
  - label: "在代码库中定位"
    description: "快速概览结构"
  - label: "理解某个功能如何工作"
    description: "深入特定领域"
  - label: "映射架构"
    description: "层、依赖、模式"
  - label: "找到某个代码或功能的位置"
    description: "定位特定代码/功能"

映射：

“在代码库中定位” → quick深度
“理解某个功能如何工作” → deep深度
“映射架构” → architecture深度
“找到某个代码或功能的位置” → quick带–focus

阶段2：范围

question: "我应该关注哪个区域？"
header: "焦点"
options:
  - label: "整个代码库"
    description: "探索一切"
  - label: "特定目录或模块"
    description: "我会指定路径"
  - label: "特定概念/功能"
    description: "例如，'认证'、'API路由'"

如果"特定目录"或"特定概念" → 询问路径/关键词的后续问题。

阶段3：输出格式

question: "我应该生成什么？"
header: "输出"
options:
  - label: "只需告诉我您发现了什么"
    description: "聊天中的交互式摘要"
  - label: "创建文档文件"
    description: "写入thoughts/shared/docs/"
  - label: "为实施创建交接"
    description: "为编码代理准备上下文"

映射：

“文档文件” → --output doc
“为实施创建交接” → --output handoff

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

如果选择architecture深度：

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

执行前摘要

基于您的答案，我将运行：

**深度：** deep
**焦点：** "authentication"
**输出：** handoff
**路径：** src/

继续？[是 / 调整设置]

深度

深度	时间	作用
`quick`	~1分钟	仅tldr-explorer - 快速结构概览
`deep`	~5分钟	onboard + tldr-explorer + research-codebase + 写文档
`architecture`	~3分钟	tldr arch + 调用图 + 层映射 + 循环依赖检测

选项

选项	描述	示例
`--focus "area"`	关注特定区域	`--focus "auth"`, `--focus "api"`
`--output handoff`	为下一个代理创建交接	`--output handoff`
`--output doc`	创建文档文件	`--output doc`
`--entry "func"`	从特定入口点开始	`--entry "main"`, `--entry "process_request"`

示例

# 快速结构概览
/explore quick

# 深度探索，关注认证
/explore deep --focus "auth" --output doc

# 架构分析，从特定入口开始
/explore architecture --entry "cli" --output handoff

# 快速焦点探索
/explore quick --focus "hooks"

工作流详情

快速深度

使用tldr-explorer快速结构概览。最适合：

初始定位
关于结构的快速问题
查找事物位置

步骤：

运行tldr tree获取文件结构
运行tldr structure获取代码映射
如果提供--focus，运行tldr search获取目标结果
返回摘要

命令：

# 1. 文件树
tldr tree ${PATH:-src/} --ext .py

# 2. 代码结构
tldr structure ${PATH:-src/} --lang python

# 3. 焦点搜索（如果提供--focus）
tldr search "${FOCUS}" ${PATH:-src/}

深度深度

全面探索，带文档输出。最适合：

首次进入代码库
准备主要工作
创建参考文档

步骤：

检查是否已onboard（查找.claude/cache/tldr/），如果没有，运行onboard
运行tldr-explorer获取结构
启动research-codebase代理分析模式
将发现写入文档或交接

子过程：

# 1. Onboard检查
if [ ! -f .claude/cache/tldr/arch.json ]; then
    # 启动onboard代理
fi

# 2. 结构分析
tldr structure src/ --lang python
tldr calls src/

# 3. 研究模式（通过scout代理）
Task: research-codebase → "在${FOCUS:-代码库}中记录现有模式"

# 4. 写输出
→ thoughts/shared/research/YYYY-MM-DD-explore-{focus}.md
→ 或 thoughts/shared/handoffs/{session}/explore-{focus}.yaml

架构深度

架构焦点分析，带层检测。最适合：

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

步骤：

运行tldr arch检测层
运行tldr calls获取跨文件调用图
分析入口/中间/叶层
检测循环依赖
映射架构边界

命令：

# 1. 架构检测
tldr arch ${PATH:-src/}
# 返回：entry_layer, middle_layer, leaf_layer, circular_deps

# 2. 调用图
tldr calls ${PATH:-src/}
# 返回：edges, nodes

# 3. 从入口点影响分析（如果提供--entry）
tldr impact ${ENTRY} ${PATH:-src/} --depth 3

输出结构：

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 doc

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

---
date: {ISO时间戳}
type: exploration
depth: {quick|deep|architecture}
focus: {焦点区域或"full"}
commit: {git哈希}
---

# 代码库探索：{focus}

## 摘要
{高层次发现}

## 结构
{文件树 / 代码映射}

## 架构
{层分析 - 用于架构深度}

## 关键组件
{重要文件及其角色}

## 发现的模式
{现有模式 - 用于深度深度}

## 参考
- `path/to/file.py:line` - 描述

–output handoff

创建：thoughts/shared/handoffs/{session}/explore-{focus}.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:
  - {关键发现带file:line}

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

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

与/build集成

探索技能设计用于馈入/build brownfield：

# 步骤1：探索以理解
/explore architecture --output handoff

# 步骤2：使用探索上下文构建
/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")

基于深度执行

快速：

# 仅tldr命令，无代理
tldr tree ${src_dir} --ext .py
tldr structure ${src_dir} --lang python
if [ -n "$focus" ]; then
    tldr search "$focus" ${src_dir}
fi

深度：

# 1. 检查/运行onboard
if [ ! -f .claude/cache/tldr/meta.json ]; then
    # 通过Task工具启动onboard代理
fi

# 2. 结构
tldr structure src/ --lang python

# 3. 研究（启动scout代理）
# Task工具带subagent_type: "scout"
# 提示："在${focus:-代码库}中研究模式"

# 4. 写输出
# → 基于--output的doc或handoff

架构：

# 1. 架构检测
arch_output=$(tldr arch ${src_dir})

# 2. 调用图
calls_output=$(tldr calls ${src_dir})

# 3. 从入口影响分析（如果提供）
if [ -n "$entry" ]; then
    impact_output=$(tldr impact $entry ${src_dir} --depth 3)
fi

# 4. 合成并写输出

关键原则

只读 - 此技能从不修改代码
使用scout，而非Explore - 按项目规则，scout（Sonnet）优于Explore（Haiku）
令牌高效 - 使用tldr命令（比原始读取节省95%令牌）
输出到共享位置 - thoughts/shared/research/或交接目录
进入/build的入口点 - 探索交接馈入棕地构建

故障排除

tldr未找到：

# 检查是否安装
which tldr
# 如果缺失，安装
uv tool install llm-tldr
# 或：pip install llm-tldr

未找到Python文件：

# 检查语言，调整--lang
tldr structure src/ --lang typescript  # 或go, rust

空架构输出：

# 可能需要指定src目录
tldr arch ./  # 当前目录
tldr arch src/  # 显式src

技能	何时使用
tldr-explorer	直接tldr命令（由探索内部使用）
tldr-code	特定分析命令（cfg, dfg, slice）
onboard	首次项目设置（由深度深度使用）
research-codebase	模式文档（由深度深度使用）
create_handoff	交接格式（由–output handoff使用）

代码库探索元技能Skill explore

name: explore description: 用于内部代码库在不同深度（快速/深度/架构）探索的元技能 allowed-tools: [Bash, Task, Read, Glob, Grep, Write] keywords: [探索, 代码库, 架构, 理解, 分析, 层, 调用图, 棕地]

Explore - 内部代码库探索

用法

问题流（无参数）

阶段0：工作流选择

阶段1：探索目标

阶段2：范围

阶段3：输出格式

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

执行前摘要

深度

选项

示例

工作流详情

快速深度

深度深度

架构深度

输出格式

–output doc

–output handoff

与/build集成

实现

解析参数

基于深度执行

关键原则

相关技能

故障排除