# SM Flow Phase Contracts v4.1 更新日志

> 更新日期: 2026-06-23  
> 更新原因: 基于"山东商客意向单同步接口"执行复盘  
> 更新方案: 方案 B（简化版）

---

## 更新概览

**核心目标**: 减少 apply 阶段的返工次数（从 4-5 次降低到 0-1 次）

**更新范围**:
- ✅ grill 阶段：增加技术实现维度
- ✅ apply 阶段：增加 Pre-apply Checkpoint

**文本增量**: +55 行（从 281 行 → 336 行，+20%）

---

## 详细修改

### 1. grill 阶段 — 增加技术实现维度

**修改位置**: `phase-contracts.md` 第 85-88 行

**新增内容**:
```markdown
- **技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
  - 参考实现的具体文件路径是什么？
  - 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
  - 有哪些技术点需要先调研或新建？
```

**目的**: 在 grill 阶段就识别技术调研需求，避免 apply 时才发现技术栈不熟悉。

---

### 2. apply 阶段 — 增加 Pre-apply Checkpoint

**修改位置**: `phase-contracts.md` 第 234-265 行

**新增章节**: Pre-apply Checkpoint（15-20 分钟）

#### 触发条件（3 条）
- design 或 tasks 中提到"参考 XXX 实现"
- 需要调用项目现有基础设施（MQ/统一请求结构/工具类等）
- 技术栈不熟悉或第一次在该项目实现类似功能

#### 执行步骤（3 步）
1. **完整阅读所有参考实现**（约 10 分钟）
   - 从 OpenSpec design 或 tasks 中定位参考实现文件
   - 如果路径不明确，通过 Grep 搜索关键类名或模式
   - 逐行理解关键逻辑，提取可复用代码片段和模式

2. **Grep 关键技术栈**（约 5 分钟）
   - 请求/响应结构模式
   - 消息队列模式
   - 统一工具类
   - 异常处理和日志记录标准

3. **形成技术栈清单并写入 decisions.md**
   - 项目使用的请求/响应结构标准
   - MQ 消息定义和发送标准
   - Consumer 标准位置和写法
   - 加密/验签/工具类的标准用法
   - 识别需要新建的工具类或基础设施

#### 输出要求（3 条）
- ✅ 技术栈清单已写入 `decisions.md` 的 "Pre-apply Research" 章节
- ✅ 已列出所有参考实现的文件路径
- ✅ 已识别需要新建的工具类/基础设施

#### 快速模式支持
- micro 分档可缩短为 5-10 分钟快速扫描，但仍需形成清单

---

### 3. apply 阶段 — 实现过程增强

**修改位置**: `phase-contracts.md` 第 267-284 行

**新增要求**:
- **分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序
- **首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能不允许空实现或纯 TODO 注释
- **快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报

---

### 4. apply 阶段 — 退出条件增强

**修改位置**: `phase-contracts.md` 第 286-292 行

**新增退出条件**:
- ✅ 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`
- ✅ 核心功能已实现或明确标注"待联调"，无纯 TODO 占位

---

## 简化对比

### 与完整方案对比

| 维度 | 完整方案 | 简化方案 B | 差异 |
|------|----------|-----------|------|
| 文本增量 | +100 行 | +55 行 | -45% |
| 子阶段数 | 3 个（Phase 1/2/3） | 1 个（Pre-apply Checkpoint） | -67% |
| 强制规则 | 9 条 | 5 条 | -44% |
| 检查清单 | 2 个详细清单 | 1 个简化清单 | -50% |
| 时间分档 | 3 档（15/20/30 分钟） | 1 档（15-20 分钟） | -67% |

### 保留核心价值

✅ **保留**（解决返工问题）:
- 前置调研（最重要）
- 技术栈清单（防止想当然）
- 核心功能不能空实现（保证质量）
- 快速失败机制

❌ **简化**（去掉过度约束）:
- 严格的执行顺序
- 频繁的检查点
- 详细的操作指南模板

---

## 预期效果

### 量化指标

| 指标 | 当前 | 目标 | 改善 |
|------|------|------|------|
| 返工次数 | 4-5 次 | 0-1 次 | -80% |
| 核心功能空实现率 | 高（3/3 核心功能） | 0% | -100% |
| 实现时间（含返工） | 2 小时 | 1.5 小时 | -25% |
| 前置调研时间 | 0 分钟 | 15-20 分钟 | +20 分钟 |

### ROI 分析

```
投入: 15-20 分钟调研
回报: 节省 60 分钟返工 + 避免核心功能遗漏
ROI = (60 - 20) / 20 = 200%
```

---

## 适用场景

### ✅ 强烈推荐

- 中等及以上规模需求（3+ 接口或涉及多模块）
- 涉及项目现有基础设施（MQ/统一请求结构/工具类）
- 第一次在该项目实现类似功能
- 设计文档提到"参考 XXX 实现"

### 🟡 可选执行

- micro 分档的简单需求（可缩短为 5-10 分钟）
- 纯数据处理或工具脚本（技术栈熟悉）

### ❌ 不推荐

- 紧急热修复（时间紧急）
- 一次性脚本（不涉及项目标准）

---

## 后续优化方向

### 短期（1-2 个需求后）

- 收集数据：实际调研时间、返工次数、遗漏率
- 验证效果：是否达到预期 ROI
- 调整参数：时间要求、触发条件

### 中期（观察 5+ 个需求后）

如果效果显著，考虑升级为完整方案：
- 增加 Alignment Checkpoint（每模块对齐检查）
- 增加详细的技术栈清单模板
- 增加分步实现的每步验证要求

### 长期（跨项目验证后）

- 提取通用技术栈清单模板（Java/Go/Python 等）
- 建立参考实现库（常见模式的最佳实践）
- 自动化部分调研步骤（Grep 脚本、清单生成）

---

## 实施检查清单

### 立即验证

- [ ] `phase-contracts.md` 文件已更新
- [ ] grill 阶段增加了技术实现维度
- [ ] apply 阶段增加了 Pre-apply Checkpoint
- [ ] apply 退出条件增加了 2 条新检查
- [ ] 文件语法无误，可以正常解析

### 下次执行验证

- [ ] agent 是否正确识别触发条件
- [ ] agent 是否执行了完整的 3 步调研
- [ ] 技术栈清单是否写入 decisions.md
- [ ] 是否有效减少了返工次数
- [ ] 核心功能是否避免了空实现

---

## 附录：复盘案例链接

- 原始复盘文档: `skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`
- 修改前版本: phase-contracts.md (commit: 待补充)
- 修改后版本: phase-contracts.md (commit: 待补充)