John Qiu
712063071c
skills/ → skills-dev(9), skills-req(10), skills-ops(4), skills-integration(8), skills-biz(4), skills-workflow(7) generate-marketplace.py 改为自动扫描所有 skills-* 目录。 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
437 lines
19 KiB
Markdown
437 lines
19 KiB
Markdown
---
|
||
name: req-commands
|
||
description: 需求命令详细参考。当需要查看 /req 命令的详细用法、参数、示例时使用。
|
||
---
|
||
|
||
# req 命令参考
|
||
|
||
## 基础命令
|
||
|
||
### `/req` 或 `/req list`
|
||
列出所有需求，按状态分组显示。
|
||
|
||
### `/req new [标题]`
|
||
创建新需求。
|
||
- 参数：`--priority=high|medium|low`，`--project=<name>`，`--category=feature|bug|improvement`
|
||
- 创建后提示使用 `req-prd` 技能编写 PRD
|
||
|
||
### `/req status [REQ-ID]`
|
||
查看需求详情、进度、关联任务。
|
||
|
||
## 阶段管理命令
|
||
|
||
### `/req phase [REQ-ID]`
|
||
查看需求当前开发阶段和任务状态。
|
||
|
||
**执行逻辑**：
|
||
1. `get_requirement(id)` → 获取 `delivery_stage`
|
||
2. `get_requirement_tasks(id)` → 获取所有关联任务
|
||
3. 按 linkRole 分组展示，标注当前阶段任务完成度
|
||
|
||
**输出示例**：
|
||
```
|
||
REQ-20260218-0013 | 阶段: dev (开发)
|
||
────────────────────────────────────
|
||
✅ analysis (评审)
|
||
✅ #6035 【评审】PRD: 需求全生命周期阶段化管理
|
||
✅ #6040 【评审】技术设计: 数据模型
|
||
▶ dev (开发) ← 当前阶段
|
||
🔄 #6042 【开发-后端】实现阶段管理 API [in_progress]
|
||
⬜ #6043 【开发-前端】阶段可视化组件 [todo]
|
||
⬜ review (代码评审)
|
||
(无任务)
|
||
⬜ testing (测试)
|
||
(无任务)
|
||
```
|
||
|
||
### `/req next [REQ-ID]`
|
||
检测当前阶段完成度，推进到下一阶段。
|
||
|
||
**执行逻辑**：
|
||
1. 获取当前 `delivery_stage` 和该阶段所有任务
|
||
2. 检查任务完成度：
|
||
- 全部完成 → 提示「当前阶段已完成，是否推进到 {下一阶段}？」
|
||
- **部分未完成 → 显示未完成任务列表 + AskUserQuestion**：
|
||
- 选项 A: "强制推进（需说明原因）"
|
||
- 选项 B: "返回完成任务"
|
||
- 用户选 A → 输入跳过原因 → `advance_delivery_stage(force=true)`
|
||
- 记录到需求历史: `POST /requirements/{id}/history`，comment 包含跳过原因
|
||
- **⚠️ 禁止 AI 自动使用 force=true，必须经过 AskUserQuestion 确认**
|
||
3. **智能跳阶段检测**（推进前）：
|
||
- `get_requirement_tasks(id)` → 收集所有 linkRole
|
||
- 如果目标阶段与当前 linkRole 不匹配，主动建议跳过：
|
||
- 无 `implementation` → 推进到 review/testing 时提示「该需求无代码任务，建议跳过此阶段」
|
||
- 无 `code_review` → 推进到 review 时提示跳过
|
||
- 无 `test` → 推进到 testing 时提示跳过
|
||
- 通过 AskUserQuestion 确认：「跳过」或「仍然创建任务」
|
||
4. 用户确认推进后：
|
||
- 更新 `delivery_stage` 到下一阶段
|
||
- **自动创建**目标阶段的建议任务（`create_stage_task` 批量创建，无需询问）
|
||
- 展示已创建任务列表：「✅ 已创建: #XXXX 【代码评审】CR: {需求标题}。如需撤销请说明」
|
||
- ⚠️ 仅当用户主动要求撤销时才删除已创建任务
|
||
|
||
**阶段顺序**：
|
||
```
|
||
analysis → design → dev → review → testing → [待部署池] → released
|
||
↑ /req deploy 批量推进
|
||
```
|
||
|
||
**linkRole 到阶段的映射**：
|
||
| linkRole | 所属阶段 |
|
||
|----------|----------|
|
||
| prd | analysis |
|
||
| design | design |
|
||
| implementation | dev |
|
||
| code_review | review |
|
||
| test | testing |
|
||
| deploy (staging) | staging |
|
||
| deploy (prod) | released |
|
||
|
||
## 会话恢复命令
|
||
|
||
### `/req resume [REQ-ID]`
|
||
从上次中断的位置恢复工作。**会话被截断后的首选命令**。
|
||
|
||
**执行逻辑**：
|
||
1. 若无 REQ-ID → `list_requirements(status=approved)` 找到最近活跃的需求
|
||
2. `get_requirement(id)` → 获取需求基本信息和 `delivery_stage`
|
||
3. `get_requirement_tasks(id)` → 获取所有关联任务及状态
|
||
4. 汇总展示恢复上下文
|
||
|
||
**输出格式**：
|
||
```
|
||
📋 恢复工作上下文
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
需求: REQ-20260218-0016 | 需求全生命周期 AI 开发管理优化
|
||
状态: approved | 阶段: dev (开发)
|
||
|
||
📊 任务进度: 2/4 完成
|
||
✅ #6051 【开发-后端】实现 advance_delivery_stage MCP 工具
|
||
✅ #6052 【开发-后端】实现 create_stage_task 组合 MCP 工具
|
||
🔄 #6053 【开发-Skill】req-commands 阶段 checklist 模板化 [in_progress]
|
||
⬜ #6054 【开发-Skill】会话断点恢复机制 [todo]
|
||
|
||
▶ 建议操作:
|
||
1. 继续任务 #6053（当前 in_progress）
|
||
2. 执行 /req next 推进阶段
|
||
3. 执行 /req phase 查看完整阶段视图
|
||
```
|
||
|
||
**自动行为**：
|
||
- 如果有 `in_progress` 任务，提示继续该任务
|
||
- 如果当前阶段所有任务已完成，提示执行 `/req next`
|
||
- 如果需求已 `archived`，告知用户无需操作
|
||
|
||
## 评审命令
|
||
|
||
### `/req review [REQ-ID]`
|
||
提交评审。**前置条件**：必须有 PRD 文档。
|
||
|
||
**评审等待机制（强制）**：
|
||
1. `submit_requirement(id)` → status 变为 pending
|
||
2. 展示 PRD 要点摘要：
|
||
```
|
||
PRD 评审摘要
|
||
─────────────────────
|
||
标题: {需求标题}
|
||
核心方案: {1-2句总结}
|
||
验收标准: {N}项
|
||
改动范围: {文件列表}
|
||
```
|
||
3. **AskUserQuestion**: "请确认 PRD 是否通过评审"
|
||
- "通过评审" → `approve_requirement(id)`
|
||
- "需要修改" → 回到编辑流程
|
||
4. **⚠️ 禁止 AI 自动审批**，必须等待用户明确选择
|
||
|
||
### `/req review pass [REQ-ID]`
|
||
评审通过。支持多人审批。参数：`--comment="审批意见"`
|
||
|
||
### `/req review reject [REQ-ID] [原因]`
|
||
评审驳回。必须提供驳回原因。
|
||
|
||
### `/req review status [REQ-ID]`
|
||
查看审批进度（多人审批时）。
|
||
|
||
## 开发命令
|
||
|
||
### `/req dev [REQ-ID]`
|
||
启动开发，自动选择优先级最高的 todo 任务并开始计时。
|
||
- 参数：`--task=<task-id>` 指定任务
|
||
- 优先启动 `implementation` 角色任务
|
||
- **自动设置** `delivery_stage = dev`（如尚未设置）
|
||
|
||
### `/req cr [REQ-ID]`
|
||
代码评审。**前置条件**：开发任务完成。
|
||
- 显示 Git diff 摘要
|
||
- 生成代码评审检查清单
|
||
- **自动设置** `delivery_stage = review`
|
||
|
||
### `/req test [REQ-ID]`
|
||
启动测试。**前置条件**：代码评审通过。
|
||
- 参数：`--skip-cr --reason="原因"` 跳过代码评审
|
||
- **自动设置** `delivery_stage = testing`
|
||
- **⭐ 遵循 `req-test-gate` v2 技能的 5 道门禁**
|
||
|
||
**执行逻辑（5-Gate 流程，详见 `req-test-gate` 技能）**：
|
||
1. **Gate 1 前置条件**：CR 已通过 + 开发任务全部完成（不可跳过）
|
||
2. **Gate 2 测试执行**：推断需求类型（code/skill/ops），分阶段验证
|
||
- **code 类型四阶段**：
|
||
- **2A 静态验证**：编译 + 单元测试 + 条件前端/iOS 测试
|
||
- **2B 集成验证**：API 端点 + DB 约束 + 错误处理
|
||
- **2C 冒烟测试**：Staging 环境健康检查 + 核心流程（已部署时）
|
||
- **2D 原型符合性**：对比原型 HTML 的结构/字段/交互/状态（有原型时）
|
||
- **skill**: 关键词一致性 + 规则无歧义 + 边界情况（至少 3 项）
|
||
- **ops**: 部署命令可执行 + 健康检查
|
||
3. **Gate 3 质量验证**：派遣 test-validator 子代理审查测试质量
|
||
- code 类型：总是触发 | skill 类型：≥5 测试项时触发 | ops 类型：不触发
|
||
- Critical 缺陷必须修复，Important 缺陷需 AskUserQuestion 确认
|
||
4. **Gate 4 文档持久化（不可跳过）**：`create-and-attach` 将完整测试报告写入测试任务文档
|
||
- 文档模板见 `req-test-gate` 技能的「最小必填模板」（含 2A-2D 阶段标记）
|
||
- 必须包含：前置条件结果 + 测试执行表格 + 质量验证摘要 + 通过/失败结论
|
||
- 无此文档 → `/req deploy` 前置检查会警告
|
||
5. **Gate 5 回归贡献（code 类型）**：检查是否有 linkRole=regression 任务和用例文档
|
||
- v2.0 过渡期为警告级别，不阻塞
|
||
- 提醒补充回归测试用例到回归池
|
||
|
||
### `/req deploy [--project <name>] [--env <environment>]`
|
||
**项目级批量部署**。收集所有待部署需求，一次构建部署。
|
||
|
||
- **这是项目级动作**，不是单需求操作
|
||
- `--project` 默认为当前项目，`--env` 默认为 `staging`
|
||
- 参数：`--platform=web|ios|android`
|
||
- **⭐ 遵循 `req-test-gate` v2 的 Deploy Gates (DG1-DG6)**
|
||
|
||
**执行逻辑**：
|
||
1. **前置检查（强制）**：
|
||
- 对每个待部署需求，检查 testing 阶段任务是否有文档附件（`has_task_document`）
|
||
- ✅ 有文档 → 继续
|
||
- ⚠️ 无文档 → AskUserQuestion「测试任务 #XXXX 无测试记录文档，确认继续部署？」
|
||
2. **收集待部署需求**：
|
||
- `delivery_stage = testing` 且所有 test 任务 completed
|
||
- 有 implementation 任务（排除纯运维/文档需求）
|
||
3. **展示待部署列表** → `AskUserQuestion` 确认部署范围
|
||
4. **创建部署批次任务**：
|
||
- 标题：`【部署】{project} {date} ({N} requirements)`
|
||
- 对每个选中需求：`link_tasks_to_requirement(role=deploy)`
|
||
5. **Deploy Gates (DG1-DG6)**（详见 `req-test-gate/deploy-gates.md`）：
|
||
- **DG1 迁移检查（不可跳过）**：对比 migrations/ vs 数据库，有新 migration 先备份再执行
|
||
- **DG2 Staging 部署**：构建镜像 + 部署到 singapore
|
||
- **DG3 冒烟测试**：健康检查 + 登录 + 新 API 验证
|
||
- **DG4 影响域回归**：根据 module-deps.json 运行对应回归套件（无套件时跳过）
|
||
- **DG5 性能基线（推荐）**：关键 API 响应时间检查
|
||
- **DG6 生产部署（不可跳过）**：部署 + 健康检查，失败立即回滚
|
||
6. **部署后强制检查点**：
|
||
- ✅ **部署文档创建**（必须）：`create-and-attach` 到部署任务，包含 Deploy Gates 结果表格
|
||
- ☑️ **截图验证**（可选）：有 chrome-dev MCP → 执行截图；无 → 记录跳过
|
||
7. **部署成功后**：
|
||
- 所有关联需求 `advance_delivery_stage → released`
|
||
- `complete_task(部署任务)`
|
||
|
||
**单需求兼容**：当仅 1 个需求待部署时，流程自动退化为单需求部署。
|
||
|
||
### `/req done [REQ-ID]`
|
||
完成归档。参数：`--force` 强制归档。
|
||
|
||
**类型化归档门禁（强制）**：
|
||
|
||
1. `get_requirement_tasks(id)` → 获取所有关联任务
|
||
2. **推断需求类型**（从 linkRole 集合判断）：
|
||
- **code**: 有 `implementation` 角色任务 → 代码需求
|
||
- **skill**: 无 `implementation`，有 `prd`/`code_review`/`test` → Skill/文档需求
|
||
- **ops**: 仅 `deploy` 角色任务 → 运维需求
|
||
3. **按类型执行检查清单**：
|
||
|
||
| 检查项 | code | skill | ops |
|
||
|--------|------|-------|-----|
|
||
| delivery_stage = released | ✅ | - | - |
|
||
| delivery_stage >= testing | - | ✅ | - |
|
||
| deploy 任务已完成 | ✅ | - | ✅ |
|
||
| 部署文档存在 | ✅ | - | - |
|
||
| 所有关联任务已完成 | ✅ | ✅ | ✅ |
|
||
|
||
4. **检查结果处理**：
|
||
- 全部通过 → 展示检查清单 + AskUserQuestion "确认归档？"
|
||
- 有缺失 → 显示缺失项 + AskUserQuestion "是否强制归档？"
|
||
- 用户确认 → 进入步骤 5
|
||
5. **Git 提交（强制）**：
|
||
- `git add` 本需求相关变更文件
|
||
- `git commit -m "feat(skill): REQ-XXXX 需求标题"`（或 `fix`/`refactor` 等合适的 type）
|
||
- `git push origin <current-branch>`
|
||
- ⚠️ 提交前确认无敏感文件（.env、credentials 等）
|
||
6. `archive_requirement(id)`
|
||
7. 归档后生成生命周期总结，触发同步
|
||
|
||
### `/req regression [--module <name>] [--mode <mode>]`
|
||
**运行回归测试**。系统级持续质量活动。
|
||
|
||
- `--module` 指定模块（okr/task/auth/...），不指定则按影响域推断
|
||
- `--mode` 执行模式：`impact`（影响域）| `critical`（关键路径）| `full`（全量）
|
||
- 默认模式：`impact`（根据最近变更推断影响域）
|
||
|
||
**执行逻辑**（详见 `req-test-gate/regression.md`）：
|
||
1. **确定范围**：
|
||
- 指定 module → 直接运行该模块回归套件
|
||
- 未指定 → `git diff --name-only` 获取变更 → 查 `module-deps.json` → 推断影响域
|
||
2. **运行回归套件**：
|
||
- 执行 `regression-suite/suites/` 下对应脚本
|
||
- 记录每个用例的 PASS/FAIL 状态
|
||
3. **回归判定**：
|
||
- 对比上次运行结果
|
||
- 上次 PASS + 本次 FAIL → 标记为「回归」
|
||
4. **结果处理**：
|
||
- 全部通过 → 展示通过率
|
||
- 有回归 → AskUserQuestion「是否为回归项创建 bug 需求？」
|
||
- 有新失败 → 展示失败列表，建议排查
|
||
5. **报告输出**：
|
||
```
|
||
回归测试结果 - {module/all}
|
||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||
模式: {impact/critical/full}
|
||
套件: {N} 个 | 用例: {M} 个
|
||
✅ 通过: {P} | ❌ 失败: {F} | 🔴 回归: {R}
|
||
```
|
||
|
||
**当前状态**：回归套件待初始化，首次运行会提示建立基线。
|
||
|
||
## 辅助命令
|
||
|
||
### `/req link [REQ-ID] --task-id [TASK-ID]`
|
||
关联任务到需求。
|
||
|
||
### `/req decompose [REQ-ID]`
|
||
分解需求为任务。**创建时自动加阶段前缀**。
|
||
|
||
### `/req generate-tasks [REQ-ID]`
|
||
根据 PRD 自动生成开发任务。**所有任务带【开发】前缀**。
|
||
|
||
### `/req priority [REQ-ID] [low|medium|high]`
|
||
设置需求优先级。
|
||
|
||
### `/req stats [REQ-ID|--all]`
|
||
查看需求统计信息。
|
||
|
||
## 阶段任务 Checklist 模板
|
||
|
||
当 `/req next` 推进到新阶段时，根据目标阶段自动建议创建的任务。使用 `create_stage_task` 组合工具一步完成（创建+关联+可选启动）。
|
||
|
||
### analysis（评审）
|
||
```
|
||
☐ 【评审】PRD: {需求标题} (linkRole: prd)
|
||
☐ 【评审】技术设计: {需求标题} (linkRole: design) [可选]
|
||
```
|
||
|
||
### design（设计）
|
||
```
|
||
☐ 【设计】技术方案: {需求标题} (linkRole: design)
|
||
☐ 【设计】数据模型设计 (linkRole: design) [可选]
|
||
```
|
||
|
||
### dev（开发）
|
||
```
|
||
☐ 【开发-后端】{需求标题} (linkRole: implementation)
|
||
☐ 【开发-前端】{需求标题} (linkRole: implementation) [可选]
|
||
☐ 【开发-MCP】{需求标题} (linkRole: implementation) [可选]
|
||
```
|
||
|
||
### review（代码评审）
|
||
```
|
||
☐ 【代码评审】{需求标题} (linkRole: code_review)
|
||
```
|
||
|
||
### testing（测试）
|
||
```
|
||
☐ 【测试】单元测试: {需求标题} (linkRole: test)
|
||
☐ 【测试】集成测试: {需求标题} (linkRole: test) [可选]
|
||
```
|
||
|
||
**按需求类型的最低测试标准**：
|
||
|
||
| 需求类型 | 最低测试要求 |
|
||
|----------|-------------|
|
||
| **code** | `go test` 或前端测试通过 + API 验证 + 截图验证 |
|
||
| **skill** | 关键词跨文件一致性 + 规则无歧义验证 + 边界情况检查（至少 3 项） |
|
||
| **ops** | 部署命令可执行 + 健康检查通过 |
|
||
|
||
**skill 类型测试 checklist**（最低 3 项）：
|
||
```
|
||
☐ 关键词一致性：grep 验证核心概念在所有相关 skill 文件中对齐
|
||
☐ 规则无歧义：每条规则的触发条件和执行动作明确，无二义性
|
||
☐ 边界情况：至少验证 1 个边界场景（如混合类型需求的分类）
|
||
☐ 交叉引用：文件间的引用（如"见 xxx 技能"）指向正确 [可选]
|
||
```
|
||
|
||
### 部署（项目级，由 `/req deploy` 触发）
|
||
|
||
部署不再按单需求创建任务，而是通过 `/req deploy` 批量收集待部署需求：
|
||
```
|
||
testing 完成的需求 → 进入「待部署池」
|
||
/req deploy → 创建批次任务：【部署】{project} {date} ({N} requirements)
|
||
关联到所有选中需求 (linkRole: deploy)
|
||
部署成功后批量推进 → released
|
||
```
|
||
|
||
### `/req next` 执行流程（更新版）
|
||
|
||
1. `get_requirement(id)` → 获取 `delivery_stage`
|
||
2. `get_requirement_tasks(id)` → 获取关联任务，收集 linkRole 集合
|
||
3. **智能跳阶段检测**：检查目标阶段是否与 linkRole 匹配
|
||
- 不匹配 → AskUserQuestion「建议跳过 {阶段}，是否同意？」
|
||
- 用户同意跳过 → 递归检测下一阶段
|
||
- 用户拒绝 → 继续推进到该阶段
|
||
4. **门禁检查**：`advance_delivery_stage(id, nextStage)` 自动检查
|
||
- 通过 → 进入步骤 4.5
|
||
- 未通过 → 显示阻塞任务，AskUserQuestion 确认 force（禁止自动 force）
|
||
4.5. **⭐ 内容门禁检查（防空转）**：对关键阶段的已完成任务验证文档附件
|
||
- **适用阶段**: review（CR 报告）、testing（测试结果）、staging（部署文档）
|
||
- **检查逻辑**：
|
||
```
|
||
对当前阶段的每个 completed 任务:
|
||
has_task_document(taskId) → 有文档？
|
||
✅ 有 → get_task_document(taskId) → 检查质量:
|
||
- review: ≥500字符 + 含 file:line 代码引用 + 含结论章节
|
||
- testing: 含测试项表格 + 含通过/失败结论 + ≥200字符
|
||
（详见 req-test-gate 技能 Gate 4 文档质量门禁）
|
||
- staging: 含健康检查结果 + 含镜像/commit 信息
|
||
❌ 无 → 阻止推进，提示「任务 #XXXX 缺少 {类型} 文档」
|
||
```
|
||
- **未通过处理**：AskUserQuestion「内容门禁未通过，选择操作」
|
||
- 选项 A: "补充文档后重试"
|
||
- 选项 B: "强制跳过（记录原因）" → 记录跳过原因到需求历史
|
||
- **⚠️ 禁止 AI 自动跳过**，必须经过 AskUserQuestion
|
||
5. **自动创建阶段任务**：`create_stage_task` 批量创建目标阶段建议任务
|
||
- 展示已创建列表：「✅ 已创建: #XXXX {任务名}。如需撤销请说明」
|
||
- 用户主动要求撤销时才删除
|
||
|
||
## MCP 工具映射
|
||
|
||
| 命令 | MCP 工具 |
|
||
|------|----------|
|
||
| `/req` | `list_requirements` |
|
||
| `/req new` | `create_requirement` |
|
||
| `/req phase` | `get_requirement` + `get_requirement_tasks` |
|
||
| `/req next` | `advance_delivery_stage` (门禁检查+推进) + `create_stage_task` (创建任务) |
|
||
| `/req resume` | `get_requirement` + `get_requirement_tasks` (断点恢复) |
|
||
| `/req dev` | `get_requirement` + `get_requirement_tasks` + `start_task_with_timer` |
|
||
| `/req cr` | `get_requirement_tasks` + Git diff |
|
||
| `/req test` | `req-test-gate` v2 5-Gate 流程: 前置检查 → 类型化测试(2A-2D) → test-validator 子代理 → `create-and-attach` 持久化 → 回归贡献检查 |
|
||
| `/req deploy` | 前置检查 + Deploy Gates(DG1-DG6): 迁移→staging→冒烟→回归→性能→生产 + 部署文档 |
|
||
| `/req regression` | `git diff` 影响域推断 + 运行回归套件 + 回归判定 + 可选创建 bug 需求 |
|
||
| `/req done` | 类型推断 + 检查清单 + `AskUserQuestion` + `archive_requirement`（⚠️ 禁止直接调用 archive） |
|
||
| `/req review` | `submit_requirement` |
|
||
| `/req review pass` | `approve_requirement` |
|
||
| `/req review reject` | `reject_requirement` |
|
||
| `/req link` | `link_tasks_to_requirement` |
|
||
|
||
## 任务关联类型
|
||
|
||
| link_role | 说明 | 阶段前缀 | 进度权重 |
|
||
|-----------|------|----------|----------|
|
||
| prd | PRD 文档 | 【评审】 | 0.1 |
|
||
| design | 技术设计 | 【评审】 | 0.05 |
|
||
| implementation | 开发实现 | 【开发】 | 0.5 |
|
||
| code_review | 代码评审 | 【代码评审】 | 0.05 |
|
||
| test | 测试验证 | 【测试】 | 0.15 |
|
||
| deploy | 部署发布 | 【部署】 | 0.1 |
|
||
| regression | 回归用例 | 【回归】 | 0.0 |
|
||
| documentation | 文档编写 | 【文档】 | 0.05 |
|