spec-kit-specify

根据自然语言描述创建功能规格说明。

输入：功能描述。如果未提供，请询问用户想要构建什么。

步骤

1. 收集功能描述

   用户随请求提供的文本就是功能描述；不要让他们重复说明。 如果缺少描述，或描述过于模糊，无法确定参与者和操作，请询问：

   “你想要定义什么功能？请描述它应该做什么，以及为什么。”

   提炼一个由 2 到 4 个单词组成的简短 kebab-case 名称，尽可能采用动词-名词形式， 保留技术术语和缩写 （例如，“添加用户身份验证” → user-auth，“修复支付处理超时” → fix-payment-timeout）。

2. 创建变更目录

   创建 specs/changes/<name>/。 每次运行只处理一个功能。

   specs/changes/ 已被 git 忽略。只有 specs/features/ 是规范且纳入版本控制的目录。

3. 阅读现行约束

   撰写前，阅读 specs/features/ 中与该功能涉及领域相关的现行规格说明，以及 specs/decisions/ 中的决策记录（如果项目将它们存放在此处），并阅读 FRAMEWORK.md（如有 FRAMEWORK.local.md，也一并阅读）。 规格说明应在现行规则的基础上编写，不得默默重述或违背这些规则。

4. 编写 specs/changes/<name>/spec.md

   结构：

   # Spec: <Feature Name>
   
   ## Problem
   <Why this feature is needed.>
   
   ## Goals
   <What success looks like, in measurable, technology-agnostic terms.>
   
   ## Non-Goals
   <What is explicitly out of scope.>
   
   ## User Stories
   - US-1: As a <role>, I want <goal> so that <benefit>. [P1]
     Independent test: <how this story alone can be demonstrated to work>
   
   ## Requirements
   ### FR-01: <one behaviour the system must have>
   - WHEN <situation> THEN <observable outcome>
   
   ## Edge Cases
   ### <a surface the change alters: a screen, a command, an endpoint, a message>
   - FR-02: on failure — WHEN <it fails> THEN <what the person or caller sees>
   - FR-03: while waiting — WHEN <it has not answered yet> THEN <...>
   - FR-04: with nothing to show — WHEN <there is no data> THEN <...>
   - FR-05: after closing and reopening — WHEN <it is dismissed and opened again> THEN <...>
   - FR-06: on a repeated or concurrent action — WHEN <it is triggered twice> THEN <...>
   - FR-07: with hostile or malformed input — WHEN <outside input arrives malformed or crafted> THEN <...>
   - <state>: cannot arise, because <reason>
   - None: the change alters no screen, command, endpoint or message, because <reason>
   
   ## Key Entities
   <Only when data is involved: each entity, what it represents, its key attributes and relationships, without implementation.>
   
   ## Success Criteria
   - SC-01: <measurable, technology-agnostic outcome>
   
   ## Assumptions
   - <informed default taken> — <why it is the safe reading>
   
   ## Open Questions
   - [NEEDS CLARIFICATION] <question> — impact: <scope|security|ux|technical>
   

   删除不适用的可选部分（例如“关键实体”），而不是填写“N/A”。

   规则：

   • 聚焦于做什么以及为什么。绝不描述如何实现或点名技术。
   • 面向业务相关方，而非开发者。
   • 遵循 FRAMEWORK.md 中的治理原则。
   • 每一项都必须带有标识符。 用户故事使用 US-n，并标注优先级（P1 最重要），且应可独立测试。 需求使用 FR-nn；成功标准使用 SC-nn。 在整个变更期间，标识符不得重复使用或重新编号，以便后续文档引用。
   • 每项需求只描述一种行为。 每项需求都应说明一种行为，并至少包含一个符合 specs/features/ 格式的 WHEN/THEN 场景。 将复合需求拆分开来，以便明确显示哪些部分尚未满足。
   • 变更影响的每个界面都必须在 ## Edge Cases 下定义其状态： 故障、等待、无内容可显示、关闭后重新打开，以及重复或并发操作。 每种已决定的状态都应单独作为一项需求，并附带场景；也可以用一行说明该状态为何不会出现。 接收来自人员、其他 Agent 或其他系统的输入的界面，也必须以相同方式定义其对恶意或格式错误输入的处理状态。 如果变更不影响任何界面，应在此处说明，并解释原因。
   • 边缘情况的默认处理方式是沿用现行规则。 引用已有明确规定该情况的现行规格说明或决策记录。 若现有规则未涵盖某种状态，且没有合理的默认处理方式，则将其列为待解决问题，而不是自行设计。
   • 为未明确的细节设定有依据的默认值，并结合上下文和惯例，在“假设”部分记录每项默认值及其安全依据。 已确定的默认值属于需求；其理由属于假设。 对已有合理默认值的细节（数据保留、常规错误处理、一般性能预期），不要提问。
   • 成功标准必须可衡量、不依赖具体技术、以用户为中心，并且无需了解实现即可验证。 “用户在 3 分钟内完成结账”是一个标准；“API 在 200 毫秒内响应”或“缓存命中率超过 80%”则属于实现细节。
   • 最多使用 3 个 [NEEDS CLARIFICATION] 标记，且仅限于会显著改变范围或用户体验、存在多种合理解读且没有默认值的情况。 按范围 > 安全与隐私 > 用户体验 > 技术的优先顺序处理。其余情况应作出有依据的推断。
   • 不要在规格说明中嵌入检查清单。

5. 根据质量检查清单验证规格说明 写入 specs/changes/<name>/checklists/requirements.md：

   # Specification Quality Checklist: <Feature Name>
   
   **Purpose**: Validate the specification before planning.
   **Feature**: [spec.md](../spec.md)
   
   ## Content Quality
   - [ ] No implementation details (languages, frameworks, APIs)
   - [ ] Focused on user value and business needs
   - [ ] Written for non-technical stakeholders
   - [ ] All mandatory sections completed
   
   ## Requirement Completeness
   - [ ] No [NEEDS CLARIFICATION] markers remain
   - [ ] Every story, requirement and success criterion carries its identifier
   - [ ] Every requirement states one behaviour and has a WHEN/THEN scenario
   - [ ] Requirements are testable and unambiguous
   - [ ] Success criteria are measurable and technology-agnostic
   - [ ] Every surface the change alters has its edge-case states decided
   - [ ] Scope is clearly bounded
   - [ ] Dependencies and assumptions are identified
   
   ## Feature Readiness
   - [ ] Every user story has an independent test
   - [ ] User stories cover the primary flows
   - [ ] No implementation details leak into the specification
   

   对照每一项审查规范，仅勾选通过的项目；对每一项未通过的项目，引用规范中的对应章节。 除未决问题外，修正规范中每一项未通过的内容，并重新验证，最多重复三次。 如果第三次迭代后仍有未通过的项目，请在清单下方注明剩余问题，并告知用户。 此清单由此技能和 spec-kit-clarify 维护；由 spec-kit-checklist 编写的清单归审查者所有。

输出

写好规范后，请总结：

• 变更名称和文件位置。
• 按标识符统计的用户故事、需求和成功标准。
• 清单结果：通过项数／总项数，以及仍未通过的项目（如有）。
• 未决问题的数量（如有）。
• 下一步：“使用 spec-kit-clarify 技能解决未决问题；如果规范已明确，则使用 spec-kit-plan 技能。”

注意事项

• 如果已存在同名变更，请询问用户是要继续处理该变更，还是创建一个新的变更。
• 规范中不得包含 HOW——不得涉及技术栈、框架或实现细节。
• 优先做出合理假设，而不是提出不必要的问题。
• 如果与现行规范或决策记录相矛盾，切勿隐瞒；应将其作为未决问题提出。