Imported from wuchubuzai2018/expert-skills-hub (
skills/haizei-ears-requirements/SKILL.md). Install upstream withnpx skills add wuchubuzai2018/expert-skills-hub --skill haizei-ears-requirements. Copyright stays with the author.
EARS 需求规格改写与审查
本技能用于基于 EARS（Easy Approach to Requirements Syntax，需求语法简易方法）将模糊、口语化或有歧义的需求改写为清晰、无歧义、可测试、可评审的规格陈述，并在需要时给出句式选择、拆分建议和校验意见。
以下模板中的关键字和 shall 保留原始英文写法，以确保 EARS 语法表达准确。
文件路由表
先判断当前任务属于哪一类，再按下表加载对应文件；不要默认把所有参考文档一次性读完。
| 文件 | 什么时候优先查看 | 主要内容 |
|---|---|---|
SKILL.md |
每次进入技能时都先看 | 触发词、主流程、模式路由入口、文件分工 |
references/ears-usage-guide.md |
需要判断是否适合使用 EARS，或了解使用场景、常见触发方式时 | 使用说明、适用场景、不适用场景、快速上手 |
references/ears-chinese-output.md |
需要对外输出中文需求，不希望出现 WHEN、WHILE、IF、THEN、WHERE、shall 等英文关键词时 | 中文输出约定、关键词替换、中文模板 |
references/ears-patterns.md |
不确定该选哪种 EARS 模式，或需要查看各模式细节和常见错误时 | 六种模式详解、示例、常见错误 |
references/ears-output-template.md |
需要统一输出结构、改写前后对照格式、待确认问题模板时 | 单条改写、多条拆分、审查模板、输出要求 |
references/ears-writing-rules.md |
需要检查写法质量、模糊词、可测试性和完成标准时 | 编写规则、处理策略、完成标准 |
examples/ears-examples.md |
需要参考具体改写案例时 | 改写前 / 改写后示例 |
生产输出默认约定
- 对外输出需求规格时，默认使用中文句式，不输出
WHEN、WHILE、IF、THEN、WHERE、shall等英文关键词。 - 英文 EARS 关键字仅用于模式讲解、分类说明、内部讨论或用户明确要求保留英文模板的场景。
- 改写结果默认使用“当…时”“在…时”“如果…，则…”“应”等中文表达。
- 如果需要同时给出模式解释和最终规格，先说明模式名称，再输出中文规格正文。
改写流程
快速改写流程
- 识别原始语义：找出系统名称、动作对象、触发事件、状态条件、异常条件和约束信息。
- 标记问题点：圈出模糊词、多动作混写、未量化约束、缺失主语和语义漂移风险。
- 判断是否拆分：如果一句话里包含多个动作、多个异常场景或多个时序阶段，先拆成多条需求。
- 进入模式路由：根据是否有事件、状态、功能开关或异常场景，选择对应 EARS 模式。
- 执行改写：按模板输出规格，优先保留原始业务意图，不擅自补充业务规则。
- 补足可测试性：尽量补出时间限制、次数限制、范围限制、失败处理和提示内容；缺失时列出待确认问题。
- 按固定结构输出：给出模式判断、改写前后对照、拆分说明和审查意见。
判断与分支
- 如果原句同时表达“状态变化前”和“状态变化后”两个行为，应优先拆成两条，而不是直接保留复杂模式。
- 如果一句话里既有正常流程又有异常流程，应分别改写，不要写成一条混合需求。
- 如果无法明确“谁来做什么”，先补主语，再改写。
- 如果无法明确触发条件或响应动作，应停止硬改，转为输出待确认问题。
单独使用时
- 接收 用户提供的模糊规格或需求。
- 分类 使用模式选择指南，对每条陈述进行分类。
- 重写 使用合适的 EARS 模板重写规格。
- 校验 重写后的规格是否满足以下要求：
- 每条陈述恰好只包含一个
shall。 - 使用可衡量、可验证的语言。
- 不包含歧义黑名单词汇（参见 USDM 编写指南）。
- EARS 关键字（WHEN、WHILE、IF、THEN、WHERE）必须全部大写。
- 每条陈述恰好只包含一个
- 呈现 向用户展示重写前后的对比。
与 USDM 一起使用时
EARS 应用于 USDM 层级中的 规格级别（SPEC-NNN）。在 USDM 第 3 步（层级构建）中，应使用合适的 EARS 模式编写每一条规格：
- 正常路径行为 → Ubiquitous、Event-driven 或 State-driven
- 错误 / 边界场景 → Unwanted behavior（IF-THEN）
- 依赖功能开关的行为 → Optional feature（WHERE）
- 多条件行为 → Complex
模式路由
6 种 EARS 模式
先按下表判断应进入哪一种模式，再使用对应模板改写。
| 路由判断 | 进入模式 | 解决的典型问题 | 模板 | 示例 |
|---|---|---|---|---|
| 没有触发事件、没有持续状态、没有功能开关，行为始终成立 | Ubiquitous（普适型） | 把“系统一直都应这样做”的泛化描述写清楚 | 系统 shall <响应>. |
系统 shall 使用 AES-256 对静态数据进行加密。 |
| 存在明确、离散的触发事件 | Event-Driven（事件驱动型） | 把“什么时候发生”补充清楚，避免只有动作没有触发条件 | WHEN <触发事件>, 系统 shall <响应>. |
WHEN 用户点击“提交”按钮时，系统 shall 校验所有必填字段。 |
| 存在持续成立的状态或约束 | State-Driven（状态驱动型） | 把“在什么状态下一直生效”表达清楚，避免把状态误写成事件 | WHILE <状态>, 系统 shall <响应>. |
WHILE 系统处于维护模式时，系统 shall 对所有请求返回 HTTP 503。 |
| 处理错误、故障、边界情况或异常输入 | Unwanted Behavior（非期望行为型） | 把异常场景下的处理动作写具体，避免“妥善处理”这类空话 | IF <条件>, THEN 系统 shall <响应>. |
IF 支付网关返回错误时，THEN 系统 shall 将待处理订单标记为支付失败。 |
| 行为只在某个功能或配置启用时成立 | Optional Feature（可选功能型） | 把功能开关前提写明，避免把可选功能误写成默认行为 | WHERE <功能已启用>, 系统 shall <响应>. |
WHERE 已启用双因素认证时，系统 shall 在密码校验通过后要求输入 TOTP 验证码。 |
| 同时存在两个条件，例如事件 + 状态、事件 + 功能开关 | Complex（复合型） | 处理单一模式不足以表达的组合条件，但仍限制在两个关键字内 | 组合使用 WHEN、WHILE、IF、WHERE，且每条规格最多使用 2 个关键字 | WHILE 系统处于离线模式时，WHEN 用户新建记录时，系统 shall 将记录写入本地待同步队列。 |
模式选择指南
请按以下决策流程选择正确的模式：
1. 是否存在触发事件？
├─ 是 → 是否还存在持续状态？
│ ├─ 是 → 复合型（WHILE + WHEN）
│ └─ 否 → 事件驱动型（WHEN）
└─ 否
2. 是否存在持续条件？
├─ 是 → 状态驱动型（WHILE）
└─ 否
3. 是否属于错误 / 故障 / 边界场景？
├─ 是 → 非期望行为型（IF-THEN）
└─ 否
4. 是否依赖某个功能 / 配置？
├─ 是 → 可选功能型（WHERE）
└─ 否 → 普适型
参考引用资料（需按需加载）
references/ears-usage-guide.md— 使用说明、触发表达、适用与不适用场景references/ears-chinese-output.md— 中文生产输出约定、关键词替换与中文模板references/ears-patterns.md— 6 种模式的详细参考资料，包含多个示例references/ears-output-template.md— 固定输出结构、对照格式与待确认问题模板references/ears-writing-rules.md— 编写规则、典型处理策略与完成标准examples/ears-examples.md— 典型场景的改写前 / 改写后示例
