# Us Readability Check

> 检查User Story是否对非技术人员友好，检测技术术语残留、过于精炼的表达、缺乏场景感等问题。适合在US初稿完成后、准备提交验收前使用，当需要质量检查时。帮助敏捷新手自我检查，知道自己写的US哪里需要改进，给出具体可操作的改进建议。

- Skill: `majiayu000/us-readability-check` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/us-readability-check`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/us-readability-check/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-readability-check

---


# US Readability Check Skill

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

---

## 概述

检查User Story的可读性，确保US对PM/BA/客户等非技术人员友好，发现技术术语残留、过于精炼、缺乏场景感等问题，并给出改进建议。

**核心价值**：
- 自动检测技术术语残留（目标：0%）
- 识别过于精炼的表达（建议增加场景描述）
- 检测缺乏场景感的US（无具体角色、时间、地点）
- 发现模糊表达（如"用户"太宽泛）
- 生成可操作的改进建议

**适合人群**：不太熟悉敏捷开发，想知道自己写的US质量如何的用户

---

## 适用场景

### 场景1：自我检查US质量
写完US后不确定是否符合标准，使用本SKILL进行质量检查，发现问题并改进

### 场景2：准备客户评审前预检
在发给客户确认前，先检查US是否对客户友好，避免因技术术语或过于精炼而导致客户困惑

### 场景3：团队代码审查（Peer Review）
团队成员互相审查US时，使用本SKILL作为检查清单，确保质量一致

---

## 执行步骤

### 步骤1：读取US文档
- 读取requirements/目录下的所有US文件
- 提取每个US的As-Want-So内容
- 识别US的ID、SN、标题

### 步骤2：检测维度（4个核心维度）

#### 检测1：技术术语残留 ⭐ 最高优先级
**目标**：技术术语密度 = 0%（REQUIREMENTS阶段硬性要求）

**关键词库**（扩展性设计）：
- **API/接口类**：API, REST, GraphQL, Webhook, Endpoint, 接口, 端点
- **数据库类**：数据库, Database, SQL, NoSQL, Redis, MongoDB, Table, 表
- **数据格式**：JSON, XML, YAML, CSV, Protocol Buffer
- **认证授权**：Token, JWT, OAuth, 会话, Cookie
- **技术架构**：服务端, 客户端, 前端, 后端, 中间件, 微服务
- **编程术语**：函数, 方法, 类, 对象, 变量, 参数, 返回值

**检测密度**：
- ✅ 0个术语 = 优秀（符合CRAFT标准）
- ⚠️ 1-2个术语 = 需要改进（警告）
- ❌ ≥3个术语 = 不合格（必须修改）

**改进建议示例**：
- "API接口" → "系统功能"
- "数据库查询" → "查找信息"
- "JSON格式" → "结构化数据"
- "Token认证" → "身份验证"

#### 检测2：精炼度检测
**目标**：As-Want-So每段应≥10字，否则可能过于精炼

**检测规则**：
- As段 < 5字 → ❌ 过于精炼（如"作为用户"）
- Want段 < 10字 → ⚠️ 可能过于精炼（如"查看数据"）
- So that段 < 10字 → ⚠️ 价值描述不足（如"方便使用"）

**建议**：
- 过于精炼的AS：建议具体化角色（如"便利店店长"而非"用户"）
- 过于精炼的Want：建议增加场景描述（推荐使用 us-enrich-context）
- 过于精炼的So that：建议补充业务价值（如"节省30%的时间"）

#### 检测3：场景感检测
**目标**：检测US是否包含具体的场景元素

**检测要素**：
- [ ] 具体角色名字（如"王小明"、"A店店长"）
- [ ] 时间信息（如"每天早上"、"月底前"）
- [ ] 地点信息（如"在店铺"、"在办公室"）
- [ ] 具体动作描述（如"输入账号密码"而非"登录"）
- [ ] 用户心理/动机（如"因为早上时间紧张"）

**评分规则**：
- ≥3项 = ✅ 场景感充足
- 1-2项 = ⚠️ 场景感一般（建议增强）
- 0项 = ❌ 缺乏场景感（强烈建议使用 us-enrich-context）

#### 检测4：模糊表达检测
**目标**：识别过于抽象或宽泛的表达

**常见模糊词汇**：
- **角色模糊**：
  - "用户" → 建议具体化为"店长"、"客户"、"管理员"等
  - "系统管理员" → 建议明确是"IT管理员"还是"业务管理员"

- **功能模糊**：
  - "查看数据" → 建议具体化为"查看营收数据"、"查看库存数据"
  - "管理信息" → 建议具体化为"编辑商品信息"、"删除用户信息"

- **价值模糊**：
  - "方便使用" → 建议量化为"节省30%操作时间"
  - "提高效率" → 建议具体化为"减少手动输入，避免错误"

### 步骤3：生成可读性报告

#### 报告格式（按US分组）
```markdown
# US可读性检查报告

生成时间：2025-12-04
检查范围：requirements/ 目录下所有US
检查US数量：15个

## 总体评分
- ✅ 优秀：8个（53%）
- ⚠️ 需改进：5个（33%）
- ❌ 不合格：2个（14%）

---

## 详细报告

### US-AUTH-001: 用户登录

**总体评分**：⚠️ 需改进（65分）

**问题清单**：
1. ❌ **技术术语残留**（权重：40%）
   - 发现：1个技术术语
   - 位置：Want段 - "输入Token认证"
   - 建议：将"Token认证"改为"身份验证"或"登录凭证"

2. ⚠️ **场景感不足**（权重：30%）
   - 发现：缺少时间、地点、用户心理描述
   - 建议：使用 >>us-enrich 增加场景感

3. ⚠️ **模糊表达**（权重：20%）
   - 发现：As段 - "用户"过于宽泛
   - 建议：具体化为"便利店店长"或"前台收银员"

4. ✅ **精炼度**（权重：10%）
   - 通过：As(8字) Want(15字) So that(12字)

**改进建议**：
- 🎯 高优先级：移除"Token认证"，改为"登录凭证"
- 💡 建议：具体化角色为"便利店店长"
- 💡 可选：使用 >>us-enrich 增加场景感

---

### US-ORDER-003: 下单流程

**总体评分**：✅ 优秀（92分）

**评价**：
- ✅ 无技术术语
- ✅ 场景感充足（包含时间、地点、具体动作）
- ✅ 角色具体（"A店收银员王小红"）
- ✅ 价值清晰且量化（"减少30%录入时间"）

**亮点**：
- 角色具体化做得很好
- 价值量化明确

---

## 改进建议汇总

### 必须修改（阻塞问题）
1. US-AUTH-001: 移除技术术语"Token认证"
2. US-SALES-005: 移除技术术语"JSON数据格式"、"RESTful API"

### 建议改进
3. US-AUTH-001, US-PROD-007: 角色过于宽泛，建议具体化
4. US-SALES-002, US-INV-004: 缺乏场景感，建议使用 >>us-enrich
5. US-ORDER-006: So that价值描述过于抽象，建议量化

### 可选优化
6. 所有US：考虑添加用户心理描述，增强共鸣感
```

### 步骤4：推荐后续操作
- 对于技术术语残留（❌）：必须修改，提供替换建议
- 对于场景感不足（⚠️）：推荐使用 `>>us-enrich` 命令
- 对于模糊表达（⚠️）：给出具体化建议

---

## 快速开始

最快的3步使用流程：

- [ ] **第1步：确认已有US文档**
  - 文件位置：`spec/requirements/user_stories.md`（或其他.md文件）
  - 格式要求：每个US包含 As-Want-So 三段式结构
  - 数量建议：至少2-3个US（可以检查更多）

- [ ] **第2步：一键调用检查**
  - 命令：`>>us-readability` 或 `>>us-readability-batch`
  - AI会自动扫描 `spec/requirements/` 下所有US文档
  - 检查过程：4个维度（技术术语/精炼度/场景感/模糊表达）
  - ⚠️ **只读检查**：不会修改你的US文档

- [ ] **第3步：查看检查报告**
  - 结果显示：对话窗口中直接显示完整报告
  - 报告内容：每个US的评分 + 问题清单 + 改进建议
  - 后续操作：根据报告手动修改US，或使用推荐的其他SKILL（如 `>>us-enrich`）

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

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

---

## 使用说明

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

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

**项目结构示例**：
```
你的项目/
└── spec/
    └── requirements/
        ├── user_stories.md      ← AI会读取检查
        ├── acceptance_criteria.md  ← 也会检查AC
        └── nfr.md
```

**AI会检查什么问题**：
- 是否有技术术语残留（如"API"、"数据库"、"JSON"）
- US是否太简短（缺少场景描述）
- 角色是否模糊（如"用户"太宽泛）
- 价值是否抽象（如"方便使用"不够具体）

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

**生成的内容**：
AI会生成一份**可读性检查报告**（新文档），**不会修改你的原始US文件**

**报告内容**：
1. **总体评分统计**：
   - 优秀的US有多少个（✅）
   - 需要改进的有多少个（⚠️）
   - 不合格的有多少个（❌）

2. **每个US的详细报告**（逐个分析）：
   - 发现的问题类型（技术术语/过于精炼/缺乏场景/角色模糊）
   - 问题具体在哪里（如"Want段使用了'API接口'"）
   - 具体的改进建议（如"将'API接口'改为'系统功能'"）
   - 评分（0-100分）

3. **改进建议汇总**：
   - 必须修改的问题（阻塞问题，如技术术语）
   - 建议改进的问题（如角色太模糊）
   - 可选优化的建议（如增加用户心理描述）

**结果位置**：
- 报告会显示在对话窗口中
- 你可以将报告复制保存为文件
- **你的原始US文档完全不会被修改**

**示例（报告片段）**：
```markdown
### US-AUTH-001: 用户登录

**总体评分**：⚠️ 需改进（65分）

**问题清单**：
1. ❌ 技术术语残留
   - 位置：Want段 - "输入Token认证"
   - 建议：将"Token认证"改为"登录凭证"

2. ⚠️ 角色模糊
   - 位置：As段 - "用户"过于宽泛
   - 建议：具体化为"便利店店长"
```

### 🎯 如何使用

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

**第2步：调用这个SKILL**
- 在与AI对话时输入：`>>us-readability`
- AI会自动读取所有US并开始检查
- 检查时间：约2-5分钟 / 10个US

**第3步：查看报告**
- AI会在对话中显示完整的检查报告
- 你可以根据报告逐个修改US
- 对于技术术语问题，必须修改
- 对于场景感不足，可以使用 `>>us-enrich` 增强

**常见问题**：

Q: AI会修改我的US文档吗？
A: **不会**。这是一个纯检查工具，只生成报告，不修改原文件。

Q: 如果报告说我的US有技术术语怎么办？
A: 报告会告诉你具体在哪里有什么术语，并给出替换建议。你可以手动修改，或者询问AI具体怎么改。

Q: 我的US很多，检查会很慢吗？
A: 通常10个US检查只需要2-5分钟。如果US很多（超过30个），AI会显示进度。

Q: 检查后发现很多问题，该先改哪些？
A: 报告会按优先级分组："必须修改"（阻塞问题，如技术术语）要立即改，"建议改进"可以逐步改。

---

## 质量检查

### 必检项（100%通过）
- [ ] 不修改原US文档（只读检查）
- [ ] 每个US都生成检查结果
- [ ] 技术术语检测准确率≥95%
- [ ] 报告格式清晰可读

### 建议项（≥85%通过）
- [ ] 场景感检测准确（识别缺失的场景元素）
- [ ] 模糊表达检测有效（给出具体化建议）
- [ ] 改进建议可操作（不是泛泛的"改进"）
- [ ] 推荐的后续操作合理

---

## 限制条件

### ✅ 适用场景
- 已有US文档，符合基本的As-Want-So格式
- 需要质量自查（在提交验收前或客户评审前）
- 想知道US中哪里需要改进（自我诊断）
- 准备客户评审前预检，避免因技术术语困扰客户
- 团队成员互相审查US时，作为标准化检查清单

### ❌ 不适用场景
- **完全没有US文档** → 先使用 `interview-to-us` 从访谈生成US
- **US格式完全错误（缺少As-Want-So结构）** → 先使用 `user-story-format` 验证和修复格式
- **需要自动修复US而非只检查** → 本SKILL只生成报告，不修复；需手动改或用其他SKILL
- **需要检查AC/NFR的详细逻辑** → 本SKILL专注US可读性，不深入检查AC/NFR
- **期望100%无误报** → 检测基于关键词库，可能有少量误报或漏报

### 📋 前置条件
- 至少有2-3个User Story（包含As-Want-So三段式）
- US文档是.md格式，位于`spec/requirements/`目录下
- US已经过基本的格式验证（有id, sn等Front Matter）
- 愿意接受改进建议并手动修改（本SKILL不自动修复）
- 理解报告中的评分和建议是辅助判断，最终决策由用户做出

---

## 分级检查策略

### L1-STREAMLINED（快速检查）
**检测维度**：2个核心维度
- 技术术语残留（权重70%）
- 精炼度检测（权重30%）

**通过标准**：技术术语密度≤10%（≤1个术语/US）
**时间目标**：< 5分钟 / 10个US

### L2-BALANCED（标准检查）
**检测维度**：3个维度
- 技术术语残留（权重50%）
- 场景感检测（权重30%）
- 精炼度检测（权重20%）

**通过标准**：综合得分≥75分
**时间目标**：10-15分钟 / 10个US

### L3-RIGOROUS（全面检查）
**检测维度**：4个全面维度
- 技术术语残留（权重40%）
- 场景感检测（权重30%）
- 模糊表达检测（权重20%）
- 精炼度检测（权重10%）

**通过标准**：综合得分≥85分
**时间目标**：20-30分钟 / 10个US
**额外检查**：
- 角色一致性（同一角色在不同US中的描述是否一致）
- 价值链完整性（所有US的价值是否对齐项目目标）

---

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

### 学习指引：每个检测维度的意义

#### 为什么要避免技术术语？
**业务语言 vs 技术语言**：

```markdown
# ❌ 技术语言（对客户不友好）
As a 系统管理员
I want to 通过RESTful API获取JSON格式的用户Token
So that 实现OAuth2.0认证流程

# ✅ 业务语言（客户能理解）
As a 系统管理员
I want to 安全地验证用户身份
So that 确保只有授权用户才能访问系统
```

**原因**：
- PM/BA/客户通常不懂技术术语
- 技术术语会导致误解（如"Token"可能被理解为"代币"）
- 需求阶段应聚焦业务价值，不涉及实现细节

#### 为什么需要场景感？
**精炼版 vs 丰富版**：

```markdown
# ⚠️ 精炼版（缺乏场景感）
As a 店长
I want to 查看营收
So that 了解业绩

# ✅ 丰富版（有场景感）
As a 便利店A店店长王小明
I want to 每天早上8点到店后立即查看昨日营收数据
So that 快速了解昨日业绩，决定今日备货策略
```

**价值**：
- 帮助团队理解"谁、何时、为什么"使用这个功能
- 减少误解和来回沟通
- 让所有人（包括客户）达成一致理解

### 优秀US示例（供对比学习）

```markdown
## ✅ 示例1：角色具体、场景清晰、价值量化

As a 连锁便利店区域经理（负责10家门店）
I want to 在每周一早上自动收到上周所有门店的销售对比报表
So that 快速识别表现优异和需要改进的门店，节省2小时的手动统计时间

**评分**：95分
- ✅ 角色具体（区域经理 + 负责范围）
- ✅ 场景清晰（每周一早上 + 自动收到）
- ✅ 价值量化（节省2小时）
- ✅ 无技术术语

## ✅ 示例2：用户心理+具体动作

As a 第一次使用系统的新收银员
I want to 在登录后看到简单的操作指引（不超过3步）
So that 不用等店长培训就能快速上手，减少工作压力

**评分**：92分
- ✅ 角色具体（新收银员）
- ✅ 用户心理（减少工作压力）
- ✅ 量化限制（不超过3步）
- ✅ 场景真实（第一次使用）
```

---

## >> 命令

```
>>us-readability               # 检查单个US可读性
>>us-readability-batch         # 批量检查所有US
>>us-readability-report        # 生成完整可读性报告
>>us-tech-terms               # 只检查技术术语（快速模式）
>>us-recommend-fix            # 推荐自动修复建议
```

---

## 相关 Skills

**检查后使用**：
- **us-enrich-context** - 发现缺乏场景感后，使用本SKILL增强
- **user-story-format** - 本SKILL检查可读性，format SKILL检查结构正确性

**配合使用**：
- **interview-to-us** - 从访谈生成US后，用本SKILL检查质量
- **principle-invest** - 本SKILL检查可读性，INVEST检查业务价值

**质量保证**：
- **document-quality** - 本SKILL针对US，doc-quality针对整体文档

**工作流位置**：
- WORKFLOW S3-3（Self-Reflection）后使用本SKILL进行深度可读性检查
- WORKFLOW S3-5（CONSTRAINT验收）前使用本SKILL预检，提高验收通过率

---

**注意**：
1. 本SKILL是**只读检查**，不会修改原US文档
2. 检测准确率依赖关键词库的完整性，可根据项目定制扩展
3. 改进建议仅供参考，最终决策由用户做出