write-requirements

根据已批准的头脑风暴结果，生成 docs/specs/<YYYY-MM-DD>-<feature>/requirements.md。需求是持久的意图来源：它们会在本次对话结束后继续保留，每项任务、测试和提交都会引用其 ID。

两种模式——根据你接到的工作选择

Tier-1 迷你规格说明——针对已批准功能的修复加防护（你是从 amend 或 debug 流程转来的）。你不是在编写新的 requirements.md。将以下内容追加到所属功能的 requirements.md（如果没有所属功能，则追加到 docs/specs/fixes.md）：

• 修复需求——使用 EARS 标准中的一条准则（第 2 步的形式）描述修正后的行为；
• 对应的 SHALL CONTINUE TO 防护——使用第 3 步，描述修复不得破坏的行为。

然后只对这两条准则进行自我审查：执行歧义和可测试性检查；仅当准则断言系统当前如何运作时，才执行代码断言检查（第 5 步）——防护通常属于这种情况。提交这两条追加的准则供审批，保留功能的 Status，然后转到 tdd。跳过第 1 步和第 4 步，也跳过整份文件审查——新功能代码、Out-of-Scope 部分和完整文件自我审查适用于新功能，不适用于只有两行的迷你规格说明。

新功能——Tier 2，或尚无规格说明的任何功能。从技能集中的 templates/requirements.md 开始——作为插件安装时，将 templates/ 解析为 ${CLAUDE_PLUGIN_ROOT}/templates；否则，相对于此 SKILL.md 使用 ../../../templates。模板中的每个标题都是必填项：填写内容，或在其下写入 None——绝不能删除标题。然后执行以下完整流程。为每一步创建一个待办事项。

第 1 步：注册功能代码

选择一个简短且唯一的前缀（2–12 个字符，仅限 A–Z 和数字 0–9，以字母开头，例如 SHELL、SYNC2）。检查 docs/specs/INDEX.md；在编写需求之前先添加一行。绝不复用已退役的代码。

关联路线图条目。 如果存在 docs/roadmap/INDEX.md，且此项工作实现了其中的某个条目，则在该行的 Roadmap item 列中记录该条目的 ROAD-N。如果没有路线图，或此项工作从未作为条目列入计划，则填写 —，其余照常注册。此列是计划与规格说明之间唯一的关联，且只有这一步可以填写——此处绝不编造 ROAD-N，只能引用已有条目。 完成条件： 代码已在 INDEX.md 中占一行，状态为 Draft，且 Roadmap item 单元格填写了 ROAD-N 或 —。

第 2 步：编写用户故事和 EARS 准则

每个用户故事单独使用一个 ## N. <title> 小节，每个小节都包含采用 EARS 句式的验收准则，并带有分层 ID **CODE-N.M**——N 是故事编号（与 ## N 标题中的 N 相同）。此标识至关重要：后续技能会据此推导审查单元。

每个行为故事都包含：

**Story:** As a <actor>, I want <capability>, so that <benefit>.

**Story:** 行必须描述一个人可以在故事落地后执行或验证的单一、可演示操作——而非技术层面的内容（例如“重写存储层”）。

EARS 句式：

• WHEN <event> THE SYSTEM SHALL <behavior>——事件驱动
• WHILE <state> THE SYSTEM SHALL <behavior>——状态驱动
• IF <unwanted condition> THEN THE SYSTEM SHALL <behavior>——错误处理
• WHERE <feature enabled> THE SYSTEM SHALL <behavior>——可选功能
• THE SYSTEM SHALL <behavior>——始终成立的不变量

每条准则只描述一种可观察行为。如果一句话中需要使用“和”，通常就应该拆成两条准则。准则数量没有上限——后续可在计划／执行前置检查时，通过任务文件路径看出规模，而不是通过统计 EARS 行数。 完成条件： 每个故事至少有一条准则；每条准则恰好采用一种 WHEN／WHILE／IF／WHERE／通用形式；每条 **Story:** 都描述一个可演示操作。

步骤 2b：非功能性需求（质量属性）

行为标准（步骤 2）说明系统做什么；非功能性需求（NFR）说明系统必须做得多好——未明确说明的质量属性，往往会让功能悄然失效。完成行为标准后，填写模板中的 NFR 部分（已预先印在 templates/requirements.md 中）：

## <N>. Quality attributes
**Section-kind:** nfr

SECTION-KIND IRON LAW
- NFR section MUST carry **Section-kind:** nfr (pre-printed in the template —
  do not delete it).
- absent = story  (unmarked section is a behavioral review unit)
- Fail visible: unmarked NFR → extra unit in preflight.
- Fail silent (forbidden): marking a real story nfr → boundary disappears.

逐一检查以下四项质量属性：

• 性能 — 延迟、吞吐量、资源上限。
• 安全性 — 身份验证／授权、数据保护、跨越的信任边界。
• 可靠性 — 可用性、错误预算、恢复能力、持久性。
• 无障碍性 — 符合目标（例如 WCAG 2.1 AA）、键盘和屏幕阅读器支持。

将每项适用属性写成 EARS 标准（步骤 2 中的形式），并注明一个可衡量或可检查的目标及其验证方法，同时使用层级式 **CODE-N.M** ID，使其能够像行为标准一样贯穿任务和测试进行追踪。例如：

• **CODE-3.1** WHEN the notes list renders 1,000 items THE SYSTEM SHALL paint the first screen within 200 ms at p95 — verified by a CI performance trace.

不适用的属性不得默默省略：应记录为 None 并简要说明原因（例如“无障碍性：None — 无头 CLI”），让跳过成为明确的决定，而不是疏忽。

此类别是附加项，绝不构成新门槛：没有质量属性方面顾虑的功能，应对四项属性全部记录 None，其行为标准、结构和两种编写模式保持不变——NFR 用于呈现质量方面的顾虑，不会以此设卡。在 tier-1 迷你规格模式中，只有当修复本身属于质量属性变更时，才记录 NFR；此类别不会为行为迷你规格增加 NFR 义务。 完成条件： NFR 部分包含 **Section-kind:** nfr，且四项质量属性均为带 ID 的 NFR 标准，或明确标记为 None。

步骤 3：保护现有行为

列出变更涉及的每个文件，然后逐一处理。对于不存在现有行为风险的文件，只添加一行明确的 no behavior to guard，不做其他处理；对于其余文件中的每项现有行为，都添加一条保护标准 — **CODE-N.M** (guard) WHEN <condition> THE SYSTEM SHALL CONTINUE TO <existing behavior>。保护标准可防止 Agent 破坏无人提及但至关重要的行为。对于 tier-1 错误修复，此步骤加上一条修复需求即构成规格，并附加到“两种模式”中指定的目标位置。 完成条件： 变更涉及的每个文件都已列出；这些文件中发现的每项现有行为都有各自的保护需求；每个没有现有行为的文件都包含明确的 no behavior to guard 行。没有列表支撑的空保护集不算完成。

步骤 4：范围之外

列出此功能明确不会做什么。本节用于防止实现在实施和评审过程中出现范围蔓延。

步骤 5：自我审查，然后进入审批关卡

向用户展示前先进行自我审查：

• 歧义检查： 是否有任何标准可能被作两种不同的解读？选定一种解读并写清楚。
• 可测试性检查： 每项标准都能通过自动化测试或具体的手动检查进行验证吗？改写任何无法验证的标准。
• 占位内容检查： 不得出现“TBD”“等等”“适当处理错误”等内容。
• 代码声明检查（独立进行）： 如果任何标准声称系统当前的工作方式——例如数据格式、现有行为或限制——请派遣一个审查子 Agent，根据实际代码核实每项此类声明（搜索/阅读文件，引用 file:line，标记任何不成立的内容），并将发现写入 .skills/<slug>-req-review.md。错误的前提——例如“正文是 ProseMirror-JSON”，而实际是 Markdown——会污染设计、计划和代码。在进入审批关卡前修正标准；不要亲自阅读代码。（没有子 Agent？请自行根据代码进行检查。）

故事质量关卡（以可演示行为为依据）。 流程：

1. 列出每个非 NFR 的 ## N 及其 **Story:** 行。
2. 请用户确认每项都描述了一个可演示的行为。
3. 如果有任何一项不符合 → 拆分/改写后重新展示。如果全部确认 → 用户批准文件后，可以将 Status: Approved 设为已批准。
4. 切勿默默批准。仅说“看起来没问题”而没有逐项确认，不算确认。

然后将文件展示给用户审阅并停止。不要仅凭对话中的共识就继续设计——获得批准的是书面需求。获得批准（包括故事质量确认）后，将 Status: Approved 设为已批准。 完成条件： 用户已批准书面文件，并确认每个行为型故事都描述了一个可演示的行为。

ID 不可变性

状态设为已批准后，ID 的含义不得改变，也不得重新编号。 退役某项需求时，将其划掉（~~**CODE-1.2**~~ superseded by CODE-1.4）。trace 检查会将划掉的 ID 视为未定义，因此引用它的测试/任务会立即显现问题。

退出

必需的子技能：使用 write-design（第 2 级），或将第 1 级修复项连同新的 ID 直接交给 tdd。