tikazyq/ac-to-examples

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 系统显示登录成功消息并跳转到首页

问题：

• "有效凭证"是什么？（[email protected]?）
• "提交登录请求"怎么做？（点击按钮?）
• "显示成功消息"显示什么？（在哪里显示?）

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

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

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

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

---

执行步骤

步骤1：读取AC基本信息

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

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

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

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

策略2：明确状态和环境

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

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

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

# 抽象 → 具体
"用户提交" →
  1. 在用户名框输入"[email protected]"
  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**（前置条件）：
- 数据库中存在用户：邮箱[email protected], 密码=Pass123!（已加密）
- 用户未登录，当前在登录页面（URL: /login）

**When**（操作步骤）：
1. 在"邮箱"输入框输入：[email protected]
2. 在"密码"输入框输入：Pass123!
3. 点击"登录"按钮

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

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

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

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

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

### 测试数据准备
| 数据项 | 值 |
|-------|---|
| 用户邮箱 | [email protected] |
| 用户密码 | Pass123! |
| 用户ID | U001 |
| 用户姓名 | 王小明 |
| 角色 | 便利店店长 |

### 操作步骤
1. 打开登录页面（URL: https://example.com/login）
2. 在"邮箱"框输入：[email protected]
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并生成具体示例
  • 生成内容：将"有效凭证"变成"[email protected], 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（前提条件）：从"有效凭证"变成"邮箱: [email protected], 密码: Pass123!"
• When（操作步骤）：从"用户提交"变成"1.输入邮箱 2.输入密码 3.点击登录"
• Then（预期结果）：从"显示成功消息"变成"页面顶部显示'登录成功，欢迎王小明'"

可选的补充信息：

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

📤 AI会产生什么（输出）

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

新增示例包含：

1. 具体的前提条件（Given）：

   • 不再是"用户已登录"，而是"用户王小明（ID: U001）已登录系统"
   • 不再是"有效凭证"，而是"邮箱: [email protected], 密码: Pass123!"

2. 详细的操作步骤（When）：

   • 不再是"用户提交"，而是"1.输入邮箱 2.输入密码 3.点击登录按钮"
   • 每步操作都清晰具体，可以直接照着测试

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**（前置条件）：
- 数据库中存在用户：邮箱[email protected], 密码=Pass123!
- 用户未登录，当前在登录页面

**When**（操作步骤）：
1. 在"邮箱"输入框输入：[email protected]
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（如"有效凭证"）测试人员不知道用什么数据测，具体示例（如"[email protected]"）可以直接用于手动测试。

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

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

---

质量检查

必检项（100%通过）

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

建议项（≥85%通过）

• [ ] Given包含具体数值（如"[email protected]"）
• [ ] 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/客户不确定验收标准是否符合期望
• 开发写单元测试时需要猜测具体值

具体示例的价值：

• 明确测试数据（如"[email protected]"）
• 明确操作步骤（如"点击登录按钮"）
• 明确预期结果（如"显示'登录成功，欢迎王小明'"）

"抽象 vs 具体"的区别

| 维度 | 抽象AC | 具体示例 | |------|--------|---------| | Given | "有效凭证" | "邮箱: [email protected], 密码: 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秒后消失）

测试人员使用指南

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

1. 准备测试数据：

   • 创建测试用户：[email protected] / Pass123!
   • 准备测试商品：苹果、香蕉等
   • 设置账户余额：¥500

2. 执行操作步骤：

   • 按照When部分的步骤1-2-3...逐步执行
   • 每步操作后观察界面变化

3. 验证预期结果：

   • 对照Then部分的验证点逐一检查
   • 发现不符合时记录Bug（附截图）

---

>> 命令

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

---

相关 Skills

配合使用：

• us-enrich-context - US增加场景感，AC增加具体示例，两者互补
• acceptance-criteria - 先用本SKILL检查AC格式，再用examples增强

后续流程：

• bdd-scenario - AC具体示例可直接转换为BDD测试场景
• test-strategy - 测试示例帮助制定测试策略

质量保证：

• principle-kiss - 具体示例应保持简洁，不过度复杂化
• document-quality - 确保示例文档质量

工作流位置：

• WORKFLOW S3-7（用户验收确认）前使用，帮助用户理解验收标准
• 或在设计阶段前使用，为开发提供明确的测试用例

---

注意：

1. 具体示例应该真实可行（不是随机编造的数据）
2. 示例数据应该覆盖典型场景（不仅仅是最简单的场景）
3. 可根据项目需要扩展边界条件示例（如密码错误、余额不足等）