# Us Enrich Context

> 为精炼的User Story增加真实场景描述、用户心理和具体对话，让US对PM/客户更亲切易懂。适合在US初稿完成后、需要向客户展示理解或准备验收时使用，当US格式正确但缺乏场景感时。帮助不熟悉敏捷的PM/BA、需要对外沟通的团队，通过丰富的场景感让需求文档更容易被理解和接受。

- Skill: `majiayu000/us-enrich-context` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/us-enrich-context`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/us-enrich-context/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/us-enrich-context

---


# US Enrich Context Skill

> **Scope**: REQUIREMENTS
>
> **版本**: 0.1.0 | **创建日期**: 2025-12-04

---

## 概述

将符合CRAFT标准的精炼User Story增强为更具场景感和亲和力的版本，通过添加真实业务场景和用户期望，让PM/BA/客户更容易理解需求。

**核心价值**：
- 保留标准的As-Want-So结构（符合CRAFT标准）
- 新增"业务场景"章节（具体角色、时间、地点、动机）
- 新增"用户期望"章节（非功能性的用户体验期望）
- 100%业务语言，无技术术语

**适合人群**：不太熟悉敏捷开发但有一定研发背景的用户

---

## 适用场景

### 场景1：US太精炼，缺乏场景感
**现状**：
```markdown
As a 便利店店长
I want to 输入账号密码登录系统
So that 我可以查看今日营收数据
```

**问题**：符合格式但太抽象，PM/客户难以理解具体使用场景

### 场景2：需要向客户展示需求理解
客户提出需求后，需要快速确认理解是否正确，但标准US太简洁，客户不确定是否准确表达了他们的意图

### 场景3：团队成员对需求理解不一致
Dev看US觉得清晰，但PM/客户觉得缺乏细节，需要增强场景感帮助所有人达成共识

---

## 执行步骤

### 步骤1：读取US基本信息
- 读取US的Front Matter（id, sn, priority等）
- 提取As-Want-So三段内容
- 可选：读取SPEC_PRJ_DESC获取项目背景

### 步骤2：生成业务场景
基于As部分的角色和So that部分的业务价值，生成真实场景描述：

1. **具体化角色**：
   - "用户" → "王小明，某便利店A店的店长"
   - 添加角色的日常工作背景

2. **添加时间地点**：
   - "每天早上8点到店后"
   - "在店铺收银台旁边"

3. **描述使用场景和动机**：
   - 为什么需要这个功能？
   - 在什么情况下使用？
   - 使用这个功能的目标是什么？

### 步骤3：生成用户期望
从"So that"推导非功能性期望：

1. **性能期望**：
   - 抽象："快速查看" → 具体："3秒内完成登录"

2. **易用性期望**：
   - 抽象："方便使用" → 具体："记住账号，不用每次输入"

3. **明确反馈**：
   - 抽象："操作成功" → 具体："密码错误时明确提示'密码错误'而非'登录失败'"

### 步骤4：插入到US文档
保持原有结构不变，在适当位置插入新章节：

```markdown
## US-ID: 标题

**业务场景**：
[生成的具体场景描述]

**核心需求**：
As a [原始内容]
I want to [原始内容]
So that [原始内容]

**用户期望**：
- [期望1]
- [期望2]
- [期望3]
```

### 步骤5：质量验证
- 核心As-Want-So未被修改
- 新增内容100%业务语言（无技术术语）
- 场景描述真实可信（符合项目背景）
- Front Matter和ID完全保留

---

## 快速开始

最快的3步使用流程：

- [ ] **第1步：准备US文档**
  - 文件位置：`spec/requirements/user_stories.md`（或其他.md文件）
  - 需要包含：As-Want-So 三段式结构
  - 文档示例：至少2-3个US，格式正确但缺乏场景感

- [ ] **第2步：调用SKILL**
  - 命令：`>>us-enrich` 或 `>>us-enrich-context`
  - AI会自动读取文档并处理（无需手动指定文件路径）
  - 处理过程：为每个US增加"业务场景"和"用户期望"章节

- [ ] **第3步：查看增强后的US**
  - 结果位置：原文件（`spec/requirements/user_stories.md`）
  - 查看方式：打开原文档，查看新增的"业务场景"和"用户期望"章节
  - 或在对话中查看AI的修改摘要

⏱️ **预计耗时**：5-10分钟 / 10个US

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

---

## 使用说明

### 📥 AI会读取什么（输入）

**自动读取的文档**：
- AI会读取 `spec/requirements/` 文件夹下的User Story文档
- 文档需要是 **.md格式**（如 `user_stories.md`）
- 每个US需要包含：
  * 文档头部的编号信息（如 `id: US-AUTH-001`）
  * As-Want-So三段式结构（角色-功能-价值）

**项目结构示例**：
```
你的项目/
└── spec/
    └── requirements/
        ├── user_stories.md  ← AI会读取这个文件
        └── acceptance_criteria.md
```

**可选的补充信息**（有这些会更好）：
- 如果有项目背景描述文件，AI能生成更贴合项目的场景
- 如果有用户画像文档，AI能使用真实的用户特征

### 📤 AI会产生什么（输出）

**修改的内容**：
AI会在**原有US文件**中新增2个章节，**原有内容完全保留**：

1. **业务场景**（新增章节）：
   - 具体的用户名字（如"王小明"）
   - 时间和地点（如"每天早上8点到店后"）
   - 用户的工作背景和使用动机
   - 约100-150字的生动描述

2. **用户期望**（新增章节）：
   - 3-5条具体的期望清单
   - 每条都可以被观察或测量（如"3秒内完成登录"）
   - 覆盖性能、易用性、反馈等方面

**结果位置**：
- 修改后的文档仍在原位置：`spec/requirements/user_stories.md`
- **原有的As-Want-So内容不会改变**
- 你可以在对话窗口中看到AI的修改摘要

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

```markdown
# 修改前（精炼版）
## US-AUTH-001: 用户登录

As a 便利店店长
I want to 输入账号密码登录系统
So that 我可以查看今日营收数据

---

# 修改后（丰富版）
## US-AUTH-001: 用户登录

**业务场景**：
王小明是连锁便利店A店的店长，每天早上8点到店后的第一件事就是打开系统查看昨日营收情况。他习惯用自己的手机号+密码登录系统（公司统一配置的账号）。

**核心需求**：
As a 便利店店长
I want to 输入账号密码登录系统
So that 我可以查看今日营收数据

**用户期望**：
- 登录过程快速（不超过3秒），因为早上时间紧张
- 系统记住手机号，不用每次都重新输入
- 密码错误时明确提示"密码错误"而非"登录失败"
```

### 🎯 如何使用

**第1步：确保文档已准备好**
- 打开 `spec/requirements/` 文件夹
- 确认有User Story文档（.md格式）
- 确认US包含 As-Want-So 结构

**第2步：调用这个SKILL**
- 在与AI对话时输入：`>>us-enrich`
- AI会自动读取需求文档并开始处理
- 处理时间：约1-2分钟 / 10个US

**第3步：查看结果**
- 打开原来的US文档
- 你会看到每个US下面新增了"业务场景"和"用户期望"
- AI会在对话中告诉你具体修改了哪些US

**常见问题**：

Q: AI会覆盖我原来的US内容吗？
A: **不会**。AI只会新增"业务场景"和"用户期望"两个章节，原有的As-Want-So完全保留。

Q: 如果我的US格式不对怎么办？
A: AI会提示你哪些US需要调整，比如："US-AUTH-001缺少As部分，请补充角色信息"。

Q: 我能控制场景丰富到什么程度吗？
A: 可以。在调用时告诉AI你的偏好，比如："请生成简短的场景（50字左右）"或"请生成详细的场景"。

Q: 我不想要某个US的场景可以吗？
A: 可以。在调用时指定："只丰富US-AUTH-001到US-AUTH-005，其他的不用处理"。

---

## 质量检查

### 必检项（100%通过）
- [ ] 核心As-Want-So未被修改
- [ ] Front Matter（id, sn等）完全保留
- [ ] 新增内容无技术术语（0个技术词汇）
- [ ] 场景描述真实可信（不脱离项目背景）

### 建议项（≥80%通过）
- [ ] 业务场景包含具体角色名字
- [ ] 业务场景包含时间和地点信息
- [ ] 用户期望有3条以上
- [ ] 用户期望包含可量化标准（如"3秒内"）
- [ ] 整体可读性提升（比原始US更容易理解）

---

## 限制条件

### ✅ 适用场景
- US已经存在，格式基本正确（符合As-Want-So结构）
- US比较精炼，缺乏具体的业务场景描述
- 需要向客户、管理层或非技术人员展示需求理解
- 希望让US更容易被理解，减少后续澄清工作
- 团队成员对需求理解不一致，需要通过场景达成共识

### ❌ 不适用场景
- **没有任何US文档** → 先使用 `interview-to-us` 从访谈记录生成US
- **US格式完全混乱** → 先使用 `user-story-format` 验证和修复格式
- **US已经很详细，有大量场景描述** → 无需使用本SKILL，避免冗余
- **仅供开发团队内部使用，不对外沟通** → 精炼版即可，无需增强
- **US还在起草阶段，内容未定稿** → 等待定稿后再使用

### 📋 前置条件
- 至少有2-3个完整的User Story（包含As-Want-So三段式）
- US文档是.md格式，位于`spec/requirements/`目录下
- US已经过基本的格式检查（有id, sn等Front Matter）
- 项目背景信息相对清晰（如果有项目描述文档会更好）

---

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

### 为什么需要场景丰富？

**精炼版的价值**：
- 结构标准，易于管理
- 符合敏捷最佳实践
- 技术团队容易理解

**丰富版的价值**：
- PM/BA/客户更容易理解
- 帮助团队达成一致理解
- 减少需求澄清的来回沟通

### 两种风格的适用场景

| 场景 | 推荐风格 | 理由 |
|------|----------|------|
| Sprint Planning（开发团队内部） | 精炼版 | 团队熟悉敏捷，需要快速浏览 |
| 客户需求确认 | 丰富版 | 客户不熟悉敏捷，需要详细场景 |
| 需求文档归档 | 精炼版 | 长期维护，保持简洁 |
| 需求评审会议 | 丰富版 | 多方参与，需要充分理解 |

### 学习提示

**对比示例**：

```markdown
# 精炼版（符合CRAFT标准）
As a 便利店店长
I want to 输入账号密码登录系统
So that 我可以查看今日营收数据

# 丰富版（增强场景感）
**业务场景**：
王小明是连锁便利店A店的店长，每天早上8点到店后的第一件事就是打开系统查看昨日营收情况。他习惯用自己的手机号+密码登录系统（公司统一配置的账号）。

**核心需求**：
As a 便利店店长
I want to 输入账号密码登录系统
So that 我可以查看今日营收数据

**用户期望**：
- 登录过程快速（不超过3秒），因为早上时间紧张
- 系统记住手机号，不用每次都重新输入
- 密码错误时明确提示"密码错误"而非"登录失败"
```

**关键改进点**：
1. ✅ 具体角色：从"店长"到"王小明，A店店长"
2. ✅ 时间场景：每天早上8点，查看昨日营收
3. ✅ 使用习惯：用手机号登录，公司统一配置
4. ✅ 量化期望：3秒内完成，明确的错误提示

---

## >> 命令

```
>>us-enrich              # 增强单个US的场景感
>>us-enrich-batch        # 批量增强多个US
>>us-enrich-compare      # 对比精炼版和丰富版
>>us-enrich-revert       # 还原为精炼版（移除场景章节）
```

---

## 相关 Skills

**互补使用**：
- **us-readability-check** - 检查US可读性，发现缺乏场景感的问题后使用本SKILL增强
- **interview-to-us** - 从访谈记录生成US后，使用本SKILL增加场景感

**后续流程**：
- **user-story-format** - 增强后仍需验证As-Want-So格式正确性
- **acceptance-criteria** - 基于丰富的场景，编写更具体的AC

**质量保证**：
- **principle-invest** - 场景丰富不应破坏INVEST原则
- **document-quality** - 确保增强后的文档质量仍然合格

---

**注意**：本SKILL是可选工具，不是强制步骤。在WORKFLOW已生成符合标准的US后，根据受众需要选择性使用。