sm-flow v4.1: add pre-apply research checkpoint to reduce rework
Based on real execution review (shandong-intent-sync), apply phase suffered from 4-5 rework cycles due to insufficient upfront research. Changes: - grill: add technical implementation dimension to question pool - apply: add mandatory pre-apply checkpoint (15-20min research) - read reference implementations thoroughly - grep key tech stack patterns - form tech stack checklist in decisions.md - apply: add incremental implementation guidance - apply: add first-module alignment check - apply: add fast-fail rule (≥2 rework → pause) Expected impact: - Rework: 4-5 cycles → 0-1 cycle (-80%) - Core feature empty impl: 100% → 0% - ROI: 200% (invest 20min, save 60min) Complexity: +55 lines to phase-contracts.md (+20%) Approach: simplified version (plan B) to balance value vs overhead Docs: - phase-contracts.md: updated grill + apply phases - workflow.md: added v4.1 evolution chapter - phase-contracts-v4.1-changelog.md: detailed change log - sm-flow-execution-review-shandong-intent-sync.md: source review
This commit is contained in:
zhuyongxin
@@ -819,3 +819,137 @@ v4：
|
||||
### 后续观察项
|
||||
|
||||
问题 1 和 2 暂不改协议，如果多次验证中反复出现再考虑加约束。问题 3 需要在下次 specify 阶段验证：spec scenario 是否自然地描述用户行为而非实现细节。
|
||||
|
||||
## v4.1：Apply 阶段前置调研增强（2026-06-23）
|
||||
|
||||
### 背景
|
||||
|
||||
基于"山东商客意向单同步接口"的执行复盘（`skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`），发现 apply 阶段存在严重的返工问题：
|
||||
|
||||
- **返工次数**：4-5 次重大返工
|
||||
- **核心问题**：apply 阶段"想当然"开始写代码，缺少充分调研和分步验证
|
||||
- **主要表现**：
|
||||
- 参考实现利用不充分（设计文档提到参考实现，但直到用户提醒才去看）
|
||||
- 技术栈不熟悉（RequestMsg 结构、Kafka 发送方式、Consumer 位置全部返工）
|
||||
- 设计-实现偏离（验签/解密/查询接口只有 TODO 注释）
|
||||
|
||||
### 核心改进：Pre-apply Checkpoint
|
||||
|
||||
在 apply 阶段开始前增加强制性调研检查点（方案 B 简化版）：
|
||||
|
||||
#### 修改 1：grill 阶段增加技术实现维度
|
||||
|
||||
在 question pool 中新增"技术实现维度"：
|
||||
|
||||
```markdown
|
||||
**技术实现维度**（新增）：当 proposal 提到参考实现、或涉及项目现有基础设施时，增加技术澄清问题：
|
||||
- 参考实现的具体文件路径是什么？
|
||||
- 项目现有的 [请求结构/MQ/缓存/加密/工具类] 标准是什么？
|
||||
- 有哪些技术点需要先调研或新建？
|
||||
```
|
||||
|
||||
**目的**：在 grill 阶段就识别技术调研需求，避免 apply 时才发现技术栈不熟悉。
|
||||
|
||||
#### 修改 2：apply 阶段增加 Pre-apply Checkpoint
|
||||
|
||||
在 apply 阶段开始前增加 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 实现过程增强
|
||||
|
||||
**分步实现**：建议按 Controller → Service → MQ/异步组件 → Consumer/下游 顺序，每完成一层验证后再继续。
|
||||
|
||||
**首模块完成后对齐检查**：完成第一个接口/模块后，对比 OpenSpec design/tasks，标记"已完成/TODO"；核心功能（加密/验签/核心业务逻辑）不允许空实现或纯 TODO 注释。
|
||||
|
||||
**快速失败**：连续返工 ≥ 2 次时，暂停并重新执行 pre-apply checkpoint 或向用户汇报。
|
||||
|
||||
#### 修改 4：apply 退出条件增强
|
||||
|
||||
新增退出条件：
|
||||
- ✅ 已完成 pre-apply checkpoint（如触发条件满足），技术栈清单已写入 `decisions.md`
|
||||
- ✅ 核心功能已实现或明确标注"待联调"，无纯 TODO 占位
|
||||
|
||||
### 预期效果
|
||||
|
||||
| 指标 | 当前 | 目标 | 改善 |
|
||||
|------|------|------|------|
|
||||
| 返工次数 | 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%
|
||||
```
|
||||
|
||||
### 复杂度评估
|
||||
|
||||
**本次修改复杂度**：中等
|
||||
- 文本增量：+55 行（从 281 行 → 336 行，+20%）
|
||||
- 概念层级：+1 层（apply 内部增加 Pre-apply Checkpoint 子阶段）
|
||||
- 强制规则：+5 条（pre-apply 触发条件、执行步骤、输出要求）
|
||||
|
||||
**整体复杂度**：高（但合理）
|
||||
- 总行数：606 行 → ~700 行（+15%）
|
||||
- 阶段数：9 个（不变）
|
||||
- 门控数：4 个 → 6 个（+propose checkpoint, +pre-apply checkpoint）
|
||||
|
||||
**简化设计**：
|
||||
- 采用方案 B（简化版），相比完整方案减少 45% 文本量和 44% 规则数
|
||||
- 保留核心价值（前置调研、技术栈清单、核心功能质量保证）
|
||||
- 去掉过度约束（严格执行顺序、频繁检查点、详细操作模板）
|
||||
|
||||
### 适用场景
|
||||
|
||||
✅ **强烈推荐**：
|
||||
- 中等及以上规模需求（3+ 接口或涉及多模块）
|
||||
- 涉及项目现有基础设施（MQ/统一请求结构/工具类）
|
||||
- 第一次在该项目实现类似功能
|
||||
- 设计文档提到"参考 XXX 实现"
|
||||
|
||||
🟡 **可选执行**：
|
||||
- micro 分档的简单需求（可缩短为 5-10 分钟）
|
||||
- 纯数据处理或工具脚本（技术栈熟悉）
|
||||
|
||||
❌ **不推荐**：
|
||||
- 紧急热修复（时间紧急）
|
||||
- 一次性脚本（不涉及项目标准）
|
||||
|
||||
### 相关文档
|
||||
|
||||
- 执行复盘：`skill-workbench/docs/sm-flow/sm-flow-execution-review-shandong-intent-sync.md`
|
||||
- 更新日志：`skill-workbench/docs/sm-flow/phase-contracts-v4.1-changelog.md`
|
||||
- 修改文件：`.agents/skills/sm-flow/references/phase-contracts.md`
|
||||
|
||||
Reference in New Issue
Block a user