git-learn/skill-workbench/docs/sm-flow/sm-flow-optimization-suggestions.md

SM Flow Skill - 使用情况分析与优化建议

执行概况

项目: lookup-knowledge-integration
执行日期: 2026-06-24
执行模式: 手动跳阶段（用户直接要求"修复问题"）

实际执行的阶段

1. ❌ Clarify - 跳过（用户直接给了 handoff 文档）
2. ❌ Context - 跳过（未读取 devflow 历史）
3. ❌ Propose - 跳过（OpenSpec 已存在）
4. ❌ Grill - 跳过（未进行澄清）
5. ❌ Specify - 跳过（OpenSpec 已完整）
6. ❌ Audit - 跳过（未进行架构审计）
7. ❌ Commit - 跳过（关键遗漏）
8. ✅ Apply - 执行（实现代码）
9. ⚠️ Archive - 部分执行（先创建 handoff，后补 devflow）

---

做得好的地方 ✅

1. Archive 规则详细且可执行

优点：

• archive-rules.md 提供了清晰的提取映射表
• 目录结构规范（devflow/projects/YYYY-MM-DD-{slug}/）
• 产物分档（micro/standard/complex）明确
• 索引维护规则具体

证据：被提醒后，我能快速创建符合规范的 devflow 档案

2. 硬约束明确

优点：

• 6 条核心规则写在 SKILL.md 顶部，醒目
• 规则表述清晰（不得跳过 context/grill/commit）

问题：虽然规则清晰，但缺少执行机制（见后续建议）

3. Phase 契约结构清晰

优点：

• phase-contracts.md 定义了进入/退出条件
• 每个阶段的职责明确

---

关键问题 ❌

问题 1: Commit 检查缺少可执行标准

现象：

• 我不知道如何判断"通过 commit 检查"
• phase-contracts.md 说了要做 commit，但没说具体怎么判断

影响：

• 我直接跳过 commit，进入 apply
• 违反了硬约束规则 4："不得跳过 commit"

根本原因：

phase-contracts.md:
  "Commit 阶段：检查 Draft OpenSpec 是否达到可执行状态"
  
但没有说：
  - 什么叫"可执行状态"？
  - 需要检查哪些文件？
  - 每个文件的必需内容是什么？
  - 如何标记"已通过"？

问题 2: Apply 阶段缺少前置门控

现象：

• 用户说"修复问题"，我直接开始实现
• 没有检查是否存在 Committed OpenSpec

影响：

• 可能基于不完整的 OpenSpec 执行
• 违反了 "apply 必须基于 Committed OpenSpec" 的约束

根本原因：

• Apply 阶段的"进入条件"是软性描述
• 没有强制的文件检查机制（如 .committed 文件）

问题 3: Archive 阶段缺少 Checklist

现象：

• 我先创建了 handoff 文档
• 忘记了 devflow 才是核心记忆层
• 被提醒后才补创建 devflow 档案

影响：

• 归档流程不完整
• 需要用户纠正

根本原因：

• archive-rules.md 有详细说明，但没有强制执行顺序
• 我容易按"直觉"操作，而不是按"规范"操作

问题 4: 缺少流程状态追踪

现象：

• 我不知道当前在哪个阶段
• 每次执行都像"全新开始"

影响：

• 容易跳过中间阶段
• 无法断点续做

---

优化建议（按优先级）

High Priority（立即修复）

建议 1: Commit 检查增加可执行 Checkpoint

位置：references/phase-contracts.md - Commit 阶段

增加内容：

## Commit 阶段退出条件

必须完成以下 checkpoint：

### 文件完整性检查
- [ ] `proposal.md` 存在且包含：
  - 问题描述（至少 50 字）
  - 建议方案（至少 100 字）
  - 范围/非范围

- [ ] `design.md` 存在且包含：
  - 架构设计（文字或图）
  - 数据结构定义（至少 1 个）
  - 关键决策记录（至少 2 条）

- [ ] `specs/functional-specs.md` 存在且包含：
  - 至少 3 个 requirement
  - 每个 requirement 有 scenario

- [ ] `tasks.md` 存在且包含：
  - 至少 5 个可执行子任务
  - 每个任务有验收标准

### 一致性检查
- [ ] proposal 中的核心概念在 design 中有对应设计
- [ ] design 中的关键决策在 tasks 中有对应实现任务
- [ ] tasks 的验收标准可验证（不是"正确实现"这种模糊描述）

### 标记
通过后创建 `.committed` 文件：
```bash
echo "committed at $(date)" > openspec/changes/{slug}/.committed

执行指令： 在 apply 阶段入口，必须先执行此检查。

#### 建议 2: Apply 阶段增加前置门控

**位置**：`references/phase-contracts.md` - Apply 阶段

**修改"进入条件"**：
```markdown
## Apply 阶段进入条件

**硬约束**：
1. 必须存在 `.committed` 文件
2. 如果不存在，执行以下流程：
   a. 汇报：Draft OpenSpec 未通过 commit 检查
   b. 列出缺失的 checkpoint
   c. 询问用户：是否补做 commit 检查，或明确跳过（需显式确认）

**检查代码**：
```bash
if [ ! -f "openspec/changes/{slug}/.committed" ]; then
    echo "错误：Draft OpenSpec 未通过 commit 检查"
    echo "请先完成 commit 阶段，或显式确认跳过"
    exit 1
fi

#### 建议 3: Archive 阶段增加强制 Checklist

**位置**：`references/archive-rules.md` 顶部

**增加内容**：
```markdown
## Archive 阶段强制执行顺序

**按以下顺序执行，不得跳过或重排**：

### Step 1: 创建 devflow 档案（必需）
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/brief.md`
      （从 proposal.md 提取：背景、目标、范围、非目标）
      
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/decisions.md`
      （从 decisions.md 整理：关键决策、权衡、风险）
      
- [ ] 创建 `devflow/projects/YYYY-MM-DD-{slug}/acceptance.md`
      （记录：静态验证、脚本验证、人工验证、未验证）

### Step 2: 更新索引（必需）
- [ ] 在 `devflow/index.md` 末尾追加一行：
      `| YYYY-MM-DD | slug | 领域 | 关键词 | OpenSpec路径 | archived |`

### Step 3: 标记 OpenSpec（必需）
- [ ] 创建 `openspec/changes/{slug}/.completed` 文件

### Step 4: 创建 Handoff（可选）
- [ ] 创建 `handoff/YYYY-MM-DD-{slug}.md`
      （运维交接文档，给未来开发者）

### Step 5: 向用户汇报
- [ ] 列出创建的 devflow 档案
- [ ] 汇报验证情况（按类型分类）
- [ ] 列出剩余风险
- [ ] 询问：**是否现在归档 OpenSpec？**

**自检**：在执行 Step 5 前，检查 Step 1-4 是否都完成。

---

Medium Priority（下个版本）

建议 4: 增加流程状态文件

目标：让我知道当前在哪个阶段

实现：在 OpenSpec 目录维护 .sm-flow-state 文件

{
  "change": "lookup-knowledge-integration",
  "currentPhase": "apply",
  "completed": ["clarify", "context", "propose", "grill", "specify", "audit", "commit"],
  "nextPhase": "archive",
  "committed": true,
  "timestamps": {
    "commit": "2026-06-24T10:00:00Z",
    "apply_start": "2026-06-24T10:05:00Z"
  }
}

使用方式：

• 每个阶段开始时：读取此文件，确认前置阶段已完成
• 每个阶段结束时：更新此文件，标记当前阶段完成
• 用户下次调用时：直接从 nextPhase 继续

集成到 SKILL.md：

## 执行前检查

1. 读取 `.sm-flow-state` 文件
2. 确认当前阶段的前置阶段已完成
3. 如有缺失，汇报并询问是否补做

建议 5: Context 阶段增加必读清单

位置：references/phase-contracts.md - Context 阶段

增加内容：

## Context 阶段必读文件

按顺序读取（即使文件不存在也要尝试）：

1. **devflow/index.md** - 项目索引
   - 查找相关领域的历史项目
   - 识别可能相关的关键词
   
2. **devflow/glossary/CONTEXT.md** - 术语表
   - 提取项目术语和业务规则
   
3. **相关项目的 decisions.md** - 历史决策
   - 从 index.md 中识别的相关项目
   - 读取其决策，避免重复或冲突
   
4. **devflow/compound/*.md** - 可复用知识
   - 查找可复用的设计模式、经验

**如果文件不存在**：
- 记录"无历史上下文"
- 在 proposal.md 中标注"首次相关实现"
- 继续执行

建议 6: 增加"违规自检"机制

目标：每个阶段结束前，自动检查是否违反硬约束

实现：在每个阶段的退出条件后增加"自检清单"

## [阶段名] 退出前自检

检查以下硬约束是否违反：

- [ ] 是否跳过了 context？
      检查：是否读取了 devflow/index.md？
      
- [ ] 是否跳过了 grill？
      检查：decisions.md 中是否记录了至少 3 个澄清问题？
      
- [ ] 是否跳过了 commit？
      检查：是否存在 .committed 文件？
      
- [ ] apply 是否基于 Committed OpenSpec？
      检查：apply 开始前是否读取了 OpenSpec 文件？
      
- [ ] 遇到冲突是否先分类？
      检查：冲突记录是否标记了类型（规格遗漏/实现偏差）？
      
- [ ] 是否调用了所有必需的子 skill？
      检查：阶段定义中要求的 skill 是否都调用了？

如有违规项，停止执行并汇报。

---

Low Priority（可选增强）

建议 7: Grill 阶段增加 Question Pool 模板

目标：帮助我提出高质量的澄清问题

位置：references/phase-contracts.md - Grill 阶段

增加内容：

## Grill Question Pool 模板

必须覆盖至少 3 个维度：

### 维度 1: 范围边界
模板问题：
- "Out of scope 里的 X 功能，为什么不在这次做？有什么依赖或风险？"
- "如果用户要求 Y，这个方案能扩展支持吗？需要改动多少？"
- "边界场景 Z 应该怎么处理？报错还是降级？"

### 维度 2: 技术风险
模板问题：
- "如果依赖的 A 服务挂了，这个方案有降级策略吗？"
- "为什么选择技术方案 B 而不是 C？主要考虑什么？"
- "数据量增长到 N 倍，性能瓶颈在哪里？"

### 维度 3: 用户验证
模板问题：
- "这个方案解决的核心痛点是什么？有真实场景吗？"
- "有没有现成的替代方案？为什么不用？"
- "如果上线后发现不符合预期，回滚成本多大？"

### 维度 4: 实现可行性
模板问题：
- "最复杂的部分是什么？有没有技术预研？"
- "需要改动哪些核心模块？影响面多大？"
- "有没有类似的历史实现可以参考？"

建议 8: 增加"快速模式"明确定义

当前问题：operating-rules.md 提到快速模式，但没说具体怎么做

建议：明确快速模式的简化规则

## 快速模式

### 触发条件
满足以下所有条件时，可使用快速模式：
- 变更小于 5 个文件
- 无架构变更
- 无数据库迁移
- 用户明确要求"快速"

### 简化规则
1. Grill 阶段：至少 1 个问题（而非 3 个）
2. Specify 阶段：tasks.md 可简化为 3 个子任务
3. Audit 阶段：可跳过（标注"快速模式跳过审计"）
4. Archive 阶段：使用 micro 分档（brief/decisions/acceptance）

### 不得简化
- Context 阶段：仍需读取 devflow
- Commit 阶段：仍需检查 OpenSpec 完整性
- Apply 阶段：仍需基于 Committed OpenSpec

---

执行机制优化建议

当前问题：约束是"软性"的

现象：

• 规则写得很清楚："不得跳过 commit"
• 但我仍然能跳过，没有强制机制

根本原因：

• 规则是"描述性"的（说应该做什么）
• 缺少"执行性"的机制（强制检查、文件依赖）

解决方案：引入"门控文件"

设计：

每个阶段完成后，创建一个标记文件：
- .context-done
- .grill-done
- .commit-done (即 .committed)
- .apply-done
- .archive-done

下一个阶段开始前，检查前置文件是否存在。

示例：Apply 阶段入口检查

if [ ! -f ".committed" ]; then
    echo "错误：Commit 阶段未完成"
    echo "缺失文件：.committed"
    echo "请先完成 commit 阶段，或显式跳过（需用户确认）"
    exit 1
fi

好处：

1. 强制执行顺序（无法跳过）
2. 可视化进度（ls 就能看到哪些阶段完成了）
3. 支持断点续做（下次执行自动识别位置）

---

用户体验优化

当前问题：用户不知道"现在在哪"

场景：

• 用户说"继续"
• 我不知道该从哪个阶段继续

建议：每次开始时，主动汇报状态

开始执行 SM Flow...

当前状态：
✅ Context 已完成
✅ Propose 已完成
⏸️ Grill 未开始 ← 当前阶段

下一步：执行 Grill 阶段（人类对齐澄清）
预计耗时：5-10 分钟

建议：增加"进度条"

SM Flow 进度：
[✅] Clarify
[✅] Context
[✅] Propose
[⏸️] Grill ← 当前
[ ] Specify
[ ] Audit
[ ] Commit
[ ] Apply
[ ] Archive

---

总结

核心问题

1. Commit 检查缺少可执行标准（导致容易跳过）
2. Apply 阶段缺少前置门控（没有强制检查 .committed）
3. Archive 阶段缺少 Checklist（容易遗漏 devflow）
4. 缺少流程状态追踪（不知道当前在哪）

优先修复（High Priority）

• ✅ Commit 检查增加 Checkpoint
• ✅ Apply 增加前置门控
• ✅ Archive 增加 Checklist

这三个修复后，绝大多数"跳过阶段"问题都能解决。

框架本身很好

• 架构清晰（9 个阶段、4 层架构）
• 规则明确（6 条硬约束）
• 文档详细（phase-contracts, archive-rules）

问题不是"约束不够"，而是"执行机制不够明确"。

增加可验证的 checkpoint 和门控文件后，我就很难"偷懒"了。