upgrade sm-flow v3.1 workflow

2026-05-21 19:55:23 +08:00
parent f45122dafb
commit 6a5520db33
26 changed files with 955 additions and 40 deletions
@@ -0,0 +1,54 @@
+## Context
+
+SM Flow v3 已经把 `devflow/` 定位为上下文真理源，把 `openspec/changes/<change>/` 定位为执行真理源。当前摩擦来自执行细节：一些需要人类判断的规则没有形成 gate，导致代理可能过早把 Draft OpenSpec 当成最终规格，或者在 Phase 3 中用代码侧发现直接覆盖原设计。
+
+本次改造的对象是 skill 协议本身，主要文件位于 `.agents/skills/sm-flow/`，历史说明位于 `skill-workbench/docs/sm-flow/workflow.md`。用户提供的问题记录位于 `skill-workbench/docs/sm-flow/使用问题.md`。
+
+## Goals / Non-Goals
+
+**Goals:**
+- 让 v3.1 明确“文档不是越多越好”：devflow 记录上下文、证据、决策和验收，OpenSpec 记录执行依据。
+- 对接口变更建立分级规则，避免“所有接口变更都独立成文档”和“接口影响没人记录”两个极端。
+- 引入 Draft / Committed OpenSpec，允许 Phase 1 先形成讨论对象，但禁止未提交的草稿直接进入 Phase 3。
+- 为 devflow 增加索引入口和固定检索顺序，解决项目档案增长后的定位问题。
+- 在 Phase 3 增加实现期沟通和冲突分类规则，避免把用户质疑、测试失败或代码建议直接当作新规格。
+
+**Non-Goals:**
+- 不重写 OpenSpec CLI 或 `.claude/skills/openspec-*`。
+- 不改业务代码或知识索引功能。
+- 不把 devflow 重新提升为执行真理源。
+- 不强制每次接口变更都创建独立接口文档。
+
+## Decisions
+
+1. **Draft / Committed OpenSpec 分离**
+   - 决策：Phase 1 产物称为 Draft OpenSpec；Phase 2 和 Phase 2.5 后进入新增的 Phase 2.9 Commit OpenSpec，只有通过提交检查的 OpenSpec 才能进入 Phase 3。
+   - 原因：完全推迟 OpenSpec 会缺少讨论对象；完全信任 Phase 1 初稿又会让 grill 后返工显得像异常。草稿/提交分离把返工变成正常流程。
+   - 替代方案：把 grill 放到 propose 前。拒绝原因是缺少结构化规格草稿时，澄清容易停留在对话层，难以精确回写 proposal/specs/tasks。
+
+2. **接口影响分级，而不是固定独立文档**
+   - 决策：所有接口变更都必须有接口影响记录；只有 L3/L4 级别才必须独立产出接口文档。
+   - 原因：接口变更需要可追踪，但低风险内部接口不应制造额外文档负担。
+   - 替代方案：凡接口变更都新增接口文档。拒绝原因是会让 micro/standard 变更过重，增加文档重复和漂移。
+
+3. **devflow 通过索引和检索顺序控制增长**
+   - 决策：新增或维护 `devflow/index.md`，并规定 Phase 0.5 的检索顺序为 `devflow/index.md`、`devflow/glossary/CONTEXT.md`、相关项目 brief/acceptance/ADR、compound knowledge。
+   - 原因：devflow 的长期价值来自可回溯；没有索引时，文档越多越像一片温柔但很黏的沼泽。
+   - 替代方案：每次用全文搜索全量扫。拒绝原因是成本随项目数增长，且容易抓到无关历史。
+
+4. **Phase 3 冲突先分类，再执行**
+   - 决策：实现阶段遇到用户质疑、代码建议、测试失败或新事实与 OpenSpec 冲突时，必须分类为实现偏差、规格遗漏、设计冲突或用户变更。
+   - 原因：Phase 3 的职责是执行已提交规格，不是把所有新输入立即吸收成代码改动。
+   - 替代方案：让代理自行判断并继续。拒绝原因是会破坏 OpenSpec 的执行真理源地位。
+
+5. **子 skill 绑定能力契约**
+   - 决策：文档应表达 `openspec-propose`、`openspec-apply-change` 等能力名和调用优先级；`.claude/skills/...` 是一个实现路径，不是唯一前提。
+   - 原因：同一流程应能迁移到 Codex、Claude 或其他代理环境。
+   - 替代方案：固定 Claude 路径。拒绝原因是兼容性弱，且与当前 `.agents/skills/` 运行方式不匹配。
+
+## Risks / Trade-offs
+
+- Draft / Committed OpenSpec 增加一个 Phase 2.9 gate → 用固定检查清单控制成本，避免变成新一轮大文档。
+- 接口影响分级可能被代理误判 → 把分级阈值写成可观察条件，并要求不确定时向用户确认。
+- `devflow/index.md` 需要维护 → Phase 4 回填时把索引更新列为默认动作，减少遗忘。
+- Phase 3 冲突分类会暂停执行 → 这是刻意设计；暂停一次比悄悄把规格改歪更便宜。