git-learn/skill-workbench/docs/sm-flow/design-review.md

# SM-Flow 设计评审与修改方向

**日期**：2026-05-25
**目的**：基于完整代码审阅和讨论，落地当前设计的评估结论和下一步修改方向。

---

## 核心定位：sm-flow 是一个协议层 Harness

### 本质认知

sm-flow 不是一个"更好的 skill"，也不是 OpenSpec 的增强插件。它是一个**用提示词实现的协议层 harness**——控制 agent 以什么顺序、什么条件、什么标准使用工具。

### Harness 能力对照

| Harness 能力 | sm-flow 的实现 |
|---|---|
| 流程编排 | Phase 0 → 0.5 → 1 → 1.5 → 2 → 2.5 → 2.9 → 3 → 4 |
| 门控 | Draft/Committed gate、checkpoint、退出条件 |
| 上下文管理 | Phase 0.5 harvest、首次加载策略、按需读取 |
| 权限控制 | human-in-the-loop、user-interview 必须等确认 |
| 工具调度 | 每个 Phase 指定子 skill、fallback 链 |
| 护栏 | micro≠skip、不得猜测式修 bug、冲突必须先分类 |

### 四层架构

```
Claude Code Harness  → 代码层：工具权限、hooks、context window（agent 绕不过）
  sm-flow Harness    → 协议层：工作流阶段、门控规则、产物约束、人类对齐（提示词实现）
    OpenSpec         → 执行引擎：propose/apply/archive 的具体操作
      Sub-skills     → 能力层：grill、zoom-out、diagnose、tdd
```

sm-flow 位于 Claude Code harness 和 OpenSpec 之间。Claude Code harness 控制 agent **能做什么**（工具、权限、context），sm-flow harness 控制 agent **怎么做**（顺序、条件、标准）。OpenSpec 是被调度的执行引擎，子 skill 是被调用的能力单元。

### 与代码层 Harness 的关键区别

- 代码层 harness（Claude Code）是**代码实现**的，agent 物理上绕不过
- 协议层 harness（sm-flow）是**提示词实现**的，agent 理论上可以违反

因此 sm-flow 需要 checkpoint、显式约束、降级声明等机制来强化执行力。这些机制的本质就是**弥补提示词 harness 缺乏物理强制力的弱点**。

### 这个定位对后续设计的指导意义

以 harness 思想为核心，所有后续修改都应该回答同一个问题：

> **这条规则/机制是在约束 agent 的什么行为？约束力够不够？会不会过度限制 agent 的判断力？**

具体推论：

1. **约束粒度**：当前以阶段级约束为主，关键动作（冲突分类、one-at-a-time）单独加约束。粒度选择合理，后续新增约束应遵循同一粒度策略。
2. **可组合性**：harness 的子模块能否独立加载？当前 Phase 2 的 grill、Phase 2.5 的 zoom-out 已经有独立性，但缺少独立的进入协议。
3. **可观测性**：checkpoint 机制是 harness 的 telemetry。每个 checkpoint 汇报当前阶段、能力来源、产出物、退出条件、blocker——这相当于告诉外部"agent 现在在做什么、为什么卡住了"。
4. **设计自由度**：作为 harness，sm-flow 天然有权约束被编排对象（OpenSpec）的使用方式——task 粒度检查、specs 可验收性评分、apply 进度汇报格式都是合理的编排行为。

---

## 当前状态评估

### 架构概览

```
SKILL.md（~85行）                    ← 入口协议：定位、真理源、~22条硬规则、阶段总览
references/
├── phase-contracts.md（~274行）      ← 逐阶段契约：进入/动作/输出/退出/checkpoint
├── operating-rules.md（~95行）       ← 运行规则：接口分级、启动检查、产物分层、快速模式、完成标准
├── fallbacks.md（~132行）            ← 降级协议：通用记录要求 + 8 个 fallback
├── archive-rules.md（~130行）        ← 归档规则：提取映射、索引维护、验收分类、ADR 条件
└── templates.md（~352行）            ← 产物模板：brief/evidence/decisions/acceptance/PRD/ADR/...
```

总计约 1070 行。首次加载只读 SKILL.md + phase-contracts.md（~360 行），其余按需补读。

### 演进脉络

```
v1   dev-flow：基础流程骨架（Phase 1-4）
     ↓ 痛点：产物散落 5 个目录，archive 后上下文全丢
v2   增加 devflow/ 聚合层（人类档案层 vs 机器工作区分离）
     ↓ 痛点：devflow 产物越来越完整，agent 直接拿 devflow 写代码，OpenSpec 被架空
v3   真理源分层：devflow=上下文, OpenSpec=执行, 代码=结果
     ↓ 痛点：devflow 和 OpenSpec 产物大量重叠；grill 后返工 proposal/design
v3.1 Draft/Committed 分离 + 可执行 gate + 产物瘦身 + 接口影响分级
     ↓ 痛点：规则太多堆在 SKILL.md，agent 加载后上下文被冲走
v3.1+ 协议瘦身：SKILL.md 减负 → operating-rules.md + fallback 去重 + 引用自洽
```

每一版都从真实执行失败中提炼，不是理论推演。

### 已经做得好的

**1. 协议自洽性**

SKILL.md → phase-contracts → operating-rules → fallbacks → archive-rules → templates 之间的引用关系完整。cross-reference 断链问题（fallback 锚点中文名、接口分级引用）已修掉。

**2. 失败驱动迭代**

retrospective.md 逐阶段分析"应该做什么 / 实际做了什么 / 没做到什么"，使用问题.md 收集了 7 个真实痛点。当前版本的规则几乎都能追溯到一次真实失败。

**3. 对 agent 行为模式的准确预判**

规则大量出现"不得把单个决策确认推断为执行授权""micro 不等于跳过""evidence-driven 不是自动通过"——这些是 agent 的真实偷懒模式。规则写的不是"应该做什么"，而是"agent 会怎么绕过，以及如何堵死"。

**4. 7 个核心设计决策逻辑自洽**

| # | 决策 | 为什么 |
|---|---|---|
| 1 | OpenSpec 是唯一执行真理源 | 防止 devflow 和 OpenSpec 成为并列执行依据 |
| 2 | Draft / Committed 分离 | Phase 1 产出是讨论对象，Phase 2.9 是显式 gate |
| 3 | devflow 按阶段就近写入，Phase 4 做 consolidation | 防止 Phase 4 变成"第一次补写" |
| 4 | Question Pool + one-at-a-time | 先列全风险面，再逐项消费 |
| 5 | Cross-artifact 对齐链 | brief→proposal→design→specs→tasks 每层接住上游 |
| 6 | 能力绑定而非路径绑定 | 子 skill 可跨平台迁移 |
| 7 | Micro ≠ Skip | 产物可合并，gate 不能省略 |

---

## 已确认的修改方向

### 修改 1：定位修正——明确"协议层 Harness"身份 ✅ 已实施

**问题**：当前 SKILL.md 说"不替代 OpenSpec，而是增强"，但实际上 sm-flow 是一个编排 OpenSpec 生命周期的协议层 harness。OpenSpec 是被调度的执行引擎，sm-flow 控制它什么时候跑、怎么跑、跑完怎么收。

**修改方向**：

- SKILL.md 角色定位段落改写，以 harness 思想为核心：sm-flow 编排 OpenSpec 的完整生命周期，通过阶段、门控、人类对齐和长期记忆，约束 agent 以正确的顺序、条件和标准使用 OpenSpec
- 不再说"不替代"，正面描述编排职责
- 真理源分层改为四层架构：

```
sm-flow        → 编排层（harness）：阶段、门控、产物约束、人类对齐
  OpenSpec     → 执行引擎：propose/apply/archive 的能力提供方
    devflow/   → 记忆层：为编排层提供上下文，接收执行结果的回填
      code     → 实现结果：apply 的产出
```

**影响范围**：SKILL.md 的角色定位和真理源分层段落。其他规则不需要变——它们本来就在做 harness 的事。

**设计自由度**：定位明确后，未来 sm-flow 约束 OpenSpec 使用方式（task 粒度检查、specs 可验收性评分、apply 进度汇报格式）都是合理的编排行为，不再需要解释"为什么 sm-flow 可以管 OpenSpec"。

### 修改 2：Fallback 重新定位——从"降级"到"内置执行引擎" ✅ 已实施

**问题**：当前 fallbacks.md 把 OpenSpec 不可用时的处理称为"降级协议"。但从 harness 视角看，sm-flow 作为编排层天然需要自带执行能力——当外部执行引擎（OpenSpec CLI）不可用时，harness 自己接管执行不是"降级"，而是正常的能力切换。

**修改方向**：

- fallbacks.md 中 OpenSpec 相关的 fallback 重新定位为"内置执行协议"
- 优先级描述改为：优先使用 openspec CLI / 原生 skill（外部执行引擎）→ 不可用时 sm-flow 使用内置执行协议（内置执行引擎）
- SKILL.md 首次加载或角色定位部分加一句：sm-flow 不强制依赖 openspec CLI，内置执行协议可以纯文件方式完成整个流程
- 措辞从"降级风险"调整为"外部引擎不可用，切换为内置引擎"，保留声明和记录要求，但去掉"降级"暗示的能力不足感

**影响范围**：fallbacks.md 的措辞 + SKILL.md 首次加载或角色定位段落。

### 修改 3：新用户上手体验——devflow 概念延迟暴露 ✅ 已实施

**问题**：SKILL.md 第一段就直接引入 `devflow/` 概念，对不熟悉的新用户来说突兀。从 harness 视角看，devflow 是 harness 的内部记忆机制，不是用户需要理解的概念——就像用户不需要理解 Claude Code 的 context window 管理一样。

**修改方向**：

- SKILL.md 角色定位段落中，先用一句话说清 sm-flow 会自动管理项目长期记忆，用户不需要手动维护
- 把 devflow 的技术细节从角色定位移到真理源分层段落中自然引出
- 对用户可见的概念只有：sm-flow（流程）→ OpenSpec（变更）→ 代码（结果）

**影响范围**：SKILL.md 角色定位段落。

---

## 待讨论的设计问题

以下是已识别但尚未决定是否修改的问题，留待后续讨论。

### 问题 1：流程总成本 ✅ 已确认方向

**分析**：问题不是"流程太贵"，而是**固定成本没有随规模充分缩放**。Phase 0/0.5/1.5/2.5/2.9/4 的成本基本是 O(1) 的——不随代码量线性增长。当前 micro 只压缩了产物（少写几个文件），没有压缩 gate 数量。

| 改动规模 | 代码工作量 | 流程开销 | 开销占比 | 感受 |
|---|---|---|---|---|
| micro（30min 代码） | 30 min | 40-60 min | ~60% | 太重 |
| standard（2h 代码） | 2 h | 1-1.5 h | ~40% | 还行 |
| complex（1-2d 代码） | 12 h | 2-3 h | ~20% | 值得 |

**确认方向**：micro 模式下合并 gate，不只是压缩产物。

```
当前 standard：Phase 1 checkpoint → Phase 1.5 → Phase 2 → Phase 2.5 checkpoint → Phase 2.9
micro 合并后：Phase 1+1.5 合并 checkpoint → Phase 2（最少 1 个问题） → Phase 2.9（简化检查）
```

micro 的定位从"产物变少"变为"gate 变少但保留最关键的"（Phase 2 最小澄清 + Phase 2.9 commit gate）。

**✅ 已落地**：operating-rules.md 快速模式段落已重写（gate 合并策略），phase-contracts.md 中各阶段已使用英文命名并体现 micro 行为。

### 问题 2：Phase 1 ↔ Phase 2 循环收敛 ✅ 已确认方向

**根因**：当前阶段顺序是 Phase 1 一次性产出完整 4 件套（proposal + design + specs + tasks），Phase 2 才做 grill 澄清。澄清结果必然要回写已经细化过的 design/specs/tasks，形成不可避免的返工循环。这不是 agent 执行问题，是**流程顺序决定了返工必然存在**。

这也是使用问题.md 中第 3 条提到的核心痛点："propose 之后生成了 task、design 等产物，再用 grill 澄清需求，澄清完又得回去更新"。

**确认方向**：调整阶段执行顺序，先澄清再细化。Phase 1 只产出轻量 proposal，Phase 2 在轻量 proposal 上做 grill，Phase 1.5 在需求稳定后才补全完整 OpenSpec。

| | Phase 1（轻量 propose） | Phase 1.5（细化 + 对齐） |
|---|---|---|
| 执行者 | sm-flow 内置协议 | openspec-propose 或内置协议 |
| 产出 | 只写 proposal.md（范围、问题、方案方向、非目标） | 补全 design.md + specs/ + tasks.md |
| 目的 | 建立讨论对象 | 需求稳定后生成完整 OpenSpec |
| token 成本 | 低 | 正常 |

调整后的阶段顺序：

```
Phase 0    入口澄清
Phase 0.5  devflow 上下文收集
Phase 1    轻量 propose（sm-flow 内置协议，只写 proposal.md）  ← 不调用 openspec-propose
Phase 2    grill 澄清（基于 proposal.md，把需求钉死）
Phase 1.5  细化 + cross-artifact 对齐（调用 openspec-propose 补全 design/specs/tasks）
Phase 2.5  架构审计
Phase 2.9  commit gate
Phase 3    apply
Phase 4    回填 devflow
```

**三个附带收益**：

1. **循环消失**：grill 在细化之前，不存在"细化 → grill → 回写细化"的循环
2. **token 节省**：micro 模式下 Phase 1 只写轻量 proposal，不浪费 token 写详细产物（与问题 1 联动）
3. **openspec-propose 角色更准确**：不再是"从零 propose"，而是"基于已稳定的 proposal 做细化补全"——harness 对执行引擎的合理调度

**Phase 编号不变，Phase 2 和 Phase 1.5 的执行顺序对调**。阶段总览列表中的编号保持原样，但实际执行顺序变为 0 → 0.5 → 1 → 2 → 1.5 → 2.5 → 2.9 → 3 → 4。

**✅ 已落地**：SKILL.md 阶段总览使用英文命名（clarify → archive），phase-contracts.md 已按新顺序重写（grill 在 specify 前），fallbacks.md 中 OpenSpec 提案降级触发时机改到 specify 阶段。

### 问题 3：devflow 就近写入 vs agent 注意力 ✅ 已确认方向

**分析**：Phase 1-3 期间要求 agent 同时维护 OpenSpec（执行真理源）和 devflow（人类档案层），本质上是**双重记录**——同一份内容写两遍，Phase 4 还要再检查修正，变成三次写入。

**确认方向**：Phase 1-3 只维护一个轻量 decisions.md 作为过程日志，Phase 4 从中提取完整 devflow。

| 阶段 | 写入什么 | 性质 |
|---|---|---|
| Phase 1-3 | 只维护 `decisions.md`（grill 结论、关键决策、验证结果） | 过程日志，轻量追加 |
| Phase 4 | 从 decisions.md + OpenSpec 产物提取 brief/evidence/acceptance | 最终档案，一次性提取 |

**约束**：Phase 4 的 devflow 提取必须基于 decisions.md 和 OpenSpec 产物，不能是纯粹的事后回忆录。decisions.md 是提取的依据链。

**✅ 已落地**：SKILL.md 核心规则已改为"clarify → apply 只维护 decisions.md 作为过程日志；archive 阶段从中提取完整 devflow 档案"，phase-contracts.md 各阶段退出条件已同步更新。

### 问题 4：部分阶段独立使用 ✅ 已确认方向

**问题**：当前支持"指定阶段模式"，但从中间启动时上游阶段的产物可能不满足当前阶段的进入条件。

**确认方向**：借鉴 OpenSpec 的 "Actions, Not Phases" 设计哲学——**用户命令表达意图，不表达阶段**。阶段是 harness 的内部词汇，不是用户的 API。

**用户命令设计（4 个）**：

```
/sm-flow                    → 完整流程（从入口到归档）
/sm-flow explore            → 先聊聊（需求不清楚）
/sm-flow apply              → 直接执行（已有 Committed OpenSpec）
/sm-flow archive            → 归档（执行完了，回填 devflow + 归档 OpenSpec）
```

| 命令 | 用户意图 | harness 内部行为 |
|---|---|---|
| `/sm-flow` | 从头到尾 | 完整编排 9 个阶段 |
| `/sm-flow explore` | 先想想 | 带上下文的探索模式 |
| `/sm-flow apply` | 只执行 | 检查 commit gate → apply |
| `/sm-flow archive` | 收尾 | backfill devflow + 归档确认 |

**典型使用场景**：

```
# 第一次：完整规划
/sm-flow 给站内消息加 OMC 支持
→ 走完 propose → grill → specify → audit → commit
→ 停在 apply 前，用户说"先不执行了"

# 第二次：继续执行
/sm-flow apply ops-message-support
→ 进入 apply，执行完 tasks

# 第三次：归档
/sm-flow archive ops-message-support
→ 回填 devflow，询问是否归档 OpenSpec change
```

三个阶段，三次调用，每次只做一个用户意图的事。

**阶段命名（内部协议）**：

借鉴 OpenSpec 的动词式命名风格，阶段名称保留为 **agent 的词汇表**（用于 checkpoint 汇报和进度通知），不作为用户命令：

```
旧编号      →  描述名（内部）    做什么
Phase 0    →  clarify          入口澄清
Phase 0.5  →  context          上下文收集
Phase 1    →  propose          轻量 propose（只写 proposal）
Phase 2    →  grill            人类对齐澄清
Phase 1.5  →  specify          细化 + 对齐（补全 design/specs/tasks）
Phase 2.5  →  audit            架构审计
Phase 2.9  →  commit           commit gate
Phase 3    →  apply            OpenSpec 执行
Phase 4    →  archive          回填 devflow + 归档确认
```

**agent 用阶段名做 telemetry**：
- "当前在 grill 阶段，已解决 2/5 个问题"
- "grill 完成，进入 specify"

**用户用自然语言交互**：
- "/sm-flow" → 启动完整流程
- "ops-message-support 的 grill 已经做完了，继续" → harness 识别意图，自动补做最小前置检查
- "帮我检查一下 add-dark-mode 的 OpenSpec 对齐" → harness 识别意图，只做 specify 阶段的对齐检查

**核心原则**：用户只需要知道四件事（完整流程 / explore / apply / archive），其余全部通过自然语言交互，由 harness 识别意图后编排。

**✅ 已落地**：SKILL.md 用户命令表格（4 个命令），operating-rules.md 启动检查已识别用户命令意图，phase-contracts.md 所有阶段已使用英文命名。

### 问题 5：workflow.md 的维护方式 ✅ 已确认方向

**问题**：workflow.md 是 590 行的设计演进文档，混合了三类内容：设计理念（稳定）、变更日志（每次迭代追加）、历史对比（写完不动）。读者需要翻 590 行才能理解"现在的设计是什么"。

**确认方向**：方向 A——顶部加"当前设计理念"摘要，历史部分作为审计轨迹保留。

```markdown
# SM-Flow 工作流

## 当前设计理念（v4 方向）
- sm-flow 是协议层 harness，编排 OpenSpec 生命周期
- 四层架构：harness → OpenSpec → devflow → code
- 用户命令 4 个：/sm-flow / explore / apply / archive
- 9 个内部阶段（英文描述命名）：clarify → context → propose → grill → specify → audit → commit → apply → archive
- 阶段名是内部协议，不是用户 API
- 真理源分层：devflow=上下文, OpenSpec=执行, 代码=结果
- Draft/Committed 分离
- ...（20-30 行）

---

## 演进历史
（原有的 v1→v3.1+ 内容不动）
```

**来源**：design-review.md 的"核心定位"章节可以直接作为摘要的草稿。

**⏳ 待落地**：在 workflow.md 顶部插入当前设计理念摘要段落（本项属于文档维护，不在 skill 文件范围内）。

### 问题 6：SKILL.md 核心规则分类 ✅ 已确认方向

**问题**：当前 ~22 条核心规则平铺在一个列表里，混合了三种不同性质的约束。agent 读到第 15 条已经记不清前 5 条的优先级。

**确认方向**：三类分组 + 英文阶段命名 + 质量约束必须有可观测产出。

**A. 三类分组**

```markdown
## 核心规则

### 硬约束（违反即流程失败）
- apply 必须通过 OpenSpec apply 执行
- 不得跳过 context
- 不得跳过 grill（至少三个高价值问题）
- 不得跳过 commit
- 不得猜测式修 bug
- fallback 产物必须标注
- micro 不能跳过关键 gate

### 流程约束（必须按顺序做）
- 先建 question pool，再消费 user-interview
- 单个 grill 决策确认不等于 apply 授权
- 冲突必须先分类再处理
- 影响实现的发现必须先回写 OpenSpec
- 子 skill 必须显式调用或显式降级
- clarify → apply 只维护 decisions.md，archive 阶段提取完整档案
- archive 前必须询问是否归档

### 质量约束（必须有可观测产出）
- specify 的 checkpoint 必须包含 cross-artifact 对齐检查表（4 行，每行标记已对齐/存在 gap）
- evidence-driven 结论必须写入 decisions.md，且 checkpoint 必须列出汇报状态
- user-interview 必须在 decisions.md 中记录问题原文、用户原话、确认状态；未确认的不能从 question pool 移除
- checkpoint 必须包含：当前阶段、能力来源、产出物清单、已满足退出条件、未解决阻塞
- human-in-the-loop 检查点：propose 后、audit 后、commit 后、apply 前

> 三类约束都不可违反。分类的目的是帮助快速定位规则类型。
> 质量约束必须转化为可观测的产出（写入文件 + checkpoint 检查），否则不是约束而是建议。
```

**B. 阶段编号改为英文描述名**

去掉 Phase 0/0.5/1/1.5/2/2.5/2.9/3/4 的数字编号，全部用英文动词：

```
clarify  → 入口澄清
context  → 上下文收集
propose  → 轻量 propose（只写 proposal）
grill    → 人类对齐澄清
specify  → 细化 + cross-artifact 对齐
audit    → 架构审计
commit   → commit gate
apply    → OpenSpec 执行
archive  → 回填 devflow + 归档确认
```

执行顺序：clarify → context → propose → grill → specify → audit → commit → apply → archive

用户命令是 API（4 个），阶段名是内部协议（9 个）。风格统一（英文动词），职责分离。

**C. 质量约束的可观测产出原则**

协议层 harness 的核心弱点：质量约束如果没有可观测的产出，agent 一定会跳过。

| 约束 | 原写法（软） | 改为（硬） |
|---|---|---|
| evidence-driven 汇报 | "必须向用户汇报" | 写入 decisions.md + checkpoint 列出汇报状态 |
| user-interview 确认 | "必须等待用户显式回答" | decisions.md 记录问题原文/用户原话/确认状态 |
| cross-artifact 对齐 | "必须显式检查" | checkpoint 包含 4 行对齐检查表，每行标记已对齐/存在 gap |

**✅ 已落地**：SKILL.md 核心规则已按三类分组重写（硬约束 / 流程约束 / 质量约束），phase-contracts.md 所有阶段使用英文命名，各 checkpoint 退出条件已加可观测产出检查。

### 问题 7：grill 阶段 evidence-driven 和 user-interview 的节奏 ✅ 已确认方向

**问题**：当前规则说"可以并行整理 evidence-driven 证据，但 user-interview 仍然必须 one-at-a-time"。但 agent 可能把所有 evidence-driven 结论一口气汇报完，然后才问 user-interview 问题，导致用户被动接收大量信息后再被采访。

**确认方向**：在 grill 阶段的动作描述里明确"交替推进"。

```markdown
grill 阶段的推进节奏：
- evidence-driven 和 user-interview 应交替推进，避免把所有证据结论攒到一起汇报
- 典型模式：查证 1-2 个 evidence-driven → 汇报 → 问 1 个 user-interview → 等确认 → 继续
- evidence-driven 可以并行查证（不需要用户参与），但汇报和 user-interview 穿插进行
```

**实际落地**：phase-contracts.md grill 阶段动作描述已调整。经评估后，"交替推进"对 agent 的要求过高（LLM 天然倾向批量处理），改为更务实的"先批量查证 evidence-driven 并一次性汇报，再逐个处理 user-interview"，降低执行复杂度同时保留核心约束。