# Haizei Ears Requirements

> 需求描述 EARS 改写与审查技能。Use when: EARS 需求改写、EARS requirement rewrite、EARS spec rewrite、EARS 规格改写、用 EARS 改写需求、把需求转成 EARS 规格、review EARS requirements、EARS 模式选择、需求规格消歧、验收标准改写、USDM SPEC 规格统一。解决的问题：把模糊需求改成可测试规格，补齐触发条件、状态条件、异常处理和功能开关，拆分一条需求中的多个动作，识别 should/can/supports/appropriately 等模糊表达，并输出模式判断、改写前后对照、拆分建议和待确认问题。

- Skill: `wuchubuzai2018/haizei-ears-requirements` (Agent Skill, multi-file: 7 files)
- Install (CLI): `npx skillmds@latest add wuchubuzai2018/haizei-ears-requirements`
- Raw SKILL.md: https://api.skillmd.com/api/skills/wuchubuzai2018/haizei-ears-requirements/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: wuchubuzai2018 (https://skillmd.com/u/wuchubuzai2018)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/wuchubuzai2018/haizei-ears-requirements

---


# 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 关键字仅用于模式讲解、分类说明、内部讨论或用户明确要求保留英文模板的场景。
- 改写结果默认使用“当…时”“在…时”“如果…，则…”“应”等中文表达。
- 如果需要同时给出模式解释和最终规格，先说明模式名称，再输出中文规格正文。

## 改写流程

### 快速改写流程

1. **识别原始语义**：找出系统名称、动作对象、触发事件、状态条件、异常条件和约束信息。
2. **标记问题点**：圈出模糊词、多动作混写、未量化约束、缺失主语和语义漂移风险。
3. **判断是否拆分**：如果一句话里包含多个动作、多个异常场景或多个时序阶段，先拆成多条需求。
4. **进入模式路由**：根据是否有事件、状态、功能开关或异常场景，选择对应 EARS 模式。
5. **执行改写**：按模板输出规格，优先保留原始业务意图，不擅自补充业务规则。
6. **补足可测试性**：尽量补出时间限制、次数限制、范围限制、失败处理和提示内容；缺失时列出待确认问题。
7. **按固定结构输出**：给出模式判断、改写前后对照、拆分说明和审查意见。

### 判断与分支

- 如果原句同时表达“状态变化前”和“状态变化后”两个行为，应优先拆成两条，而不是直接保留复杂模式。
- 如果一句话里既有正常流程又有异常流程，应分别改写，不要写成一条混合需求。
- 如果无法明确“谁来做什么”，先补主语，再改写。
- 如果无法明确触发条件或响应动作，应停止硬改，转为输出待确认问题。

### 单独使用时

1. **接收** 用户提供的模糊规格或需求。
2. **分类** 使用模式选择指南，对每条陈述进行分类。
3. **重写** 使用合适的 EARS 模板重写规格。
4. **校验** 重写后的规格是否满足以下要求：
   - 每条陈述恰好只包含一个 `shall`。
   - 使用可衡量、可验证的语言。
   - 不包含歧义黑名单词汇（参见 USDM 编写指南）。
   - EARS 关键字（WHEN、WHILE、IF、THEN、WHERE）必须全部大写。
5. **呈现** 向用户展示重写前后的对比。

### 与 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` — 典型场景的改写前 / 改写后示例