4.3 KiB
4.3 KiB
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
-
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。
-
接口影响分级，而不是固定独立文档
- 决策：所有接口变更都必须有接口影响记录；只有 L3/L4 级别才必须独立产出接口文档。
- 原因：接口变更需要可追踪，但低风险内部接口不应制造额外文档负担。
- 替代方案：凡接口变更都新增接口文档。拒绝原因是会让 micro/standard 变更过重，增加文档重复和漂移。
-
devflow 通过索引和检索顺序控制增长
- 决策：新增或维护
devflow/index.md，并规定 Phase 0.5 的检索顺序为devflow/index.md、devflow/glossary/CONTEXT.md、相关项目 brief/acceptance/ADR、compound knowledge。 - 原因：devflow 的长期价值来自可回溯；没有索引时，文档越多越像一片温柔但很黏的沼泽。
- 替代方案：每次用全文搜索全量扫。拒绝原因是成本随项目数增长，且容易抓到无关历史。
- 决策：新增或维护
-
Phase 3 冲突先分类，再执行
- 决策：实现阶段遇到用户质疑、代码建议、测试失败或新事实与 OpenSpec 冲突时，必须分类为实现偏差、规格遗漏、设计冲突或用户变更。
- 原因：Phase 3 的职责是执行已提交规格，不是把所有新输入立即吸收成代码改动。
- 替代方案：让代理自行判断并继续。拒绝原因是会破坏 OpenSpec 的执行真理源地位。
-
子 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 冲突分类会暂停执行 → 这是刻意设计；暂停一次比悄悄把规格改歪更便宜。