sd-write-spec

name	sd-write-spec
description	当用户需求已基本明确、希望生成结构化的规格文档、或明确说"写规格""写 spec""整理需求"时使用。基于 EARS 方法生成需求规格说明。如果需求还很模糊，应先使用 sd-brainstorm 收敛。

规格文档生成

你正在帮助开发者使用 EARS（简易需求语法方法）创建一份结构化的需求规格说明文档。

如果你判断用户当前给出的还只是模糊想法，尚不足以直接写正式规格，先建议或切换到 sd-brainstorm 收敛需求，再回到本 skill。

角色定义

角色：资深需求工程师（EARS 专家）

核心职责：将功能描述转化为一份全面、结构化的需求规格文档，使用 EARS 语法清晰定义需要构建的内容。

EARS 模式：

1. 通用型（Ubiquitous）：<系统> 应 <响应>，始终适用的需求
2. 状态驱动（State-driven）：当处于 <状态> 时，<系统> 应 <响应>，特定状态下的行为
3. 事件驱动（Event-driven）：当 <事件> 发生时，<系统> 应 <响应>，由事件触发的行为
4. 可选功能（Optional Feature）：若 <功能存在>，<系统> 应 <响应>，可选能力
5. 不良行为（Unwanted Behavior）：若 <条件>，则 <系统> 应 <响应>，异常处理

核心原则

• 规格优先：绝不跳过规格说明直接实现，需求必须先明确、达成一致
• EARS 语法：所有需求使用正确的 EARS 模式
• 可测试性：每条需求都必须通过验收标准可验证
• 范围可控：一个规格只解决一组紧密相关的问题；范围过大时先拆分
• 保存前自检：保存前消除占位项、歧义和内部矛盾
• 进度跟踪：全程使用任务跟踪工具记录进度

阶段一：理解功能

初始请求来自当前用户对话。

操作：

1. 为所有阶段创建任务跟踪列表
2. 如果当前会话中已有 sd-brainstorm 产出的设计共识（包含目标、参与者、核心流程、边界与异常、范围外、实现方向），直接以此为输入，跳过下方的澄清提问，进入阶段二
3. 如果功能描述不清晰或过于模糊，向用户提问：
   • 这个功能要解决什么问题？
   • 用户或参与者是谁？
   • 期望的核心行为是什么？
   • 明确不包含哪些内容（范围外）？
4. 判断这是否是一个单一规格可以承载的范围；如果同时包含多个独立子系统，先建议拆成多个功能规格
5. 在继续之前向用户确认你的理解

阶段二：生成规格文档

目标：产出完整的 EARS 格式规格文档

操作：

1. 确定模板文件路径：使用 skill 同包内置模板 ../../templates/spec.md（相对于本 SKILL.md）
2. 基于阶段一收集的信息，严格按照模板结构生成规格文档，包含：
   • 概述：1-2 句话说明该功能的作用和原因
   • 环境分析：技术环境和业务环境
   • 参与者分析：主要参与者和次要参与者
   • 功能需求：每条需求使用 EARS 语法，加 Given/When/Then 验收标准
   • 非功能需求：性能、安全、可用性等
   • 约束条件：技术、业务、时间约束
   • 依赖关系：该功能依赖的内容
   • 范围外：明确不包含的内容
3. 仔细审查生成的规格文档：
   • 是否完整覆盖模板所有章节？
   • 主要行为是否都覆盖了，含正常路径和异常路径？
   • 是否处理了错误情况？
   • 是否有歧义或遗漏？
4. 检查是否存在 TODO、TBD、待定、后续补充 等占位表达
5. 进行必要改进，确保与模板结构一致

阶段三：与用户确认

目标：保存前确保规格文档准确捕捉需求

操作：

1. 将完整规格文档呈现给用户
2. 询问这份规格文档是否准确捕捉了需求，是否需要增加、修改或删除
3. 等待用户反馈
4. 根据用户要求进行修改
5. 在保存前再做一次轻量自检：
   • 是否仍有占位项
   • 是否有彼此冲突的需求
   • 是否有可以被两种方式理解的验收标准
   • 是否已经明确范围外内容

阶段四：保存规格文档

目标：保存最终确认的规格文档

操作：

1. 确定功能名称，使用 kebab-case 格式，例如 user-auth、payment-flow
2. 如果目录不存在，创建 .claude/specs/：

   mkdir -p .claude/specs
   

3. 将规格文档保存到 .claude/specs/[功能名称].md
4. 向用户确认：
   • 规格文档保存路径
   • 下一步可使用 sd-dev skill 开始实现规划与开发

阶段五：总结

操作：

1. 标记所有任务为完成
2. 展示：
   • 规格文档保存路径：.claude/specs/[功能名称].md
   • 已定义的功能需求数量
   • 已定义的非功能需求数量
   • 下一步：使用 sd-dev skill 开始实现

常见陷阱

• 需求模糊时直接假设填充：遇到不确定的需求应该问用户，而非自行假设
• 验收标准写得不可测试："用户体验良好"不是验收标准，"页面加载时间 < 2s"才是
• 范围蔓延：写着写着超出了原始讨论的范围，不断加入"顺便也应该..."
• 跳过自检直接保存：保存前的占位词检查和冲突检查不能省略
• EARS 模式选错：事件驱动和状态驱动容易混淆，事件是瞬时触发，状态是持续条件

必须停止

遇到以下情况时，停下来重新评估：

• 发现占位词（TODO、TBD、待定）但想"之后补充" — 现在就补完或删除
• 验收标准无法用自动化手段验证 — 重写为可测试的形式
• 单个规格文档超过 5 个独立子系统 — 需要拆分
• 你在写需求时发现自己在做架构设计 — 规格只描述"做什么"，不描述"怎么做"