需求扩写

将用户简短需求扩展为结构化的需求文档，建立功能点、用户故事、验收标准的关联体系。

语言规则

• 支持中英文提问
• 统一中文回复
• 使用中文生成文档

触发条件

• 用户提供功能需求或想法
• 用户要求创建/编写 PRD
• 用户想要澄清或记录需求
• 来自 /devdocs-feature 的增量需求委托
• 用户需要补充项目背景信息（尤其是 retrofit 后）
• 用户提供参考资料、领域知识、技术约束

运行模式

/devdocs-requirements              → 自动检测模式
/devdocs-requirements --incremental → 强制增量模式（追加功能点）
/devdocs-requirements --context     → 背景信息模式（追加/更新背景）

工作流程

初始模式

1. 理解需求
   │
   ▼
2. 探索代码库（如适用）
   │
   ▼
3. 识别功能点 (F-XXX)
   │
   ▼
4. 编写用户故事 (US-XXX)
   │
   ▼
5. 定义验收标准 (AC-XXX)
   │
   ▼
6. 生成追溯矩阵
   │
   ▼
7. 用户确认

增量模式

1. 扫描现有编号
   │
   ├── 读取 01-requirements.md
   └── 获取 F/US/AC 最大编号
   │
   ▼
2. 理解新增需求
   │
   ▼
3. 追加功能点/用户故事/验收标准
   │
   ├── 延续现有编号
   └── 标注增量版本和日期
   │
   ▼
4. 更新追溯矩阵
   │
   ▼
5. 用户确认
   │
   ▼
6. 返回新增编号列表（供调用方使用）

背景信息模式

1. 读取现有文档
   │
   ├── 检查 01-requirements.md 是否存在
   └── 提取现有"背景与目标"章节内容
   │
   ▼
2. 收集背景信息
   │
   ├── 引导用户提供信息（AskUserQuestion）
   ├── 接收用户直接输入
   ├── 从文件路径提取（Read）
   └── 从 URL 提取摘要（WebFetch）
   │
   ▼
3. 整合信息
   │
   ├── 合并到"背景与目标"章节
   ├── 补充到"技术约束"子章节
   └── 补充到"参考资料"子章节
   │
   ▼
4. 更新文档
   │
   ▼
5. 用户确认

编号规范

编号规则：

• 全局顺序编号，不嵌套
• 通过追溯矩阵表达关联关系
• 编号一旦分配不可复用

输出文件

主文件：docs/devdocs/01-requirements.md

如文档超过 300 行，可拆分为：

• 01-requirements.md – 概览和功能点
• 01-requirements-stories.md – 用户故事详情
• 01-requirements-nfr.md – 非功能性需求

详细模板参见 templates/requirements-template.md

文档结构

# 需求文档：<功能名称>

## 1. 背景与目标
## 2. 功能点清单
## 3. 用户故事
## 4. 验收标准
## 5. 追溯矩阵
## 6. 非功能性需求
## 7. 范围边界
## 8. 风险与假设

核心概念

功能点 (Feature)

功能点是用户可感知的独立功能单元。

识别方法：

• 可以独立交付和验证
• 对用户有明确价值
• 粒度适中（不过大也不过小）

示例：

| 编号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| F-001 | 用户注册 | 新用户通过邮箱注册账号 | P0 |
| F-002 | 用户登录 | 已注册用户登录系统 | P0 |
| F-003 | 密码找回 | 用户通过邮箱重置密码 | P1 |

用户故事 (User Story)

用户故事描述用户如何使用功能点完成目标。

格式：作为 <角色>，我希望 <功能>，以便 <价值>

示例：

| 编号 | 功能点 | 角色 | 期望 | 目的 |
|------|--------|------|------|------|
| US-001 | F-001 | 新用户 | 使用邮箱注册 | 获得系统访问权限 |
| US-002 | F-001 | 新用户 | 设置安全密码 | 保护账号安全 |
| US-003 | F-002 | 已注册用户 | 使用邮箱密码登录 | 进入系统 |

验收标准 (Acceptance Criteria)

验收标准定义用户故事的完成条件，是测试用例设计的依据。

原则：

• 可量化、可验证
• 描述预期行为，不描述实现
• 每个用户故事至少 2-3 条验收标准

示例：

### US-001: 使用邮箱注册

| 编号 | 标准描述 | 验证方式 |
|------|----------|----------|
| AC-001 | 有效邮箱格式可以提交注册 | 输入 test@example.com，提交成功 |
| AC-002 | 已存在邮箱显示错误提示 | 输入已注册邮箱，显示"邮箱已存在" |
| AC-003 | 注册成功后发送验证邮件 | 收到包含验证链接的邮件 |

追溯矩阵

追溯矩阵展示功能点、用户故事、验收标准的关联关系。

示例：

| 功能点 | 用户故事 | 验收标准 |
|--------|----------|----------|
| F-001 | US-001 | AC-001, AC-002, AC-003 |
| F-001 | US-002 | AC-004, AC-005 |
| F-002 | US-003 | AC-006, AC-007, AC-008 |

增量模式详解

编号扫描

从现有文档提取最大编号：

## 当前状态

| 类型 | 当前最大编号 | 下一编号 |
|------|-------------|----------|
| 功能点 (F) | F-003 | F-004 |
| 用户故事 (US) | US-008 | US-009 |
| 验收标准 (AC) | AC-015 | AC-016 |

追加格式

---

## 功能迭代 v2: <功能名称> (2024-01-15)

> 本次新增 F-004，包含 2 个用户故事、5 个验收标准。

### F-004: <功能名称>

**描述**：<功能描述>

**用户故事**：

| 编号 | 角色 | 期望 | 目的 |
|------|------|------|------|
| US-009 | 作为<角色> | 我希望<功能> | 以便于<价值> |

**验收标准**：

- [ ] AC-016: <标准1>
- [ ] AC-017: <标准2>

返回值

增量模式完成后，返回新增编号列表供调用方使用：

新增编号：
- F-004
- US-009, US-010
- AC-016 ~ AC-020

背景信息模式详解

典型场景

1. Retrofit 后补充：代码逆向推导完成后，补充代码中看不出的背景
2. 新项目初始化：在定义功能点之前，先记录项目背景
3. 迭代过程中：随时补充新发现的约束或参考资料

信息收集引导

使用 AskUserQuestion 引导用户提供信息：

## 背景信息收集

当前"背景与目标"章节状态：
> [显示现有内容，或"暂无内容"]

请选择要补充的信息类型：

1. **项目背景** - 为什么做这个项目、解决什么问题
2. **领域知识** - 关键业务概念、术语解释
3. **技术约束** - 兼容性要求、性能指标、安全要求
4. **参考资料** - 设计稿、竞品、文档链接
5. **决策记录** - 关键技术/产品选择及原因

信息输入方式

文档结构更新

背景信息模式会更新”背景与目标”章节的结构：

## 1. 背景与目标

### 1.1 项目背景

**项目起源**：<为什么启动这个项目>

**目标用户**：<谁会使用这个系统>

**核心问题**：<解决什么问题>

### 1.2 领域知识

| 术语 | 解释 |
|------|------|
| <术语1> | <解释> |
| <术语2> | <解释> |

### 1.3 技术约束

| 约束类型 | 约束内容 | 原因 |
|----------|----------|------|
| 兼容性 | 需支持 iOS 15+ | 用户设备分布 |
| 性能 | 首屏加载 < 2s | 用户体验要求 |
| 安全 | 数据需加密存储 | 合规要求 |

### 1.4 参考资料

| 资料 | 链接/路径 | 说明 |
|------|-----------|------|
| 设计稿 | `designs/v1.fig` | Figma 原型 |
| 竞品分析 | `docs/competitor.md` | 竞品功能对比 |
| API 文档 | https://api.example.com/docs | 第三方接口 |

### 1.5 决策记录

| 决策 | 选择 | 原因 | 日期 |
|------|------|------|------|
| 状态管理 | Redux | 团队熟悉，生态成熟 | 2024-01-10 |
| 数据库 | PostgreSQL | 需要复杂查询支持 | 2024-01-10 |

增量更新

背景信息模式支持增量更新，不会覆盖现有内容：

---

## 背景信息更新 (2024-01-20)

### 新增技术约束

| 约束类型 | 约束内容 | 原因 |
|----------|----------|------|
| 国际化 | 需支持中英文 | 海外市场需求 |

### 新增参考资料

| 资料 | 链接/路径 | 说明 |
|------|-----------|------|
| 新设计稿 | `designs/v2.fig` | 迭代版本 |

约束

功能点约束

• 每个功能点必须有唯一编号 (F-XXX)
• 功能点必须标注优先级 (P0/P1/P2)
• 功能点描述应简洁明确

用户故事约束

• 每个用户故事必须关联到功能点
• 必须遵循”作为…我希望…以便…”格式
• 每个功能点至少有 1 个用户故事

验收标准约束

• 每个验收标准必须有唯一编号 (AC-XXX)
• 每个用户故事至少有 2 条验收标准
• 验收标准必须可量化、可验证
• 必须描述验证方式

追溯约束

• 必须提供追溯矩阵
• 所有功能点必须有对应的用户故事
• 所有用户故事必须有对应的验收标准

增量模式约束

• 必须先扫描现有编号，延续编号
• 追加内容必须标注增量版本和日期
• 不得删除或覆盖现有内容
• 完成后必须返回新增编号列表

背景信息模式约束

• 必须先读取现有”背景与目标”章节内容
• 不得删除或覆盖现有背景信息
• 新增内容必须标注更新日期
• URL 引用必须使用 WebFetch 提取摘要，不能仅记录链接
• 文件引用必须使用 Read 验证文件存在
• 敏感信息（密钥、密码、内部 URL）不得写入文档
• 参考资料必须注明用途和关联性

确认约束

• 必须与用户确认功能点是否完整
• 不得添加用户未提及且未确认的功能

Skill 协作

下一步