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
@@ -0,0 +1,216 @@
|
||||
# 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: 待补充)
|
||||
@@ -0,0 +1,293 @@
|
||||
# SM Flow 执行复盘 - 山东商客意向单同步接口
|
||||
|
||||
> 项目: yingke-platform
|
||||
> 需求: 385 山东公司商机信息同步接口
|
||||
> 执行日期: 2026-06-23
|
||||
> 复盘人: Claude Code
|
||||
|
||||
---
|
||||
|
||||
## 执行概况
|
||||
|
||||
- **需求规模**: 中等（3个接口 + Kafka消费 + 数据库变更）
|
||||
- **总耗时**: 约 2 小时（含多次返工）
|
||||
- **返工次数**: 4-5 次重大返工
|
||||
- **最终状态**: 核心代码完成，但验签/解密/查询接口未实现
|
||||
|
||||
---
|
||||
|
||||
## 发现的问题
|
||||
|
||||
### 1. 前置调研不足，导致多次返工
|
||||
|
||||
#### 问题表现
|
||||
|
||||
| 返工点 | 初次实现（错误） | 返工后（正确） | 浪费时间 |
|
||||
|--------|------------------|----------------|----------|
|
||||
| RequestMsg 结构 | 自创 `SyncIntentOrderReq/Resp` | 使用项目标准 `RequestMsg<T>` | 15 分钟 |
|
||||
| Kafka 发送方式 | `SendMessageTunnel` + `TaskTypeEnum` | `ykMqTemplate` + `@YkMsg` | 20 分钟 |
|
||||
| Consumer 模块位置 | order-service 模块 | web 模块（参考案例位置） | 10 分钟 |
|
||||
| 透传字段结构 | Map → DTO → 最终平铺 | 应一次到位平铺到 Msg | 15 分钟 |
|
||||
|
||||
**根本原因**: apply 阶段直接开始写代码，没有充分调研现有代码模式。
|
||||
|
||||
#### 改进建议
|
||||
|
||||
**在 apply 阶段前增加强制调研步骤**（pre-apply research checkpoint）：
|
||||
|
||||
1. **阅读所有参考实现**（设计文档中明确提到的）
|
||||
- 完整阅读参考代码，而不是凭想象
|
||||
- 提取关键模式：请求结构、Kafka 使用、模块划分
|
||||
|
||||
2. **Grep 关键技术栈**
|
||||
```bash
|
||||
grep -r "@YkMsg" --include="*.java"
|
||||
grep -r "ykMqTemplate" --include="*.java"
|
||||
grep -r "RequestMsg<" --include="*.java"
|
||||
```
|
||||
|
||||
3. **形成"技术栈清单"文档**（临时产物）
|
||||
```markdown
|
||||
- 项目使用 RequestMsg<T> 作为统一请求包装
|
||||
- Kafka 消息使用 @YkMsg + MsgData + ykMqTemplate.sendAsync()
|
||||
- Consumer 统一放在 web 模块的 manager/stream/consumer
|
||||
```
|
||||
|
||||
4. **调研时间要求**: 不少于 15 分钟，复杂需求可延长至 30 分钟
|
||||
|
||||
---
|
||||
|
||||
### 2. 设计文档与实现偏离，缺少一致性检查
|
||||
|
||||
#### 问题表现
|
||||
|
||||
| 设计文档要求 | 实际实现 | 偏离程度 |
|
||||
|--------------|----------|----------|
|
||||
| Controller 层 SM3 验签 | 只有 TODO 注释 | ❌ 核心功能缺失 |
|
||||
| Service 层 AES256-GCM 解密 | 只有 TODO 注释 | ❌ 核心功能缺失 |
|
||||
| queryIntentOrder 调用一体化客服 | 空实现 | ❌ 核心功能缺失 |
|
||||
| syncIntentOrder 同步调用 | 改为 Kafka 异步 | ⚠️ 架构差异（可能合理） |
|
||||
|
||||
**根本原因**: apply 阶段没有"设计-实现对齐检查点"。
|
||||
|
||||
#### 改进建议
|
||||
|
||||
**在 apply 阶段中增加对齐检查点**（alignment checkpoint）：
|
||||
|
||||
1. **每完成 1 个接口/模块，立即对比设计文档**
|
||||
- 逐条核对设计文档的任务清单
|
||||
- 标记"已完成/部分完成/TODO"
|
||||
|
||||
2. **核心功能不允许"TODO 占位"直接通过**
|
||||
- 加密/解密、验签、核心业务逻辑必须实现或明确标注"待联调"
|
||||
- 区分"框架完整但待联调"（✅） vs "空实现"（❌）
|
||||
|
||||
3. **架构差异必须显式记录并询问用户**
|
||||
- 设计说同步，实现改异步 → 必须记录原因并确认
|
||||
- 创建 `decisions.md` 记录所有偏离设计的架构决策
|
||||
|
||||
---
|
||||
|
||||
### 3. 分步验证不足，一次写太多代码
|
||||
|
||||
#### 问题表现
|
||||
|
||||
- 一次性写完 Controller + Service + Kafka + Consumer，然后发现 RequestMsg 结构错了
|
||||
- 没有"写一点 → 编译 → 确认方向"的小步迭代
|
||||
|
||||
#### 改进建议
|
||||
|
||||
**强制分步验证**（incremental validation）：
|
||||
|
||||
1. **Controller 层先行**
|
||||
- 只写 Controller + 最小 Service 骨架
|
||||
- 确认请求/响应结构正确
|
||||
- 编译通过后再继续
|
||||
|
||||
2. **Kafka 发送独立验证**
|
||||
- 写完发送逻辑，先打印 JSON 确认消息格式
|
||||
- 再写 Consumer
|
||||
|
||||
3. **Consumer 最后实现**
|
||||
- 基于已确认的消息格式实现
|
||||
|
||||
---
|
||||
|
||||
### 4. 参考案例利用不充分
|
||||
|
||||
#### 问题表现
|
||||
|
||||
- 设计文档明确提到"参考 AddIntentOrderOutSystemDealTunnel"
|
||||
- 但实际执行时，直到用户提醒才去看参考实现
|
||||
- 之前都在凭想象写，导致返工
|
||||
|
||||
#### 改进建议
|
||||
|
||||
**强制参考案例优先**（reference-first approach）：
|
||||
|
||||
1. **grill 阶段就应该找出所有参考案例**
|
||||
- 不要只记录"参考 XXX"，而是实际阅读并提取模式
|
||||
|
||||
2. **apply 前必须完整阅读参考实现**
|
||||
- 不是"扫一眼"，而是逐行理解关键逻辑
|
||||
- 提取可复用的代码片段
|
||||
|
||||
3. **参考案例模式提取清单**（临时文档）
|
||||
```markdown
|
||||
## AddIntentOrderOutSystemDealTunnel 关键模式
|
||||
|
||||
1. Consumer 方法签名: `public void onXXX(XXXMsg msgBO)`
|
||||
2. 调用链: msg → AES加密 → OnlineOpportunityApi → 回填状态
|
||||
3. 异常处理: try-catch → updateStatus(EXCEPTION) → throw
|
||||
4. 成功判断: isSyncSuccess() 三层校验
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### 5. grill 阶段澄清不够深入
|
||||
|
||||
#### 问题表现
|
||||
|
||||
- grill 阶段问了业务问题（省份校验、透传字段），但没有问技术实现问题
|
||||
- 导致后续实现时才发现技术栈不熟悉
|
||||
|
||||
#### 改进建议
|
||||
|
||||
**grill 阶段增加技术实现澄清**：
|
||||
|
||||
除了业务澄清，还应该包括：
|
||||
|
||||
1. **技术栈确认问题**
|
||||
- "项目现有的 Kafka 消息怎么定义和发送？"
|
||||
- "RequestMsg/ResponseMsg 的标准用法是什么？"
|
||||
- "类似接口的 Controller/Service 是怎么写的？"
|
||||
|
||||
2. **参考实现确认**
|
||||
- "设计文档提到的参考实现是哪些文件？"
|
||||
- "这些参考实现的核心模式是什么？"
|
||||
|
||||
3. **技术风险识别**
|
||||
- "有哪些技术点我不熟悉，需要先调研？"
|
||||
|
||||
---
|
||||
|
||||
## 改造建议汇总
|
||||
|
||||
### 方案 A: 在现有 9 阶段中增强（保守）
|
||||
|
||||
```
|
||||
clarify → context → propose → grill+ → specify → audit → commit → pre-apply+ → apply+ → archive
|
||||
↑ ↑ ↑
|
||||
增加技术澄清 增加调研 增加检查点
|
||||
```
|
||||
|
||||
**修改点**：
|
||||
|
||||
1. **grill 阶段**：增加技术实现澄清问题模板
|
||||
2. **apply 阶段前**：增加 pre-apply research checkpoint（15-30分钟）
|
||||
3. **apply 阶段中**：增加 alignment checkpoint（每完成1个模块对比设计文档）
|
||||
|
||||
### 方案 B: 新增独立调研阶段（激进）
|
||||
|
||||
```
|
||||
clarify → context → propose → grill → research → specify → audit → commit → apply → archive
|
||||
↑
|
||||
新增独立调研阶段
|
||||
```
|
||||
|
||||
**新阶段 research**：
|
||||
|
||||
- **输入**: proposal + 参考实现列表
|
||||
- **输出**: 技术栈清单 + 参考模式提取 + 风险评估
|
||||
- **时间**: 15-30 分钟
|
||||
- **产物**: `research.md`（临时文档，archive 时删除）
|
||||
|
||||
**research.md 结构**：
|
||||
|
||||
```markdown
|
||||
# 技术调研 - [需求名称]
|
||||
|
||||
## 参考实现分析
|
||||
|
||||
### AddIntentOrderOutSystemDealTunnel
|
||||
- 文件位置: web/manager/stream/consumer/...
|
||||
- 关键模式:
|
||||
- Consumer 定义: @YkMqConsumer + MsgData 子类
|
||||
- 调用链: ...
|
||||
|
||||
## 技术栈清单
|
||||
|
||||
- 请求结构: RequestMsg<T> / ResponseMsg<T>
|
||||
- Kafka: @YkMsg + ykMqTemplate.sendAsync()
|
||||
- 加密: AESUtil.encryptAES() (AES-128 ECB)
|
||||
|
||||
## 风险点
|
||||
|
||||
- AES256-GCM 工具类不存在，需要新建
|
||||
- 验签逻辑没有现成拦截器，需要在 Service 层实现
|
||||
```
|
||||
|
||||
### 推荐方案
|
||||
|
||||
**方案 A**（渐进增强）：
|
||||
|
||||
1. 对现有流程影响小
|
||||
2. 实施成本低
|
||||
3. 可以立即生效
|
||||
|
||||
**具体实施**：
|
||||
|
||||
- 修改 `phase-contracts.md` 的 grill 和 apply 阶段规范
|
||||
- 增加 checkpoint 描述
|
||||
- 更新 question pool 增加技术澄清问题
|
||||
|
||||
---
|
||||
|
||||
## 其他建议
|
||||
|
||||
### 1. 增加"快速失败"机制
|
||||
|
||||
当发现以下情况，立即暂停并询问用户：
|
||||
|
||||
- 需要创建的类/接口在参考实现中有类似的（防止重复造轮）
|
||||
- 实现方式与设计文档明显偏离
|
||||
- 连续返工超过 2 次（说明方向可能错了）
|
||||
|
||||
### 2. 产物可观测性增强
|
||||
|
||||
在 apply 阶段，定期输出：
|
||||
|
||||
```markdown
|
||||
## 实现进度（每 30 分钟更新）
|
||||
|
||||
✅ Controller 层（已完成）
|
||||
- ShandongSyncController.syncIntentOrder
|
||||
- 请求结构使用 RequestMsg<ShandongIntentOrderData>
|
||||
|
||||
🚧 Service 层（进行中）
|
||||
- ShandongSyncService 接口完成
|
||||
- 实现类 70% 完成
|
||||
- ⚠️ 验签解密未实现（TODO）
|
||||
|
||||
⏳ Kafka 层（待开始）
|
||||
```
|
||||
|
||||
### 3. 设计文档质量要求
|
||||
|
||||
设计文档应该包含：
|
||||
|
||||
- ✅ 参考实现的具体文件路径（而不是只说"参考 XXX"）
|
||||
- ✅ 关键技术栈的使用示例（而不是只说"使用 Kafka"）
|
||||
- ✅ 数据流图（清晰展示同步/异步边界）
|
||||
|
||||
---
|
||||
|
||||
## 总结
|
||||
|
||||
**核心问题**: apply 阶段"想当然"开始写代码，缺少充分调研和分步验证。
|
||||
|
||||
**解决方向**: 在 apply 前增加强制调研步骤，在 apply 中增加对齐检查点。
|
||||
|
||||
**预期效果**: 返工次数从 4-5 次降低到 0-1 次，实现质量与设计文档一致性提升。
|
||||
|
||||
**立即可做**: 修改 `phase-contracts.md` 的 grill 和 apply 阶段规范即可生效。
|
||||
@@ -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