zhuyongxin
71e0b7f801
- Reposition sm-flow as orchestration harness over OpenSpec lifecycle - Adopt 4 user commands (Actions, Not Phases) instead of phase numbers - Rename all stages to English verbs (clarify through archive) - Reorder execution: grill before specify to eliminate rework loops - Simplify core rules from 19 to 6 hard constraints in SKILL.md - Simplify conflict classification from 4 categories to 2+1 - Switch devflow strategy to decisions.md-only process log during execution - Upgrade micro mode from artifact compression to gate merging - Add observable outputs for quality constraints - Add design review doc and user guide - Append v4.0 changelog to workflow.md
192 lines
7.4 KiB
Markdown
192 lines
7.4 KiB
Markdown
# SM-Flow 使用方式
|
||
|
||
本文档面向 sm-flow 的用户，说明如何启动、交互和使用 sm-flow。
|
||
|
||
## 快速开始
|
||
|
||
sm-flow 通过 4 个用户命令覆盖完整生命周期。你不需要了解内部阶段，只需表达意图。
|
||
|
||
| 命令 | 意图 | 典型场景 |
|
||
|---|---|---|
|
||
| `/sm-flow` | 完整流程 | 有粗略想法，从头规划到执行 |
|
||
| `/sm-flow explore` | 先聊聊 | 需求不清楚，带上下文探索 |
|
||
| `/sm-flow apply [change]` | 只执行 | 已有 Committed OpenSpec，直接实现 |
|
||
| `/sm-flow archive [change]` | 收尾 | 执行完了，回填 devflow + 归档 |
|
||
|
||
你也可以用自然语言指定阶段继续，例如：
|
||
|
||
```
|
||
ops-message-support 的 grill 已经做完了，继续
|
||
帮我检查一下 add-dark-mode 的 OpenSpec 对齐
|
||
```
|
||
|
||
sm-flow 会识别意图，自动补做最小前置检查，然后从指定阶段继续。
|
||
|
||
## 典型使用流程
|
||
|
||
### 场景 1：完整规划 → 执行 → 归档（分三次调用）
|
||
|
||
```bash
|
||
# 第一次：完整规划
|
||
/sm-flow 给站内消息加 OMC 支持
|
||
→ 走完 clarify → context → propose → grill → specify → audit → commit
|
||
→ 停在 apply 前，你说"先不执行了"
|
||
|
||
# 第二次：继续执行
|
||
/sm-flow apply ops-message-support
|
||
→ 进入 apply，执行完 tasks
|
||
|
||
# 第三次：归档
|
||
/sm-flow archive ops-message-support
|
||
→ 回填 devflow，询问是否归档 OpenSpec change
|
||
```
|
||
|
||
三个阶段，三次调用，每次只做一个用户意图的事。
|
||
|
||
### 场景 2：需求不清楚，先探索
|
||
|
||
```bash
|
||
/sm-flow explore 我们在考虑是否要重构消息队列
|
||
→ sm-flow 读取 devflow 上下文，和你讨论需求边界、风险、替代方案
|
||
→ 不生成 OpenSpec，只帮你理清思路
|
||
→ 如果讨论出明确方向，下次可以用 /sm-flow 启动完整流程
|
||
```
|
||
|
||
### 场景 3：小改动，快速模式
|
||
|
||
```bash
|
||
/sm-flow 修复按钮的拼写错误
|
||
→ sm-flow 识别为 micro 规模
|
||
→ 合并 gate：clarify+context 合并 checkpoint → propose+specify 合并 checkpoint → grill（最少 1 个问题）→ commit（简化检查）
|
||
→ 保留最关键的门控，但流程更轻量
|
||
```
|
||
|
||
### 场景 4：从中间继续
|
||
|
||
```bash
|
||
# 上次对话停在 grill 阶段
|
||
add-dark-mode 的 grill 已经做完了，继续
|
||
→ sm-flow 识别意图，自动补做 specify 的最小前置检查
|
||
→ 从 specify 阶段继续
|
||
```
|
||
|
||
## 交互模式
|
||
|
||
### Human Checkpoint
|
||
|
||
sm-flow 在关键节点会暂停并询问你：
|
||
|
||
- **propose 后**：说明 proposal 范围、关键假设、主要风险，询问是否继续 grill
|
||
- **grill 后**：汇报已解决和未解决的问题、proposal 变更，询问是否继续 specify
|
||
- **audit 后**：说明架构风险、OpenSpec 修正点，询问是否进入 commit
|
||
- **commit 后**：说明 Committed OpenSpec 范围、接口影响、剩余风险，询问是否进入 apply
|
||
- **archive 前**：询问是否归档 OpenSpec change
|
||
|
||
你可以选择继续、暂停、或要求返回上一阶段。
|
||
|
||
### Grill 阶段的一对一澄清
|
||
|
||
grill 阶段会建立一个 question pool，覆盖术语、边界、验收三个维度。问题分两类：
|
||
|
||
- **evidence-driven**：sm-flow 先查证代码、文档、OpenSpec 或 ADR，再向你汇报证据和结论
|
||
- **user-interview**：sm-flow 一次只问一个问题，等你确认后才继续
|
||
|
||
典型节奏：查证 1-2 个 evidence-driven → 汇报 → 问 1 个 user-interview → 等确认 → 继续。
|
||
|
||
### 自然语言交互
|
||
|
||
除了 4 个命令，你可以用自然语言与 sm-flow 交互：
|
||
|
||
```
|
||
# 指定 change name
|
||
继续 ops-message-support
|
||
|
||
# 指定阶段
|
||
add-dark-mode 的 specify 做完了吗？
|
||
|
||
# 指定动作
|
||
帮我检查一下 add-dark-mode 的 cross-artifact 对齐
|
||
|
||
# 混合表达
|
||
ops-message-support 的 grill 已经确认了术语和边界，继续 specify
|
||
```
|
||
|
||
sm-flow 会识别意图，自动编排后续阶段。
|
||
|
||
## 规模分档
|
||
|
||
sm-flow 根据变更规模自动分档，调整流程重量：
|
||
|
||
| 分档 | 适用场景 | 流程特点 |
|
||
|---|---|---|
|
||
| `micro` | 小改动、低风险、需求明确 | gate 合并，grill 最少 1 个问题，commit 简化检查 |
|
||
| `standard` | 默认模式 | 完整 9 阶段流程 |
|
||
| `complex` | 高风险、跨模块、需求不清、多人协作 | standard 基础上增加扩展产物（PRD/research/design/tasks/alignment） |
|
||
|
||
你不需要显式指定分档，sm-flow 会在 clarify 阶段自动判断。如果判断不准，会作为 user-interview 问题等待你确认。
|
||
|
||
## devflow：自动维护的项目长期记忆
|
||
|
||
sm-flow 会自动维护 `devflow/` 目录作为项目长期记忆。你不需要手动管理它。
|
||
|
||
```
|
||
devflow/
|
||
├── projects/YYYY-MM-DD-{slug}/ ← 项目档案（brief/evidence/decisions/acceptance）
|
||
├── glossary/CONTEXT.md ← 领域词汇表
|
||
├── compound/ ← 跨项目知识沉淀
|
||
├── reference/ ← 共享模板
|
||
└── index.md ← 项目索引
|
||
```
|
||
|
||
**clarify → apply 期间**：sm-flow 只维护 `decisions.md` 作为过程日志（grill 结论、关键决策、验证结果）。
|
||
|
||
**archive 阶段**：从 decisions.md + OpenSpec 产物提取完整档案（brief.md、evidence.md、decisions.md、acceptance.md）。
|
||
|
||
**下次使用时**：sm-flow 会自动读取 devflow 上下文，增强 OpenSpec 产物。术语、历史决策、验收记录不会丢失。
|
||
|
||
## OpenSpec 集成
|
||
|
||
sm-flow 编排 OpenSpec 的生命周期，但不强制依赖 OpenSpec CLI：
|
||
|
||
- **优先使用 OpenSpec CLI**：如果 `openspec-propose`、`openspec-apply-change`、`openspec-archive-change` 可用，sm-flow 会调用它们
|
||
- **内置执行协议**：如果 OpenSpec CLI 不可用，sm-flow 使用内置协议接管（标注为降级执行）
|
||
|
||
Draft / Committed 分离：
|
||
|
||
- **Draft OpenSpec**：propose 阶段产出，是讨论对象，不是执行许可
|
||
- **Committed OpenSpec**：通过 commit gate 后，成为 apply 的执行依据
|
||
- **apply 只执行 Committed OpenSpec**：防止未经澄清的方案直接进入实现
|
||
|
||
## 常见问题
|
||
|
||
### Q: 我需要在启动前准备什么？
|
||
|
||
不需要。sm-flow 会从你的粗略想法、issue、PRD 或已有 research 开始。如果信息不足，clarify 阶段会追问。
|
||
|
||
### Q: 我可以跳过某个阶段吗？
|
||
|
||
不可以。sm-flow 的门控是硬约束（grill 至少 3 个问题、commit gate 必须通过）。但 micro 模式会合并 gate，减少流程开销。
|
||
|
||
### Q: 如果 OpenSpec 不可用怎么办？
|
||
|
||
sm-flow 会使用内置执行协议接管，标注为降级执行。产物仍然写入 `openspec/changes/{slug}/`，只是不通过 OpenSpec CLI。
|
||
|
||
### Q: devflow 和 OpenSpec 冲突怎么办？
|
||
|
||
sm-flow 会先汇报冲突，等你确认，然后修正 OpenSpec，再继续执行。devflow 是上下文，OpenSpec 是执行真理源。
|
||
|
||
### Q: 我可以修改已经 commit 的 OpenSpec 吗？
|
||
|
||
可以。如果 apply 阶段发现规格遗漏、设计冲突或用户变更，sm-flow 会暂停 apply，修正 OpenSpec 后重新提交。
|
||
|
||
### Q: archive 阶段会自动归档 OpenSpec 吗？
|
||
|
||
不会。archive 阶段会回填 devflow，然后询问你是否归档 OpenSpec change。在你说"是"之前，不会执行归档。
|
||
|
||
## 参考文档
|
||
|
||
- **设计理念**：[workflow.md](./workflow.md) — 当前设计理念（v4 方向）和演进历史
|
||
- **设计评审**：[design-review.md](./design-review.md) — 核心定位、状态评估、已确认修改方向
|
||
- **回溯分析**：[retrospective.md](./retrospective.md) — 历史执行失败分析
|
||
- **使用问题**：[使用问题.md](./使用问题.md) — 真实痛点收集
|