explore

代码库探索

与宿主无关的工作流。按技能名称（explore）调用。Claude Code 斜杠路由、YAML 钩子加载器和 .claude/chain 请参阅 references/claude-code.md。

通过 3-5 个并行 Agent，从多个角度探索代码库。

🎯 快速开始

explore authentication

Opus 5.5：探索 Agent 使用原生自适应思考，以便在大型代码库中更深入地识别模式。

---

STEP -0.5：按工作量扩展 Agent（CC 2.1.120+）

在做出任何其他决定之前，读取 $CLAUDE_EFFORT，据此调整探索深度。

# CC 2.1.120+ env var; explicit --effort= overrides
EFFORT = os.environ.get("CLAUDE_EFFORT")
for token in "$ARGUMENTS".split():
    if token.startswith("--effort="):
        EFFORT = token.split("=", 1)[1]
EFFORT = EFFORT or "high"  # default

工作量	Agent 数量	阶段	时间
low	1（仅结构）	1、2、8	~1 分钟
medium	2（结构 + 数据流）	1、2、3（子集）、8	~3 分钟
high（默认）	4（完整并行团队）	1–8	~6 分钟
xhigh（Opus 5）	5（在健康度评分中增加不确定性检查）	1–8 + 注意事项	~8 分钟

**覆盖规则：**如果用户显式传入 --effort=high，而 $CLAUDE_EFFORT 为 low，则以该标志为准。只有当 doctor 在其 XHIGH_UNSUPPORTED_PREFIXES 表中列出的模型配置了 xhigh 时，才会发出警告。

---

STEP 0：使用 AskUserQuestion 确认用户意图

创建任务之前，先确认用户想探索什么：

AskUserQuestion(
  questions=[{
    "question": "What aspect do you want to explore?",
    "header": "Focus",
    "options": [
      {"label": "Full exploration (Recommended)", "description": "Code structure + data flow + architecture + health assessment"},
      {"label": "Quick scan", "description": "Find relevant files + structure, skip deep analysis"},
      {"label": "Data flow", "description": "Trace how data moves through the system"},
      {"label": "Architecture patterns", "description": "Identify design patterns and integrations"}
    ],
    "multiSelect": false
  }]
)

根据回答调整工作流：

• 全面探索：执行所有阶段，启动所有并行 Agent
• 快速扫描：仅检查文件和结构（阶段 1–2），跳过健康度、依赖项和产品视角，不启动深度探索 Agent
• 数据流：让阶段 3 的 Agent 聚焦于追踪数据
• 架构模式：聚焦于 backend-system-architect Agent

---

STEP 0b：选择编排模式

MCP 探测

# memory is alwaysLoad in .mcp.json (CC 2.1.121+, #1541) — probe below kept as fallback for older CC:
ToolSearch(query="select:mcp__memory__search_nodes")
Write(".claude/chain/capabilities.json", { memory, timestamp })

if capabilities.memory:
  mcp__memory__search_nodes({ query: "architecture decisions for {path}" })
  # Enrich exploration with past decisions

探索结果交接

探索完成后，为后续技能写入结果：

Write(".claude/chain/exploration.json", JSON.stringify({
  "phase": "explore", "skill": "explore",
  "timestamp": now(), "status": "completed",
  "outputs": {
    "architecture_map": { ... },
    "patterns_found": ["repository", "service-layer"],
    "complexity_hotspots": ["src/auth/", "src/payments/"]
  }
}))

---

选择 Agent Teams（网状）或 Agent tool（星形）：

1. Agent Teams 模式（自 CC 2.1.33 起正式发布）→ 4 个及以上 Agent 时推荐
2. Agent tool 模式 → 适用于快速探索或单一重点探索
3. ORCHESTKIT_FORCE_TASK_TOOL=1 → Agent tool（覆盖设置）

方面	Agent Tool	Agent Teams
共享发现	所有探索完成后由负责人综合整理	探索者边探索边共享发现
交叉引用	负责人梳理关联	数据流探索者向架构探索者发出提醒
成本	~150K tokens	~400K tokens
适用场景	快速/聚焦搜索	深入探索整个代码库

**回退：**如果 Agent Teams 遇到问题，则剩余探索改用 Agent tool。

**模型指定：**在 Agent tool 模式下，为内置的 Explore 调用设置 model="haiku"。此试验仅覆盖该调用路径。Agent Teams 调用保留现有模型选择。分叉调用使用父模型和共享上下文。

---

🚨 任务管理（强制）

在执行任何其他操作之前，创建任务以显示进度：

# 1. Create main task IMMEDIATELY
TaskCreate(subject="Explore: {topic}", description="Deep codebase exploration for {topic}", activeForm="Exploring {topic}")

# 2. Create subtasks for each phase
TaskCreate(subject="Initial file search", activeForm="Searching files")                # id=2
TaskCreate(subject="Check knowledge graph", activeForm="Checking memory")              # id=3
TaskCreate(subject="Launch exploration agents", activeForm="Dispatching explorers")     # id=4
TaskCreate(subject="Assess code health (0-10)", activeForm="Assessing code health")    # id=5
TaskCreate(subject="Map dependency hotspots", activeForm="Mapping dependencies")       # id=6
TaskCreate(subject="Add product perspective", activeForm="Adding product context")     # id=7
TaskCreate(subject="Generate exploration report", activeForm="Generating report")      # id=8

# 3. Set dependencies for sequential phases
TaskUpdate(taskId="3", addBlockedBy=["2"])  # Memory check needs file search first
TaskUpdate(taskId="4", addBlockedBy=["3"])  # Agents need memory context
TaskUpdate(taskId="5", addBlockedBy=["4"])  # Health needs exploration done
TaskUpdate(taskId="6", addBlockedBy=["4"])  # Hotspots need exploration done
TaskUpdate(taskId="7", addBlockedBy=["4"])  # Product needs exploration done
TaskUpdate(taskId="8", addBlockedBy=["5", "6", "7"])  # Report needs all analysis done

# 4. Update status as you progress
TaskUpdate(taskId="2", status="in_progress")  # When starting
TaskUpdate(taskId="2", status="completed")    # When done — repeat for each subtask

---

🔄 工作流概览

阶段	活动	输出
1. 初步搜索	使用 Grep、Glob 查找匹配项	文件位置
2. 记忆检查	搜索知识图谱	先前上下文
3. 深入探索	4 个并行探索者	多角度分析
4. AI 系统（如适用）	LangGraph、提示词、RAG	AI 专项发现
5. 代码健康度	为代码打 0–10 分	质量评分
6. 依赖热点	识别耦合关系	热点可视化
7. 产品视角	业务背景	易发现性建议
8. 报告生成	汇总发现	可执行报告

渐进式输出（CC 2.1.76）

每个阶段完成后，立即逐步输出发现结果——不要等到报告生成时才一次性输出：

阶段结束后	向用户展示
1. 初始搜索	文件匹配项、grep 结果
2. 记忆检查	先前的决策和相关上下文
3. 深入探索	每个探索 Agent 返回的发现结果
5. 代码健康度	健康度评分及各维度明细

对于第 3 阶段的并行 Agent，要在每个 Agent 返回时立即输出其发现结果——不要等所有 4 个探索 Agent 都完成。某个 Agent 的早期发现可能已经回答了用户的问题，因此可以提前终止其余任务。

---

阶段 1：初始搜索

先加载仓库地图。 分支技能不会运行 frontmatter 钩子（#4683），因此请手动运行加载器，并牢记其 additionalContext：

echo '{"tool_name":"Bash","tool_input":{}}' | node "${CLAUDE_PLUGIN_ROOT}/hooks/bin/run-hook.mjs" skill/repo-structure-indexer

# PARALLEL - Quick searches
Grep(pattern="$ARGUMENTS[0]", output_mode="files_with_matches")
Glob(pattern="**/*$ARGUMENTS[0]*")

阶段 2：记忆检查

mcp__memory__search_nodes(query="$ARGUMENTS[0]")
mcp__memory__search_nodes(query="architecture")

阶段 3：并行深入探索（4 个 Agent）

加载 Read("rules/exploration-agents.md") 以获取 Agent 工具模式提示词。

加载 Read("rules/agent-teams-mode.md") 以获取 Agent Teams 替代方案。

阶段 4：AI 系统探索（如适用）

对于 AI/ML 主题，增加以下内容的探索：LangGraph 工作流、提示词模板、RAG 管道、缓存策略。

阶段 5：代码健康度评估

加载 Read("rules/code-health-assessment.md") 以获取 Agent 提示词。加载 Read("references/code-health-rubric.md") 以获取评分标准。

阶段 6：依赖热点图

加载 Read("rules/dependency-hotspot-analysis.md") 以获取 Agent 提示词。加载 Read("references/dependency-analysis.md") 以获取指标。

阶段 7：产品视角

加载 Read("rules/product-perspective.md") 以获取 Agent 提示词。加载 Read("references/findability-patterns.md") 以获取最佳实践。

阶段 8：生成报告

加载 Read("references/exploration-report-template.md")。

阶段 8b：输出仪表板规范（json-render）

从 $ARGUMENTS 中解析 --render=。默认值为 both。

模式	行为
markdown	当前行为——仅输出 Markdown 报告。不输出规范。
json-render	仅输出 .claude/chain/explore-dashboard.json。跳过 Markdown 报告。
both	输出规范和 Markdown。默认模式——为用户提供报告，并为后续技能提供结构化交接内容。

输出规范时：

1. 加载格式和目录：Read("references/dashboard-spec.md")。示例参考：references/dashboard-example.json。
2. 仅使用目录中的组件类型构建规范对象：Card、StatGrid、DataTable、StatusBadge、BarMeter、Heatmap、Markdown。
3. 使用紧凑 JSON（不缩进）写入 .claude/chain/explore-dashboard.json——以降低下游使用方的 token 成本。
4. 声明成功前先进行验证：

node "${CLAUDE_SKILL_DIR}/scripts/render-spec.mjs" .claude/chain/explore-dashboard.json --check

如果验证失败（退出码 ≠ 0），不要输出规范——改为仅输出 Markdown，并向用户说明错误。切勿写入不完整或无效的规范。

5. 对于 --render=both，从规范渲染 Markdown 视图，以保持一致性：

node "${CLAUDE_SKILL_DIR}/scripts/render-spec.mjs" .claude/chain/explore-dashboard.json

将输出传入面向用户的 Markdown 报告（或原样使用）。这样可以确保 JSON 规范和 Markdown 报告保持同步——以规范为唯一事实来源。

**为何重要：**下游技能（fix-issue、implement、create-pr）会直接解析 .claude/chain/explore-dashboard.json，而不是重新读取 3000 token 的 Markdown。实测：相同内容的规范约为 580 token。向后兼容：在 both 模式下，依赖 Markdown 的旧链式工作流仍可正常运行。

阶段 6.5 — 笔记本摘要（信号触发，可选）

会话综合结果生成后，可选择调用 scripts/post_explore_summary.py <session-dir>，自动生成由笔记本支持的探索摘要。遇到任何非正常情况都会自动跳过，因此绝不会中断运行：

python3 ${CLAUDE_SKILL_DIR}/scripts/post_explore_summary.py "$CLAUDE_JOB_DIR"

自动跳过条件（均以 0 退出，均记录 WARN 日志）：

跳过原因	触发条件
signal absent	len(dirs_scanned) < 3（或 explore-output.json 中缺少该字段）
yg-mcp-core not importable	未安装 yg-mcp-core>=0.3.0（orchestkit 是公开的；yg-mcp-core 位于私有的 pypi.yonyon.ai，仅 HQ 可用）
hq-content MCP unreachable	MCP 服务宕机，或 .mcp.json 未定义 hq-content

会话目录必须包含 explore-output.json（含 dirs_scanned: list[str]、可选的 synthesis: str、必需的 notebook_id: str）。<session-dir>/explore-summary.json 中的交接 JSON 会记录 status（fired / skipped），成功时还会记录 summary_path。

此功能仿照 PR #1889 中 brainstorm 的综合后播客模式。解决 orchestkit#1893。

长时间探索的注意事项

读取超大内容（CC 2.1.144+）： 当读取整个文件超出令牌限制时，Read 会返回截断后的第一页 [PARTIAL view]（而非硬错误）。遍历大型文件时，请识别此提示，并使用显式的 offset/limit 重新读取，以分页查看其余内容——切勿将部分内容视为完整文件。

上下文填满时（CC 2.1.141+）： 使用回退菜单中的“Summarize up to here”，压缩较早的轮次并保留近期上下文，而不是重新开始。响应式压缩（CC 2.1.142+）现在会根据实际溢出量确定首次摘要的大小，因此在一轮中途再次压缩的情况很少见。

常见探索查询

• “身份验证是如何工作的？”
• “API 端点定义在哪里？”
• “查找 EventBroadcaster 的所有用法”
• “内容分析的工作流是什么？”

使用 /goal 无人值守运行

使用 /goal（CC 2.1.139+）设置完成条件，此技能便会跨多个轮次持续运行，直到满足条件。支持交互模式、-p 和 Remote Control。叠加面板会实时显示已用时间、轮次数和令牌数。

此技能的完成条件示例：

/goal until report.has_architecture_diagram AND patterns.detected_count >= 5, or stop after 10 turns

满足以下条件时停止：生成代码库架构图，并对至少 5 种设计模式进行分类。兼容 claude.ai Remote Control 运行。

质量标准

满足以下所有条件才算完成：

• 每项架构或数据流论述都引用具体证据（文件:行号或文件路径），而非仅作文字断言
• 代码健康度以 0-10 分报告，并按维度细分，而非只给出单一分数
• 指出依赖热点和耦合情况，并列出造成这些问题的文件
• 报告包含所探索范围的架构或结构可视化
• 如果生成了 json-render 规范，必须通过 render-spec.mjs --check；失败时退回仅使用 Markdown，且绝不写入不完整的规范

📜 相关技能

• ork:implement：探索后实施

---

版本： 2.6.0（2026 年 4 月）— $CLAUDE_EFFORT 环境变量可调整 Agent 数量（CC 2.1.120，#1540）