test-case-designer v2.0.2A

Immutable. This exact content is served forever at /api/v1/blob/76ab24a4b74dfd66.

---
name: test-case-designer
description: 当用户需要测试设计、测试用例、test case 或 test design 时使用。基于 PRD、设计稿、技术方案、接口文档、代码或 diff，产出输入上下文、测试点和完整用例；支持黑盒与白盒分析、回归补测、完整模式（三阶段门禁）及快速模式（一次性产出）。
metadata:
  author: "devkeel"
  version: "2.0.2"
---

# 测试用例设计师

## Read First

按需加载以下参考文档：

- `references/testing-dimension-matrix.md` — 领域检测信号、基础/专项维度矩阵、使用规则
- `references/source-analysis.md` — OpenSpec spec 使用规则、查找流程、输入合并策略
- `references/output-contract.md` — 产出路径、输出格式、平台标签规则

## 概述

这个 skill 支持两种工作模式：

- **Mode A: full** — 三阶段门禁流程，适合人工驱动的完整测试设计（输入上下文 → 测试点 → 测试用例）
- **Mode B: fast** — 一次性产出，适合 subagent 调用或需要快速产出的场景

## 参数

| 参数 | 可选值 | 默认值 | 说明 |
|------|--------|--------|------|
| mode | `full` / `fast` | `full` | 工作模式。full = 三阶段门禁；fast = 一次性产出 |
| domain | `auto` / `前端` / `后端` / `移动端` / `桌面` / `CLI` / `库` / `系统` / `DevOps` | `auto` | 领域类型，决定启用哪些测试维度。auto = 自动检测项目信号 |

参数传递方式：用户通过自然语言或显式参数指定，例如：
- `/test-case-designer` → full 模式，自动检测领域
- `/test-case-designer fast 桌面` → fast 模式，桌面领域维度
- subagent 调用时默认 `fast` + `auto`

向后兼容：`frontend`/`backend`/`all` 仍可作为 domain 值使用（映射为 前端/后端/前端+后端）。

## Agent 接口

当作为 subagent 被调用时：

- 默认 `mode=fast`（除非显式指定 full）
- 输入：调用方提供的上下文文件路径（brainstorm.md、explore.md、specs 等）
- 输出：写入调用方指定的路径（schema 流程内为 `openspec/changes/<name>/test-points.md`）
- 自检 checklist 自动执行，不等待人工门禁

## 共享层

以下规则在两种模式中均生效。

### Hard Rules

1. 同时存在黑盒与白盒输入时，必须联合分析，不允许只凭其中一侧生成交付物。
2. 把 PRD / 设计稿 / 技术方案视为"目标行为"，把代码 / diff / 运行现状视为"当前行为"；两者冲突时，必须输出"规格与实现差异"。
3. 每个测试点必须分配稳定追溯键，格式：`TP-<BIG>-<SMALL>-<TYPE>-NNN`。
4. 每条测试用例都必须能回链到至少一个测试点编号。
5. 若任务来自缺陷修复，至少补两类测试用例：问题复现与防回归。
6. 用户已提供功能清单、测试点清单、脑图或模块列表时，必须逐项映射到能力域、页面载体或测试点。

### 输入源分析

测试设计基于以下输入，按优先级从高到低：

| 优先级 | 输入来源 | 路径 | 说明 |
|--------|---------|------|------|
| 1 | OpenSpec Spec 文件 | `openspec/changes/<name>/specs/*/spec.md` | 精确的 WHEN/THEN 行为契约，每个场景必须有对应测试用例 |
| 2 | 需求文档 / brainstorm | `openspec/changes/<name>/brainstorm.md` 或 `docs/requirement/*.md` | 功能模块描述、交互规则、页面状态 |
| 3 | 技术方案 / explore | `openspec/changes/<name>/design.md`、`explore.md` | 架构决策、关键路径、风险点 |
| 4 | 用户直接提供 | 对话上下文 | PRD、交互说明或功能描述 |

#### Spec 文件使用规则

当存在 OpenSpec spec 文件时：

1. **Spec 场景全覆盖**：每个 `#### Scenario` 必须映射为至少一条测试用例，不允许遗漏
2. **WHEN/THEN 映射**：Scenario 中的 WHEN 条件映射为前置条件 + 操作步骤，THEN 映射为预期结果
3. **需求文档作为补充**：在 spec 覆盖的场景之外，从需求文档中提取 spec 未涉及的边界值、异常场景、隐性场景
4. **溯源标注**：当用例直接来源于 spec 场景时，在用例标题末尾标注 `[spec]`

#### Spec 查找流程

执行前自动扫描：
1. 检查对话上下文中是否提到了 OpenSpec change 名称
2. 运行 `npx devkeel@latest openspec list --json` 查找活跃的 change
3. 读取 `openspec/changes/<name>/specs/*/spec.md` 中的所有 spec 文件
4. 如果没有找到 spec 文件，仅基于需求文档生成（退化为原有行为）

### 覆盖模型

测试维度的选择由 `references/testing-dimension-matrix.md` 驱动：

1. **基础维度 T1-T5**（所有领域均启用）：功能正确性、输入验证、异常容错、权限安全、数据一致性
2. **领域专项维度 T6-T25**：根据 `domain` 参数（或自动检测结果）查矩阵启用

每个启用的维度，按四个角度展开测试点：正向、边界、异常、交叉。

**关键约束**：矩阵是分析需求的透镜，不是独立的测试生成器。只有需求触及的维度才会产出测试点。

### 领域检测（domain=auto 时）

扫描项目信号自动匹配领域。详见 `references/testing-dimension-matrix.md` 的"领域检测信号"表。多领域命中时取并集。检测失败时退化为 custom（仅基础维度 + 需求驱动按需启用专项维度）。

### 追溯体系

```
TP-<BIG>-<SMALL>-<TYPE>-NNN  (测试点)
    │
    ├─ TC-XXX [spec]  (直接映射自 spec scenario)
    │
    └─ TC-YYY         (从需求/隐性场景扩展)
```

### 领域维度应用规则

根据 `domain` 参数（或自动检测结果），从矩阵中查表确定启用的维度集合。

- `●` 维度 + 需求触及 → 主动展开测试点
- `○` 维度 + 需求/spec 显式提及 → 展开
- `—` 维度 → 跳过

用例编写随领域调整：
- 前端/移动端/桌面领域：操作步骤侧重用户可见交互，预期结果侧重 UI 表现
- 后端/系统领域：操作步骤侧重接口调用或系统命令，预期结果侧重返回值/状态变更
- CLI 领域：操作步骤侧重命令执行，预期结果侧重输出内容和退出码
- 多领域并集时：用例标题标注领域标签（如 `[FE]`、`[BE]`、`[CLI]`）

### 隐性场景识别

以下场景即使需求未明确描述，也应适度补充（每类仅 1-2 条典型场景）：

| 功能类型 | 补充场景 |
|---------|---------|
| 弹窗/模态框 | 关闭后状态清理 |
| 异步加载 | 加载中交互、中断处理 |
| 列表/分页 | 滚动加载边界 |
| 搜索/查询 | 特殊输入处理 |
| 外链跳转 | 链接可用性 |

## Mode A: full（三阶段门禁）

适用于人工驱动的完整测试设计场景。

默认产物落到 `docs/test/<big-module-slug>/<small-module-slug>/`，并配套一个 `README.md` 维护阶段门禁状态。

### 阶段门禁规则

- `01-context.md` 未通过，禁止开始 `02-test-points.md`
- `02-test-points.md` 未通过，禁止开始 `03-test-cases.md`

### 1. 识别模块层级与扫描模式

先识别大模块 / 小模块，再判断扫描模式：

- `全量模块（FULL_MODULE）`
- `增量差异（DIFF_ONLY）`
- `文档优先（DOC_FIRST）`
- `仅文档（DOC_ONLY）`

### 2. 初始化目录与门禁文件

默认结构：

- `docs/test/<big-module-slug>/<small-module-slug>/README.md`
- `docs/test/<big-module-slug>/<small-module-slug>/01-context.md`
- `docs/test/<big-module-slug>/<small-module-slug>/02-test-points.md`
- `docs/test/<big-module-slug>/<small-module-slug>/03-test-cases.md`

### 3. 产出 `01-context.md`

回答"模块是什么、谁在用、能力域有哪些、关键链路如何流转、风险在哪里"。

必须包含：文档元信息、输入材料清单、模块目标与参与角色、能力地图、页面载体地图、用例图、关键时序图、规格与实现差异、能力域覆盖确认表。

### 4. 产出 `02-test-points.md`

只有 `01-context.md` 状态为"已通过"才能开始。只回答"要测什么"，不给完整执行细节。

必须按以下结构输出：

- 固定覆盖清单对照表
- 模块补充覆盖项对照表
- `# 大模块` → `## 小模块` → `### 测试类型` → `#### TP-... 一句话描述`

覆盖对照表状态固定为：已覆盖、不适用、未覆盖、待确认。

若覆盖对照表中仍存在"未覆盖"或"待确认"，禁止生成 `03-test-cases.md`。

### 5. 产出 `03-test-cases.md`

只有 `02-test-points.md` 状态为"已通过"才能开始。

每条测试用例都必须写清：用例编号与名称、用例状态、大模块 / 小模块、测试类型、优先级、是否冒烟、自动化候选、前置条件、测试数据、操作步骤、预期结果、追溯测试点、追溯依据。

### 6. 更新门禁状态与下一步

每推进一阶段，同步更新 `README.md` 门禁状态、当前阻塞、下一步动作。

## Mode B: fast（一次性产出）

适用于 subagent 调用或需要快速产出的场景。Phase 1-3 为内部思考过程，不输出到最终结果中。

### 产出路径

| 调用场景 | 产出路径 |
|---------|---------|
| schema 流程内 | `openspec/changes/<name>/test-points.md` |
| 独立调用 | `docs/test/<module>/` |

### Phase 1: 需求解构与拆分

#### 1.0 输入收集

1. 扫描 OpenSpec spec 文件（检查活跃 change，读取 `specs/*/spec.md`）
2. 读取需求文档（brainstorm.md 或 `docs/requirement/`）
3. 合并输入：将 spec 中的 Requirement 和 Scenario 与需求文档中的功能模块对齐

如果同一功能点在 spec 和需求文档中都有描述，以 spec 为准。

#### 1.1 需求解构

将宏观需求拆分为独立、完整、可测试的需求点。

拆分维度：功能模块、用户角色、操作场景、数据状态、UI 状态、输入边界、平台/端。

#### 1.2 必选扫描维度

每个需求点经过基础维度的强制扫描，再叠加平台侧重的额外维度。

基础维度（所有领域均适用）：
- 功能维度：主流程、分支流程、状态切换、多触发方式
- 输入验证维度：边界值、空值/缺省、格式校验、特殊输入
- 交互维度：触发方式、状态展示、反馈响应（frontend/all 适用）
- 接口维度：入参校验、返回值结构、错误码、鉴权（backend/all 适用）
- 异常维度：网络异常、数据异常、权限异常、资源异常

#### 1.3 拆分控制规则

禁止拆分的情况（必须合并）：同类防重逻辑、衍生边界值、纯视觉状态、同类异常变体、状态清理组合、控件存在性。

排除规则：纯像素尺寸值、纯样式/颜色值、纯动画效果。

保留规则：溢出处理逻辑、响应式功能变化、可交互状态变化。

### Phase 2: 场景规划与用例生成

优先级分布：P0（10-15%）、P1（30-40%）、P2（其余）。

测试方法：等价类、边界值、场景法、错误推测、因果图。

#### 操作步骤（step）规范

操作步骤只包含用户的实际操作动作，禁止包含检查、验证、观察类描述。

允许的操作动词：输入、填写、录入、粘贴、点击、单击、双击、长按、选择、勾选、下拉选择、切换、进入、打开、跳转、返回、关闭、等待、暂停、上传、拖拽、导入、删除、清空、移除。

禁止在操作步骤中出现：检查、查看、观察、留意、注意、验证、确认、核实、校验、判断、应显示、应弹出、应提示。

#### 预期结果（expect）规范

- 必须明确可验证，包含具体校验点
- 避免模糊表述（禁止"正常"、"成功"、"无异常"）
- 多个预期分条列出，每条一个校验点

### Phase 3: 自检 checklist

生成用例后，按以下 checklist 自检，发现问题立即修正：

#### 需求覆盖（5 项）
- [ ] 每个需求点都有对应用例覆盖，覆盖率 ≥ 95%
- [ ] 每个 OpenSpec Scenario（WHEN/THEN）都有对应的 `[spec]` 标注用例，无遗漏
- [ ] 用例准确反映需求中的业务规则和约束条件
- [ ] 边界值、临界值场景被充分覆盖
- [ ] 异常场景覆盖至少 2 种类型

#### 用例质量（4 项）
- [ ] 操作步骤具体、明确、可执行，无模糊表述
- [ ] 预期结果明确、可验证，包含具体校验点
- [ ] 前置条件完整描述执行用例前的必要条件
- [ ] 优先级分配合理：P0(10-15%), P1(30-40%), P2(其余)

#### 编写规范（4 项）
- [ ] 操作步骤中无检查类/验证类词汇
- [ ] 每个边界值都是独立用例
- [ ] 每个可独立验证的功能点都是独立用例
- [ ] 精确信息（数值/文案/控件名）未被模糊化

### Phase 4: 输出

按功能模块分组，每个模块一个表格：

```markdown
## [功能模块名称]

| 用例编号 | 用例标题 | 前置条件 | 操作步骤 | 预期结果 | 优先级 | 测试方法 |
|---------|---------|---------|---------|---------|-------|---------|
| TC-001  | ...     | ...     | 1. ...<br>2. ... | 1. ...<br>2. ... | P0 | 场景法 |
```

当 `domain` 命中多个领域时，用例标题前加领域标签（如 `[FE]`、`[BE]`）。

当存在 spec 输入时，在文档末尾输出 spec 覆盖率统计。

## 质量门槛

一份合格的产出，必须让评审人可以快速判断：

- 当前模块的上下文是否已经清楚（full 模式）
- 固定覆盖清单与模块补充覆盖项是否已经全部清零（full 模式）
- 测试点是否已经精炼到可评审粒度
- 完整测试用例是否可执行、可追溯、可维护
- 当前阻塞点是什么，下一步该由谁推进