John Qiu
f7f5428812
CR 从"Git diff + 检查清单"升级为结构化的五视角对抗性审查： - 攻击者：跨租户泄露、越权、注入 - 泄露者：错误消息/日志/响应信息泄露 - 并发者：竞态、幂等、锁粒度 - 边界者：参数校验、类型溢出 - 依赖者：超时、降级、token 区分 每个视角配具体扫描 checklist，CR 报告模板增加五视角分节， /req cr 流程从 1 行扩展为 8 步完整链路。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
385 lines
17 KiB
Markdown
385 lines
17 KiB
Markdown
---
|
||
name: req
|
||
description: 需求工作流管理。用于 /req 命令使用、需求全生命周期管理（创建→PRD→评审→开发→测试→部署→归档）。当用户提到需求管理、/req 命令、REQ-XXX 相关任务时自动激活。
|
||
arguments: <subcommand> [args]
|
||
---
|
||
|
||
# req - 需求工作流管理
|
||
|
||
需求全流程工作流管理，与 ai-proj CLI 深度集成。
|
||
|
||
## 需求生命周期
|
||
|
||
**审批状态**（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 自审批
|
||
- **归档前门禁检查** — `/req done` 按需求类型（code/skill/ops）动态检查
|
||
- **部署是项目级动作**，由 `/req deploy` 统一触发
|
||
- **需求完成后必须 git 提交并 push** — commit 格式：`feat(skill): REQ-XXXX 需求标题`
|
||
- **操作前先确认实际 ID** — 从 URL 提取 ID（如 `/requirements/897` → ID=897）
|
||
- **务实路线关闭也必须补全关联任务** — 每个进度条阶段需创建关联任务
|
||
- **阶段内容门禁（防空转）** — `/req next` 时检查关键阶段任务是否有实质内容
|
||
|
||
## 禁止直接调用（必须走命令流程）
|
||
|
||
| 禁止直接调用 | 必须通过 | 原因 |
|
||
|-------------|---------|------|
|
||
| `ai-proj req create` with allowSelfApprove | `/req new` | 禁止自动提交，必须创建为 draft |
|
||
| `ai-proj req submit` (直接调用) | `/req submit` | 必须先通过 4 道门禁检查 |
|
||
| `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 的 4 道门禁
|
||
|
||
```
|
||
Gate 1: 需求讨论 ── description 末尾有「## 讨论结论」章节
|
||
Gate 2: 方案确认 ── AskUserQuestion 获得「方案确认通过」
|
||
Gate 3: PRD 文档 ── linkRole=prd 的任务存在且有文档
|
||
Gate 4: 完整性检查 ── 三段式完整 + 验收标准 ≥ 2 条 + PRD 存在
|
||
```
|
||
|
||
## 完整工作流
|
||
|
||
```
|
||
1. /req new → 创建需求 (draft)
|
||
2. 需求讨论 → 输出结论摘要，用户确认
|
||
3. req-prd 技能 → 编写 PRD（创建【评审】PRD 任务）
|
||
4. /req submit → 提交评审 (pending)，含 4 道门禁
|
||
5. /req review pass → 评审通过 (approved, delivery_stage=analysis)
|
||
6. /req next → 推进到 design/dev 阶段
|
||
7. /req dev → 启动开发（创建【开发】任务, delivery_stage=dev）
|
||
8. /req next → 推进到 review 阶段
|
||
9. /req cr → 代码评审（创建【代码评审】任务）
|
||
10. /req next → 推进到 testing 阶段
|
||
11. /req test → 测试验收（5-Gate 流程）
|
||
12. /req deploy → 批量部署（DG1-DG6 Deploy Gates）
|
||
13. /req done → 归档 (archived) + git commit + push
|
||
```
|
||
|
||
**5 阶段文档**：
|
||
|
||
| 阶段 | 文档名 | 技能 |
|
||
|------|--------|------|
|
||
| PRD | 01-PRD.md | `req-prd` |
|
||
| 测试 | 02-测试报告.md | 自动生成 |
|
||
| 发布 | 03-发布记录.md | 自动生成 |
|
||
| 归档 | 04-生命周期总结.md | 自动生成 |
|
||
|
||
## 任务命名规范
|
||
|
||
| linkRole | 前缀 | 示例 |
|
||
|----------|------|------|
|
||
| prd | 【评审】 | 【评审】PRD: 用户认证功能 |
|
||
| design | 【评审】 | 【评审】技术设计: 数据模型 |
|
||
| implementation | 【开发】 | 【开发-后端】实现 API |
|
||
| code_review | 【代码评审】 | 【代码评审】CR: 代码审查 |
|
||
| test | 【测试】 | 【测试】集成测试验证 |
|
||
| deploy | 【部署】 | 【部署】部署到 staging |
|
||
| documentation | 【文档】 | 【文档】API 文档更新 |
|
||
|
||
## 阶段内容门禁（防空转）
|
||
|
||
`/req next` 推进时，对关键阶段检查任务**是否有实质内容**（文档附件）：
|
||
|
||
| 离开阶段 | 检查标准 |
|
||
|----------|---------|
|
||
| **review** | CR 任务有文档，字数 ≥ 500，含 `file:line` 代码引用，含五视角扫描结果，含结论章节 |
|
||
| **testing** | 测试任务有文档，含测试结果表格，含通过/失败结论 |
|
||
| **staging** | 部署任务有文档，含健康检查结果 |
|
||
|
||
未通过 → AskUserQuestion（补充文档 or 强制跳过+记录原因）
|
||
|
||
### 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} | {攻击者/泄露者/...} | {问题} | {建议} |
|
||
|
||
### 测试覆盖
|
||
| 测试类型 | 数量 | 状态 |
|
||
|----------|------|------|
|
||
| ... | ... | ... |
|
||
|
||
### 结论
|
||
{通过 / 有条件通过 / 需修改}
|
||
```
|
||
|
||
## 命令参考
|
||
|
||
### 撰写命令
|
||
|
||
**`/req new [标题]`** — 对话式创建需求（仅 draft）
|
||
- 参数：`--priority=high|medium|low`，`--project=<name>`，`--category=feature|bug|improvement`
|
||
- 流程：描述→提取关键信息→用户故事→验收标准→`ai-proj req create`→ Gate 1 需求讨论
|
||
|
||
**`/req draft <描述>`** — 一句话快速创建 draft，AI 自动补全
|
||
|
||
**`/req edit [REQ-ID]`** — 编辑需求：`ai-proj req get` → 询问修改点 → `ai-proj req update` → 显示变更摘要
|
||
|
||
**`/req check [REQ-ID]`** — 完整性检查（Gate 4）：
|
||
```
|
||
✅ 三段式结构完整 / ✅ 验收标准: 4 条 / ✅ 讨论结论已记录 / ❌ PRD 文档缺失
|
||
```
|
||
|
||
**`/req split [REQ-ID]`** — 拆分为开发任务（后端/前端/测试）并关联
|
||
|
||
### 提交评审
|
||
|
||
**`/req submit [REQ-ID]`** ⭐ — 从 draft 到 pending 的唯一合法路径：
|
||
1. Gate 1: description 末尾有「## 讨论结论」
|
||
2. Gate 2: 讨论结论经过用户确认
|
||
3. Gate 3: 有 linkRole=prd 任务且附有文档
|
||
4. Gate 4: 执行 `/req check` 全部通过
|
||
5. → `ai-proj req submit --id <id>` → 展示 PRD 摘要 → 等待评审
|
||
|
||
**`/req review pass [REQ-ID]`** — 评审通过（必须用户明确确认后才调用 `ai-proj req approve --id <id>`）
|
||
|
||
**`/req review reject [REQ-ID] [原因]`** — 评审驳回，必须提供原因
|
||
|
||
### 阶段管理
|
||
|
||
**`/req` 或 `/req list`** — 按状态分组列出所有需求（`ai-proj req list`）
|
||
|
||
**`/req status [REQ-ID]`** — 查看需求详情（`ai-proj req get --id <id>`）、进度、关联任务
|
||
|
||
**`/req next [REQ-ID]`** — 推进到下一阶段：
|
||
1. 检查当前阶段任务完成度
|
||
2. 智能跳阶段检测（无 implementation 任务时建议跳过 review/testing）
|
||
3. `ai-proj req advance --id <id> --to <stage>`（门禁检查，未通过→AskUserQuestion，**禁止 AI 自动 force**）
|
||
4. ⭐ 内容门禁检查（review/testing/staging 阶段）
|
||
5. 自动创建目标阶段建议任务
|
||
6. 展示：「✅ 已创建: #XXXX {任务名}。如需撤销请说明」
|
||
|
||
**阶段顺序**：`analysis → design → dev → review → testing → [待部署池] → released`
|
||
|
||
**`/req resume [REQ-ID]`** — 会话断点恢复：`ai-proj req get --id <id>` 获取 delivery_stage + 任务状态 + 建议操作
|
||
|
||
### 开发命令
|
||
|
||
**`/req dev [REQ-ID]`** — 启动开发：
|
||
1. `ai-proj req tasks --id <id>` 找 implementation 任务
|
||
2. `ai-proj task start --id <task_id>` 更新任务状态为开发中
|
||
3. `/pr start` 从 origin/main 建分支
|
||
|
||
**`/req cr [REQ-ID]`** — 代码评审（前置：开发任务完成）：
|
||
1. `ai-proj req tasks --id <id>` 确认所有 implementation 任务已完成
|
||
2. `git diff` / `find` 确定变更范围（文件数、行数）
|
||
3. 读取所有变更文件源码（非 test 文件）
|
||
4. **五视角扫描**：逐一用攻击者/泄露者/并发者/边界者/依赖者视角审查
|
||
5. `ai-proj task create` 创建【代码评审】任务并关联需求（linkRole=code_review）
|
||
6. `ai-proj create-and-attach` 附加 CR 报告文档（必须含五视角扫描结果）
|
||
7. 展示发现摘要，AskUserQuestion 确认是否创建 bug 修复任务
|
||
8. 若有 High/Critical 发现 → `ai-proj task create` 创建关联修复任务
|
||
|
||
**`/req test [REQ-ID]`** — 测试（前置：代码评审通过），遵循 dev-test 技能的 5-Gate 流程
|
||
|
||
**`/req deploy [--project <name>] [--env <env>]`** — 项目级批量部署：
|
||
1. 收集待部署需求（delivery_stage=testing + 全 test 任务 completed）
|
||
2. AskUserQuestion 确认范围
|
||
3. `ai-proj task create` 创建部署批次任务
|
||
4. Deploy Gates DG1-DG6：staging 部署 → 冒烟测试 → 回归 → 生产部署
|
||
5. `ai-proj task append-doc` 记录部署文档
|
||
6. `ai-proj req advance --id <id> --to released` 批量推进
|
||
|
||
**`/req done [REQ-ID]`** — 类型化归档门禁 + git commit + push + `ai-proj req archive --id <id>`：
|
||
- **推断类型**：有 implementation → code；无 implementation 有 prd/test → skill；仅 deploy → ops
|
||
- **code 检查**：delivery_stage=released + deploy 任务完成 + 部署文档 + 所有任务完成
|
||
- **skill 检查**：delivery_stage≥testing + 所有任务完成
|
||
- **ops 检查**：deploy 任务完成 + 所有任务完成
|
||
|
||
### PRD 文档创建（通过任务中转）
|
||
|
||
```bash
|
||
# create-and-attach 只支持任务 ID（task_documents 外键约束）
|
||
# 1. 创建任务
|
||
ai-proj task create --title "【评审】PRD: 用户认证功能"
|
||
|
||
# 2. 关联需求
|
||
ai-proj req link --id 711 --task-ids 5214
|
||
|
||
# 3. 附加文档到任务
|
||
ai-proj task append-doc --id 5214 --content "# PRD: 用户认证功能\n..."
|
||
```
|
||
|
||
### 阶段任务 Checklist
|
||
|
||
| 阶段 | 建议任务 | linkRole |
|
||
|------|----------|----------|
|
||
| analysis | 【评审】PRD: {需求标题} | prd |
|
||
| design | 【评审】技术设计: {需求标题} | design |
|
||
| dev | 【开发-后端】{需求标题}、【开发-前端】{需求标题} | implementation |
|
||
| review | 【代码评审】{需求标题} | code_review |
|
||
| testing | 【测试】集成测试: {需求标题} | test |
|
||
| deploy | 由 `/req deploy` 批量创建 | deploy |
|
||
|
||
## 测试环境流程
|
||
|
||
```
|
||
[本机] → 通过 → [预发布] → 通过 → [生产]
|
||
↑ │ │
|
||
└────────────────┴─── 失败 ─────┘
|
||
```
|
||
|
||
## 任务关联规范
|
||
|
||
| link_role | 阶段前缀 | 所属阶段 | 进度权重 |
|
||
|-----------|----------|----------|----------|
|
||
| prd | 【评审】 | analysis | 10% |
|
||
| design | 【评审】 | design | 5% |
|
||
| implementation | 【开发】 | dev | 50% |
|
||
| code_review | 【代码评审】 | review | 5% |
|
||
| test | 【测试】 | testing | 15% |
|
||
| deploy | 【部署】 | staging/released | 10% |
|
||
| 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)
|
||
```
|
||
|
||
## 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`, `regression`, `documentation`
|
||
|
||
## 相关技能
|
||
|
||
| 技能 | 用途 |
|
||
|------|------|
|
||
| `req-prd` | PRD 文档编写 + 评审方法论 |
|
||
| `dev-test` | 测试 + 质量门禁 |
|