simple-spec-builder

适用场景

在以下情况下使用此技能：

• 用户描述了一项通用功能，并要求将其转换为正式的用户故事。
• 需要将一个想法转化为结构化且直观呈现的敏捷需求。
• 需要直观地映射完整的用户体验（用户故事地图）。
• 用户故事过于庞大（史诗故事），需要使用高级拆分技术进行拆分。
• 现有用户故事缺少可衡量的验收标准，或需要采用 Gherkin 格式进行结构化。
• 存在技术或功能上的不确定性，需要开展 Spike、编写独立的技术故事，或构建功能性 Walking Skeleton。
• 不清楚某项功能能为业务或客户带来怎样的实际价值。

---

每个工单的增强规格

对于此仓库中已在磁盘上记录垂直切片的工作：

产物	位置
索引和执行顺序	.tasks/<PBI-or-other-id>/index-spec.md
每个故事／切片一个文件	.tasks/<id>/spec-<NN>-<kebab-name>.md
决策	.tasks/<id>/open-questions.md
解决方案图表	.tasks/<id>/solution-diagrams.md

规格格式的官方团队模板位于 templates/enriched-template.md。 解决方案图表的官方模板位于 templates/solution-diagrams.md。

open-questions.md 文档 — 必须生成

生成时机： 如果在拆分和生成规格（spec-*.md）期间发现阻塞项、歧义或功能／技术不一致，必须生成 open-questions.md 文件。这不是可选产物：只要存在至少一项尚未解决或有争议的问题，就必须立即创建并填写该文档。

更新规则： 用户只需通过标记 [x]（或填写 Other:）来表明选择。用户标记选项后，Agent 必须自动解析这些选择，在相应规格中体现变更，并在标题为 ## Summary (Only for Agent, do not edit this table manually) 的最终摘要表中填写决策。用户不得手动编辑此表。

该文档的完整结构、格式规则和实际示例位于 templates/open-questions.md。

solution-diagrams.md 文档 — 必须生成

生成时机： 必须生成 solution-diagrams.md 文件，用于记录指定解决方案的技术设计和可视化图表。

必须立即创建此文件，并包含：

1. 一份时序图，详细说明组件、参与者和系统之间的交互与调用流程。
2. 一份类图，概述解决方案的静态结构、关系、属性和方法。
3. 一个额外图表占位部分，帮助理解解决方案的其他方面（例如状态图、数据流或组件架构）。

该文档的模板和完整结构位于 templates/solution-diagrams.md。

---

项目背景

方面	详情
用户故事格式	As a [user role], I want [goal], so that [benefit]
验收标准	BDD 格式 / Gherkin 语言（Given / When / Then）
质量框架	INVEST 模型、SMART 标准、待完成工作（JTBD）
规划方法	用户故事地图（Jeff Patton），成果 > 产出

与此技能相关的架构： 用户故事必须代表功能性的纵向切片。在大型项目和史诗中，第一个切片必须构成一个功能性行走骨架，端到端贯穿整个系统，以便尽早验证技术风险。

---

关键模式

A. 持续分析与共情

• 模式 1：从 3C 扩展到 5C。 确保不要停留在 卡片、对话、确认；用户故事必须通过扩展到 构建 和 后果 来规划成功。添加指标，以了解已实现的功能是否真正带来了预期收益。
• 模式 2：防止“踢过墙”反模式。 绝不能编写并假设这只是产品负责人的孤立工作；要让用户参与提问循环。用户故事始终是开启对话的邀请。
• 模式 3：聚焦用户角色和待完成工作（JTBD）。 不要再使用笼统的“用户”角色。为角色字段创建并使用详细的虚构原型，体现对其人口统计特征和动机的共情。聚焦客户需要解决的根本任务或问题（JTBD）。
• 模式 4：以共同理解优先于文档（“沟通并记录”）。 用户故事的真正目标不是编写完美的文档，而是通过持续对话建立共同理解。写下对话内容以便回忆，而不是取代对话。

B. 需求组织与质量

• 模式 5：严格区分用例。 不要让用户故事变成用例；聚焦用户需要的“是什么”，将“如何实现”及系统交互留给图表等其他文档。
• 模式 6：技术用户故事与 Spike。 编写纯技术用户故事（例如基础设施或重构）时，不必强行套用“As a [role]”格式。如果存在较高的不确定性，应先创建一个技术 Spike，通过限时探索评估可行性。
• 模式 7：分离 NFR。 绝不要将性能、可扩展性、无障碍性或安全性视为简单的验收标准；应将其作为对系统质量施加约束的非功能性需求（NFR）单独列出。
• 模式 8：遵循“完成定义”（DoD）。 验收标准用于验证具体的功能需求；绝不要将通用质量任务（单元测试、代码审查）列入其中，因为这些属于项目强制要求的 DoD。
• 模式 9：针对 IA 采用规划-验证-执行流程。 对于复杂需求，先在验证文件中生成结构化计划或大纲，提交给用户审批，然后再用 Gherkin 撰写最终内容。

C. 编写验收标准

• 模式 10：SMART 质量。 将每项标准设计为具体（Specific）、可衡量（Measurable）、可实现（Achievable）、相关（Relevant）且有时限（Time-bound）。好的标准始终可以通过二元方式验证。
• 模式 11：通用 BDD/Gherkin 语言。 严格应用基本组成部分：Given（上下文）、When（触发事件）和 Then（预期结果）。
• 模式 12：先处理顺利流程，再处理异常流程。 假设环境理想，先设计主要场景。之后，有意通过错误或替代路径打破该场景。
• 模式 13：拆分复杂标准。 如果一项标准串联了过多条件（“GIVEN a AND b WHEN c THEN d AND e”），必须将其拆分为多项独立标准。
• 模式 14：三方协作规则。 在头脑中模拟并确保标准涵盖三大支柱之间的一致性：业务（PO）、开发（IT）以及设计/QA 边缘情况。

D. 高级用户故事拆分（Epic 的垂直切片策略）

• 模式 15：按工作流步骤拆分（策略 1）。 将流程的起始和结束部分分离出来，作为 MVP；中间步骤则留待后续。
• 模式 16：按业务规则拆分（策略 2）。 首先放宽操作限制，之后再通过后续用户故事加入严格规则（法律规则、拒绝情形）。
• 模式 17：按输入选项/平台拆分（策略 4）。 根据界面（App 或 Web）或数据输入方式，分别创建用户故事。
• 模式 18：按数据类型拆分（策略 5）。 提取参数复杂度，将需求分开（例如，简单搜索与高级筛选）。
• 模式 19：按 CRUD 操作拆分（策略 6）。 避免使用动词“Manage”；将其拆分为创建、读取、更新和删除。
• 模式 20：按测试场景拆分（策略 7）。 将异常流程和复杂边缘情况从父需求中分离出来，创建独立的用户故事。
• 模式 21：按角色拆分（策略 8）。 如果结果对普通客户、VIP 或管理员的影响方式不同，就将目标拆分为多个用户故事。
• 模式 22：稍后再优化（策略 9）。 贯彻“先让它运行起来”，保留基础功能，将重大的性能改进推迟到未来的用户故事中。
• 模式 23：技术兼容性（策略 10）。 将初期开发集中在主流浏览器或技术上，确保交付价值。
• 模式 24：“好—更好—最佳”拆分。 为避免陷入停滞，先定义“目前够用”的用户故事（好），再提取能让体验“更好”的用户故事（更好），最后处理“最佳”方案。

E. 用户故事地图（可视化产品规划）

• 模式 25：成果优先于产出。 你的任务不是构建更多软件，而是最大化解决方案的影响力。优先考虑业务成果，而非功能。
• 模式 26：先广后深（宽一英里，深一英寸）。 绘制地图时，不要陷入细节。先构建“主干”，按照从左到右的叙事流程对高层级活动进行分组，然后再从上到下深入细节。
• 模式 27：战略性切片（MVP）。 在用户故事地图上画出水平线，剔除所有非必要内容，并将第一层切片中的用户故事组合起来，形成可用的 MVP。
• 模式 28：功能性行走骨架。 切片时，不要按技术层拆分。创建一个端到端的功能性行走骨架作为第一层切片，以便立即发现技术风险。

F. 估算与经济价值评估工具

• 模式 29：MoSCoW 矩阵。 帮助用户将需求标记为必须有（Must have）、应该有（Should have）、可以有（Could have）和不会有（Won't have），以提供背景信息。
• 模式 30：实际价值计算（ROI / WSJF）。 应用 WSJF 优先级排序（延迟成本 / 规模），鼓励根据经验性经济效益进行衡量。

---

高级决策树

Agent 必须判断请求是针对特定内容的撰写／优化，还是完整的产品映射。

流程 1：分析、撰写和拆分（故事／史诗）

1. 用户提供的需求是否缺少明确的角色、实证价值或「原因」背景？
   • 是：停止。提出问题以构建「用户角色」，并使用 Jobs-to-be-Done 理解需求。应用 模式 9。
   • 否：继续执行步骤 2。
2. 这是面向客户的需求（功能性），还是系统技术需求？
   • 技术性：应用 模式 6（不采用「作为用户」格式的技术故事／Spike）。
   • 功能性：继续执行步骤 3。
3. 请求是否涉及含义模糊的「管理」一词，或涵盖一个庞大的流程（史诗）？
   • 是：评估是否按 CRUD（模式 19）、输入选项（模式 17） 或 好－更好－最好（模式 24） 进行拆分。提出 2 或 3 种拆分策略。
   • 否：继续执行步骤 4。
4. 验收标准（AC）是否只涵盖顺利场景？
   • 是：中断。应用 模式 12，要求定义 异常流程。如果风险很高，使用 模式 20 拆分。
   • 否：继续执行步骤 5。
5. 验收标准是否包含过多验证，或包含「快速加载」之类的要求？
   • 是：优化并应用 模式 13 拆分冗长的标准。应用 模式 7 和 8，将全局约束（NFR）与 DoD 分开。
   • 否：继续按 BDD/Gherkin 语法编写结构。
6. 在生成或优化规格说明时，是否发现了阻塞项、歧义或不一致？
   • 是：必须生成 open-questions.md，详细列出实施前需要解决的所有问题。
   • 否：继续执行步骤 7。
7. 必须生成解决方案图：
   • 必须生成 solution-diagrams.md，其中包含解决方案流程的时序图、技术设计的类图，以及用于帮助说明开发工作的其他辅助图表空间。
8. 用户是否知道如何衡量部署后的影响？
   • 否：在讨论中加入跟踪指标（后果／模式 1）。
   • 是：生成最终的敏捷用户故事。

流程 2：用户故事映射（产品映射／可视化布局） 如果用户请求「映射」、「创建流程」或「定义 MVP」：

1. 界定问题： 是否已定义用户角色和预期结果（结果／模式 25）？
2. 映射全局（骨干）： 按时间顺序从左到右排列主要活动，定义骨干（模式 26）。
3. 深入探索（细节）： 从上到下深入探讨。询问替代方案、业务规则或数据变化。
4. 划分发布策略（MVP）： 绘制水平分割线，只关注实现主要结果所需的最低限度内容（模式 27）。
5. 划分学习策略（行走骨架）： 如果技术风险较高，建议将「功能性行走骨架」（模式 28）作为第一个切片（切片 1）。

---

示例

示例 1：标准 Gherkin 故事（顺利／异常流程）

故事： 作为一名客户，我想从 ATM 取现，以免在银行排队。 验收标准（场景 1：顺利流程）：

• Given 账户有余额且银行卡有效
• When 客户请求取现
• Then 账户扣款并发放现金。

验收标准（场景 2：异常流程）：

• Given 账户透支金额超过约定限额
• When 客户请求取现
• Then ATM 显示拒绝请求的消息。

示例 2：按 CRUD 操作拆分用户故事

请求：“作为用户，我想管理我的购物车”

• 创建： 作为购物者，我想将新书添加到购物车，以便下单。
• 读取： 作为购物者，我想查看购物车中的商品，以便了解总价。
• 更新： 作为购物者，我想修改购物车中书籍的数量。

示例 3：用户故事地图——广度（主干）与深度（细节）

主干（从左到右）： 搜索商品 -> 加入购物车 -> 付款 -> 确认发货。 “付款”下的细节（从上到下）：

• 足够好： 使用信用卡付款（MVP）。
• 更好： 使用 PayPal 付款。
• 异常流程： 如果信用卡被拒绝，则显示错误。

示例 4：切片与功能性 Walking Skeleton

Epic： 作为组织者，我想管理活动参与者。

• 切片 1（Walking Skeleton）： 手动登记参与者的姓名和邮箱，以验证数据库流程端到端正常运行。
• 切片 2（做得更好）： 通过 CSV 导入参与者名单。
• 切片 3（达到可发布状态）： 自动发送欢迎邮件。

---

资源

• 质量指南：INVEST 准则与用户故事质量
• HTML 参考模板：templates/user_story_template.md
• 解决方案图示模板：templates/solution-diagrams.md
• 地图绘制方法论：《用户故事地图》，Jeff Patton 著（概念：主干、叙事流程、成果 > 产出、切片）