一套 Skills，搞定需求评审 + 用例生成全流程

一套 Skills，搞定需求评审 + 用例生成全流程

读完这篇文章，你将能够在自己的项目里从零搭建一套完整的需求评审 + 用例生成 Skills。

---

整体架构：四个 Skill 如何协作

这套工具由 4 个 Skill 组成，按 3 个阶段 协作完成从需求到用例的全流程：

                        ┌─────────────────────────┐
                        │    用户输入需求描述        │
                        └────────────┬────────────┘
                                     │
                                     ▼
┌──────────────────────────────────────────────────────────────┐
│                    📋 阶段一：需求评审                         │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  ① req-review（主协调器）                              │   │
│  │    Step 1: 解析需求 → 识别模块/类型                    │   │
│  │    Step 2: 委托 ② associator 做关联分析               │   │
│  │    Step 3: 委托 ③ challenger 做逐条审查 → 输出评审报告 │   │
│  └────────────┬───────────────────┬─────────────────────┘   │
│               │                   │                         │
│               ▼                   ▼                         │
│  ┌────────────────────┐  ┌────────────────────────────┐     │
│  │ ② associator       │  │ ③ challenger               │     │
│  │ · 语义搜索受影响     │  │ · 加载审查清单（15条通用     │     │
│  │   模块和用例        │  │   + 按类型加载专项清单）     │     │
│  │ · 输出关联分析      │  │ · 逐条命中→检查→分级        │     │
│  └────────────────────┘  │ · 输出分级问题清单          │     │
│                          └────────────────────────────┘     │
│                                     │                        │
│                                     ▼                        │
│                          评审报告输出                         │
│                    docs/req-review/<slug>-review.md          │
└──────────────────────────────────────────────────────────────┘
                                     │
                                     │  评审报告包含：
                                     │  · 🚨 阻塞问题 × N
                                     │  · ⚠️ 严重问题 × N
                                     │  · 📝 建议改进 × N
                                     │  · ℹ️ 信息确认 × N
                                     │
                                     ▼
┌──────────────────────────────────────────────────────────────┐
│                💬 阶段二：需求澄清与补充（用户参与）            │
│                                                              │
│   用户（PM/测试）针对评审报告中的问题逐条回复：                 │
│                                                              │
│   例：                                                        │
│   B-01. 追加时字段名称不匹配的处理策略未定义                   │
│   → 用户回复：报错阻止，大小写敏感，提示具体文案                │
│                                                              │
│   M-02. 追加时数据结构"不允许修改"的交互范围未明确             │
│   → 用户回复：全部置灰不可编辑，但能看到原表结构               │
│                                                              │
│   ...（逐条回复所有问题）...                                   │
│                                                              │
│                    │                                          │
│                    ▼                                          │
│           AI 自动处理所有回复：                                │
│           ① 将澄清结论同步补充到需求文档                       │
│           ② 更新评审报告，标记 ✅ 已解决                       │
│           ③ 对建议改进（Minor）给出设计方案                    │
│           ④ 生成新的衍生待澄清问题（如有）                     │
│                                                              │
│          ⚠️ 关键：这个阶段可能反复多轮                         │
│          直到所有阻塞和严重问题清零                            │
└──────────────────────────────────────────────────────────────┘
                                     │
                                     │  所有 Blocker 和 Major 清零
                                     │  需求文档已补充完整
                                     │
                                     ▼
┌──────────────────────────────────────────────────────────────┐
│                    📝 阶段三：用例生成                         │
│                                                              │
│  ┌──────────────────────────────────────────────────────┐   │
│  │  ④ req-test-cases（用例生成器）                        │   │
│  │    Phase 1: 生成测试点清单 → 等待用户确认              │   │
│  │    Phase 2: 展开完整手工用例                          │   │
│  └──────────────────────────────────────────────────────┘   │
│                                     │                        │
│                                     ▼                        │
│                          测试用例输出                         │
│                  docs/req-review/<slug>-test-cases.md         │
└──────────────────────────────────────────────────────────────┘

四个 Skill 的分工

Skill	角色	输入	输出	所属阶段
req-review	主协调器	需求文档路径或描述	评审报告文件	阶段一
req-review-associator	关联分析	需求描述 + 模块/类型	受影响模块和用例列表	阶段一
req-review-challenger	审查挑战	需求描述 + 类型 + 关联分析	分级问题清单	阶段一
（用户参与）	需求澄清	评审报告中的问题清单	逐条回复，AI 同步更新需求和报告	阶段二
req-test-cases	用例生成	已澄清的完整需求	结构化测试用例	阶段三

---

准备工作：创建目录结构

在你的项目根目录下创建以下文件夹结构：

.codex/
└── skills/
    ├── req-review/
    │   └── references/
    │       └── review_checklist_by_type/
    ├── req-review-associator/
    ├── req-review-challenger/
    └── req-test-cases/
        └── references/

打开终端，在项目根目录执行：

mkdir -p .codex/skills/req-review/references/review_checklist_by_type
mkdir -p .codex/skills/req-review-associator
mkdir -p .codex/skills/req-review-challenger
mkdir -p .codex/skills/req-test-cases/references

---

第一步：搭建审查清单（整个体系的知识基础）

为什么先做这个？ 审查清单是 AI 评审时逐条对照的"检查表"。没有清单，AI 只会泛泛而谈；有了清单，AI 才能不遗漏地逐条扫描。所有 Skill 都依赖它。

1.1 创建通用审查清单

创建文件 .codex/skills/req-review/references/review_checklist_common.md，写入以下完整内容：

# 通用审查清单（review_checklist_common.md）

> 与具体业务无关的测试方法论，放之四海皆准的审查规则。
> 每条规则结构统一：id / 类别 / 默认严重度 / 适用范围 / 检查问题 / 命中条件 / 建议追问

---

## 一、输入字段类（CHK-IN）

### CHK-IN-001 字符串字段的长度边界
- **类别**: boundary
- **默认严重度**: blocker
- **适用范围**: 任何用户输入的字符串字段（名称、描述、备注、标签等）
- **检查问题**:
  1. 是否明确了最小字符数？
  2. 是否明确了最大字符数？
  3. 空字符串、纯空格如何处理（拒绝/默认值/允许）？
  4. 超长输入是截断、报错还是拒绝？
- **命中条件**: 需求中提到"输入/名称/描述/备注/标签"等字段，但未给出长度范围
- **建议追问**: 请明确 <字段名> 的字符数范围（含上下界）、空值/纯空格的处理、超长输入的处理策略

### CHK-IN-002 字符串字段的字符集限制
- **类别**: boundary
- **默认严重度**: major
- **适用范围**: 任何用户输入的字符串字段
- **检查问题**:
  1. 是否明确了允许的字符集（中文/英文/数字/特殊符号/emoji）？
  2. 是否明确了禁止的字符？
  3. 特殊符号（如 `< > & " '`）如何处理（转义/过滤/拒绝）？
- **命中条件**: 需求中提到字符串输入字段，但未说明字符集限制
- **建议追问**: 请明确 <字段名> 支持的字符集，以及特殊符号的处理策略

### CHK-IN-003 数字字段的取值范围
- **类别**: boundary
- **默认严重度**: blocker
- **适用范围**: 任何用户输入的数字字段（数量、大小、时长等）
- **检查问题**:
  1. 是否明确了最小值？
  2. 是否明确了最大值？
  3. 是否支持小数？支持几位小数？
  4. 负数是否允许？
  5. 超出范围如何处理（截断/报错/拒绝）？
- **命中条件**: 需求中提到数字输入，但未给出取值范围
- **建议追问**: 请明确 <字段名> 的取值范围（含上下界）、小数位支持、超范围处理策略

### CHK-IN-004 URL/路径字段的格式校验
- **类别**: validation
- **默认严重度**: blocker
- **适用范围**: 任何 URL、文件路径、网络地址输入字段
- **检查问题**:
  1. 是否明确了合法格式（协议、域名格式、端口范围）？
  2. 是否禁止内网地址（SSRF 防护）？
  3. 是否禁止 localhost/127.0.0.1？
  4. 非法格式如何提示？
  5. 是否限制 URL 最大长度？
- **命中条件**: 需求中提到 URL/地址/路径输入，但未说明格式校验规则
- **建议追问**: 请明确 <字段名> 的合法格式、内网地址/本地地址的防护策略、非法格式的错误提示

### CHK-IN-005 枚举/下拉字段的选项完整性
- **类别**: completeness
- **默认严重度**: major
- **适用范围**: 任何枚举类型字段、下拉选择、单选/多选
- **检查问题**:
  1. 是否列出了所有可选值？
  2. 是否有默认值？
  3. 是否允许不选（空值）？
  4. 选项文案是否已确认？
  5. 选项之间是否互斥？
- **命中条件**: 需求中提到选择/下拉/枚举/类型，但未列出完整选项
- **建议追问**: 请列出 <字段名> 的所有可选值，确认默认值和是否允许空选

---

## 二、异常处理类（CHK-EX）

### CHK-EX-001 网络异常处理
- **类别**: exception
- **默认严重度**: major
- **适用范围**: 涉及外部服务调用、网络请求的功能
- **检查问题**:
  1. 外部服务超时如何处理（超时时间、重试次数、降级策略）？
  2. 外部服务返回错误（4xx/5xx）如何处理？
  3. 网络不可达时用户看到什么提示？
- **命中条件**: 需求涉及外部调用/API/连接/请求，但未说明异常处理
- **建议追问**: 请明确超时时间、重试策略、各异常状态码的处理方式和用户提示文案

### CHK-EX-002 并发/重复操作处理
- **类别**: exception
- **默认严重度**: major
- **适用范围**: 任何涉及创建、提交、删除的操作
- **检查问题**:
  1. 重复提交如何处理（幂等性）？
  2. 同名资源是否允许创建？
  3. 并发操作同一资源如何处理？
- **命中条件**: 需求涉及创建/提交/删除操作，但未说明重复/并发处理
- **建议追问**: 请明确重复提交的防重策略、同名资源的处理规则

### CHK-EX-003 资源引用/依赖处理
- **类别**: exception
- **默认严重度**: major
- **适用范围**: 资源之间存在引用关系的功能
- **检查问题**:
  1. 被其他资源引用的资源能否删除？
  2. 删除后引用方如何处理（级联删除/阻止删除/置空）？
  3. 删除前是否需要二次确认？
- **命中条件**: 需求涉及删除操作，且该资源可能被其他模块引用
- **建议追问**: 请明确 <资源名> 被引用时的删除策略和引用方的处理方式

### CHK-EX-004 数据为空/不存在处理
- **类别**: exception
- **默认严重度**: minor
- **适用范围**: 任何涉及列表/查询/展示的功能
- **检查问题**:
  1. 数据为空时展示什么（空状态文案/图示）？
  2. 资源不存在时（如访问已删除资源）如何提示？
  3. 加载中状态是否有展示？
- **命中条件**: 需求涉及列表/查询/展示，但未说明空状态和加载状态
- **建议追问**: 请确认空状态、加载中、资源不存在时的 UI 展示

---

## 三、权限与安全类（CHK-SEC）

### CHK-SEC-001 权限点定义
- **类别**: security
- **默认严重度**: blocker
- **适用范围**: 任何新增功能/页面
- **检查问题**:
  1. 是否定义了访问权限点（谁能访问）？
  2. 是否定义了操作权限点（谁能操作）？
  3. 无权限用户看到什么（隐藏入口/禁用按钮/提示无权限）？
  4. 是否涉及数据权限（只看自己的/看全部）？
- **命中条件**: 需求涉及新功能/页面/操作，但未说明权限
- **建议追问**: 请明确 <功能> 的访问权限和操作权限点，以及无权限时的 UI 表现

### CHK-SEC-002 敏感数据处理
- **类别**: security
- **默认严重度**: major
- **适用范围**: 涉及密码、Token、密钥、个人信息的功能
- **检查问题**:
  1. 敏感数据是否加密存储？
  2. 敏感数据是否脱敏展示？
  3. 传输过程是否加密？
  4. 日志中是否会记录敏感信息？
- **命中条件**: 需求涉及密钥/密码/Token/个人信息
- **建议追问**: 请确认敏感数据的存储加密、展示脱敏、传输加密策略

---

## 四、兼容性与环境类（CHK-ENV）

### CHK-ENV-001 多环境适配
- **类别**: compatibility
- **默认严重度**: minor
- **适用范围**: 任何新增功能
- **检查问题**:
  1. Private 环境（内网/私有化）是否可用？
  2. International 环境（国际化）是否可用？
  3. 不同环境下行为是否有差异？
- **命中条件**: 产品支持多环境部署，但需求未提及环境差异
- **建议追问**: 请确认 <功能> 在 Private/International 环境下的行为差异

### CHK-ENV-002 浏览器兼容性
- **类别**: compatibility
- **默认严重度**: minor
- **适用范围**: Web 前端功能
- **检查问题**:
  1. 是否明确了支持的浏览器及版本？
  2. 是否涉及特殊浏览器 API（可能不兼容）？
- **命中条件**: Web 前端功能，但未说明浏览器兼容
- **建议追问**: 请确认支持的浏览器及最低版本

---

## 五、数据与状态类（CHK-DT）

### CHK-DT-001 数据持久化与生命周期
- **类别**: data
- **默认严重度**: major
- **适用范围**: 任何涉及数据创建/修改的功能
- **检查问题**:
  1. 数据存储在哪里（数据库表/文件）？
  2. 数据是否有过期/删除机制？
  3. 数据量上限是多少？
  4. 数据是否需要备份/恢复？
- **命中条件**: 需求涉及数据创建/存储，但未说明生命周期
- **建议追问**: 请明确数据的存储方式、数量上限、过期策略

### CHK-DT-002 状态流转
- **类别**: data
- **默认严重度**: major
- **适用范围**: 资源有状态变化的功能
- **检查问题**:
  1. 是否定义了所有可能的状态？
  2. 状态之间如何流转（哪些是合法流转）？
  3. 各状态下允许哪些操作？
  4. 非法状态流转如何处理？
- **命中条件**: 需求涉及资源状态变化，但未给出完整状态机
- **建议追问**: 请给出 <资源名> 的完整状态流转图和各状态下的可用操作

---

## 六、审计与日志类（CHK-LOG）

### CHK-LOG-001 操作审计日志
- **类别**: audit
- **默认严重度**: major
- **适用范围**: 任何涉及创建/编辑/删除的功能
- **检查问题**:
  1. 是否需要记录审计日志？
  2. 日志记录哪些字段（操作人/时间/操作类型/操作对象/操作详情）？
  3. 日志 Content 格式是什么？
- **命中条件**: 需求涉及增删改操作，但未提及审计日志
- **建议追问**: 请确认是否需要记录审计日志，以及日志的 Content 格式

### CHK-LOG-002 统计/计费口径
- **类别**: audit
- **默认严重度**: major
- **适用范围**: 涉及资源消耗/调用的功能
- **检查问题**:
  1. 是否纳入用量统计？
  2. 统计颗粒度是什么（次数/Token/流量/时长）？
  3. 是否计费？
- **命中条件**: 需求涉及资源调用/消耗，但未说明统计口径
- **建议追问**: 请确认是否纳入资源看板统计，以及统计颗粒度和计费规则

---

## 七、交互与体验类（CHK-UX）

### CHK-UX-001 操作反馈与提示
- **类别**: ux
- **默认严重度**: minor
- **适用范围**: 任何用户操作
- **检查问题**:
  1. 操作成功是否有反馈（Toast/提示/跳转）？
  2. 操作失败是否有明确错误提示？
  3. 耗时操作是否有进度提示？
  4. 是否需要操作确认（如删除二次确认）？
- **命中条件**: 需求涉及用户操作，但未说明反馈方式
- **建议追问**: 请确认操作成功/失败的提示方式和文案

### CHK-UX-002 列表/表格功能
- **类别**: ux
- **默认严重度**: minor
- **适用范围**: 涉及列表/表格展示的功能
- **检查问题**:
  1. 是否支持分页？每页默认条数？
  2. 是否支持排序？支持哪些字段排序？
  3. 是否支持筛选/搜索？搜索范围是什么？
  4. 列表为空时展示什么？
- **命中条件**: 需求涉及列表/表格，但未说明分页/排序/筛选
- **建议追问**: 请确认列表的分页、排序、筛选需求

---

## 维护说明
- 每条规则的 id 格式：`CHK-<类别缩写>-<序号>`，确保唯一可追溯
- 修改审查行为只需编辑此文件，SKILL.md 无需改动（知识与流程解耦）
- 随着测试经验积累，可持续补充新规则

1.2 创建需求类型识别表

创建文件 .codex/skills/req-review/references/requirement_types.md：

# 需求类型识别表

> 用于 req-review-challenger 判断需求类型，按命中类型加载专项审查清单。

| type_id | 需求类型 | 关键词/特征 | 对应 checklist |
|---------|----------|-------------|---------------|
| TYPE-001 | 新增功能 | 新增、新建、增加、创建、添加 | `review_checklist_by_type/new_feature.md` |
| TYPE-002 | 功能优化 | 优化、改进、调整、修改 | `review_checklist_by_type/optimization.md` |
| TYPE-003 | 缺陷修复 | 修复、bug、问题、异常 | `review_checklist_by_type/bugfix.md` |
| TYPE-004 | 交互变更 | 交互、UI、页面、展示、样式 | `review_checklist_by_type/ui_change.md` |
| TYPE-005 | 权限变更 | 权限、角色、访问控制、可见性 | `review_checklist_by_type/permission.md` |

## 维护说明
- 随着产品迭代，可新增更多类型
- 每个类型对应 `review_checklist_by_type/` 下一个 md 文件
- 类型表为空或未命中时，challenger 仅使用通用清单

1.3 创建 5 个专项审查清单

创建 review_checklist_by_type/new_feature.md（新增功能专项）：

# 新增功能专项审查清单

> 当需求类型识别为"新增功能"时，在通用清单基础上补充加载本清单。

### CHK-NF-001 与已有功能的边界
- **类别**: completeness
- **默认严重度**: blocker
- **适用范围**: 任何新增功能
- **检查问题**:
  1. 新功能与已有类似功能的关系是什么（替换/并存/子集）？
  2. 如果替换旧功能，旧功能的迁移路径是什么？
  3. 旧入口是否保留？旧 API 是否兼容？
  4. 新功能是否影响已有功能的枚举/配置项？
- **命中条件**: 新增功能与已有功能存在重叠或替代关系
- **建议追问**: 请明确新功能与已有 <功能名> 的关系，以及旧功能的处理策略

### CHK-NF-002 入口与导航
- **类别**: completeness
- **默认严重度**: major
- **适用范围**: 任何新增页面/功能入口
- **检查问题**:
  1. 功能入口放在哪个菜单/页面？
  2. 是否需要独立的导航路由？
  3. 是否需要在多处入口（如快捷入口）？
  4. 移动端/不同分辨率下入口是否可见？
- **命中条件**: 新增功能需要页面入口，但未说明入口位置
- **建议追问**: 请确认功能入口位置、导航路径和是否需要在多处露出

### CHK-NF-003 数据初始化与默认值
- **类别**: completeness
- **默认严重度**: major
- **适用范围**: 新增功能涉及数据
- **检查问题**:
  1. 系统初始化时是否有默认数据？
  2. 首次使用时用户看到什么（引导/空状态）？
  3. 历史数据是否需要迁移/初始化？
- **命中条件**: 新增功能，但未说明初始状态
- **建议追问**: 请确认功能的初始状态、默认数据和首次使用引导

创建 review_checklist_by_type/optimization.md（功能优化专项）：

# 功能优化专项审查清单

> 当需求类型识别为"功能优化"时，在通用清单基础上补充加载本清单。

### CHK-OP-001 优化范围与兼容性
- **类别**: compatibility
- **默认严重度**: blocker
- **适用范围**: 任何功能优化
- **检查问题**:
  1. 优化是否改变已有行为（Breaking Change）？
  2. 旧数据/旧配置是否需要迁移？
  3. 旧 API 是否保持兼容？
  4. 是否有灰度/回滚方案？
- **命中条件**: 需求涉及功能优化，但未说明兼容性和回滚策略
- **建议追问**: 请确认本次优化的 Breaking Change 清单、数据迁移方案和回滚策略

### CHK-OP-002 性能影响
- **类别**: performance
- **默认严重度**: major
- **适用范围**: 涉及查询/计算/批量操作的功能优化
- **检查问题**:
  1. 优化后性能是否有预期提升？
  2. 大数据量下表现如何？
  3. 是否需要性能基准测试？
- **命中条件**: 需求涉及性能相关优化或影响查询效率
- **建议追问**: 请确认性能优化的预期指标和大数据量下的表现

创建 review_checklist_by_type/bugfix.md（缺陷修复专项）：

# 缺陷修复专项审查清单

> 当需求类型识别为"缺陷修复"时，在通用清单基础上补充加载本清单。

### CHK-BF-001 影响范围
- **类别**: completeness
- **默认严重度**: major
- **适用范围**: 任何缺陷修复
- **检查问题**:
  1. 修复是否只影响报告的场景，还是影响更广？
  2. 是否有类似场景也存在同样问题？
  3. 修复是否引入了新问题（回归风险）？
- **命中条件**: 缺陷修复，但未说明影响范围
- **建议追问**: 请确认修复的影响范围和是否存在类似问题需要一并修复

### CHK-BF-002 回归测试范围
- **类别**: completeness
- **默认严重度**: major
- **适用范围**: 任何缺陷修复
- **检查问题**:
  1. 修复涉及哪些模块/接口？
  2. 需要回归哪些已有功能？
  3. 是否需要更新自动化用例？
- **命中条件**: 缺陷修复，但未说明回归范围
- **建议追问**: 请确认需要回归的功能清单

创建 review_checklist_by_type/ui_change.md（交互变更专项）：

# 交互变更专项审查清单

> 当需求类型识别为"交互变更"时，在通用清单基础上补充加载本清单。

### CHK-UI-001 多端适配
- **类别**: compatibility
- **默认严重度**: major
- **适用范围**: 任何 UI/交互变更
- **检查问题**:
  1. 不同分辨率下表现是否一致？
  2. 移动端/平板端是否需要适配？
  3. 不同浏览器渲染是否一致？
- **命中条件**: UI 变更，但未说明多端适配
- **建议追问**: 请确认多分辨率/多设备/多浏览器的适配方案

### CHK-UI-002 文案与国际化
- **类别**: completeness
- **默认严重度**: minor
- **适用范围**: 涉及文案变更的 UI 改动
- **检查问题**:
  1. 新增/修改的文案是否需要国际化翻译？
  2. 不同语言下文案长度是否会导致布局问题？
  3. 是否有英文/中文文案已确认？
- **命中条件**: UI 变更涉及文案，但未说明国际化
- **建议追问**: 请确认文案的国际化需求和不同语言下的文案内容

创建 review_checklist_by_type/permission.md（权限变更专项）：

# 权限变更专项审查清单

> 当需求类型识别为"权限变更"时，在通用清单基础上补充加载本清单。

### CHK-PM-001 权限点全量覆盖
- **类别**: completeness
- **默认严重度**: blocker
- **适用范围**: 任何权限变更
- **检查问题**:
  1. 新增/修改的权限点是否覆盖所有受影响的入口？
  2. 是否有遗漏的页面/按钮/操作？
  3. 权限点之间的继承/包含关系是否清晰？
- **命中条件**: 权限变更，但未列出完整的受影响入口
- **建议追问**: 请列出所有受权限变更影响的页面入口和操作按钮

### CHK-PM-002 越权验证
- **类别**: security
- **默认严重度**: blocker
- **适用范围**: 任何权限变更
- **检查问题**:
  1. 无权限用户是否被正确拦截？
  2. 通过 URL 直接访问是否能绕过权限？
  3. 通过 API 直接调用是否能绕过权限？
  4. 低权限角色能否越权执行高权限操作？
- **命中条件**: 权限变更，需验证越权防护
- **建议追问**: 请确认无权限用户的拦截策略（隐藏入口/提示无权限/返回 403）

1.4 创建关联规则表（初始为空，预留结构）

创建文件 .codex/skills/req-review/references/association_rules.md：

# 关联规则表

> 定义模块间隐式依赖关系，帮助关联分析时发现需求中未提及但可能受影响的模块。
> 起步为空，随着评审实践逐步补充。

| rule_id | trigger_module | trigger_keywords | affected_modules | reason |
|---------|---------------|------------------|------------------|--------|
| | | | | |

## 维护说明
- `trigger_module`：触发模块名
- `trigger_keywords`：触发关键词（需求中出现这些词时可能影响其他模块）
- `affected_modules`：可能受影响的模块列表
- `reason`：关联原因说明
- 每次评审后如发现新的隐式关联，可补充到表中

## 填写示例（根据你的实际产品调整）
| rule_id | trigger_module | trigger_keywords | affected_modules | reason |
|---------|---------------|------------------|------------------|--------|
| AR001 | 配置中心 | 标签、标签管理 | 探索发现-市场, 我的资源-分类 | 标签变更影响市场筛选和资源分类 |

1.5 创建产品特性关联规则（初始为空，预留结构）

创建文件 .codex/skills/req-test-cases/references/feature_impact_rules.md：

# 产品特性关联规则（feature_impact_rules.md）

> 业务规则：编码产品特有的隐式依赖关系。
> 当某个模块发生变更时，必须连带验证哪些下游特性。
> 起步为空，随着测试实践逐步补充。

| rule_id | trigger_module | trigger_action | must_test_features | reason |
|---------|---------------|----------------|--------------------|--------|
| | | | | |

## 维护说明
- `rule_id`：规则唯一标识，格式 `FR<序号>`
- `trigger_module`：触发模块名（对应产品模块）
- `trigger_action`：触发动作描述
- `must_test_features`：必须连带验证的特性列表
- `reason`：关联原因说明
- 每条规则帮助 req-test-cases 在生成测试点时自动补充必测点

## 填写示例（根据你的产品特性调整）
| rule_id | trigger_module | trigger_action | must_test_features | reason |
|---------|---------------|----------------|--------------------|--------|
| FR001 | 配置中心-标签管理 | 新增/修改标签 | 探索发现-市场-筛选, 我的资源-标签展示 | 标签是市场和资源列表的筛选维度 |
| FR002 | 配置中心-扩展属性 | 新增/修改扩展属性 | 对应资源的详情页, 对应资源的编辑页 | 扩展属性绑定到具体资源类型 |
| FR003 | 消息中心 | 新增消息类型 | 对应触发模块-消息发送, 消息中心-消息列表 | 消息类型变更需验证发送和接收全链路 |

✅ 第一步完成：你现在有了 15 条通用审查规则 + 5 类专项审查清单（共 11 条专项规则），覆盖了输入字段、异常处理、权限安全、兼容性、数据状态、审计日志、交互体验 7 大维度。

---

第二步：创建 4 个 Skill 文件

2.1 创建 req-review（主协调器）

创建文件 .codex/skills/req-review/SKILL.md：

# 需求评审主 Skill (req-review)

## 概述
本 Skill 负责对产品需求进行结构化评审，通过主从编排串联关联分析和审查挑战两个子 Skill，最终产出评审报告。

## 输入
- 需求描述文本（用户直接输入或粘贴）
- 可选：需求文档路径（`产品需求文档/` 下的 md 文件）

## 工作流（3 步）

### Step 1: 输入理解与需求解析
1. 理解用户输入的需求内容，提取关键信息：
   - 需求所属模块（根据你的产品模块列表填写，如：数据集成 / 工作台 / 我的资源 / 探索发现 / 数据质量 / 配置中心 / 消息中心）
   - 需求类型（新增功能 / 功能优化 / 缺陷修复 / 交互变更 / 权限变更）
   - 涉及的字段、接口、页面入口
2. 生成一个 `slug`（需求简称，英文小写+连字符，如 `connector-create`），用于后续文件命名。
3. 向用户确认解析结果（模块、类型、slug），确认无误后进入 Step 2。

### Step 2: 关联分析（委托 req-review-associator）
1. 调用子 Skill `req-review-associator`，将需求描述和已确认的模块/类型传入。
2. 子 Skill 返回关联分析结果（受影响模块列表 + 受影响用例列表）。
3. 将关联分析结果暂存，进入 Step 3。

### Step 3: 审查挑战（委托 req-review-challenger）
1. 调用子 Skill `req-review-challenger`，将以下内容传入：
   - 原始需求描述
   - Step 1 确认的需求类型
   - Step 2 关联分析结果
2. 子 Skill 返回评审报告内容。
3. 将评审报告写入 `docs/req-review/<slug>-review.md`。
4. 向用户展示评审报告摘要，标记阻塞问题数量和严重问题数量。

## 输出
- 评审报告文件：`docs/req-review/<slug>-review.md`
- 对话中展示的摘要信息

## 知识库引用
- `references/requirement_types.md` --- 需求类型识别表
- `references/review_checklist_common.md` --- 通用审查清单
- `references/review_checklist_by_type/` --- 按类型的专项审查清单
- `references/association_rules.md` --- 关联规则表
- `产品需求文档/` --- 已有产品需求文档
- `cases/` --- 已有测试用例

2.2 创建 req-review-associator（关联分析子 Skill）

创建文件 .codex/skills/req-review-associator/SKILL.md：

# 关联分析子 Skill (req-review-associator)

## 概述
单一职责：根据新需求描述，找出受影响的已有模块和相关测试用例。

## 输入
- 需求描述文本
- 已确认的需求所属模块
- 已确认的需求类型

## 工作流

### Step 1: 语义搜索受影响模块
1. 在 `产品需求文档/` 目录下执行语义检索（优先使用语义搜索，搜索词从需求描述中提取关键概念）。
2. 语义搜索失效时降级为文本关键词搜索。
3. 识别出与新需求有功能重叠、数据依赖、流程关联的已有模块。
4. 列出受影响模块清单，附上引用证据（文档路径 + 关键段落摘要）。

### Step 2: 搜索受影响用例
1. 在 `cases/` 目录下搜索与受影响模块相关的已有测试用例。
2. 优先使用语义搜索，失效时降级为文本搜索。
3. 读取 Top 3 匹配用例的文件头（类名、用例描述、测试步骤摘要），了解已有测试覆盖范围。
4. 列出受影响用例清单，附上引用证据（文件路径 + 用例描述摘要）。

### Step 3: 读取关联规则表
1. 读取 `req-review/references/association_rules.md`（如存在）。
2. 如果关联规则表中有匹配的规则，补充到关联分析结果中。

## 输出
返回 Markdown 格式的关联分析结果（不落盘，由主 Skill 合并到评审报告）：

```markdown
## 关联分析

### 受影响模块
| 模块 | 关联原因 | 引用证据 |
|------|----------|----------|
| <模块名> | <原因> | <文档路径> |

### 受影响用例
| 用例文件 | 关联原因 | 引用证据 |
|----------|----------|----------|
| <文件路径> | <原因> | <用例描述摘要> |

### 关联规则匹配（如有）
| 规则 ID | 触发条件 | 建议验证点 |
|---------|----------|------------|
```

## 知识库引用
- `产品需求文档/` --- 已有产品需求文档（语义搜索目标）
- `cases/` --- 已有测试用例（语义搜索目标）
- `req-review/references/association_rules.md` --- 关联规则表

2.3 创建 req-review-challenger（审查挑战子 Skill）

创建文件 .codex/skills/req-review-challenger/SKILL.md：

# 审查挑战子 Skill (req-review-challenger)

## 概述
单一职责：按照审查清单逐条挑战需求，发现缺失、矛盾、模糊之处，组装评审报告。

## 输入
- 原始需求描述
- 需求类型（来自主 Skill Step 1 确认结果）
- 关联分析结果（来自 associator 子 Skill）

## 工作流

### Step 1: 加载审查清单
1. 读取 `req-review/references/requirement_types.md`，确认需求类型是否命中已知类型。
2. 始终加载 `req-review/references/review_checklist_common.md`（通用审查清单）。
3. 如果需求类型命中，加载 `req-review/references/review_checklist_by_type/<type>.md`（专项审查清单）。
4. 如果类型表为空或未命中，仅使用通用清单。

### Step 2: 逐条挑战
对加载的每一条审查规则：
1. 读取规则的"命中条件"，判断当前需求是否触发该规则。
2. 如果触发，按规则的"检查问题"逐条分析需求中是否已有明确说明。
3. 如果需求未覆盖该检查点，记录为 finding。
4. 结合关联分析结果，判断是否需要跨模块验证。

### Step 3: 分级归类
将发现的 finding 按严重度分级：
- **🚨 阻塞问题（Blocker）**：需求缺失导致无法设计用例
- **⚠️ 严重问题（Major）**：影响范围大，需 PM 确认
- **📝 建议改进（Minor）**：不影响用例设计，但建议完善
- **ℹ️ 信息确认（Info）**：关联模块影响，需确认

### Step 4: 组装报告
按以下结构组装评审报告：

```markdown
# <需求名称> 需求评审报告

## 基本信息
- 需求 slug: <slug>
- 所属模块: <模块>
- 需求类型: <类型>
- 评审日期: <日期>

## 关联分析
<来自 associator 的结果>

## 🚨 阻塞问题（Blocker）
### B<N>. <问题标题>
- **命中规则**: <规则 ID 和名称>
- **问题**: <问题描述>
- **引用证据**: <相关文档/用例路径>
- **给 PM 的追问**: <具体追问>

## ⚠️ 严重问题（Major）
...

## 📝 建议改进（Minor）
...

## ℹ️ 信息确认（Info）
...

## 评审统计
- 阻塞问题: <数量>
- 严重问题: <数量>
- 建议改进: <数量>
- 信息确认: <数量>
```

## 输出
完整的评审报告 Markdown 内容，由主 Skill 写入文件。

## 知识库引用
- `req-review/references/review_checklist_common.md` --- 通用审查清单（必加载）
- `req-review/references/requirement_types.md` --- 需求类型识别表
- `req-review/references/review_checklist_by_type/` --- 按类型的专项审查清单

2.4 创建 req-test-cases（用例生成器）

创建文件 .codex/skills/req-test-cases/SKILL.md：

# 手工用例生成 Skill (req-test-cases)

## 概述
两阶段工作流：先生成测试点清单（轻量），用户确认后再展开为详细手工用例。

## 输入
- 需求评审报告（`docs/req-review/<slug>-review.md`）或原始需求描述
- 可选：用户对测试点的补充说明

## 工作流

### Phase 1: 生成测试点清单

#### Step 1: 读取需求与评审结果
1. 如果提供了评审报告路径，读取报告内容。
2. 如果只有需求描述，直接使用需求描述。
3. 提取需求中的功能点、字段、交互入口。

#### Step 2: 加载业务规则
1. 读取 `references/feature_impact_rules.md`（如存在且非空）。
2. 匹配当前需求涉及的模块和动作，找出 `must_test_features`（必测特性）。
3. 将命中的必测特性纳入测试点规划。

#### Step 3: 语义搜索已有用例
1. 在 `cases/` 目录下执行 2-3 次语义搜索，关键词为需求涉及的模块名和功能关键词。
2. 读取 Top 3 匹配用例的文件头，了解步骤粒度和写法风格。
3. 标记"关联用例参考"用于后续用例编写。

#### Step 4: 生成测试点清单
按优先级分层生成测试点：

- **🟥 最高 - 核心功能**：核心功能的正常路径
- **🟧 较高 - 边缘功能 & 核心功能的异常路径 & 核心功能的边界值**
- **🟦 一般 - 边缘功能的边界值 & 边缘功能的异常路径**
- **🟨 低 - 兼容性 & 权限 & 多环境**
- **⬜ 暂不测试 / 待澄清**：依赖 PM 澄清的测试点

#### Step 5: 写入文件并等待确认
1. 将测试点清单写入 `docs/req-review/<slug>-test-cases.md`。
2. 文件头设置 `status: 测试点待确认`。
3. 在对话中展示测试点清单摘要，明确告知用户：
   - "请确认以上测试点，你可以：直接回复「确认，生成用例」/ 删除不需要的测试点 / 补充新的测试点"
4. **停止执行，等待用户反馈。**

### Phase 2: 展开手工用例（用户确认后执行）

#### Step 1: 读取测试点清单
1. 读取 `docs/req-review/<slug>-test-cases.md`。
2. 解析用户确认后的测试点列表。

#### Step 2: 加载业务规则（补充验证）
1. 再次读取 `references/feature_impact_rules.md`。
2. 检查业务规则中是否有"测试要点"需要在用例步骤中体现。

#### Step 3: 展开手工用例
为每个测试点生成结构化手工用例，使用以下表格格式：

```markdown
| 用例名称 | 前置条件 | 关键词 | 优先级 | 用例类型 | 适用阶段 | 用例状态 | 步骤 | 预期 |
| -------- | -------- | ------ | ------ | -------- | -------- | -------- | ---- | ---- |
| <一级目录>-<二级目录>-<功能点序号><功能点>-<测试点>功能测试 | - <条件1><br/>- <条件2> |  | 最高/较高/一般/低 | 功能测试/安全测试/界面测试/其他 |  | 待评审 | 1. <步骤1><br/>2. <步骤2><br/>... | 1. <结果1><br/>2. <结果2><br/>... |
```

#### Step 4: 覆写文件
1. 将完整用例覆写 `docs/req-review/<slug>-test-cases.md`。
2. 更新 `status: 已生成`。
3. 向用户展示生成结果摘要（用例总数、最高/较高/一般/低 分布）。

## 输出
- 测试用例文件：`docs/req-review/<slug>-test-cases.md`

## 知识库引用
- `references/feature_impact_rules.md` --- 产品特性关联规则（业务规则）
- `cases/` --- 已有测试用例（语义搜索参考）
- `产品需求文档/` --- 已有产品需求文档

✅ 第二步完成 ：你现在有了完整的 4 个 Skill 文件。req-review 作为主协调器，associator 和 challenger 各司其职，req-test-cases 负责两阶段用例生成。

---

第三步：准备需求文档和用例目录

Skill 需要读写以下目录，确保它们存在：

mkdir -p "产品需求文档"
mkdir -p cases
mkdir -p docs/req-review

• 产品需求文档/：存放你的产品需求 MD 文件（按模块组织）
• cases/：存放已有测试用例（AI 会参考写法风格）
• docs/req-review/：AI 输出的评审报告和用例文件

---

第四步：验证------跑一次完整流程

现在来完整演示一次。假设你有一个需求文档 产品需求文档/4.我的资源/数据资源/数据资源.md，其中 §2.2.5 描述了"上传数据-替换、追加"功能。

4.1 阶段一：触发需求评审

在 codex 对话框中输入：

@req-review 请评审 产品需求文档/4.我的资源/数据资源/数据资源.md 中 §2.2.5 上传数据-替换、追加 的需求

AI 会执行 3 个步骤：

Step 1 --- 解析需求 ：AI 提取出模块="我的资源 > 数据资源"，类型="功能优化"（因为关键词"替换/追加"属于"调整/修改"范畴），生成 slug=upload-replace-append，然后向你确认。

Step 2 --- 关联分析 ：AI 搜索 产品需求文档/ 和 cases/ 目录，找出受影响模块。例如发现：

• 消息中心（上传任务进度通知）
• 数据建模（替换后的数据作为建模输入）
• 数据市场（已发布数据被替换后的同步）

Step 3 --- 逐条审查：AI 加载通用清单 15 条 + 优化专项清单 2 条，逐条判断命中条件。命中的规则触发检查，未覆盖的检查点记录为问题。

最终输出评审报告 docs/req-review/upload-replace-append-review.md，包含类似这样的问题清单：

严重度	数量	示例
🚨 阻塞	3	追加字段不匹配策略未定义、替换结构不一致边界未定义、目标表范围兼容性
⚠️ 严重	5	已发布市场冲突校验、追加交互范围、替换交互定义、不匹配提示文案、空间不足
📝 建议	4	清空二次确认、行数超限、敏感数据校验、目标表选择交互
ℹ️ 确认	3	已有评审关联、数据结构刷新、审计日志

4.2 阶段二：需求澄清（最关键的人机协作环节）

评审报告给出了 12 个问题，但 AI 不知道答案。你需要把问题丢给 PM。PM 在问题后面直接回复（不需要写完整句子）：

B-01. 追加时字段名称不匹配的处理策略未定义：
  报错阻止，大小写敏感，提示具体文案

B-02. 替换时数据结构"可以不一致"的边界未定义：
  列名必须一致，字段类型可重新定义，字段数量不减少

B-03. 目标表选择范围缩小为仅「离线上传」，是否存在兼容性问题：
  仅限于离线上传

M-01. 追加/替换时"已发布到市场"的冲突校验仍然缺失：
  自动同步更新，不需要二次确认

M-02. 追加时数据结构"不允许修改"的交互范围未明确：
  全部置灰不可编辑，但能看到原表结构

M-03. 替换模式下用户手动修改数据结构的交互定义不完整：
  交互规则与离线上传（新增）一致

M-04. 追加时字段名称对应失败后的用户引导不明确：
  需要具体的提示文案（多余列/缺失列/名称不匹配/格式不匹配四种场景）

M-05. 替换/追加操作的空间不足处理：
  暂不考虑

📝 建议改进（Minor）：帮我改进

将以上回复发给 AI，AI 自动完成 5 件事：

动作	效果
① 整理澄清结论	将简短回复展开为结构化结论，标注命中规则
② 同步更新需求文档	将规则、文案、交互细节补充到需求文档对应章节
③ 更新评审报告	问题标记 ✅ 已解决，附上澄清结论
④ 处理 Minor 建议	"帮我改进"的建议自动给出设计方案（二次确认弹窗、行数上限校验等）
⑤ 生成衍生问题	如有新模糊点，生成衍生待澄清问题

这一轮之后：3 个阻塞 + 5 个严重全部清零，4 个建议全部设计完成。 需求文档从"模糊"变成"完整"。

这就是这套工具价值最大的一步：以前测试工程师要分 3-4 次、在 IM 上零散地追问 PM，现在所有问题一次性列出来，PM 一次性回复，文档一次性补全。

4.3 阶段三：生成测试用例

需求已经完整了，现在生成用例：

@req-test-cases 帮我生成这部分的功能用例：#### 2.2.5 上传数据-替换、追加
（粘贴已澄清后的需求内容）

Phase 1：AI 生成测试点清单（56 条），按优先级分层展示，等待确认。

Phase 2：你确认后（可以说"确认，生成用例"，也可以"删除 T15"或"补充 XX 场景"），AI 展开为 54 条完整手工用例，格式统一：

用例名称	前置条件	关键词	优先级	用例类型	适用阶段	用例状态	步骤	预期

---

第五步：适配到你自己的项目

5.1 改模块列表

编辑 req-review/SKILL.md 的 Step 1，把模块列表改成你产品的模块：

- 需求所属模块（你的模块A / 你的模块B / 你的模块C / ...）

5.2 补充关联规则（重要！）

association_rules.md 和 feature_impact_rules.md 初始为空。但你可以根据对自己产品的了解，把模块间的隐式依赖填进去。例如：

association_rules.md 中补充：

| AR001 | 配置中心 | 标签变更 | 探索发现-市场, 我的资源-分类 | 标签是市场和资源列表的筛选维度 |
| AR002 | 消息中心 | 新增消息类型 | 所有触发模块 | 消息类型变更影响所有发送方 |

feature_impact_rules.md 中补充：

| FR001 | 数据集成-连接管理 | 新增连接类型 | 工作台-数据源选择, 我的资源-数据列表 | 连接类型是所有数据操作的入口 |

这些规则填得越全，AI 的关联分析和必测点推荐就越准。

5.3 调整用例格式

如果你的团队用不同的用例模板（比如多了一列"测试数据"），编辑 req-test-cases/SKILL.md 中 Phase 2 Step 3 的表格格式即可。

---

常见问题

Q: 审查清单会不会太长，导致 AI 输出太多无用问题？

A: 每条规则都有"命中条件"，只有命中的规则才会触发检查。比如"URL 字段格式校验"只在需求出现 URL 相关描述时才触发。15 条通用规则在单次评审中通常只命中 5-8 条。

Q: 关联规则表是空的，AI 怎么找受影响模块？

A: AI 会通过语义搜索在 产品需求文档/ 中找相关内容。关联规则表的作用是补充 AI 搜索不到的"隐式依赖"（比如改标签配置会影响市场筛选，这种依赖很难通过文本搜索发现）。建议每次评审后把发现的隐式关联补进去。

Q: 我没有任何技术背景，能搭建这套 Skills 吗？

A: 可以。所有文件都是纯 Markdown 格式的自然语言指令，不需要写任何代码。本文每一步都给出了完整的文件内容，复制粘贴即可。

Q: 搭建后怎么分享给团队？

A: .codex/skills/ 目录在项目仓库里，提交到 Git 后团队成员 clone 下来就能用。审查规则（references）也可以让团队成员共同维护。

---

总结

环节	以前	搭建这套 Skills 后
需求评审	逐字读文档，凭经验找遗漏	AI 按 15 条通用 + 11 条专项规则逐条扫描
需求澄清	IM 上零散追问 PM，容易遗漏	所有问题一次性列出来，PM 一次性回复，文档一次性补全
写测试用例	正常流程居多，异常路径靠记忆	异常路径和边界值自动覆盖，54 条用例覆盖 7 个维度
经验传承	靠人传人，离职即流失	沉淀在审查清单和关联规则中，越用越强

这套工具的核心不是 AI 有多聪明，而是把测试工程师的审查方法结构化、可复用、不遗漏。当你的审查清单覆盖了 15 条规则，AI 每次评审都会逐一扫描------不会因为加班太晚漏掉"权限校验"，不会因为需求太长忘了"空数据处理"。