# Ac To Examples

> 将抽象的Acceptance Criteria（Given-When-Then）转换为具体的数值示例和真实对话，让AC对PM/客户/测试人员更易懂。适合在AC编写完成后、准备测试或向客户展示时使用，当AC格式正确但过于抽象时。帮助不熟悉BDD的PM/BA/测试人员理解测试场景，让AC从抽象规则变成可直接用于手动测试的具体步骤。

- Skill: `diegosouzapw/ac-to-examples` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add diegosouzapw/ac-to-examples`
- Raw SKILL.md: https://api.skillmd.com/api/skills/diegosouzapw/ac-to-examples/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: diegosouzapw (https://skillmd.com/u/diegosouzapw)
- Updated: 2026-09-08
- Page: https://skillmd.com/skills/diegosouzapw/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太抽象，测试人员不知道如何测
**现状**：
```markdown
## 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：将抽象条件转为具体数值
```markdown
# 抽象 → 具体
"有效凭证" → "邮箱: test@example.com, 密码: Pass123!"
"用户已登录" → "用户王小明（ID: U001）已登录系统"
"购物车中有商品" → "购物车中有3件商品：苹果x2, 香蕉x1"
"账户余额充足" → "账户余额: ¥500，购买金额: ¥299"
```

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

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

#### 策略1：分解为具体操作步骤
```markdown
# 抽象 → 具体
"用户提交" →
  1. 在用户名框输入"test@example.com"
  2. 在密码框输入"Pass123!"
  3. 点击"登录"按钮

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

#### 策略2：明确交互细节
```markdown
# 抽象 → 具体
"用户选择日期" → "用户点击日期选择器，选择'2025-12-25'"
"用户上传文件" → "用户点击上传按钮，选择本地文件'report.pdf'（2.5MB）"
```

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

#### 策略1：描述可观察现象
```markdown
# 抽象 → 具体
"显示成功消息" →
  - 页面顶部显示绿色提示条
  - 提示文字："登录成功，欢迎王小明"
  - 3秒后自动消失

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

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

### 步骤5：生成完整示例

#### 格式1：嵌入原AC（推荐）
在原AC的Then部分下方增加"具体示例"章节：

```markdown
## 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生成独立的示例文档：

```markdown
# 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完全保留**

**新增示例包含**：
1. **具体的前提条件**（Given）：
   - 不再是"用户已登录"，而是"用户王小明（ID: U001）已登录系统"
   - 不再是"有效凭证"，而是"邮箱: test@example.com, 密码: Pass123!"

2. **详细的操作步骤**（When）：
   - 不再是"用户提交"，而是"1.输入邮箱 2.输入密码 3.点击登录按钮"
   - 每步操作都清晰具体，可以直接照着测试

3. **可观察的预期结果**（Then）：
   - 不再是"显示成功消息"，而是"页面顶部显示绿色提示'登录成功，欢迎王小明'，3秒后消失"
   - 结果可以被观察和验证

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

**示例（修改前后对比）**：

```markdown
# 修改前（抽象版）
## 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 | "显示成功消息" | "页面顶部显示绿色提示'登录成功，欢迎王小明'" |
| 可测性 | ❌ 不知道怎么测 | ✅ 照着步骤测即可 |

### 对比示例

```markdown
# ❌ 抽象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. **准备测试数据**：
   - 创建测试用户：test@example.com / 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. 可根据项目需要扩展边界条件示例（如密码错误、余额不足等）