to-spec

本 skill 接收当前对话的上下文和对代码库的理解，产出一个 spec（规格说明）。不要访谈用户；只综合你已经知道的东西。

工单系统（issue tracker）和分诊标签词汇应当已经提供给你。如果没有，请让用户运行 /setup-engineering-skills。

流程

1. 如果还没有做过，先探索仓库以理解代码库现状。在整个 spec 中使用项目的领域词汇表用语，并遵守你所改动区域内的任何 ADR（架构决策记录）。

2. 勾画出你要用来验收该功能的接缝（seam）。已有接缝应优先于新接缝。使用尽可能高的稳定接缝。如果需要新接缝，在你能提出的最高位置提出。代码库中接缝越少越好——理想数量是一。

与用户确认这些接缝符合他们的预期。

1. 从已经确认的需求中整理验收用例。至少覆盖正常行为和已知的重要业务异常；功能依赖数据库、网络、文件、时钟或外部服务时，还要判断不可用、超时、部分成功、重复请求和并发冲突中哪些会产生不同的对外承诺。

验收用例只描述通过已确认接缝可观察到的结果，不暴露内部调用次数、SQL、私有方法或具体驱动错误。让用户确认验收用例和非目标；不要在这个综合阶段重新进行完整访谈。

1. 使用下面的模板编写 spec，然后将其发布到项目的工单系统。打上 ready-for-agent 分诊标签——无需额外分诊。

问题陈述

用户面临的问题，从用户视角描述。

解决方案

问题的解决方案，从用户视角描述。

用户故事

一份很长的、带编号的用户故事列表。每个用户故事的格式为：

1. 作为 ，我想要 ，以便

这份用户故事列表应当极其详尽，覆盖功能的方方面面。

验收用例

一份带稳定编号的代表性场景列表，例如 AC-001。每个场景包含：

• Given：业务前提；
• When：调用方动作；
• Then：通过验收接缝可观察到的结果；
• 证据：自动化测试、人工操作、指标或其他独立证据；
• 层级：模块验收、契约/集成或系统关键路径。

覆盖正常行为、关键业务异常，以及会改变接口承诺的技术故障。验收用例是代表性规格，不穷举数据库驱动或框架的内部错误组合。

故障与一致性决策

列出相关外部依赖的失败模式，以及系统对调用方承诺的错误、状态不变量、重试、幂等或补偿行为。不相关的故障类型明确省略，不为想象中的未来写测试。

实现决策

已做出的实现决策列表。可以包括：

• 将要构建/修改的模块
• 这些模块中将被修改的接口
• 来自开发者的技术澄清
• 架构决策
• Schema 变更
• API 契约
• 具体交互

不要包含具体的文件路径或代码片段。它们可能很快过时。

例外：如果某个原型（prototype）产出的代码片段比散文更精确地编码了一个决策（状态机、reducer、schema、类型形状），把它内联到相关决策中，并简要注明它来自原型。裁剪到富含决策的部分，不是能跑的演示，只要重要的部分。

测试决策

已做出的测试决策列表。包括：

• 对什么才是好测试的描述（只测外部行为，不测实现细节）
• 验收测试使用哪个接缝，以及哪些 AC-* 需要自动化
• 哪些复杂局部规则需要单元或模块测试
• 哪些真实 Adapter、协议、数据库或 Schema 需要集成测试
• 是否存在一条必须由系统级端到端测试证明接线正确的关键路径
• 哪些架构、依赖方向或公共契约需要机器检查
• 测试的先例（即代码库中类似类型的测试）

不要让每一层原样重复同一个事实。每项测试都应说明它独立证明了什么。

临时结构与退出条件

如果实现需要兼容层、Feature Flag、双写、新旧接口并存或其他临时结构，记录它存在的理由、删除条件、负责删除的后续工单和重新评估触发条件。没有临时结构时写“无”。

上下文影响

列出功能完成后需要更新的领域术语、上下文关系、ADR、接口契约或架构说明。只列真实变化，不把实现进度写进 CONTEXT.md。

超出范围

对该 spec 范围之外事项的描述。

补充说明

关于该功能的任何补充说明。