Perspective: QA Analyst — Focuses on boundary coverage and path completeness, pursuing testability rather than implementation details.
Design test cases based on requirements documents, establishing traceability between acceptance criteria and test cases.
Quick Start
One-liner: Design test cases (UT/IT/E2E/Journey), establish requirements→test traceability.
Most Common Usage: /test-cases(auto-detect initial/incremental)
Not suitable? Run tests→/test-run, development guidance→/dev-workflow
Language Rules
- Support questions in Chinese and English
- Reply uniformly in Chinese
- Generate documents in Chinese
Trigger Conditions
- User has completed the requirements document
- User requests test case design
- User needs a test coverage strategy
Prerequisites
- Requirements document:
docs/devdocs/01-requirements.md - System design document:
docs/devdocs/02-system-design.md(needed to understand interface signatures and module division when designing UT/IT) - If it does not exist, it is recommended to run the prerequisite phase first
Core Concepts
Test Case Sources
功能点 (F-XXX)
│
└── 用户故事 (US-XXX)
│
└── 验收标准 (AC-XXX)
│
├── 单元测试 (UT-XXX) ← 验证内部逻辑
│
├── 集成测试 (IT-XXX) ← 验证组件协作
│
├── E2E 测试 (E2E-XXX) ← 验证单 US 用户场景
│
└── 用户旅程 (Journey-XXX) ← 验证跨 US 业务闭环
Key Principles：
- Test cases are derived from requirements, not from code
- Each acceptance criterion is covered by at least one test case
- Test type is chosen based on the nature of the acceptance criterion
Test Type Selection
| Acceptance Criterion Type | Recommended Test Type | Example |
|---|---|---|
| Input validation rules | Unit Test | "Email format validation" → UT |
| Business logic rules | Unit Test + Integration Test | "Password encrypted storage" → UT + IT |
| User interaction flow | E2E Test | "Complete registration flow" → E2E |
| Cross-functional user flow | User Journey Test | "New user from registration to first use" → Journey |
| Collaboration between components | Integration Test | "Send verification email" → IT |
Difference Between E2E and Journey: E2E-XXX verifies the complete interaction of a single user story; Journey-XXX chains >= 2 user stories, verifying the cross-functional business closed loop and state transfer between steps.
Numbering Convention
| Type | Prefix | Format | Example |
|---|---|---|---|
| Unit Test | UT | UT-XXX | UT-001, UT-002 |
| Integration Test | IT | IT-XXX | IT-001, IT-002 |
| E2E Test | E2E | E2E-XXX | E2E-001, E2E-002 |
| User Journey | Journey | Journey-XXX | Journey-001, Journey-002 |
Run Modes
/test-cases→ Standard mode (step-by-step confirmation)/test-cases --realign[=scope]→ Specification upgrade re-scan (fill structural/field gaps; missing test types passed to dev-workflow). See references/realign.md; recommended/pipeline realign
Fast Track (ceremony: fast）
- Skip step-by-step confirmation of test type selection
- Automatically select the best test type based on the nature of the AC
- Keep only 1 confirmation before the final write
- The tier is decided by the
ceremonypassed down from the orchestration layer（task/intent-normalization）：fast→ this section;standard(default) /deep→ standard mode. ⛔ Do not interpret the user's original words on your own to determine the tier.
Workflow
1. 读取需求文档
│
▼
2. 提取功能点、用户故事、验收标准
│
▼
3. 为每个验收标准选择测试类型
│
▼
4. 按功能点分批设计测试用例
│ 对每个功能点 (F-XXX)：
│ ├── 设计该功能点的 UT
│ ├── 设计该功能点的 IT
│ ├── 设计该功能点的 E2E
│ └── 质量一致性自检（与首批对比详细程度）
│
▼
4.5 汇总用户旅程
│ 所有功能点的 UT/IT/E2E 完成后：
│ ├── 回顾跨功能点的 US 串联关系
│ ├── 筛选核心旅程（>= 2 个 US 串联）
│ └── 设计 Journey 用例
│
▼
5. 生成追溯矩阵（含 Journey）
│
▼
6. 用户确认
Context management
Batching principle
Design in batches by feature point (F-XXX); each batch completes all test cases for one feature point (UT + IT + E2E).
Quality anchor
- The test cases of the first feature point serve as thequality anchor
- Before starting each new feature point, review the level of detail of the first batch of test cases (field completeness, scenario coverage, input/output specificity)
- If the current batch's level of detail is noticeably lower than the anchor, supplement it immediately
Consistency self-check
After completing each feature point, compare and check:
- Whether scenario coverage includes normal + exception paths
Output files
Main file：docs/devdocs/03-test-cases.md
Document splitting rules
Default splittinginto a main file + sub-file structure. Keep each sub-file within a reasonable size; the Agent writes only one sub-file at a time to reduce context burden.
Splitting method：
docs/devdocs/
├── 03-test-cases.md # 大纲：策略、覆盖率、追溯矩阵、用例索引
├── 03-test-unit.md # UT 详情
├── 03-test-integration.md # IT 详情
└── 03-test-e2e.md # E2E 详情
Content retained in the main document(outline, without specific test cases):
- Test strategy description
- Coverage target
- Complete traceability matrix (F → US → AC → test)
- Description of the test case scope of each sub-document
Small project exception: when test cases ≤ 15and the document ≤ 200 lines, they may be merged into a single file 03-test-cases.md。
For detailed templates, see:
- templates/test-cases-template.md
- templates/unit-test-template.md
- templates/integration-test-template.md
- templates/e2e-test-template.md
Test case overview document structure
# 测试用例：<功能名称>
## 1. 测试策略
## 2. 覆盖率要求
## 3. 追溯矩阵
## 4. 测试用例索引
Traceability matrix
The traceability matrix is the core output, showing the complete association between requirements, tests, and code.
Basic format (design phase)
| 功能点 | 用户故事 | 验收标准 | 单元测试 | 集成测试 | E2E/旅程测试 | 状态 |
|--------|----------|----------|----------|----------|-------------|------|
| F-001 | US-001 | AC-001 | UT-001 | - | E2E-001, Journey-001 | ⏳ |
| F-001 | US-001 | AC-002 | UT-002 | - | E2E-001, Journey-001 | ⏳ |
| F-001 | US-002 | AC-004 | UT-003, UT-004 | IT-001 | - | ⏳ |
| F-002 | US-003 | AC-006 | - | IT-002 | Journey-001 | ⏳ |
Full format (development phase, including change source)
The change source is maintained by
/sync: ⛔ Do not write any keel number in the code, and the connection direction isdocument → commit(reverse dependency).
| AC 编号 | 验收标准 | 测试编号 | 变更来源 | 状态 |
|---------|----------|----------|----------|------|
| AC-001 | 邮箱格式校验 | UT-001 | `api@a3f9c21` 邮箱格式校验 | ✅ |
| AC-002 | 密码强度校验 | UT-002 | `api@a3f9c21` 邮箱格式校验；`api@7b2e104` 密码强度 | ✅ |
| AC-003 | 用户名唯一性 | UT-003 | `api@c81d5f0` 用户名唯一性 | ⏳ |
| AC-004 | 发送验证邮件 | IT-001 | - | ❌ |
Change source field description
| Field | Form | Description |
|---|---|---|
| Change source | <repository>@<full-sha> + one-sentence description |
Which changes introduced this AC.Multiple entries allowed(one AC may span multiple commits, and one commit may satisfy multiple ACs) |
⛔ It is a change event anchor, not a locator for the current implementation. A commit can only answer "where did this change occur at the time"; "where it is implemented today" must be found by searching the current code and tests. After subsequent refactoring, moving, or reverting, the commit still exists, but it no longer represents the current state.
When the hash becomes invalid(squash / rebase / upstream force-push): ⚠️ warn and return to thecurrent code factsto rebuild; ⛔ do not build a mechanism for this. The sentence next to it is the only clue for manual recovery, so it must be written.
Status description
| Status | Meaning | Condition |
|---|---|---|
| ✅ | Complete coverage | Has test case + change source + test passes |
| ⏳ | In progress | Has test cases, code/test parts complete |
| ⚠️ | Partially covered | Has change source but lacks tests, or has tests but no change source |
| ❌ | Not covered | No test cases or no code implementation |
Matrix maintenance process
设计阶段 开发阶段 同步阶段
│ │ │
▼ ▼ ▼
生成基础矩阵 生成骨架代码（带标注） /sync
(AC → 测试编号) (入口 + 测试) │
▼
扫描代码标注
│
▼
填充代码位置列
│
▼
更新状态列
Test case format
Unit test cases
| 编号 | 验收标准 | 测试对象 | 场景 | 输入 | 预期输出 | 优先级 |
|------|----------|----------|------|------|----------|--------|
| UT-001 | AC-001 | validateEmail() | 有效邮箱 | "test@example.com" | true | P0 |
| UT-002 | AC-002 | validateEmail() | 无效格式 | "invalid" | false | P0 |
Integration test cases
| 编号 | 验收标准 | 测试场景 | 涉及组件 | 预期结果 | 优先级 |
|------|----------|----------|----------|----------|--------|
| IT-001 | AC-004 | 密码加密存储 | UserService + DB | 密码以 bcrypt 格式存储 | P0 |
E2E test cases
| 编号 | 用户故事 | 验收标准 | 操作步骤 | 预期结果 | 优先级 |
|------|----------|----------|----------|----------|--------|
| E2E-001 | US-001 | AC-001~AC-003 | 1. 打开注册页<br>2. 输入邮箱密码<br>3. 点击注册 | 注册成功，收到验证邮件 | P0 |
User journey test cases
| 编号 | 角色 | 串联故事 | 旅程步骤摘要 | 优先级 |
|------|------|----------|-------------|--------|
| Journey-001 | 新用户 | US-001→US-003 | 注册→验证→登录→首页 | P0 |
Coverage requirements
Line / branch coverage values use
/testing-guidecore threshold table as authority; this section does not mirror it (agent side changes pointer; artifact templates may inline it, see the "mirror boundary" of that table). The table below only defines test-cases-specificcoverage unitsrequirements.
| Test type | Coverage target | Coverage requirement |
|---|---|---|
| Unit test | Core business logic | Line / branch coverage see /testing-guide core threshold table |
| Integration test | Component collaboration scenarios | At least 1 IT per feature point |
| E2E test | User story | Decided by risk and cost; core paths prioritized |
| User journey | Core user paths | At least 1 core journey; 2-3 for medium-to-large products |
Constraints
Phase boundary constraints (highest priority)
- ⛔ Do not continue: the documentation phase must not produce implementation code or test code files(Recovery method: use /dev-workflow to execute coding)
- ⛔ Do not continue: generated/updated documents did not write at the top the
generated_by / spec_version / generated_atthree-field YAML frontmatter(Recovery method: fill in according to templates/test-cases-template.md top example; for spec_version constants see references/realign.md）
Traceability constraints
- Each acceptance criterion is covered by at least 1 test case
- A traceability matrix must be generated
Case design constraints
- Each case must have a clear expected result
- Priority must be marked (P0/P1/P2)
- The level of detail of later-batch cases must be no lower than that of the first batch (field completeness, specific values, scenario coverage)
Coverage constraints
AC quality assessment criteria are detailed in ../requirements/references/ac-quality-rubric.md; refer to it when verifying AC→test coverage.
- P0 acceptance criteria must have 100% test coverage (P0-P2 in this skill arecase priorities, same name but different meaning from the verify issue severity P levels)
- Unit test coverage targets follow the
/testing-guidecore threshold table for execution
Generator self-check (automatically executed before user confirmation)
Before presenting to the user for confirmation, load ../requirements/references/ac-quality-rubric.md and automatically verify:
- The inputs/outputs of test cases have specific values (not vague descriptions such as "normal input")
Items that fail the self-check are automatically fixed before being presented to the user, without adding user interaction steps.
Quality constraints
Assertion quality criteria (test naming / prohibition of weak assertions / Mock boundaries) use /testing-guide as authority; this document does not mirror it.
Skill collaboration
| Scenario | Collaboration Skill | Description |
|---|---|---|
| Requirement input | /requirements |
Prerequisite: provide F/US/AC as the basis for test design |
| New feature testing | /feature |
Invoked: new features require new test cases |
| Bug regression testing | /bugfix |
Invoked: bug fixes require supplementary regression tests |
| Improvement testing | /insights |
Invoked: improvement suggestions may require test coverage |
| Traceability update | /sync |
Collaboration: trace mode updates the code locations in the traceability matrix |
| Test quality | /testing-guide |
Collaboration: quality constraints when writing test code |
| Task breakdown | /dev-tasks |
Follow-up: convert test cases into development tasks |
Sub-Agent summary format
When this Skill runs as a sub-Agent, return the following structured summary:
For envelope field definitions (reserved fields such as status enum / blockers / output_files / new_ids), see shared/constraints.md §yaml-summary-v1; the following example focuses on
summary.detailsprivate fields.
skill: test-cases
status: success | failed | partial
summary:
headline: "测试设计完成，12 UT + 3 IT + 2 E2E + 1 Journey"
details:
mode: initial | incremental
traceability_matrix_updated: true
blockers: []
output_files:
- docs/devdocs/03-test-cases.md
new_ids:
unit_tests: [UT-001~UT-012]
integration_tests: [IT-001~IT-003]
e2e_tests: [E2E-001~E2E-002]
journeys: [Journey-001]
next_recommended:
skill: dev-tasks
Next steps
After completion, it is recommended to run /dev-tasks to break down development tasks.
Tip: when document changes are significant, it is recommended to run
/agent-memoryto sync the memory files.