271 lines
9.5 KiB
Markdown
271 lines
9.5 KiB
Markdown
# Explore / Essence / Follow 最新设计总结
|
||
|
||
**版本基线**：v0.5.0
|
||
**对应 skill 本体**：`skill-workbench/generated-skills/skills/`
|
||
**历史来源**：
|
||
|
||
- `skill-workbench/history/changelog/2026-04-30-skills-v0.5.0-consolidation.md`
|
||
- `skill-workbench/history/docs/superpowers/specs/`
|
||
- `skill-workbench/history/docs/superpowers/changelog/`
|
||
|
||
## 一句话定位
|
||
|
||
`explore`、`essence`、`follow` 是一组学习型 skill family：
|
||
|
||
- `explore` 负责项目级理解。
|
||
- `essence` 负责深挖 1-2 个最值得迁移的核心设计。
|
||
- `follow` 负责基于已有报告做交互式跟学。
|
||
|
||
三者不是“深浅不同的同一个技能”，而是学习链路中的三个不同角色。
|
||
|
||
## 设计背景
|
||
|
||
早期 superpowers 设计试图覆盖完整学习过程，但在实践中出现了几个问题：
|
||
|
||
1. 阶段过多，`explore` 同时承担项目理解、深度分析、教学输出，边界不清。
|
||
2. `/essence` 曾被误设计成 `/explore` 的轻量版，导致无法稳定聚焦“值得偷走的设计”。
|
||
3. `/follow` 曾倾向重新扫描项目，削弱了它“基于已有报告教学”的定位。
|
||
4. HTML、Deep Fission、Verify 等输出阶段让 skill 变重，增加上下文和执行成本。
|
||
5. 历史 docs 中存在过时 proposal、plan 和已删除技能引用，需要收敛为当前真实实现。
|
||
|
||
v0.5.0 的核心改造是：**拆清职责，减少阶段，只保留能稳定触发、稳定产出的学习动作。**
|
||
|
||
## 三技能职责边界
|
||
|
||
| Skill | 核心问题 | 输入 | 输出 | 不做什么 |
|
||
| --- | --- | --- | --- | --- |
|
||
| `explore` | 这个项目是什么，为什么值得学，从哪里开始？ | 新项目、代码仓库、文档仓库、skill 仓库 | 项目学习报告、结构图、2-3 个核心设计概览 | 不做深度模式提取，不做互动教学 |
|
||
| `essence` | 这个项目最值得偷走的设计是什么？ | 明确设计目标，或需要自动找 standout design | 设计模式卡、证据链、迁移示例 | 不做全项目概览，不做普通代码讲解 |
|
||
| `follow` | 如何基于已有报告一步步学会？ | 已有 `/explore` 或 `/essence` 报告 | Runnable 或 Reader 跟学会话 | 不重新扫描项目，不替用户执行代码 |
|
||
|
||
## 推荐学习链路
|
||
|
||
```text
|
||
第一次接触项目
|
||
↓
|
||
/explore
|
||
产出项目定位、结构、主流程、核心设计候选
|
||
↓
|
||
/essence
|
||
选择一个核心设计做深挖，提炼可迁移模式
|
||
↓
|
||
/follow
|
||
基于 explore/essence 报告做交互式学习
|
||
```
|
||
|
||
也可以单独使用：
|
||
|
||
- 只想快速建立全局认知：只用 `explore`。
|
||
- 已经知道要研究哪个设计：直接用 `essence` 的 User-directed 模式。
|
||
- 已经有报告，想按教程学：直接用 `follow`。
|
||
|
||
## Explore 最新设计
|
||
|
||
### 定位
|
||
|
||
`explore` 是项目地图绘制器。它回答：
|
||
|
||
- 这个项目是什么？
|
||
- 为什么值得研究？
|
||
- 顶层结构如何组织？
|
||
- 学习入口在哪里？
|
||
- 有哪 2-3 个核心设计值得后续深挖？
|
||
|
||
### 当前阶段
|
||
|
||
v0.5.0 将原来的 5 Phase 收敛为 4 Phase：
|
||
|
||
1. **Positioning & Structure**
|
||
- 合并早期 Positioning 和 Structure。
|
||
- 输出项目定位、学习价值、顶层结构、入口区域。
|
||
2. **Flow**
|
||
- 仅代码仓库执行。
|
||
- 追踪主运行流或请求流，聚焦 golden path。
|
||
3. **Start Path**
|
||
- 仅代码仓库且可运行/可观察时执行。
|
||
- 给出最小启动路径、第一条命令或第一处观察点。
|
||
4. **Core Designs**
|
||
- 总结 2-3 个核心设计或核心想法。
|
||
- 保持概览深度，为 `essence` 提供候选对象。
|
||
|
||
### 类型分流
|
||
|
||
`explore` 必须先识别项目类型：
|
||
|
||
- **Code repository**：执行完整 4 Phase。
|
||
- **Skill / docs / knowledge repository**：跳过 Flow 和 Start Path，改用结构图、概念图或 workflow 图。
|
||
- **Template / scaffold repository**：Flow 和 Start Path 可以保持轻量。
|
||
|
||
### 关键约束
|
||
|
||
- 不做 `/essence` 级别深挖。
|
||
- 不做 `/follow` 式互动教学。
|
||
- 不保留 Verify、Deep Fission、HTML Output 等已退休阶段。
|
||
- 最终必须至少包含一个图：代码仓库用架构/流程图，非代码仓库用结构/想法/workflow 图。
|
||
|
||
## Essence 最新设计
|
||
|
||
### 定位
|
||
|
||
`essence` 是“宝石检查器”。它不是 `/explore` 的轻量版，而是专门回答：
|
||
|
||
> 这个项目里哪 1-2 个设计最值得迁移到我自己的工程里？
|
||
|
||
### 模式
|
||
|
||
| Mode | 触发场景 | 行为 |
|
||
| --- | --- | --- |
|
||
| User-directed | 用户已有目标，或来自 `/explore` 的核心设计候选 | 直接深挖用户指定设计 |
|
||
| Auto-detect | 独立启动，用户希望 AI 自动找亮点 | 扫 README、docs、结构和信号，提出 1-2 个候选 |
|
||
| Lens-guided | 用户指定 mechanical / intentional / evolution 视角 | 按透镜选择证据来源和输出框架 |
|
||
|
||
### 透镜
|
||
|
||
- **Mechanical**：它如何工作？读代码、接口、调用链。
|
||
- **Intentional**：为什么这样设计？读设计文档、RFC、PR、权衡。
|
||
- **Evolution**：它如何演化到这里？读 changelog、git 历史、迁移记录。
|
||
|
||
### 当前阶段
|
||
|
||
1. **Locate**
|
||
- 找到 1-2 个候选设计方向。
|
||
- 自动模式要求 standout design 至少满足 2 个信号。
|
||
2. **Deep Dive**
|
||
- 最多读 10 个核心文件。
|
||
- 追踪调用链或证据链，避免扩散成全项目分析。
|
||
3. **Extract Pattern**
|
||
- 提炼问题、模式、替代方案、权衡和证据。
|
||
4. **Migrate**
|
||
- 给出可迁移方式和最小示例。
|
||
- 示例必须足够小，避免复制生产代码。
|
||
5. **Self-review**
|
||
- 检查是否有证据、是否解释了权衡、是否能迁移。
|
||
|
||
### 关键约束
|
||
|
||
- “代码干净”不是 essence 信号。
|
||
- 如果没有 standout design，应明确建议改用 `explore`。
|
||
- 如果设计边界超过 10 个文件且无法收敛，应改用 `explore`。
|
||
- HTML Card 只是显式请求时的可选输出，不是默认阶段。
|
||
|
||
## Follow 最新设计
|
||
|
||
### 定位
|
||
|
||
`follow` 是跟学教练。它不做新分析，只基于已有 `/explore` 或 `/essence` 报告，带用户一步步学习。
|
||
|
||
### 前置条件
|
||
|
||
必须存在以下之一：
|
||
|
||
- `/explore` 报告
|
||
- `/essence` 报告
|
||
|
||
如果没有，必须拒绝并引导用户先运行 `explore` 或 `essence`。
|
||
|
||
### 模式
|
||
|
||
| Mode | 来源 | 行为 |
|
||
| --- | --- | --- |
|
||
| Runnable | `/explore` 报告确认是可运行代码仓库 | 从环境、启动、观察和安全修改开始 |
|
||
| Reader | 非代码仓库，或来自 `/essence`，或用户专注设计学习 | 围绕核心设计做分层阅读和推理练习 |
|
||
|
||
### 当前流程
|
||
|
||
**Runnable**：
|
||
|
||
1. 确认环境和依赖。
|
||
2. 让用户运行项目。
|
||
3. 让用户做一个安全小改动。
|
||
4. 一起走主流程。
|
||
5. 给一个小练习。
|
||
6. 回顾学习结果。
|
||
|
||
**Reader**：
|
||
|
||
1. 围绕设计或架构想法设定学习目标。
|
||
2. 按“问题 → 方法 → 实现 → 权衡”讲解。
|
||
3. 通过问题检查理解。
|
||
4. 用图或结构总结连接文件和设计。
|
||
5. 给一个迁移/推理练习。
|
||
6. 回顾学习结果。
|
||
|
||
### 关键约束
|
||
|
||
- 不重新扫描项目。
|
||
- 不执行命令或替用户写代码。
|
||
- 不新增第三种模式。
|
||
- 不只说“去读这个文件”，必须说明这个文件体现什么设计、为什么重要、看什么。
|
||
|
||
## v0.5.0 最重要的收敛
|
||
|
||
### 1. Explore 从 5 Phase 收敛到 4 Phase
|
||
|
||
早期 Positioning 和 Structure 拆开导致报告啰嗦。v0.5.0 合并为 `Positioning & Structure`，让 `explore` 更像项目地图，而不是流水账。
|
||
|
||
### 2. Essence 补齐上下文感知
|
||
|
||
`essence` 会先判断是否已有 `/explore` 结果：
|
||
|
||
- 有结果：默认 User-directed，让用户从候选设计中选择。
|
||
- 无结果：默认 Auto-detect，自行寻找 standout design。
|
||
|
||
这避免了 `essence` 在已有上下文时重复扫描。
|
||
|
||
### 3. Follow 不再重扫
|
||
|
||
`follow` 的核心价值是“基于报告教学”。如果它重新扫描项目，就会变成另一个 explore。v0.5.0 明确它必须读取前置报告，按报告决定 Runnable 或 Reader。
|
||
|
||
### 4. Reader 模式从文件级提升到设计级
|
||
|
||
早期 Reader 容易变成“带你读一个文件”。v0.5.0 改成围绕设计概念学习：问题、方法、实现、权衡。
|
||
|
||
### 5. 删除过期阶段和死引用
|
||
|
||
已退休内容包括：
|
||
|
||
- Deep Fission
|
||
- Verify 阶段
|
||
- 默认 HTML Output
|
||
- 旧 `/map`、`/fission` 等已不存在技能引用
|
||
|
||
## 当前产物边界
|
||
|
||
```text
|
||
skill-workbench/
|
||
├── generated-skills/
|
||
│ └── skills/
|
||
│ ├── explore/
|
||
│ ├── essence/
|
||
│ └── follow/
|
||
├── docs/
|
||
│ └── explore-essence-follow/
|
||
│ └── latest-design.md
|
||
└── history/
|
||
├── changelog/
|
||
└── docs/superpowers/
|
||
```
|
||
|
||
- `generated-skills/skills/` 只放可安装 skill 本体。
|
||
- `docs/explore-essence-follow/latest-design.md` 保存最新设计总结。
|
||
- `history/` 保留旧设计、changelog、handoff 和过时 specs，作为考古来源。
|
||
|
||
## 何时修改哪一层
|
||
|
||
| 变更类型 | 修改位置 |
|
||
| --- | --- |
|
||
| skill 行为变更 | `skill-workbench/generated-skills/skills/{skill}/SKILL.md` |
|
||
| 最新设计说明变更 | `skill-workbench/docs/explore-essence-follow/latest-design.md` |
|
||
| 历史记录 | `skill-workbench/history/`，不要覆盖 |
|
||
| 验证材料 | `skill-workbench/validation/` |
|
||
|
||
## 当前结论
|
||
|
||
这组三技能已经形成清晰分工：
|
||
|
||
- `explore` 是入口：建立项目级地图。
|
||
- `essence` 是深挖：提炼可迁移设计。
|
||
- `follow` 是教学：基于报告引导用户学会。
|
||
|
||
后续改进应避免把三者重新合并。最重要的维护原则是：**保持边界比增加功能更重要。**
|