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。

遇到题目没说死的地方（边界、异常、歧义），采用最小合理默认直接写进场景里，同时把这条默认**记到结尾的待确认清单**（见第 4 步），让用户一次性 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. 自检并报告待确认项

写完后逐条检查：

- 每个 feat 是不是用户能感知的完整功能点？（不是技术层、不是接口名）
- GWT 里有没有混进技术词汇？（有就改成功能性描述）
- 每个 feat 是否覆盖了正常、边界、异常三类场景？（缺哪类就补）
- THEN 写的是不是用户能看到的结果？（不是内部状态变化）
- feat 编号是否从 01 连续递增、无重复？

最后在回复里附一份**待确认清单**，把第 1 步里所有"题目没说死、我用了合理默认"的点列出来让用户一次性 review，每条写清：在哪个 feat 的哪个场景、默认给了什么结果。示例：

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

## 完整示例

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

```markdown
# 二手书交易首页

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

## 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 都是用户能直接看到的。