测试用例设计

基于需求文档设计测试用例，建立验收标准与测试用例的追溯关系。

语言规则

• 支持中英文提问

• 统一中文回复

• 使用中文生成文档

触发条件

• 用户已完成需求文档

• 用户要求设计测试用例

• 用户需要测试覆盖策略

前置条件

• 需求文档：docs/devdocs/01-requirements.md

• 系统设计文档：docs/devdocs/02-system-design.md （设计 UT/IT 时需要了解接口签名和模块划分）

• 如不存在，建议先运行前置阶段

核心理念

测试用例来源

功能点 (F-XXX) │ └── 用户故事 (US-XXX) │ └── 验收标准 (AC-XXX) │ ├── 单元测试 (UT-XXX) ← 验证内部逻辑 │ ├── 集成测试 (IT-XXX) ← 验证组件协作 │ └── E2E 测试 (E2E-XXX) ← 验证用户场景

关键原则：

• 测试用例从需求推导，不是从代码推导

• 每个验收标准至少有一个测试用例覆盖

• 测试类型根据验收标准的性质选择

测试类型选择

验收标准类型 推荐测试类型 示例

输入验证规则 单元测试 "邮箱格式校验" → UT

业务逻辑规则 单元测试 + 集成测试 "密码加密存储" → UT + IT

用户交互流程 E2E 测试 "完成注册流程" → E2E

组件间协作 集成测试 "发送验证邮件" → IT

编号规范

类型 前缀 格式 示例

单元测试 UT UT-XXX UT-001, UT-002

集成测试 IT IT-XXX IT-001, IT-002

E2E 测试 E2E E2E-XXX E2E-001, E2E-002

运行模式

/devdocs-test-cases → 标准模式（逐步确认） /devdocs-test-cases --fast → 跳过逐步确认，直接生成，仅最终确认

--fast 模式

• 跳过测试类型选择的逐步确认

• 自动根据 AC 性质选择最佳测试类型

• 仅保留最终写入前的 1 次确认

• 默认行为不变，--fast 是 opt-in

工作流程

1. 读取需求文档 │ ▼
2. 提取功能点、用户故事、验收标准 │ ▼
3. 为每个验收标准选择测试类型 │ ▼
4. 按功能点分批设计测试用例 │ 对每个功能点 (F-XXX)： │ ├── 设计该功能点的 UT │ ├── 设计该功能点的 IT │ ├── 设计该功能点的 E2E │ └── 质量一致性自检（与首批对比详细程度） │ ▼
5. 生成追溯矩阵 │ ▼
6. 用户确认

上下文管理

分批原则

按功能点 (F-XXX) 分批设计，每批完成一个功能点的全部测试用例（UT + IT + E2E）。

质量锚点

• 首个功能点的用例作为质量锚点

• 每个新功能点开始前，回顾首批用例的详细程度（字段完整性、场景覆盖、输入输出具体性）

• 若当前批次详细程度明显低于锚点，立即补充

一致性自检

每个功能点完成后，对比检查：

• 表格字段是否与首批一致（无缺列）

• 输入/输出是否有具体值（非"正常输入"等模糊描述）

• 场景覆盖是否包含正常 + 异常路径

输出文件

主文件：docs/devdocs/03-test-cases.md

文档拆分规则

默认拆分为主文件 + 子文件结构。每个子文件控制在合理大小内，Agent 每次只写一个子文件以减轻上下文负担。

拆分方式：

docs/devdocs/ ├── 03-test-cases.md # 大纲：策略、覆盖率、追溯矩阵、用例索引 ├── 03-test-unit.md # UT 详情 ├── 03-test-integration.md # IT 详情 └── 03-test-e2e.md # E2E 详情

主文档保留内容（大纲，不含具体用例）：

• 测试策略说明

• 覆盖率目标

• 完整追溯矩阵（F → US → AC → 测试）

• 各子文档的用例范围说明

小型项目例外：测试用例 ≤ 15 个且文档 ≤ 200 行时，可合并为单一文件 03-test-cases.md 。

详细模板参见：

• templates/test-cases-template.md

• templates/unit-test-template.md

• templates/integration-test-template.md

• templates/e2e-test-template.md

测试用例概览文档结构

测试用例：<功能名称>

1. 测试策略

2. 覆盖率要求

3. 追溯矩阵

4. 测试用例索引

追溯矩阵

追溯矩阵是核心产出，展示需求与测试、代码的完整关联。

基础格式（设计阶段）

完整格式（开发阶段，含代码位置）

代码位置由 /devdocs-sync 自动填充，基于代码中的 @satisfies /@verifies 标注扫描。

代码位置字段说明

字段 来源 说明

入口代码 @satisfies AC-XXX 标注 实现该 AC 的方法位置

测试代码 @verifies AC-XXX 标注 验证该 AC 的测试位置

状态说明

状态 含义 条件

✅ 完整覆盖 有测试用例 + 入口代码 + 测试代码 + 测试通过

⏳ 进行中 有测试用例，代码/测试部分完成

⚠️ 部分覆盖 有代码但缺测试，或有测试但缺代码

❌ 未覆盖 无测试用例或无代码实现

矩阵维护流程

设计阶段 开发阶段 同步阶段 │ │ │ ▼ ▼ ▼ 生成基础矩阵 生成骨架代码（带标注） /devdocs-sync (AC → 测试编号) (入口 + 测试) │ ▼ 扫描代码标注 │ ▼ 填充代码位置列 │ ▼ 更新状态列

测试用例格式

单元测试用例

集成测试用例

E2E 测试用例

覆盖率要求

测试类型 覆盖目标 覆盖要求

单元测试 核心业务逻辑 行覆盖率 ≥ 80%，分支覆盖率 ≥ 80%

集成测试 组件协作场景 每个功能点至少 1 个 IT

E2E 测试 用户故事 每个 P0 用户故事至少 1 个 E2E

约束

阶段边界约束（最高优先级）

• 本 Skill 仅产出文档，严禁编写或生成任何实现代码或测试代码文件

• Write 工具仅用于写入 docs/devdocs/ 下的 Markdown 文档

• 测试用例以文档形式（表格/文字）描述，不生成 .test.ts /.spec.ts 等代码文件

• 编码和测试编写由 /devdocs-dev-workflow 负责，本 Skill 不涉及

追溯约束

• 每个验收标准至少有 1 个测试用例覆盖

• 必须生成追溯矩阵

• 追溯矩阵必须覆盖所有 AC

用例设计约束

• 测试用例必须关联验收标准编号

• 每个用例必须有明确的预期结果

• 优先级必须标注 (P0/P1/P2)

• 后批次用例详细程度不低于首批次（字段完整性、具体值、场景覆盖）

• 每个功能点完成后执行一致性自检

覆盖约束

• P0 验收标准必须 100% 测试覆盖

• P0 用户故事必须有 E2E 测试

• 单元测试行覆盖率目标 ≥ 80%

质量约束（参考 /testing-guide ）

• 测试名称必须描述预期行为

• 禁止弱断言（toBeDefined, toBeTruthy 不能作为唯一断言）

• Mock 只用于外部依赖

Skill 协作

场景 协作 Skill 说明

需求输入 /devdocs-requirements

前置：提供 F/US/AC 作为测试设计依据

新功能测试 /devdocs-feature

被调用：新功能需要新增测试用例

Bug 回归测试 /devdocs-bugfix

被调用：Bug 修复需要补充回归测试

改进测试 /devdocs-insights

被调用：改进建议可能需要测试覆盖

追溯更新 /devdocs-sync

协作：trace 模式更新追溯矩阵代码位置

测试质量 /testing-guide

协作：编写测试代码时的质量约束

任务拆分 /devdocs-dev-tasks

后续：测试用例转化为开发任务

子 Agent 摘要格式

当本 Skill 作为子 Agent 运行时，返回以下结构化摘要：

skill: devdocs-test-cases mode: initial | incremental new_ids: unit_tests: [UT-001UT-012] integration_tests: [IT-001IT-003] e2e_tests: [E2E-001~E2E-002] traceability_matrix_updated: true status: completed output_files:

• docs/devdocs/03-test-cases.md

下一步

完成后建议运行 /devdocs-dev-tasks 进行开发任务拆分。

提示：文档变更较大时，建议运行 /agent-memory 同步记忆文件。