majiayu000 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分组）
# 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文件
报告内容：
总体评分统计：
- 优秀的US有多少个（✅）
- 需要改进的有多少个（⚠️）
- 不合格的有多少个（❌）
每个US的详细报告（逐个分析）：
- 发现的问题类型（技术术语/过于精炼/缺乏场景/角色模糊）
- 问题具体在哪里（如"Want段使用了'API接口'"）
- 具体的改进建议（如"将'API接口'改为'系统功能'"）
- 评分（0-100分）
改进建议汇总：
- 必须修改的问题（阻塞问题，如技术术语）
- 建议改进的问题（如角色太模糊）
- 可选优化的建议（如增加用户心理描述）
结果位置：
- 报告会显示在对话窗口中
- 你可以将报告复制保存为文件
- 你的原始US文档完全不会被修改
示例（报告片段）：
### 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 技术语言：
# ❌ 技术语言（对客户不友好）
As a 系统管理员
I want to 通过RESTful API获取JSON格式的用户Token
So that 实现OAuth2.0认证流程
# ✅ 业务语言（客户能理解）
As a 系统管理员
I want to 安全地验证用户身份
So that 确保只有授权用户才能访问系统
原因：
- PM/BA/客户通常不懂技术术语
- 技术术语会导致误解（如"Token"可能被理解为"代币"）
- 需求阶段应聚焦业务价值，不涉及实现细节
为什么需要场景感？
精炼版 vs 丰富版：
# ⚠️ 精炼版（缺乏场景感）
As a 店长
I want to 查看营收
So that 了解业绩
# ✅ 丰富版（有场景感）
As a 便利店A店店长王小明
I want to 每天早上8点到店后立即查看昨日营收数据
So that 快速了解昨日业绩，决定今日备货策略
价值：
- 帮助团队理解"谁、何时、为什么"使用这个功能
- 减少误解和来回沟通
- 让所有人（包括客户）达成一致理解
优秀US示例（供对比学习）
## ✅ 示例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预检，提高验收通过率
注意：
- 本SKILL是只读检查，不会修改原US文档
- 检测准确率依赖关键词库的完整性，可根据项目定制扩展
- 改进建议仅供参考，最终决策由用户做出