需求扩写

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

语言规则

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

触发条件

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

运行模式

/devdocs-requirements              → 自动检测模式
/devdocs-requirements --incremental → 强制增量模式（追加功能点）
/devdocs-requirements --context     → 背景信息模式（追加/更新背景）
/devdocs-requirements --fast        → 跳过 Plan 模式，直接生成，仅最终确认

--fast 模式

--fast 可与任意模式组合，行为变更：

• 跳过 EnterPlanMode 步骤（初始模式）
• 使用合理默认值（不询问技术栈偏好等）
• 仅保留最终写入前的 1 次确认
• 默认行为不变，--fast 是 opt-in

工作流程

初始模式

1. 收集原始需求
   │
   ├── 记录用户原话或关键表述
   ├── 标记来源（口述/邮件/Issue/会议纪要）
   └── 记录日期
   │
   ▼
2. 理解需求 + 探索代码库（如适用）
   │
   ▼
3. 进入 Plan 模式 → 呈现需求拆解方案
   │              （功能点划分、边界范围、优先级）
   ▼
4. 用户审批 Plan → 确认拆解方向或调整
   │
   ▼
5. 退出 Plan 模式 → 识别功能点 (F-XXX)
   │
   ▼
6. 编写用户故事 (US-XXX)
   │
   ▼
7. 定义验收标准 (AC-XXX)
   │
   ▼
8. 生成追溯矩阵
   │
   ▼
9. 用户确认

增量模式

1. 扫描现有编号
   │
   ├── 读取 01-requirements.md
   └── 获取 F/US/AC 最大编号
   │
   ▼
2. 收集新增原始需求
   │
   ├── 记录用户原话，追加到 `## 0. 原始需求` 表格
   └── 若该章节不存在（历史文档），标注"缺失历史原始需求"后继续
   │
   ▼
3. 理解新增需求
   │
   ▼
4. 追加功能点/用户故事/验收标准
   │
   ├── 延续现有编号
   └── 标注增量版本和日期
   │
   ▼
5. 更新追溯矩阵
   │
   ▼
6. 用户确认
   │
   ▼
7. 返回新增编号列表（供调用方使用）

背景信息模式

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

上下文管理

分批原则

按功能点 (F-XXX) 分批扩写，每批完成一个功能点的全部用户故事和验收标准。

质量锚点

• 首个功能点的 US/AC 作为质量锚点
• 每个新功能点开始前，回顾首批的详细程度（US 的角色/期望/目的具体性、AC 的可量化程度、GWT 格式完整性）
• 若当前批次详细程度明显低于锚点，立即补充

一致性自检

每个功能点扩写完成后，对比检查：

• US 格式是否与首批一致（角色/期望/目的三要素完整）
• AC 是否可量化可验证（非"系统应正常工作"等模糊描述）
• 每个 US 是否有 2-3 条 AC（覆盖密度一致）

Plan 模式规范

仅初始模式使用 Plan 模式。增量模式和背景信息模式方向明确，无需 Plan。

初始模式 Plan 内容

在理解需求和探索代码后，必须使用 EnterPlanMode 呈现需求拆解方案：

## 需求拆解方案

### 功能点划分
| 编号 | 功能点 | 描述 | 优先级 |
|------|--------|------|--------|
| F-001 | ... | ... | P0 |
| F-002 | ... | ... | P1 |

### 范围边界
- 包含：<本次范围内的功能>
- 排除：<明确不做的功能>

### 关键决策
- <需要用户确认的拆解决策>

### 预估规模
- 功能点数量：X 个
- 用户故事数量：约 Y 个
- 验收标准数量：约 Z 个

Plan 模式时机

编号规范

编号规则：

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

输出文件

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

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

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

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

文档结构

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

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

## 0. 原始需求 记录用户原话或关键表述，作为需求精化的基准参照。详见模板。

核心概念

• 功能点 (F-XXX)：用户可感知的独立功能单元，可独立交付和验证
• 用户故事 (US-XXX)：格式 "作为 <角色>，我希望 <功能>，以便 <价值>"
• 验收标准 (AC-XXX)：可量化、可验证的完成条件，每个 US 至少 2-3 条
• 追溯矩阵：展示 F → US → AC 的关联关系

详细格式和示例参见 templates/requirements-template.md

增量模式详解

编号扫描

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

## 当前状态

| 类型 | 当前最大编号 | 下一编号 |
|------|-------------|----------|
| 功能点 (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

背景信息模式详解

进入 --context 模式时，必须读取 context-mode.md 获取信息收集引导、输入方式和文档结构模板。

约束

功能点约束

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

用户故事约束

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

用户故事质量检查 (INVEST)

生成时自动验证，无需额外用户交互：

• Independent：可独立交付
• Negotiable：可协商细节
• Valuable：对用户有价值
• Estimable：可估算工作量
• Small：一次迭代可完成
• Testable：可通过测试验证

验收标准约束

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

格式选项：

• 表格格式（默认）：适合简单条件
• Given-When-Then：适合复杂行为场景
  • Given <前置条件>
  • When <操作>
  • Then <预期结果>

追溯约束

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

增量模式约束

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

原始需求约束

• 初始模式：必须在 F/US/AC 精化前收集原始需求，写入 ## 0. 原始需求
• 增量模式：新增需求必须追加到 ## 0. 原始需求 表格
• 背景信息模式（--context）：不写入 ## 0. 原始需求——除非用户提供的是需求原话而非背景补充
• 原始需求应保留原话或最小必要改写
• 历史文档若无该章节，标注"缺失历史原始需求"后继续

背景信息模式约束

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

Plan 模式约束

• 初始模式：理解需求 + 探索代码后，必须进入 Plan 模式
• Plan 必须包含功能点划分和范围边界
• 用户审批 Plan 后才能开始编号分配和文档写入
• 用户要求调整时，更新 Plan 后重新审批
• 增量模式和背景信息模式不使用 Plan 模式

确认约束

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

上下文管理约束

• 后批次 US/AC 详细程度不低于首批次（格式完整性、量化程度、覆盖密度）
• 每个功能点完成后执行一致性自检

Skill 协作

子 Agent 摘要格式

当本 Skill 作为子 Agent 运行时，返回以下结构化摘要：

skill: devdocs-requirements
mode: initial | incremental
new_ids:
  features: [F-001~F-003]
  stories: [US-001~US-008]
  acceptance: [AC-001~AC-015]
status: completed
output_files:
  - docs/devdocs/01-requirements.md

下一步

提示：文档变更较大时，建议运行 /agent-memory 同步记忆文件。