osiman/git-learn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
git-learn/skill-workbench/docs/explore-essence-follow/latest-design.md
T

9.5 KiB
Raw Permalink Blame History

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 跟学会话 不重新扫描项目，不替用户执行代码

推荐学习链路

第一次接触项目
  ↓
/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 等已不存在技能引用

当前产物边界

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 是教学：基于报告引导用户学会。

后续改进应避免把三者重新合并。最重要的维护原则是：保持边界比增加功能更重要。

Reference in New Issue View Git Blame Copy Permalink