/x-spec

name: x-spec
description: |
  和用户沟通完开发需求后使用。把需求用功能性描述（不涉及具体实现、不用技术词汇）写进 spec 文档，并把需求拆成一个个用户可感知的小功能，每个用 feat+序号（feat01 开始）作为标题，配合 Given/When/Then 场景描述。也适用于用户要求"写需求文档""整理 spec""把刚聊的方案记下来""记录需求"。

x-spec

把沟通完的需求写成一份纯功能性的 spec。只描述"用户能做什么、能看到什么"，不描述代码怎么实现。

核心原则

1. **只写做什么，不写怎么做。** 描述用户能感知的功能和结果，不写技术实现。 2. **用功能语言，不用技术词汇。** 写"保存""查询""加快""提醒"，不写"数据库""API""缓存""消息队列"。用户能看懂每一行。 3. **feat 是用户可感知的功能点。** 一个 feat 对应一个用户能说出名字的功能（如"登录""搜索""导出"），不按技术层（如"接口层""数据层"）拆。

产物

一份 `docs/spec/<spec-name>/spec.md`。结构为：标题 + 概述 + 用户已确认的关键约束 + feat 列表；未确认提议留在待确认清单。完整读取 `templates/spec.md` 后填充，删除占位符和空示例。

工作流

1. 梳理需求

从刚结束的对话里提取用户要的所有功能。不要先复述问用户、也不要停下来等确认——直接往下写完整 spec。

遇到题目没说死的地方（边界、异常、歧义），采用最小合理默认直接写进场景里，同时把这条默认**记到结尾的待确认清单**（见第 5 步），让用户一次性 review。默认和提议均不是用户决定；涉及关键约束、含歧义或可能不可实现的行为必须确认，不能用合理默认定稿。常见需要做默认的点：功能的触发条件、边界情况、出错时用户看到什么。

2. 拆分 feat

按用户可感知的功能点拆分。编号规则：

• 从 `feat01` 开始，两位序号，按文档顺序连续递增（feat01、feat02、feat03...）。
• 同一 spec 内序号不重复。
• 每个 feat 标题写功能名称，用功能性描述（如 `feat01: 用户用手机号登录`，不写 `feat01: AuthService`）。

一个 feat 是一个完整的功能点，不要拆得过细。判断标准：用户会把它当成"一个功能"来说，就归一个 feat。

3. 写场景

每个 feat 下用多个 Given/When/Then 场景描述行为。至少覆盖：

• **正常流程**：用户正常操作会发生什么。
• **边界情况**：空输入、极值、特殊字符等。
• **异常处理**：出错时用户看到什么。

格式：

## feat01: <功能名称>

<一句话说明这个功能给用户做什么>

场景1: <正常流程名>
- GIVEN <前置条件>
- WHEN <用户操作>
- THEN <可观察结果>

场景2: <边界或异常名>
- GIVEN <前置条件>
- WHEN <用户操作>
- THEN <可观察结果>

**GWT 写法：**

• **GIVEN**：用户视角的前置条件或初始状态。例："用户已登录""购物车里有3件商品"。
• **WHEN**：用户的操作。例："点击结算""输入手机号后点击获取验证码"。
• **THEN**：用户能看到、能感知的结果。例："显示订单确认页""提示手机号格式不正确"。

**禁止出现**：技术实现细节。不写"调用 POST /api/order""写入订单表""返回 200 状态码""缓存失效"。只写用户视角。

4. 提出“必定不能犯的错”并请用户确认

spec 草案完成时，主动结合用户原话和本需求的后果，提出少量具体的“必定不能犯的错”，请用户补充、修改或确认。这些约束是后续反例测试的依据，不能只列正常功能验收。

• `spec.md` 的“关键约束（用户已确认）”是约束唯一正文来源。保留用户原意，写清必要的适用范围、可观察判据与禁止结果；用户原本给出的具体测试场景保留在相应 feat 下，约束只回指，不重复维护场景正文。
• 已确认条目用稳定编号 `C1`、`C2` 等；沿用既有约束编号，不重排或复用已删除编号。用 `featNN 场景M` 关联适用行为，已有 Scenario ID 的文档沿用原 ID，不为了加约束改编号。
• 用户已明确给出的约束可直接收录并注明来源；agent 新提议和新增的范围/判据先留在待确认清单，不能混入已确认章节。只确认部分时仅收录该部分，剩余项仍待确认；没有确认项时如实注明，不能把用户沉默写成“无约束”。
• 用户表述有歧义、不可观察或可能不可实现时，列出具体问题、建议澄清的范围/判据及影响，等待确认，不能自行削弱“绝不能”的含义。确认后回写权威条目，后续设计与任务只引用 ID。

5. 自检并报告待确认项

写完后逐条检查：

• 每个 feat 是不是用户能感知的完整功能点？（不是技术层、不是接口名）
• GWT 里有没有混进技术词汇？（有就改成功能性描述）
• 每个 feat 是否覆盖了正常、边界、异常三类场景？（缺哪类就补）
• THEN 写的是不是用户能看到的结果？（不是内部状态变化）
• feat 编号是否从 01 连续递增、无重复（增量沿用已有编号）？
• 每条关键约束是否有真实用户依据、必要范围和可观察判据，C 编号稳定且关联场景有效？提议是否仍明确待确认？

最后在回复里附一份**待确认清单**，把第 1 步里所有"题目没说死、我用了合理默认"的点列出来让用户一次性 review；另列“必定不能犯的错”的提议，明确请用户补充/修改/确认。普通默认每条写清：在哪个 feat 的哪个场景、默认给了什么结果。示例：

> 待确认： > - feat02 场景2 邀请码无效时的提示文案，我默认写"邀请码无效" > - feat05 场景2 没人打卡时的进度展示，我给了"第 0 页"和"提示还没人打卡"两种，需二选一

确认之后

待确认清单及关键约束的提议逐条拍板，记录用户实际确认结论、来源和对应内容基线，spec 定稿后，主线下一步是 x-tech-design：读取已确认的 spec，在 spec 同目录产出 `tech-design.md` 技术设计（模块、协议、数据流、规范落实）。一个 spec 通常包含多个 feat，必须先有经用户确认的技术设计，才能进入 x-req 拆任务；给既有 spec 新增 feat 时，同样先补设计差异，再拆任务。

完整示例

下面是一个三 feat 的小需求示例，展示目标形态：

# 二手书交易首页

让用户在首页看到正在出售的书，并能快速搜索和收藏感兴趣的图书。

## feat01: 浏览在售图书

用户打开首页可以看到当前所有正在出售的图书。

场景1: 正常浏览
- GIVEN 首页有多本在售图书
- WHEN 用户打开首页
- THEN 按上架时间从新到旧展示图书列表，每本显示书名、价格、成色和卖家昵称

场景2: 暂无图书
- GIVEN 当前没有任何在售图书
- WHEN 用户打开首页
- THEN 显示"暂无在售图书"的提示，并给出去发布闲置的入口

## feat02: 按书名搜索

用户可以通过书名快速找到想要的图书。

场景1: 匹配成功
- GIVEN 首页有《三体》和《三体2》在售
- WHEN 用户在搜索框输入"三体"
- THEN 展示《三体》和《三体2》两本书

场景2: 无匹配
- GIVEN 首页没有包含"小说"的书
- WHEN 用户搜索"小说"
- THEN 提示"没有找到相关图书"

## feat03: 收藏图书

用户可以把感兴趣的图书收藏起来，方便以后查看。

场景1: 收藏一本未收藏的书
- GIVEN 用户已登录，且这本书没有收藏过
- WHEN 用户点击这本书的收藏按钮
- THEN 按钮变成已收藏状态，这本书出现在用户的收藏列表里

场景2: 未登录时收藏
- GIVEN 用户没有登录
- WHEN 用户点击收藏按钮
- THEN 提示"请先登录"，并跳转到登录页

注意示例里没有一个技术词：没有"数据库""接口""状态码""字段"。每条 THEN 都是用户能直接看到的。