---
name: req
description: 需求工作流管理。用于 /req 命令使用、需求全生命周期管理（创建→PRD→评审→开发→测试→部署→归档）。当用户提到需求管理、/req 命令、REQ-XXX 相关任务时自动激活。
metadata:
  arguments: <subcommand> [args]
---
## 需求生命周期

**审批状态**（status）：
```
draft ──[讨论]──► draft(已讨论) ──[PRD]──► pending ──[pass]──► approved ──► archived
          │                                    │
      与 AI 讨论                           [reject]
      明确方案                                 ▼
                                           rejected
```

**开发阶段**（delivery_stage，approved 后启用）：
```
analysis → design → dev → review → testing → [待部署池] → released
  评审       评审    开发   代码评审   测试    等待批量部署   已上线
```

**部署模型**：各需求独立走到 testing → 进入待部署池；`/req deploy` 一次构建批量推进到 released。

## ⭐ 关键约束

- **需求创建后，必须与 AI 进行一次需求讨论**，明确方案后再编写 PRD
- **讨论结束后必须输出方案确认摘要**（强制流程：讨论 → 摘要 → 用户确认 → PRD）：
  1. AI 输出结构化摘要（`## 讨论结论` 章节），`ai-proj req update` 追加到 description 末尾
  2. AskUserQuestion 确认：「方案确认通过」或「需要修改」
  3. **用户确认后才能开始 PRD 编写，禁止跳过确认**
- 需求描述三段式（技术方案写入 PRD，不写在需求中）：
  1. **需求描述** — 问题背景、现状痛点
  2. **预期结果** — 期望达到的效果
  3. **验收标准** — 可检查的完成条件（checklist，≥2 条）
- PRD 文档是提交评审的前置条件；代码评审是测试的前置条件
- **force=true 禁止自动使用** — 门禁未通过时必须 AskUserQuestion 确认 + 记录跳过原因
- **评审必须用户确认** — 禁止 AI 自审批
- **归档前 AC 逐条验收（Gate 0，强制）** — `/req done` 必须先提取需求描述中的验收标准逐条确认，无 AC 或有未确认项均阻断，用户必须提供证据或说明跳过原因
- **归档前类型化门禁检查** — Gate 0 通过后，`/req done` 再按需求类型（code/skill/ops）动态检查
- **部署是项目级动作**，由 `/req deploy` 统一触发
- **需求完成后必须 git 提交并 push** — commit 格式：`feat(skill): REQ-XXXX 需求标题`
- **操作前先确认实际 ID** — 从 URL 提取 ID（如 `/requirements/897` → ID=897）
- **务实路线关闭也必须补全关联任务** — 每个进度条阶段需创建关联任务
- **阶段内容门禁（防空转）** — `/req next` 时检查关键阶段任务是否有实质内容
- **复用盘点先于估工（Gate 5，强制）** — PRD 必须含「现有实现与复用盘点」章节：每个能力点给出**现有实现（file:line）+ 结论（复用 / 改造 / 新增）**；结论=复用/改造的只按「接入差异」估工，结论=新增的必须写「为什么现有实现不能满足」。没有 file:line 证据、或标「未排查」的，**禁止 submit、禁止按全新增估工**；独立复查由非 PRD 写作者用 grep 复核并在 note 留命令与命中结果
- **Harness 环境检测** — `/req dev` 启动开发前，快速检测项目基础设施（`.husky/` 存在？`scripts/check-*.sh` 存在？）。若两者都不存在（Level 0），输出一行提示：「项目无质量护栏，建议先运行 `/harness init`」。检测结果不阻塞开发，仅提示

## 禁止直接调用（必须走命令流程）

| 禁止直接调用 | 必须通过 | 原因 |
|-------------|---------|------|
| `ai-proj req create` with allowSelfApprove | `/req new` | 禁止自动提交，必须创建为 draft |
| `ai-proj req submit` (直接调用) | `/req submit` | 必须先通过 5 道门禁检查 |
| `ai-proj req archive` | `/req done` | 必须先执行类型化门禁检查 |
| `ai-proj req approve` | `/req review pass` | 必须先展示 PRD 摘要并等待用户确认 |
| `ai-proj req advance --to <stage>` (force) | `/req next` | 必须先 AskUserQuestion 确认 + 记录跳过原因 |

## 需求创建强制规则

```bash
# ✅ 正确：传完整业务字段
ai-proj req create \
  --title "需求标题" \
  --description "## 需求描述\n...\n## 预期结果\n...\n## 验收标准\n..." \
  --priority medium \
  --category feature \
  --due-date "2026-03-15"
# → 结果必定是 draft 状态
```

### 从 draft 到 submit 的 5 道门禁

```
Gate 1: 需求讨论 ── description 末尾有「## 讨论结论」章节
Gate 2: 方案确认 ── AskUserQuestion 获得「方案确认通过」
Gate 3: PRD 文档 ── linkRole=prd 的任务存在且有文档
Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD 存在
Gate 5: 复用盘点 ── PRD 有「现有实现与复用盘点」章节；每条能力点有 file:line 证据
        或「为什么不能复用」的理由；估工按 复用/改造/新增 分别计（无盘点 = 阻断）
```

## 完整工作流

```
1.  /req new         → 创建需求 (draft)
2.  需求讨论         → 输出结论摘要，用户确认
3.  req-prd 技能     → 编写 PRD（创建【评审】PRD 任务）
3.5 /req prototype   → 生成 Stitch 原型（可选，有 UI 时推荐）
4.  /req submit      → 提交评审 (pending)，含 4 道门禁
5.  /req review pass → 评审通过 (approved, delivery_stage=analysis)
6.  /req next        → 推进到 design/dev 阶段
7.  /req dev         → 启动开发（创建【开发】任务, delivery_stage=dev）
7.5 /req ci          → CI 质量门禁检查与自动修复（PR 提交后执行）
8.  /req next        → 推进到 review（需 quality_gate 证据）
9.  /req cr          → 代码评审 + 约定检查 + bug约定建议（⭐ harness 自动）
10. /req next        → 推进到 testing 阶段
11. /req test        → 测试验收（Gate 0B 约定检查 ⭐ + Gate 1-5）
12. /req deploy      → 批量部署（build-and-push.sh → Jenkins ai-proj）
13. /req done        → 归档 (archived) + git commit + push
```

> ⭐ 标记的步骤是 Harness Engineering 自动嵌入的，无需手动调用。

**5 阶段文档**：

| 阶段 | 文档名 | 技能 |
|------|--------|------|
| PRD | 01-PRD.md | `req-prd` |
| 测试 | 02-测试报告.md | 自动生成 |
| 发布 | 03-发布记录.md | 自动生成（含 PDV 验收章节） |
| 归档 | 04-生命周期总结.md | 自动生成 |

**03-发布记录.md 中 PDV 章节模板**：

```markdown
### 部署后验收 (PDV)
| 检查项 | 结果 | 截图 |
|--------|------|------|
| 页面可达: /path/to/page | ✅ PASS | [截图] |
| 菜单可见: {菜单名} | ✅ PASS | [截图] |
| 基础渲染: 无白屏/JS 报错 | ✅ PASS | [截图] |
| API: /api/v1/{路径} | ✅ PASS | — |

PDV 结论: ✅ 全部通过 / ❌ {N}项失败，阻断推进
```

## 任务命名规范

| linkRole | 前缀 | 示例 |
|----------|------|------|
| prd | 【评审】 | 【评审】PRD: 用户认证功能 |
| design | 【评审】 | 【评审】技术设计: 数据模型 |
| implementation | 【开发】 | 【开发-后端】实现 API |
| code_review | 【代码评审】 | 【代码评审】CR: 代码审查 |
| test | 【测试】 | 【测试】集成测试验证 |
| deploy | 【部署】 | 【部署】部署到 staging |
| verification | 【验收】 | 【验收】PDV: OKR 功能部署验收 |
| documentation | 【文档】 | 【文档】API 文档更新 |

## 阶段内容门禁（防空转）

`/req next` 推进时，对关键阶段检查任务**是否有实质内容**（文档附件）：

| 离开阶段 | 检查标准 |
|----------|---------|
| **review** | CR 任务有文档，字数 ≥ 500，含 `file:line` 代码引用，含五视角扫描结果，含结论章节 |
| **testing** | 测试任务有文档，含测试结果表格，含通过/失败结论 |
| **staging** | 部署任务有文档，含健康检查结果 |

未通过 → AskUserQuestion（补充文档 or 强制跳过+记录原因）

### 部署门禁（推进到 released 前）

`/req deploy` 推进 `released` 前，必须通过 3 道门禁：

```
Deploy Gate 1: 健康检查 ── /health 返回 200，服务存活
Deploy Gate 2: PDV 验收 ── linkRole=verification 的【验收】任务存在且 completed
Deploy Gate 3: 证据完整 ── 验收任务有文档，含检查项表格 + E2E 截图 + 通过/失败结论
```

**PDV 验收任务生命周期**：
1. `/req deploy` 步骤 6 自动创建：`ai-proj task create --title "【验收】PDV: {需求标题}"`
2. 关联需求：`ai-proj req link --id <req_id> --task-ids <task_id> --link-role verification`
3. 执行 Playwright PDV 冒烟测试
4. 附加验收文档（检查项表格 + 截图证据 + 结论）：`ai-proj task append-doc --id <task_id>`
5. **全部通过** → `ai-proj task complete --id <task_id>` → 门禁放行
6. **任一失败** → 任务保持 in_progress，阻断推进，报告失败项

### CR 五视角扫描法

**核心原则**：实现阶段关注"怎么让它跑通"，评审阶段关注"怎么让它出错"。AI 必须**切换到对抗性思维**，逐一用以下 5 个视角扫描代码。

| 视角 | 思维模式 | 扫描问题 |
|------|---------|---------|
| **1. 攻击者** | "我怎么绕过/滥用它？" | 跨租户数据泄露、越权访问、参数注入、重放攻击 |
| **2. 泄露者** | "它暴露了什么不该暴露的？" | 错误消息泄露信息、日志记录敏感数据、响应包含内部细节 |
| **3. 并发者** | "两个请求同时来会怎样？" | 竞态条件、双重扣款、幂等性缺失、锁粒度 |
| **4. 边界者** | "极端输入会怎样？" | 空值/零值/负值/超长字符串、类型溢出、分页越界 |
| **5. 依赖者** | "外部服务挂了会怎样？" | 超时处理、重试策略、降级方案、连接泄露 |

**每个视角的具体扫描清单**：

#### 视角1: 攻击者（多租户安全）
- [ ] 所有 Store 层查询是否带 `tenant_id` 过滤？（特别是通过 ID 直接查询的方法）
- [ ] 用户只能操作自己的数据？（consumer_id 校验）
- [ ] URL/请求参数是否有注入风险？（SQL、URL、命令注入）
- [ ] 外部输入是否直接拼接到查询/URL？（应使用参数化查询或编码）

#### 视角2: 泄露者（信息安全）
- [ ] 错误消息是否泄露业务状态？（如"手机号未注册"暴露用户存在性）
- [ ] 日志是否打印了密码、token、密钥？
- [ ] 响应是否包含不必要的内部字段？（如内部 ID、数据库字段名）

#### 视角3: 并发者（数据一致性）
- [ ] 涉及金额变更是否使用事务 + 悲观锁？
- [ ] 关键操作是否有幂等保护？（bizNo 唯一索引）
- [ ] 全局状态（如进程内计数器）重启后是否安全？

#### 视角4: 边界者（健壮性）
- [ ] 必填参数是否有 binding:"required" 校验？
- [ ] 数值参数是否有范围校验？（min/max）
- [ ] 分页参数是否有默认值和上限？

#### 视角5: 依赖者（可靠性）
- [ ] HTTP 客户端是否设置超时？
- [ ] 外部 API 调用失败是否有合理的错误处理？
- [ ] token 类型是否可区分？（access vs refresh 不同过期策略）

### CR 报告模板

```markdown
## 代码评审报告 - {需求标题}
日期: YYYY-MM-DD
评审范围: {N} 个文件, {M} 行变更

### 变更概要
{1-3 句描述}

### 五视角扫描结果

#### 1. 攻击者视角
{扫描发现，或 "未发现问题"}

#### 2. 泄露者视角
{扫描发现，或 "未发现问题"}

#### 3. 并发者视角
{扫描发现，或 "未发现问题"}

#### 4. 边界者视角
{扫描发现，或 "未发现问题"}

#### 5. 依赖者视角
{扫描发现，或 "未发现问题"}

### 审查发现汇总
| 严重度 | 文件:行号 | 视角 | 描述 | 建议 |
|--------|----------|------|------|------|
| {Critical/High/Medium/Low} | {file:line} | {攻击者/泄露者/...} | {问题} | {建议} |

### 测试覆盖
| 测试类型 | 数量 | 状态 |
|----------|------|------|
| ... | ... | ... |

### 结论
{通过 / 有条件通过 / 需修改}
```

## 测试环境流程

```
[本机] → 通过 → [预发布] → 通过 → [生产]
   ↑                │              │
   └────────────────┴─── 失败 ─────┘
```

## 任务关联规范

| link_role | 阶段前缀 | 所属阶段 | 进度权重 |
|-----------|----------|----------|----------|
| prd | 【评审】 | analysis | 10% |
| design | 【评审】 | design | 5% |
| implementation | 【开发】 | dev | 50% |
| code_review | 【代码评审】 | review | 5% |
| test | 【测试】 | testing | 15% |
| deploy | 【部署】 | staging/released | 5% |
| verification | 【验收】 | released | 5% |
| documentation | 【文档】 | any | 5% |

## 标准任务结构

```
需求 REQ-xxx
├── 📝 analysis  → 【评审】PRD: {需求标题}                    (linkRole: prd)
├── 📐 design    → 【评审】技术设计: {需求标题}               (linkRole: design)
├── 💻 dev       → 【开发-后端】、【开发-前端】{描述}          (linkRole: implementation)
├── 🔍 review    → 【代码评审】CR: {需求标题}                 (linkRole: code_review)
├── 🧪 testing   → 【测试】集成测试: {需求标题}               (linkRole: test)
├── 🚀 staging   → 【部署】部署到 staging                     (linkRole: deploy)
└── 🏁 released
    ├── 【部署】部署到 prod                                   (linkRole: deploy)
    └── 【验收】PDV: {需求标题}                               (linkRole: verification)
```

## ai-proj CLI 速查

```bash
# 需求操作
ai-proj req list                          # 列出需求
ai-proj req get --id <id>                 # 查看详情
ai-proj req create --title "..." ...      # 创建需求
ai-proj req update --id <id> ...          # 更新需求
ai-proj req submit --id <id>              # 提交评审
ai-proj req approve --id <id>             # 批准需求
ai-proj req advance --id <id> --to <stage> # 推进阶段
ai-proj req link --id <id> --task-ids ... # 关联任务
ai-proj req tasks --id <id>               # 查看关联任务
```

## 有效值

**审批状态**: `draft`, `pending`, `reviewing`, `approved`, `rejected`, `archived`

**开发阶段**: `backlog`, `analysis`, `design`, `dev`, `review`, `integration`, `testing`, `staging`, `released`

**linkRole**: `prd`, `design`, `implementation`, `code_review`, `test`, `deploy`, `verification`, `regression`, `documentation`

## 相关技能

| 技能 | 用途 |
|------|------|
| `req-prd` | PRD 文档编写 + 评审方法论 |
| `req-prototype` | Stitch 原型生成 + 迭代 |
| `dev-test` | 测试 + 质量门禁 |
| `req-test-gate` (harness) | 工程约束方法论。Gate 0-2 的约定检查由项目本地脚本定义，方法论见 `/harness` 命令 |

## 详细内容

以下章节已移到 [references/details.md](references/details.md)：

- 命令参考