spec-shaping

规格梳理

将产品构想转化为范围明确的规格说明和可执行的冲刺计划。此技能支持两种互补模式：

1. 访谈模式：深入探索问题空间，直到形成清晰、精简的规格说明
2. 冲刺拆分模式：将规格说明拆分为原子任务和可演示的冲刺

使用时机

• 用户有一个需要明确范围的粗略产品计划或构想
• 用户需要帮助梳理实现细节、UI/UX 或权衡取舍
• 用户已有规格说明，需要将其拆分为冲刺和任务
• 用户想在构建之前验证问题是否界定得当

文档管理

将规格说明和冲刺计划视为持续演进的文档。采用以下标准，确保内容一致且始终保持最新。

1. 文件操作（搜索、位置、更新）

• 先搜索：创建新文件前，先搜索此项目中是否已有规格说明。
• 更新还是新建：
  • 更新：如果项目的“身份”相同（核心问题相同，只是在完善或调整实现方式），则更新现有规格说明。
    • 操作：将文件重命名为今天的日期，并更新元数据。
  • 新建：如果问题定义发生了根本变化，或解决方案方向完全推倒重来，则创建一份新规格说明。
• 输出位置（自适应）：
  1. 扫描以下目录：specs/、planning/、docs/specs/、product/。
  2. 如果找到：使用该目录。
  3. 默认：创建并使用 specs/。
  4. 知识库：如果是外部知识库，请检查 agents.md/claude.md 中是否有覆盖设置。

2. 文件标准（命名、元数据、内容）

• 命名：[语义名称] - [YYYY-MM-DD].md
  • 规格说明：Checkout flow spec - 2024-03-25.md
  • 冲刺计划：Checkout flow sprints - 2024-03-25.md
• Frontmatter：

  ---
  status: [Planned | In Progress | Completed]
  last: [YYYY-MM-DD]
  ---
  

• 上下文标题（必需）：

  > [!NOTE] > **Context**: [Why was this updated? e.g. "Pivot to V2"] > _This document reflects the product thinking at the time of the last update._
  

• 变更日志：在文档末尾保留 ## Changelog。如果缺少，则初始化。仅记录重大变更（例如范围调整）。忽略细微修改。

---

访谈模式

阅读计划文件，并就技术实现、UI 和 UX、顾虑、权衡取舍等方面与用户进行深入访谈。确保问题并非显而易见。

访谈原则

1. 先收窄，再扩展：持续收窄问题范围，直到能用一句清晰的话描述问题。模糊的范围（“构建一个日历”）会导致无休止的梳理。精确的范围（“显示现有事件之间的空闲时段”）才能促成切实可行的解决方案。
2. 及早揭示复杂性：询问“这件事可能有哪些听起来不难、实际却很棘手的地方？”以及“有哪些隐藏依赖项？”目标是在构建过程中途，而非事后，发现可能带来严重问题的隐患。
3. 区分理解问题与寻求论证：留意一种反模式：有人已经决定要构建什么，只是在寻找数据为其背书。在讨论解决方案之前，先问清楚这个问题为何重要。
4. 探究相邻用户：如果这是面向用户的功能，要询问下一个用户是谁——也就是当前目标用户之外最接近的那类用户。他们需要哪些不同的设计？

访谈流程

深入访谈。持续提问，直到确信问题界定得当且关键风险已揭示，然后将规格说明写入文件。

好的规格说明应当易于梳理——任何人读完后，都应能将解决方案描述为不超过 9 个主要组成部分。如果做不到，说明问题范围还不够精简。

---

冲刺拆分模式

阅读规格说明文件，并将项目拆分为冲刺和任务。

核心原则

1. 原子化任务：每项任务都应是一个原子化、可提交的工作单元，能够独立完成、审查和合并。
2. 清晰组合：小型原子化任务应组合成一个明确的迭代目标。如果任务与迭代目标之间的关系不明显，请添加简短的“迭代目标”说明。
3. 可演示的迭代：每次迭代都应产出一份可演示的软件，能够运行、测试，并在先前迭代的基础上继续构建。
4. 明确的验证方式：每项任务都必须包含明确的验证标准——适用时编写测试，或采用其他具体的验证方法（例如：“验证：API 返回 200，且包含预期负载”“验证：组件在 Storybook 中正确渲染”）。
5. 优先处理依赖项：安排任务顺序时，应先完成依赖项，再开展依赖于它们的工作。
6. 时间固定，范围可变：迭代采用固定时间盒的工作量预期，而非范围承诺。如果工作无法按时完成，就缩小范围，而不是延长时间。
7. 为理解预留预算：预留迭代容量的约 10-20%，用于降低未来工作的风险——开展预研、调研或验证，以加快下次迭代的进度。

输出结构

组织输出，使其在项目演进过程中仍能灵活调整：

• 稳定标识符：为任务分配 ID（T1、T2 等），方便在迭代间引用和调整顺序，而不丢失上下文。
• 可追溯性：将任务关联到规范中的章节，以便规范变更能够追溯到受影响的任务。
• 清晰展示依赖关系：明确指出哪些任务依赖于其他任务。

根据项目的实际情况调整具体格式——小型项目可能只需简单列表，而复杂项目或许适合采用按迭代分组的任务注册表。请自行判断。

迭代拆分流程

1. 彻底阅读规范。找出便于追溯的自然章节边界。

2. 先创建任务注册表——重点关注原子性和依赖关系。

3. 将任务分组到各次迭代中，确保每次迭代都可演示。

4. 从以下角度进行自我审查：

   • 是否有任务过大，无法在一次专注的工作时段内完成？
   • 是否存在缺失的依赖关系或循环依赖？
   • 每项任务的验证标准是否具体且可验证？
   • 开发人员接手任何一项任务时，是否都能明确知道“完成”的标准？
   • 每次迭代是否都有明确的演示场景？
   • 范围塑造气味测试：能否用 ≤9 个主要范围描述整个迭代？如果不能，规范可能需要进一步收窄后再拆分任务。

5. 根据审查结果进行修订。

6. 将最终迭代计划写入与规范同目录的 Markdown 文件（例如，Checkout sprints - 2024-03-25.md）。

可选：子 Agent 审查

对于存在许多相互依赖项的大型或复杂规范，可以考虑让子 Agent 在全新的上下文中审查迭代计划。这能提供一双不受主要对话影响的“第二双眼睛”。子 Agent 应当：

• 检查迭代计划是否存在遗漏、循环依赖或过大的任务
• 提出改进任务范围划分或迭代分组的建议
• 标出任何含糊或无法验证的验证标准

请自行判断——对于棘手且风险较高、值得投入额外精力深入审查的规范，这种做法最有价值。

明确排除在范围之外的事项

• 时间估算：不要估算工期。由人工补充时间线相关信息。
• 资源分配：除非明确提出要求，且提供了足够的上下文，否则不要将任务分配给人员或角色。