explore-project Skill 设计思路【场景：快速上手新项目新需求】

适用场景：接手新项目、快速上手进行需求开发 依赖：Claude Code + claude-mermaid 插件 + codegraph（可选）

1. 它是什么

定位和边界

explore-project 是一个 Claude Code Skill——一份结构化的指令文档，指导 AI 自主完成「探索项目 → 分析架构 → 生成可视化文档」的全流程。

不是一个 CLI 工具，不是一个 VS Code 插件，不需要安装依赖。它是一段让 AI 知道"怎么做项目探索"的知识。

解决什么

不解决什么

• 不写代码、不做重构建议

• 不替代设计文档（它产出的是"现状分析"，不是"应该怎么改"）

• 不解决运行时问题（不跑项目、不调试）

• 不适合 monorepo 全量分析（单包粒度适用）

同类对比

要不要继续看

你应该继续看，如果你：

• 经常需要快速了解新项目的全貌

• 想给新人一个标准化的项目入门材料

• 希望在做需求前，先看清模块边界和数据流

  可以跳过，如果你：

• 只在一个项目里深耕，已经很熟悉

• 项目已有完善的架构文档且持续维护

2. 它能做什么

原生能力清单

Skill 触发后，自动完成以下产出：

Phase 1 — 全局概览（全自动）：

Phase 2 — 模块深入（指定模块后）：

自带能力

• 技术栈自动识别：读 package.json/go.mod/Cargo.toml，自动判断框架

• 前端专精：Vue 2/3、React 有额外探索逻辑（组件树、路由、Store）

• 双路探索：有 codegraph 走图查询（快且准），无索引时 fallback 到文件系统分析

• 并行执行：Phase 1 和 Phase 2 各派 3 个子代理并行工作，总耗时约 2 分钟

• Mermaid 实时预览：自动在浏览器中渲染图表

覆盖深度

项目根目录 ├── Phase 0 覆盖：package.json、入口文件、路由配置、store 目录 ├── Phase 1 覆盖：src/ 一级目录结构、模块间依赖关系、启动链路 └── Phase 2 覆盖：指定模块的所有文件、API 调用、状态流转、用户操作路径

深度取决于你选择深入的模块——Phase 2 可重复执行，逐个分析。

能"白嫖"多少

零配置即可获得：

• 完整的 Phase 1 全局概览（5 项产出）

• 在浏览器中实时预览的 Mermaid 图表

• 一份结构化的 Markdown 文档（代码块 + 图片双保险）

  需要额外投入的：

• codegraph 索引（提升准确度，但不必需）

• 指定深入模块（需要你做一次选择）

• 图表微调（AI 生成的图表可能需要手动调整布局）

3. 它怎么扩展

扩展点的形状

~/.claude/skills/explore-project/ ├── SKILL.md ← 工作流主控（改流程在这） ├── agents/ │ ├── phase1-*.md ← Phase 1 子代理 prompt（改探索策略） │ └── phase2-*.md ← Phase 2 子代理 prompt（改深入分析逻辑） └── templates/ └── output-template.md ← 输出文档模板（改最终产出格式）

每个文件就是一个扩展点——改文件内容 = 改 AI 行为。无需编译、无需部署。

Skill vs 插件

explore-project 是纯 Skill，因为它只需要 AI 已有的能力（读文件、搜索、调用 mermaid 工具）。

边界与范式

Skill 能做的：

• 规定探索步骤和顺序

• 定义输出格式和风格

• 指定用什么工具、怎么用

• 设定异常处理策略

  Skill 不能做的：

• 不能创建新工具（需要 MCP 插件）

• 不能保证确定性输出（AI 每次运行可能有差异）

• 不能跨会话记忆（每次运行独立）

自己要写什么

想加新的分析维度？比如"安全扫描"或"性能热点"：

1. 在agents/下新建一个 prompt 文件（如phase1-security.md）

2. 在SKILL.md的 Phase 1 步骤中加入新的子代理派发

3. 在templates/output-template.md中加入对应的章节

   想适配新技术栈？比如 Flutter 或 Rust：

4. 在SKILL.md的 Phase 0 中加入新的技术栈识别规则

5. 在各 agent prompt 中加入该技术栈的专精探索逻辑

   想改输出风格？比如英文输出或不同的配色：

6. 改 agent prompt 中的"风格规范"部分

7. 改 template 中的文案

4. 它内部怎么跑

关键运行时

Claude Code 会话 │ ├── 主代理（你对话的这个） │ ├── Phase 0：直接执行预扫描 │ ├── Phase 1：派发 3 个 Explore 子代理（并行） │ ├── 交互：等你选模块 │ ├── Phase 2：派发 3 个 Explore 子代理（并行） │ └── Phase 3：汇总 + 调用 mermaid 工具 + 保存文件 │ ├── 子代理 A/B/C（Phase 1，并行） │ └── 独立上下文，用 Glob/Grep/Read/codegraph 探索 │ ├── 子代理 D/E/F（Phase 2，并行） │ └── 独立上下文，用同一套工具深入指定模块 │ └── Mermaid MCP Server（独立进程） └── 接收 mermaid 代码 → 渲染 SVG → 浏览器热重载

进程与状态

数据流：

ExplorationContext（Phase 0 产出） → 序列化为具体值传入子代理 prompt → 子代理返回 JSON（约定格式） → 主代理解析 JSON、组装 Markdown、调用 mermaid 渲染 → 写入文件系统

接入面

触发方式（任选）：

"探索一下这个项目" "帮我了解这个项目的架构" /explore-project /explore-project D:\Projects\ent-micro

前置条件：

• Claude Code 已安装（CLI / Desktop / IDE 均可）

• claude-mermaid 插件已安装（用于图表渲染）

• codegraph 索引（可选，有则更快更准）

  输出位置：

{project}/docs/architecture/ ├── README.md # 主文档 ├── images/*.svg # 图表文件 └── generated-at.txt # 生成时间戳

能不能上生产

建议用法：

• 新人入职时跑一次，生成基础文档

• 需求评审前，对涉及模块跑 Phase 2

• 文档定期重新生成（commit hash 判断是否过时）

  不建议：

• 把 AI 生成的图表当作唯一的架构文档（应作为起点，人工补充）

• 在 CI 中自动运行（非确定性输出不适合自动化管道）

附：快速上手

# 1. 确认 skill 已安装 ls ~/.claude/skills/explore-project/SKILL.md ​ # 2. 进入目标项目 cd /path/to/your-project ​ # 3. 在 Claude Code 中触发 # 输入: /explore-project # 或者: "探索一下这个项目" ​ # 4. 等待 Phase 1 完成，选择要深入的模块 ​ # 5. 产出在 docs/architecture/README.md

附：实测效果

已在以下项目验证：

最后更新: 2026-06-08作者: 前端团队