AC to Examples Skill Skill

AC to Examples Skill

Scope: REQUIREMENTS

版本: 0.1.0 | 创建日期: 2025-12-04

概述

将抽象的Acceptance Criteria（AC）转换为具体的示例，让Given-When-Then从抽象规则变成具体可执行的测试场景。

核心价值：

Given: 抽象条件 → 具体数值/状态
When: 抽象动作 → 具体操作步骤
Then: 抽象结果 → 具体可观察现象
100%业务语言，可直接用于手动测试

适合人群：不熟悉BDD（行为驱动开发）的PM/BA/测试人员，需要具体示例理解测试场景

适用场景

场景1：AC太抽象，测试人员不知道如何测

现状：

## AC-AUTH-001-01: 有效凭证登录成功

Given 用户有有效凭证
When 用户提交登录请求
Then 系统显示登录成功消息并跳转到首页

问题：

"有效凭证"是什么？（test@example.com?）
"提交登录请求"怎么做？（点击按钮?）
"显示成功消息"显示什么？（在哪里显示?）

场景2：PM/客户不理解AC的验收标准

PM/客户看到Given-When-Then觉得太技术化，需要具体示例帮助理解

场景3：开发/测试需要明确的测试用例

开发写单元测试或测试人员写测试用例时，需要具体的输入输出示例

执行步骤

步骤1：读取AC基本信息

读取AC的Given-When-Then结构
提取AC的ID、SN、source_us
识别AC关联的US（获取业务背景）

步骤2：具体化Given（前置条件）

策略1：将抽象条件转为具体数值

# 抽象 → 具体
"有效凭证" → "邮箱: test@example.com, 密码: Pass123!"
"用户已登录" → "用户王小明（ID: U001）已登录系统"
"购物车中有商品" → "购物车中有3件商品：苹果x2, 香蕉x1"
"账户余额充足" → "账户余额: ¥500，购买金额: ¥299"

策略2：明确状态和环境

# 抽象 → 具体
"系统正常运行" → "系统在线，数据库连接正常，服务响应时间<200ms"
"用户在首页" → "用户已登录，当前URL: https://example.com/home"
"数据库中有订单记录" → "数据库orders表中有订单ID为O20251204001的记录"

步骤3：具体化When（操作动作）

策略1：分解为具体操作步骤

# 抽象 → 具体
"用户提交" →
  1. 在用户名框输入"test@example.com"
  2. 在密码框输入"Pass123!"
  3. 点击"登录"按钮

"用户添加商品" →
  1. 浏览商品列表，找到"苹果（红富士）"
  2. 点击商品卡片进入详情页
  3. 选择数量为"2"
  4. 点击"加入购物车"按钮

策略2：明确交互细节

# 抽象 → 具体
"用户选择日期" → "用户点击日期选择器，选择'2025-12-25'"
"用户上传文件" → "用户点击上传按钮，选择本地文件'report.pdf'（2.5MB）"

步骤4：具体化Then（预期结果）

策略1：描述可观察现象

# 抽象 → 具体
"显示成功消息" →
  - 页面顶部显示绿色提示条
  - 提示文字："登录成功，欢迎王小明"
  - 3秒后自动消失

"跳转到首页" →
  - URL变为: https://example.com/home
  - 右上角显示用户头像和姓名"王小明"
  - 页面标题显示"首页 - XX系统"

策略2：量化可验证的标准

# 抽象 → 具体
"响应速度快" → "页面在2秒内加载完成，进度条显示100%"
"数据更新成功" → "刷新页面后，订单状态从'待支付'变为'已支付'"
"错误提示清晰" → "密码错误时，密码框下方显示红色文字'密码错误，请重试（剩余2次机会）'"

步骤5：生成完整示例

格式1：嵌入原AC（推荐）

在原AC的Then部分下方增加"具体示例"章节：

## AC-AUTH-001-01: 有效凭证登录成功

Given 用户有有效凭证
When 用户提交登录请求
Then 系统显示登录成功消息并跳转到首页

**具体示例**：

**Given**（前置条件）：
- 数据库中存在用户：邮箱=test@example.com, 密码=Pass123!（已加密）
- 用户未登录，当前在登录页面（URL: /login）

**When**（操作步骤）：
1. 在"邮箱"输入框输入：test@example.com
2. 在"密码"输入框输入：Pass123!
3. 点击"登录"按钮

**Then**（预期结果）：
1. 页面顶部显示绿色提示："登录成功，欢迎王小明"
2. URL变为：/home
3. 右上角显示用户名"王小明"和头像图标
4. 页面标题变为"首页 - XX便利店管理系统"

格式2：独立示例文档（适用于复杂AC）

为每个AC生成独立的示例文档：

# AC-AUTH-001-01 测试示例

## 场景：有效凭证登录成功

### 测试数据准备
| 数据项 | 值 |
|-------|---|
| 用户邮箱 | test@example.com |
| 用户密码 | Pass123! |
| 用户ID | U001 |
| 用户姓名 | 王小明 |
| 角色 | 便利店店长 |

### 操作步骤
1. 打开登录页面（URL: https://example.com/login）
2. 在"邮箱"框输入：test@example.com
3. 在"密码"框输入：Pass123!
4. 点击蓝色"登录"按钮

### 预期结果
1. **成功提示**：
   - 位置：页面顶部
   - 样式：绿色背景，白色文字
   - 文字：登录成功，欢迎王小明
   - 持续时间：3秒后自动消失

2. **页面跳转**：
   - 新URL：https://example.com/home
   - 页面标题：首页 - XX便利店管理系统

3. **用户信息显示**：
   - 位置：页面右上角
   - 内容：用户头像（圆形） + "王小明"

### 验证点
- [ ] 提示消息文字正确
- [ ] 提示消息3秒后消失
- [ ] URL正确跳转
- [ ] 用户名显示正确

快速开始

最快的3步使用流程：

[ ] 第1步：确认已有AC文档
- 文件位置：spec/requirements/acceptance_criteria.md（或其他.md文件）
- 格式要求：每个AC包含 Given-When-Then 三段式结构
- 数量建议：至少2-3个AC（可以处理更多）
[ ] 第2步：调用SKILL生成具体示例
- 命令：>>ac-to-examples 或 >>ac-examples-batch
- AI会自动读取AC并生成具体示例
- 生成内容：将"有效凭证"变成"test@example.com, Pass123!"等具体数据
- 处理时间：约2-3分钟 / 10个AC
[ ] 第3步：查看增强后的AC
- 结果位置：原AC文件（新增"具体示例"章节）
- 原Given-When-Then完全保留，只是在下方新增示例
- 查看方式：打开原文档，查看每个AC下的具体示例
- 可直接用于手动测试：照着示例的步骤和数据执行测试

⏱️ 预计耗时：2-3分钟 / 10个AC

🆘 遇到问题？ 查看下方"使用说明"章节获取详细指导

使用说明

📥 AI会读取什么（输入）

自动读取的文档：

AI会读取 spec/requirements/ 文件夹下的验收标准文档
文档需要是 .md格式（如 acceptance_criteria.md）
每个验收标准（AC）需要包含：
- Given-When-Then 三段式结构（前提-操作-结果）
- 文档头部的编号信息（如 id: AC-AUTH-001-01）

项目结构示例：

你的项目/
└── spec/
    └── requirements/
        ├── user_stories.md
        ├── acceptance_criteria.md  ← AI会读取这个文件
        └── nfr.md

AI会为AC生成什么示例：

Given（前提条件）：从"有效凭证"变成"邮箱: test@example.com, 密码: Pass123!"
When（操作步骤）：从"用户提交"变成"1.输入邮箱 2.输入密码 3.点击登录"
Then（预期结果）：从"显示成功消息"变成"页面顶部显示'登录成功，欢迎王小明'"

可选的补充信息：

如果有User Story文档，AI能生成更贴合业务场景的示例
如果有UI设计稿，AI能生成更准确的界面描述

📤 AI会产生什么（输出）

修改的内容： AI会在原有AC文件中新增"具体示例"章节，原有的Given-When-Then完全保留

新增示例包含：

具体的前提条件（Given）：
- 不再是"用户已登录"，而是"用户王小明（ID: U001）已登录系统"
- 不再是"有效凭证"，而是"邮箱: test@example.com, 密码: Pass123!"
详细的操作步骤（When）：
- 不再是"用户提交"，而是"1.输入邮箱 2.输入密码 3.点击登录按钮"
- 每步操作都清晰具体，可以直接照着测试
可观察的预期结果（Then）：
- 不再是"显示成功消息"，而是"页面顶部显示绿色提示'登录成功，欢迎王小明'，3秒后消失"
- 结果可以被观察和验证

结果位置：

修改后的文档仍在原位置：spec/requirements/acceptance_criteria.md
原有的Given-When-Then不会改变
只是在每个AC下方新增一个"具体示例"章节

示例（修改前后对比）：

# 修改前（抽象版）
## AC-AUTH-001-01: 有效凭证登录成功

Given 用户有有效凭证
When 用户提交登录请求
Then 系统显示登录成功消息并跳转到首页

---

# 修改后（具体版）
## AC-AUTH-001-01: 有效凭证登录成功

Given 用户有有效凭证
When 用户提交登录请求
Then 系统显示登录成功消息并跳转到首页

**具体示例**：

**Given**（前置条件）：
- 数据库中存在用户：邮箱=test@example.com, 密码=Pass123!
- 用户未登录，当前在登录页面

**When**（操作步骤）：
1. 在"邮箱"输入框输入：test@example.com
2. 在"密码"输入框输入：Pass123!
3. 点击"登录"按钮

**Then**（预期结果）：
1. 页面顶部显示绿色提示："登录成功，欢迎王小明"
2. URL变为：/home
3. 右上角显示用户名"王小明"和头像图标

🎯 如何使用

第1步：确保文档已准备好

打开 spec/requirements/ 文件夹
确认有验收标准文档（.md格式）
确认AC包含 Given-When-Then 结构

第2步：调用这个SKILL

在与AI对话时输入：>>ac-to-examples
AI会自动读取AC并开始生成具体示例
处理时间：约2-3分钟 / 10个AC

第3步：查看结果

打开原来的AC文档
你会看到每个AC下面新增了"具体示例"章节
AI会在对话中告诉你具体修改了哪些AC

常见问题：

Q: AI会覆盖我原来的Given-When-Then吗？ A: 不会。AI只会新增"具体示例"章节，原有的Given-When-Then完全保留。

Q: 为什么需要具体示例？ A: 抽象的AC（如"有效凭证"）测试人员不知道用什么数据测，具体示例（如"test@example.com"）可以直接用于手动测试。

Q: 如果我的AC格式不对怎么办？ A: AI会提示你哪些AC需要调整，比如："AC-AUTH-001缺少Then部分，请补充预期结果"。

Q: 生成的示例数据是真实的吗？ A: 示例数据是基于你的业务场景生成的合理数据（如test@example.com），不是随机编造的。你可以根据实际情况调整。

质量检查

必检项（100%通过）

[ ] 示例符合业务逻辑（不是随机数据）
[ ] 100%业务语言（无技术术语如"POST请求"）
[ ] 可直接用于手动测试（不需要额外解释）
[ ] Given/When/Then三部分都具体化

建议项（≥85%通过）

[ ] Given包含具体数值（如"test@example.com"）
[ ] When分解为详细步骤（1-2-3...）
[ ] Then描述可观察现象（位置、文字、样式）
[ ] 包含验证点清单（便于测试人员勾选）

限制条件

✅ 适用场景

已有AC文档，符合Given-When-Then格式
AC过于抽象（如"有效凭证"），测试人员不知道用什么数据测
准备测试或向客户展示时，需要具体可执行的示例
开发写单元测试或测试人员写测试用例时，需要明确的输入输出
希望AC能被非技术人员（PM/客户）理解

❌ 不适用场景

完全没有AC文档 → 先使用 acceptance-criteria 生成AC
AC格式完全错误（缺少Given-When-Then结构） → 先修复格式
AC已经很具体，包含详细数据和步骤 → 无需使用本SKILL，避免冗余
需要的是自动化测试代码（如Cucumber脚本） → 本SKILL生成手动测试示例，不是代码
AC数量极少（只有1-2个）且非常简单 → 手动添加示例可能更快

📋 前置条件

至少有2-3个Acceptance Criteria（包含Given-When-Then三段式）
AC文档是.md格式，位于spec/requirements/目录下
AC格式基本正确（有id, source_us等Front Matter）
AC已关联到对应的User Story（source_us字段填写）
愿意接受AI生成的示例数据（可以根据实际情况后续调整）

特别说明（针对敏捷新手）

为什么需要具体示例？

抽象AC的问题：

测试人员不知道用什么数据测
PM/客户不确定验收标准是否符合期望
开发写单元测试时需要猜测具体值

具体示例的价值：

明确测试数据（如"test@example.com"）
明确操作步骤（如"点击登录按钮"）
明确预期结果（如"显示'登录成功，欢迎王小明'"）

"抽象 vs 具体"的区别

| 维度 | 抽象AC | 具体示例 | |------|--------|---------| | Given | "有效凭证" | "邮箱: test@example.com, 密码: Pass123!" | | When | "用户提交" | "1.输入邮箱 2.输入密码 3.点击登录按钮" | | Then | "显示成功消息" | "页面顶部显示绿色提示'登录成功，欢迎王小明'" | | 可测性 | ❌ 不知道怎么测 | ✅ 照着步骤测即可 |

对比示例

# ❌ 抽象AC（不够清晰）

Given 用户购物车中有商品且余额充足
When 用户提交订单
Then 系统创建订单并扣减库存

# ✅ 具体示例（清晰可测）

**Given**（前置条件）：
- 用户：王小明（ID: U001），账户余额：¥500
- 购物车中商品：
  * 苹果（红富士）x2，单价¥5，小计¥10
  * 香蕉x1，单价¥8，小计¥8
  * 购物车总额：¥18

**When**（操作步骤）：
1. 在购物车页面点击"去结算"按钮
2. 确认配送地址："北京市朝阳区XX小区"
3. 选择支付方式："余额支付"
4. 点击"提交订单"按钮

**Then**（预期结果）：
1. 订单创建成功，订单号：O20251204001
2. 账户余额从¥500扣减至¥482
3. 库存扣减：
   - 苹果库存从100减至98
   - 香蕉库存从50减至49
4. 页面跳转到订单详情页，显示订单号和状态"待发货"
5. 页面顶部显示"订单提交成功"绿色提示（3秒后消失）

测试人员使用指南

如何用具体示例进行手动测试：

准备测试数据：
- 创建测试用户：test@example.com / Pass123!
- 准备测试商品：苹果、香蕉等
- 设置账户余额：¥500
执行操作步骤：
- 按照When部分的步骤1-2-3...逐步执行
- 每步操作后观察界面变化
验证预期结果：
- 对照Then部分的验证点逐一检查
- 发现不符合时记录Bug（附截图）

>> 命令

>>ac-to-examples             # 为单个AC生成具体示例
>>ac-examples-batch          # 批量为所有AC生成示例
>>ac-example-format          # 选择示例格式（嵌入/独立）
>>ac-test-case               # 生成标准测试用例文档

Agent Skills: AC to Examples Skill

Install this agent skill to your local

Skill Files