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——顶部加"当前设计理念"摘要，历史部分作为审计轨迹保留。

# 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. 三类分组

## 核心规则

### 硬约束（违反即流程失败）
- 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 阶段的动作描述里明确"交替推进"。

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"，降低执行复杂度同时保留核心约束。