功能规格说明（元技能）

衔接用户画像文档与开发工作。该技能将用户画像文档中识别出的用户需求、痛点及用户旅程，转化为结构清晰、可落地实施的功能规格说明，并附带明确的验收标准。

安装

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install feature-specification

目的

用户画像文档定义了谁和为什么；功能规格说明则定义了什么以及做到何种程度才算合格。本技能弥合二者之间的鸿沟：

• 从用户画像中的痛点和旅程中提取可执行的功能点
• 结构化需求描述，使开发者能精准理解需构建的内容
• 明确定义验收标准，使测试人员能准确判断验证要点
• 在编写第一行代码前即消除范围模糊性

适用场景

• 用户画像文档已存在（docs/PERSONA.md 或 docs/personas/）之后
• 新功能或新产品开发启动之前
• 功能需求缺乏明确验收标准时
• 干系方对“完成”标准存在分歧时
• 将用户反馈转化为开发任务时

功能规格说明模板

每个功能规格说明均须采用以下结构。请将规格文档存放在 docs/specs/ 或 docs/features/ 目录下。

# 功能：[功能名称]

## 元数据
- **优先级：** [Must / Should / Could / Won't]
- **目标用户画像：** [来自用户画像文档中的画像名称]
- **状态：** Draft | Review | Approved | In Progress | Complete
- **预估工作量：** [T恤尺码：XS / S / M / L / XL]

## 问题陈述
[直接引用该功能所解决的用户画像痛点。
可引用或链接至用户画像文档中的相关章节。]

## 解决方案描述
[对该功能作用及其如何解决问题的高层描述。
2–4 句话，不含具体实现细节。]

## 用户故事

- 作为一个 [用户画像]，我希望 [执行某操作]，以便 [获得某收益]。
- 作为一个 [用户画像]，我希望 [执行某操作]，以便 [获得某收益]。

## 验收标准

### 场景：[主流程描述]
- **Given** [前提条件]
- **When** [用户操作]
- **Then** [预期结果]

### 场景：[替代路径描述]
- **Given** [前提条件]
- **When** [用户操作]
- **Then** [预期结果]

### 场景：[错误情况描述]
- **Given** [前提条件]
- **When** [无效操作]
- **Then** [错误处理结果]

## 边界情况
- [ ] [边界情况 1 — 描述及预期行为]
- [ ] [边界情况 2 — 描述及预期行为]

## 非功能性需求
- **性能：** [响应时间、吞吐量、负载目标]
- **可访问性：** [WCAG 等级、键盘导航支持、屏幕阅读器兼容性]
- **安全性：** [认证要求、数据敏感性、输入校验]
- **浏览器/设备：** [支持矩阵]

## 依赖项
- [本功能所依赖的其他功能或系统]
- [必需的外部 API 或服务]

## 不包含范围
- [明确列出本功能不涵盖的内容]
- [防止开发过程中范围蔓延]

## 设计参考
- [指向原型图、线框图或设计系统组件的链接]
- [如有，附上截图或示意图]

编写有效的用户故事

用户故事将用户画像需求与开发者任务连接起来。请遵循 INVEST 原则：

优质 vs 劣质用户故事示例

验收标准模式

模式 1：主流程（Happy Path）

Given 一位已登录且购物车中已有商品的客户
When 点击“去结算”
Then 页面跳转至支付页，且购物车摘要可见

模式 2：边界条件（Boundary Conditions）

Given 购物车中已有 100 件商品（已达上限）
When 用户尝试添加第 101 件商品
Then 显示提示：“购物车已达上限——请移除一件商品后再添加”
And 该商品未被加入购物车

模式 3：错误情况（Error Cases）

Given 用户正在提交注册表单
When 邮箱字段填写内容为 “not-an-email”
Then 表单显示内联校验提示：“请输入有效邮箱地址”
And 表单未提交
And 输入焦点自动移至邮箱字段

模式 4：状态流转（State Transitions）

Given 一笔订单状态为 “Processing”
When 仓库将其标记为已发货
Then 订单状态更新为 “Shipped”
And 客户在 5 分钟内收到发货确认邮件
And 订单详情页可见物流单号

模式 5：反向 / 安全（Negative / Security）

Given 一位非账户所有者的用户
When 尝试通过直接 URL 访问 /account/settings
Then 返回 403 Forbidden 响应
And 此次访问请求被记录到日志中

优先级框架

采用 MoSCoW 优先级法，并以用户画像影响为锚点：

优先级制定流程：

1. 列出所有候选功能
2. 将每一项映射至对应用户画像的痛点或旅程步骤
3. 依据用户画像影响（而非技术兴趣）分配 MoSCoW 标签
4. 验证：所有 P0 功能组合后，是否足以支撑目标用户画像的基本可用性？
5. 持续裁剪范围，直至所有 P0 功能均可在既定周期内完成

规格说明反模式

与工作流的集成

功能规格说明是整体开发流程的关键连接点：

1. 用户画像文档（docs/PERSONA.md）—— 用户需求的唯一可信来源
2. 功能规格说明（docs/specs/）—— 本技能的输出成果；开发工作的正式契约
3. 任务创建—— 每份规格说明生成一个或多个开发任务
4. 开发实现—— 开发者依据规格说明确认范围与验收标准
5. 测试验证—— 测试人员直接从验收标准派生测试用例
6. 评审环节 —— Pull Request 评审重点核查验收标准是否全部满足

当配合 /new-feature 命令或其他类似工作流使用时：

• 首先通读相关用户画像文档
• 基于本模板生成规格说明
• 验证验收标准是否覆盖主流程、错误路径及边界情况
• 开发启动前，与干系方共同确认优先级

绝对禁止事项

1. 绝对禁止脱离用户画像撰写规格说明 —— 每一项功能皆服务于特定用户
2. 绝对禁止省略验收标准 —— “显而易见”的需求往往引发最多缺陷
3. 绝对禁止使用模糊修饰词作为需求 —— “快速”、“简单”、“直观”等不具备可测试性
4. 绝对禁止在一个规格说明中混杂多个功能 —— 一份规格说明，一个功能，一个清晰范围
5. 绝对禁止在用户故事中指定实现细节 —— 描述 做什么，而非 怎么做
6. 绝对禁止在未记录边界情况的前提下将规格说明标记为 Approved —— 主流程只是最简单部分
7. 绝对禁止假定依赖项不言自明 —— 必须显式列出规格说明所依赖的每一个系统、API、功能及数据源