Demo Verify

---
name: demo-verify
description: 在完整开发之前，针对设计中的风险点构建可运行的验证原型，确认设计可行后再投入开发。仅在复杂/高风险需求中自动触发。适用场景：设计涉及未使用过的技术/API、性能敏感路径、第三方系统集成、有多个备选需要对比、用户要求"先做个 demo 验证"。输入设计文档，输出验证报告和决策建议。
---

# 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 用轮询" |
| **数据一致性** | 分布式/并发场景的一致性保证 | "多节点间的数据同步" |

### 输出格式

```text
⚠️ 风险识别
━━━━━━━━━━━━━━━━

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

请确认风险点是否完整。
```

---

## 阶段 2：验证范围

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

### 验证范围定义

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

### 输出格式

```text
🎯 验证范围
━━━━━━━━━━━━━━━━

| 风险点 | 验证内容 | 最小实现 | 预估工作量 |
|--------|----------|----------|-----------|
| 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
```

### 输出格式

```text
🔨 原型实现
━━━━━━━━━━━━━━━━

已完成：
- 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 重新设计 |

### 输出格式

```text
📊 验证报告
━━━━━━━━━━━━━━━━

【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（落盘归档）中**：提醒用户清理原型目录

### 输出格式

```text
✅ 验证完成

📄 验证报告：<路径>
📁 原型目录：.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，先读取需求信息作为验证参照：

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

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

```bash
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/` 目录下 | — |