68 lines
4.0 KiB
Markdown
68 lines
4.0 KiB
Markdown
# SM Flow Execution Hardening PRD
|
||
|
||
## 问题陈述
|
||
|
||
`sm-flow` 已经定义了较完整的阶段、规则和 reference 文件，但在真实项目执行中，代理仍然会把它当成“有帮助的流程建议”，而不是“必须逐阶段满足的执行协议”。结果是：
|
||
|
||
- Phase 0 没有形成入口摘要和已知影响区域。
|
||
- Phase 0.5 没有及时初始化和维护 `devflow/` 项目档案。
|
||
- Phase 1 没有显式声明 skill 或 fallback，Draft / Committed OpenSpec 的边界不稳定。
|
||
- Phase 1.5 被跳过，导致 proposal / design / research / specs / tasks 之间的一致性缺口直到用户 review 才暴露。
|
||
- Phase 2 虽然收集了证据，但没有以结构化问题池和 one-at-a-time 的方式稳定执行。
|
||
- Phase 2.5 被跳过，架构链路和接口影响没有提前暴露。
|
||
- Phase 2.9 缺少强制自检，无法可靠发现 cross-artifact 遗漏。
|
||
|
||
这说明当前痛点不是缺少理念，而是缺少“执行时自检”和“阶段切换门禁”的产品化机制。
|
||
|
||
## 解决方案
|
||
|
||
为 `sm-flow` 增加一轮“执行硬化”需求，目标是让代理在实际使用中更难偏离阶段协议。重点不是新增更多解释，而是把现有规则压缩成更可执行、更可检查、更可暴露偏差的约束，例如：
|
||
|
||
- 每个阶段结束必须有简短 checklist / checkpoint。
|
||
- 未显式声明 skill 或 fallback 视为该阶段未完成。
|
||
- Phase 2 先生成问题池，再按 one-at-a-time 消费。
|
||
- Phase 1.5 / 2.9 引入更明确的 cross-artifact diff 检查。
|
||
- `micro` 明确只能压缩产物，不得跳过关键 gate。
|
||
- devflow 产物默认在过程内同步更新，而不是拖到 Phase 4 补写。
|
||
|
||
## 用户故事
|
||
|
||
1. 作为使用 `sm-flow` 的开发者，我希望代理在进入下一阶段前自动暴露“已满足/未满足”的条件，这样我能尽早发现流程偏差。
|
||
2. 作为使用 `sm-flow` 的开发者，我希望 `micro` 模式仍然保留关键 gate，这样小改动不会因为“看起来简单”而漏掉重要检查。
|
||
3. 作为使用 `sm-flow` 的开发者，我希望 Phase 2 先形成问题池，再逐个提问，这样既符合 human-in-the-loop 约束，也能避免只问了少数问题就错误收尾。
|
||
4. 作为使用 `sm-flow` 的开发者，我希望 Phase 1.5 和 2.9 能可靠检查 proposal / design / specs / tasks / evidence / decisions 的一致性，这样问题能在 apply 前暴露，而不是等我 review。
|
||
|
||
## 实现决策
|
||
|
||
- 决策：本轮先把“执行硬化”提炼成需求，而不是直接进入文档改造。
|
||
- 原因：当前已掌握足够多的真实使用反馈，需要先明确问题边界和验收标准，再决定是否开新 OpenSpec change。
|
||
- 影响：下一步可以更顺畅地进入 `sm-flow` 的正式改造，而不是边讨论边补规则。
|
||
|
||
- 决策：把重点放在 phase gate、自检、问题池和一致性检查，而不是继续扩展 `sm-flow` 的理念层说明。
|
||
- 原因：复盘显示失真主要来自执行习惯和缺少检查，而不是原则方向错误。
|
||
- 影响：后续改动应优先落在 `SKILL.md`、`phase-contracts.md` 和模板/检查清单，而不是重写 workflow 长文。
|
||
|
||
## 测试决策
|
||
|
||
- 好测试应该通过审查 `sm-flow` 协议文本和执行产物，验证代理是否被强制带到正确的阶段检查点。
|
||
- 必须覆盖：
|
||
- `micro` 模式下 gate 不可跳过
|
||
- Phase 2 问题池与 one-at-a-time 提问
|
||
- skill/fallback 显式声明要求
|
||
- Phase 1.5 / 2.9 cross-artifact 检查
|
||
- devflow 过程内同步更新
|
||
- 不测试：
|
||
- 业务代码实现结果
|
||
- OpenSpec CLI 本身的功能正确性
|
||
|
||
## 非目标
|
||
|
||
- 不在本轮定义新的业务流程。
|
||
- 不在本轮替换 OpenSpec-first / Devflow-assisted 主设计。
|
||
- 不要求为所有小改动增加更重的文档负担。
|
||
|
||
## 补充说明
|
||
|
||
- 这轮需求直接来源于一次真实项目执行复盘，因此它比理念讨论更贴近代理实际失真模式。
|
||
- 如果后续进入 OpenSpec，建议 change 名可沿用 `sm-flow-execution-hardening`。
|