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
217 lines
6.3 KiB
Markdown
217 lines
6.3 KiB
Markdown
# 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: 待补充)
|