feature-requirements

需求

概述

通过引导用户进行需求发现、切实的范围界定，并生成一份语言清晰、实用的整合需求文档，帮助创建需求文档的结构化命令。

按照既定的功能开发流程创建需求文档。首先，阅读功能开发指南 @~/.local/share/dotfiles/ai/guides/feature-development-process.md 和愿景文档 @vision.md，了解功能范围和文档编写方式。

注意：如果项目有本地版本的指南 @project/guides/feature-development-process.md，也可以参考该版本，以了解项目特有的修改。

重要：首先创建 TODO 列表，跟踪需求创建的 3 个阶段。将第一阶段标记为 "in_progress"，其他阶段标记为 "pending"。

需求文档结构

单一整合文档（requirements.md）包括：

用户故事与业务需求：

• 按角色组织的用户故事
• 业务能力和用户工作流
• 系统必须提供的核心能力

业务数据与规则：

• 业务实体和数据需求（实体、关系、业务层面的属性和约束）
• 规范系统行为的业务逻辑和规则
• 用户体验需求

质量属性与约束：

• 性能、安全性、可靠性和可扩展性需求
• 合规性和隐私控制
• 技术约束和限制

集成与成功：

• 与现有系统的集成接入点
• 开发和测试方法
• 成功标准和验收标准
• 约束和假设

需求标识格式

所有需求都必须使用系统化的 ID 前缀，便于在规范、计划和讨论中交叉引用。

前缀	用途	编号方式
US-X.X.X	用户故事	章节.小节.条目
REQ-X.X.X	需求	章节.小节.条目
SC-X	成功标准	顺序编号

格式示例：

**US-1.1.1**: As a staff member, I want to view custom field data...

**REQ-2.1.1**: The system must render form controls dynamically based on...

**SC-1**: Staff can view custom field values on detail pages.

编号规则：

• 编号遵循文档章节层级（章节 2.1 → REQ-2.1.x）
• 第 1.1 节中的用户故事使用 US-1.1.1、US-1.1.2 等
• 第 3.2 节中的需求使用 REQ-3.2.1、REQ-3.2.2 等
• 成功标准使用简单的顺序编号（SC-1 至 SC-N）

需要考虑的现有系统模式

收集需求时，请检查现有系统能力是否适用：

• 搜索：全文搜索能力
• 文件附件：文档/文件上传和管理
• 审计跟踪：变更跟踪和历史记录
• 多租户：按组织/租户隔离数据
• 权限：基于角色的访问控制
• 标签：分类和归类系统
• 自定义字段：可扩展的数据字段

尽早询问：“这些现有能力中，哪些可能适用于此功能？”

流程：依次完成以下 3 个阶段

阶段 1：需求发现

提出有针对性的问题，收集所有需求（暂不分类）：

• 系统需要提供哪些具体能力？
• 系统需要管理哪些业务实体（主要概念、关系、业务级属性）？
• 系统需要存储哪些数据？有哪些业务约束？
• 需要执行哪些业务规则？
• 面向哪些不同的用户群体（员工、会员、公众、管理员）？
• 不同用户群体的需求有何不同？
• 每个用户群体应该能够查看和执行哪些操作？
• 用户如何与系统交互？
• 没有数据时会发生什么？（员工与会员的空状态）
• 数据以什么方式呈现？（动态信息流、表格、卡片等）
• 怎样才能让不同技术水平的用户都能轻松使用这项功能？
• 有哪些安全和权限要求？
• 有哪些性能预期？
• 需要与现有系统进行哪些集成？
• 有哪些适用的合规或隐私要求？

一次只问一个问题——等待对方回答后再继续。

阶段 2：务实聚焦与未来规划

针对发现的每项需求，询问：

• 这项需求是否适合当前范围？
• 应将其纳入当前需求，还是放入 future.md 留待后续阶段？
• 能否用清晰、简单的语言表述？
• 其范围是否适合当前阶段？
• 是否可测试、可衡量？

为以下需求创建 future.md：

• 很好的想法，但超出当前范围
• 需要在第 2/3 阶段实施的复杂功能
• 值得保留以供未来考虑的想法
• 在初始基础上扩展的高级功能

当前需求中只保留以下内容：

• 目前切实可行且能够实现的内容
• 核心功能必不可少的内容
• 用清晰、简单的语言撰写的内容

阶段 3：文档生成

• 按照上述需求标识格式，为所有用户故事（US-）、需求（REQ-）和成功标准 （SC-）添加 ID 前缀
• 创建一份统一的 requirements.md 文档，结构如下：
  1. 用户故事与业务需求 - 按角色组织，明确业务能力
  2. 核心系统能力 - 系统必须向用户提供的功能
  3. 业务数据需求 - 实体、关系和业务级属性
  4. 业务规则与逻辑 - 约束行为的规则和限制
  5. 用户体验需求 - 系统应呈现的体验和行为
  6. 质量属性与约束 - 性能、安全性、可靠性、可扩展性
  7. 集成触点 - 与现有系统的连接
  8. 开发与测试方法 - 系统的构建和验证方式
  9. 成功标准 - 明确的验收标准和成功定义
  10. 约束与假设 - 范围边界和基本假设
• 创建 future.md，记录延期的需求（按用户故事和技术阶段组织）
• 更新或创建 discussion-summary.md：
  • 检查功能目录中是否存在 discussion-summary.md
  • 如果存在：添加一个「需求阶段」章节，其中包括：
    • 需求阶段的技术讨论和研究
    • 「愿景阶段遗留问题的解决情况」小节（用表格展示待解决问题及其解决方式）
    • 将新决策添加到关键决策日志中（从愿景阶段的编号继续）
    • 使用新引用的文件更新技术背景
  • 如果不存在：创建该文件，并包含完整结构及愿景阶段占位内容
• 在所有文档中加入带有正确链接的目录
• 使用系统化的章节编号（1.1、1.2、2.1、2.2 等），以便精确交叉引用
• 引用愿景文档，说明业务背景
• 全文使用清晰、实用的语言
• 严格遵循功能开发流程中的结构
• 记录关键架构决策时（独立页面还是模态框、信息流还是表格等），说明其理由（可链接性、性能、用户体验等）

指南

• 每次只问一个问题，并等待回答
• 完成每个阶段后更新 TODO 列表
• 使用清晰、自然的语言，避免官样文章
• 聚焦当下有用的需求，避免过度设计
• 按照逻辑组织需求，形成易读的结构，服务于整个团队
• 参考愿景文档和功能开发流程
• 务实为先，编写易读、可执行的文档
• 保持在需求层面：关注是什么以及为什么，而不是如何实现
  • 好的示例：「系统必须跟踪事件是草稿还是已发布」
  • 应避免：「使用布尔值标记 is_draft 字段」
  • 好的示例：「活动归属于一个组织」
  • 应避免：「包含 organization_id 外键」
  • 数据类型、表结构和字段名等技术实现细节留到规格阶段
• 预期会有迭代：用户在考虑各种影响时，需求往往会不断完善。这很正常，也有益处。应准备好根据新的见解更新需求。
• 当需求发生重大变化（可选变为必需、添加或移除功能）时，应一致地更新所有相关章节

开始流程

1. 立即创建包含 3 个阶段的 TODO 列表
2. 询问用户：「你正在处理哪个功能目录？请提供完整路径（例如 project/features/FT033-feature-name）」
3. 询问用户：「请用 @vision.md 标记你的愿景文档，以便我了解功能范围」
4. 验证目录是否存在，并确认将在何处创建需求文档
5. 查看愿景文档，了解功能背景
6. 从第一个需求探索问题开始阶段 1
7. 集中提问；等待用户回答后再继续下一个问题