Demo Verify（设计验证）

在投入完整开发之前，用最小代价验证设计是否可行。

定位

design-craft → demo-verify（可选）→ 完整开发
    技术设计      验证风险点         验证通过后开始

• 输入：design-craft 产出的设计文档
• 输出：验证报告 + 决策建议（继续 / 回退 / 调整）
• 边界：只验证风险点，不做完整实现

核心原则

1. 风险驱动：只验证不确定的部分，不重复验证已知可行的部分
2. 最小实现：能跑通就行，不追求代码质量、不处理边界情况
3. 可丢弃：原型代码是临时的，开发完成后删除
4. 自动触发：根据设计复杂度自动判断是否需要验证，不需要用户手动触发
5. 结论明确：每个风险点必须给出明确结论——通过 / 不通过 / 有条件通过

触发条件

满足以下任一条件时自动触发：

条件	判定方式
涉及未使用过的技术/库/API	设计文档中出现项目未使用过的依赖
涉及性能敏感路径	设计中提到并发、大数据量、实时性要求
涉及第三方系统集成	设计中包含外部 API/服务调用
方案有多个备选	设计文档中列出多个方案并需要选择
用户明确要求	用户说"先验证"、"做个 demo"、"试试看"

不触发的情况：

• 简单 CRUD，无技术风险
• 纯 UI 变更，无后端逻辑变化
• 已有类似实现可参考

工作流总览

阶段 1：风险识别        → 从设计文档中提取风险点
阶段 2：验证范围        → 确定最小验证集
阶段 3：实现原型        → 在独立目录中构建可运行代码
阶段 4：验证评估        → 对每个风险点给出结论
阶段 5：决策与清理      → 继续/回退/调整，保留或删除原型

---

阶段 1：风险识别

从 design-craft 产出的设计文档中提取不确定的技术点。

风险类型

风险类型	特征	示例
技术可行性	使用项目未用过的技术	"引入 Redis 做分布式锁"
性能风险	涉及高并发/大数据量/实时性	"支持 1000 QPS 的查询"
集成风险	调用第三方 API/服务	"对接支付宝支付接口"
方案选择	设计中有多个备选方案	"方案 A 用消息队列，方案 B 用轮询"
数据一致性	分布式/并发场景的一致性保证	"多节点间的数据同步"

输出格式

⚠️ 风险识别
━━━━━━━━━━━━━━━━

| 编号 | 风险点 | 风险类型 | 来源（设计文档章节） | 验证必要性 |
|------|--------|----------|---------------------|-----------|
| R-01 | Redis 分布式锁的实现可行性 | 技术可行性 | 方案设计章 | 必须验证 |
| R-02 | 查询接口在 1000 QPS 下的响应时间 | 性能风险 | 性能考虑章 | 必须验证 |
| R-03 | 支付宝回调的可靠性 | 集成风险 | 接口设计章 | 建议验证 |

请确认风险点是否完整。

---

阶段 2：验证范围

为每个风险点确定最小验证集——只做能验证结论的最少工作。

验证范围定义

风险点	验证内容	不验证内容
Redis 分布式锁	加锁/解锁/超时释放	集群部署、持久化、监控
1000 QPS 查询	单接口压测结果	全链路压测、缓存预热
支付宝回调	回调接收+验签+状态更新	完整支付流程、退款

输出格式

🎯 验证范围
━━━━━━━━━━━━━━━━

| 风险点 | 验证内容 | 最小实现 | 预估工作量 |
|--------|----------|----------|-----------|
| R-01 | 加锁/解锁/超时 | 单文件脚本 | 30 分钟 |
| R-02 | 单接口压测 | 压测脚本 + 接口 | 45 分钟 |
| R-03 | 回调接收+验签 | Mock 服务 | 30 分钟 |

请确认验证范围是否合理。

---

阶段 3：实现原型

在独立目录中构建可运行的验证代码。

原型规则

• 独立目录：所有原型代码放在 {项目根目录}/.demo-verify/ 目录下
• 最小实现：只覆盖核心路径，不处理异常、不做日志、不做配置
• 可运行：必须能实际运行并产生结果，不能只是伪代码
• 自包含：原型代码应该能独立运行，不依赖项目的其他部分
• 标注目的：每个文件开头注释说明验证目的

目录结构

.demo-verify/
├── README.md              # 验证目标和结论
├── R-01_redis-lock/       # 风险点 R-01 的验证代码
│   └── test_lock.py
├── R-02_perf-query/       # 风险点 R-02 的验证代码
│   ├── server.py
│   └── benchmark.py
└── R-03_alipay-callback/  # 风险点 R-03 的验证代码
    └── mock_callback.py

输出格式

🔨 原型实现
━━━━━━━━━━━━━━━━

已完成：
- R-01：Redis 分布式锁验证 → .demo-verify/R-01_redis-lock/
- R-02：查询性能验证 → .demo-verify/R-02_perf-query/
- R-03：支付宝回调验证 → .demo-verify/R-03_alipay-callback/

---

阶段 4：验证评估

运行原型代码，对每个风险点给出明确结论。

结论类型

结论	含义	后续动作
✅ 通过	风险已消除，方案可行	进入完整开发
⚠️ 有条件通过	方案可行但需要调整	标注调整项，更新设计文档
❌ 不通过	方案不可行	回退到 design-craft 重新设计

输出格式

📊 验证报告
━━━━━━━━━━━━━━━━

【R-01：Redis 分布式锁】
- 结论：✅ 通过
- 依据：加锁/解锁/超时释放均正常，单机 10000 次操作无死锁
- 备注：生产环境需考虑 Redis 集群部署

【R-02：查询性能】
- 结论：⚠️ 有条件通过
- 依据：单接口 800 QPS 时 P99 延迟 120ms，未达标（目标 50ms）
- 调整项：需要增加缓存层，设计文档需补充缓存策略

【R-03：支付宝回调】
- 结论：✅ 通过
- 依据：回调接收、验签、状态更新均正常，网络超时后重试机制有效

【整体决策】
- R-01、R-03：可直接进入开发
- R-02：需要更新设计文档（补充缓存策略），更新后可进入开发

---

阶段 5：决策与清理

决策

整体结论	后续动作
全部 ✅	进入完整开发
存在 ⚠️	更新设计文档中的调整项，然后进入开发
存在 ❌	回退到 design-craft，基于验证发现重新设计

原型清理

• 开发期间：原型保留在 .demo-verify/ 目录，作为开发参考
• 开发完成后：删除整个 .demo-verify/ 目录
• 在 design-craft 的阶段 5（落盘归档）中：提醒用户清理原型目录

输出格式

✅ 验证完成

📄 验证报告：<路径>
📁 原型目录：.demo-verify/（开发完成后删除）

决策：[进入开发 / 更新设计后进入开发 / 回退设计]

下一步：
- [如继续] 进入完整开发
- [如需更新] 更新 design-craft 文档中的 [具体章节]
- [如回退] 回退到 design-craft 阶段 [X]

---

与 design-craft 的衔接

• 输入：design-craft 产出的设计文档
• 输出：验证报告，可能触发 design-craft 的回退或增量变更
• 清理：design-craft 阶段 5 落盘时提醒删除 .demo-verify/ 目录

反模式

• ❌ 所有需求都做验证 → 只在有真实风险时触发，简单需求直接开发
• ❌ 原型写成生产代码 → 原型是临时的，不需要代码质量
• ❌ 验证范围过大 → 只验证风险点，不验证 happy path
• ❌ 结论模糊（"大概可行"）→ 每个风险点必须有明确的通过/不通过
• ❌ 忘记清理原型 → 开发完成后必须删除 .demo-verify/ 目录
• ❌ 验证失败后硬继续 → 发现方案不可行必须回退，不能硬着头皮开发
• ❌ 验证失败即判方案不可行 → 先调用 use_skill("debug") 区分「方案本身不可行」与「原型实现有 Bug」：后者可修复后复验，误判会把可行方案错杀

需求管理集成

当项目配置了 .requirements/config 时，demo-verify 在阶段 5（决策与清理）后自动执行以下集成操作：

自动触发条件

项目中存在 .requirements/config 且 storage_path 指向有效目录。

集成步骤

1. 获取需求上下文：验证前，如果关联了 REQ-ID，先读取需求信息作为验证参照：

req list --id {REQ-NNN} --deps

2. 写入验证报告和 demo 代码到需求目录后，调用 req update 注册文档关联：

req update {REQ-NNN} \
  --docs add demo/verify-report.md,demo --changelog "完成设计验证"

3. demo 代码迁移：将 .demo-verify/ 下的 demo 代码复制到需求目录的 demo/ 子目录（而非 .demo-verify/），作为需求产出物的持久化部分。复制完成后删除 .demo-verify/ 临时目录。

4. 错误处理：

   • 需求 ID 不存在 → 提示用户先创建需求，跳过集成
   • 文件锁超时 → 自动重试 1 次，仍失败则告知用户

存储路径映射

产出物	存储路径	docs 类型
验证报告	demo/verify-report.md	demo
demo 代码	demo/ 目录下	—