specify-behavior

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

两种模式——根据你收到的内容选择

Tier-1 迷你规格——针对已批准功能的修复加防护（来自 amend-feature 或 root-cause）。这不是新建 requirements.md：将修复需求（一条 EARS 验收标准，采用步骤 2 中的形式）及其 SHALL CONTINUE TO 防护条件（步骤 3，针对修复不得破坏的行为）追加到所属功能的 requirements.md（若未归属任何功能，则追加到 docs/specs/fixes.md）。

仅自审这两条标准：检查歧义和可测试性，另外仅当某条标准声称系统当前的工作方式时，才执行代码声明核查（步骤 5）——防护条件通常会涉及这类声明。将两条标准都提交审批，保留功能的 Status，然后进入 test-first。跳过步骤 1 和 4，以及整份文件的审查——这些适用于新功能，而不是只有两行的迷你规格。

新功能——tier 2，或尚无任何规格的功能。从 templates/requirements.md 开始，按顺序解析种子包路径，使用第一个存在的路径：与此 SKILL.md 同目录的 templates/；否则，若已设置 ${CLAUDE_PLUGIN_ROOT}，则使用 ${CLAUDE_PLUGIN_ROOT}/templates；否则，使用相对于此 SKILL.md 的 ../../../templates。该模板中的每个标题都是必填项：填写内容，或写 None——绝不可删去任何标题。然后按以下完整流程逐步执行，每步对应一个待办事项。

步骤 1：注册功能代码

选择一个简短且唯一的前缀（2–12 个字符，仅限 A–Z0–9，以字母开头，例如 SHELL、SYNC2）。目录为共享目录：docs/specs/INDEX.md 是领域路由表；功能卡片位于 docs/specs/catalog/<domain>.md。在编写需求前，先在所属分片中添加一行卡片（确保该领域已有路由表行）。切勿在 INDEX 本身添加代码行；切勿重用已退役的代码。若 INDEX 采用扁平结构，则停止并指出 /map-features 领域边界迁移。

绑定路线图条目。 如果存在 docs/roadmap/INDEX.md，请阅读此文件旁的 roadmap-bind.md 并严格遵循其中要求——分片行的 Roadmap item 列是计划与规格之间唯一的关联方式。如果没有路线图，或这项工作从未列入路线图，则填写 —。

提升临时目录。 如果这项工作使用了 .skills/_pending-<slug>/ 目录，请将其移至 .skills/<CODE>/（若 CODE 目录不存在，则使用 mv），以便后续写入使用功能根目录——参见 templates/skills-ephemera-paths.md。 完成条件： 所属分片中已有该代码的 Draft 卡片，其 Roadmap item 单元格填写 ROAD-N 或 —，且该 ROAD 尚未绑定到其他 CODE。

步骤 2：编写故事和 EARS 标准

每个用户故事对应一个 ## N. <title> 章节，并包含带层级 ID **CODE-N.M** 的 EARS 验收标准——N 是故事编号（与 ## N 标题中的 N 相同）。这个标识至关重要：后续技能会据此推导评审单元。

每个行为故事都包含一行 **Story:**：As a <actor>, I want <capability>, so that <benefit>. 该行必须写明一项可演示的行为，即故事完成后，某人可以执行或通过证明来验证的行为——而不是技术层面的事项（“重写存储层”）。

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> — 始终成立的不变量

每条标准只描述一种可观察行为。如果一句话需要用到“and”，通常就应该拆成两条标准。针对多个输入应用同一规则（字段列表、一组默认值）的情况，应使用一条标准列出所有输入，而不是每个输入单独写一条标准——下游会为每个输入生成单独测试。标准数量没有上限——规模会在计划/执行前置检查中通过任务文件路径体现，而不是通过计算 EARS 行数体现。 **完成条件：**每个故事至少有 1 条标准，每条标准恰好采用一种 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）、键盘/屏幕阅读器支持。

用于 NFR 依据的系统文档（简要查阅）

当某项属性与此功能相关（且未计划标记为 None）时，请阅读此文件旁的 nfr-grounding.md 并严格遵循其中要求——每项属性应查阅的系统文档、优先级高于这些文档的硬性约束，以及查阅后的编写规则。不得在没有已批准文档中的加粗定义时，编造 TB/THR/CMP/SLO（或产品指标）ID。

不适用的属性不得默默省略：应将其记录为 None 并附上简短原因（例如“无障碍性：None — 无头 CLI”），让跳过该属性成为明确决定，而不是疏漏。None 适用于不相关的属性，不得在属性相关时用作跳过查阅的捷径。

该类别是增补项，绝不是新的门槛：对于没有质量属性问题的功能，应将四项属性全部记录为 None。在 tier-1 模式下，仅当修复本身属于质量属性变更时才记录 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 破坏无人提及但至关重要的行为。对于 1 级 Bug 修复，本步骤加上一条修复要求就是完整规范，应追加到 Two modes 下指定的目标文件。 **完成条件：**列出了变更涉及的每个文件；这些文件中发现的每项现有行为都有各自的保护要求；没有现有行为的文件都明确写有 no behavior to guard。没有文件清单支撑的空保护要求集不算完成。

第 4 步：范围之外

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

第 5 步：自审，然后通过审批关卡

在向用户展示之前进行自审：

• **歧义扫描：**是否有任何标准可能被解读为两种不同的意思？选定一种解读并写明。
• **可测试性扫描：**每项标准是否都能通过自动化测试或具体的手动检查验证？重写无法验证的标准。
• 占位符扫描：不得出现孤立的 “TBD”、“etc.”、“handle errors appropriately”。当澄清决策的收尾材料包列出了 Owned unknowns 时，将其原样复制到 Open Questions，格式为 topic — owner — date — forbid-guess（禁止猜测）。缺少上述三个字段的孤立 TBD 会阻止设置 Status: Approved——不要通过掩盖未知项来删除 Open Questions。
• **代码主张检查（独立）：**如果任何标准断言了系统当前的工作方式，请阅读此文件旁的 self-review-conditional.md 并严格遵循其中的要求——在审批关卡之前派遣审查子 Agent，根据实际代码验证该主张；错误的前提会污染设计、计划和代码。
• **收尾材料包导入：**当存在澄清决策的收尾材料包时，请阅读此文件旁的 self-review-conditional.md 并严格遵循其中的要求——如果收尾材料包已经确定某项 NFR，就不要以此为由将其标记为 None。

用户故事质量关卡（可演示行为的使用者）。列出每个非 NFR 的 ## N 及其 **Story:** 行，并让用户确认每条是否只描述了一个可演示行为；拆分或重写未通过的条目并重新提交。只有在全部确认且用户批准文件后，才能设置 Status: Approved。不得静默批准——用户未逐条确认每个用户故事时，仅回复“看起来不错”不算确认。

然后将文件交给用户审阅并停止——不要仅凭对话中的共识继续进行设计；获得批准的应是书面需求。 **完成条件：**用户已批准书面文件，并确认每个行为型用户故事都只包含一个可演示行为。

ID 不可变性

批准后，ID 的含义永不改变，也不得重新编号。废弃某项 ID 时，使用删除线标记它 （~~**CODE-1.2**~~ superseded by CODE-1.4）——audit-trace 会将加删除线的 ID 视为未定义，因此引用这些 ID 的测试/任务会立即显现出来。

退出

必需的子技能：使用 design-solution（2 级），或将 1 级修复直接交给 test-first，并附上新 ID。