zhuyongxin
b94ee31cb1
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
6.3 KiB
6.3 KiB
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 行
新增内容:
- **技术实现维度**（新增）：当 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 步）
-
完整阅读所有参考实现（约 10 分钟）
- 从 OpenSpec design 或 tasks 中定位参考实现文件
- 如果路径不明确，通过 Grep 搜索关键类名或模式
- 逐行理解关键逻辑，提取可复用代码片段和模式
-
Grep 关键技术栈（约 5 分钟）
- 请求/响应结构模式
- 消息队列模式
- 统一工具类
- 异常处理和日志记录标准
-
形成技术栈清单并写入 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: 待补充)