devdocs-requirements

用途

devdocs-requirements 用于将用户简短需求扩展为结构化的需求文档，建立功能点、用户故事、验收标准的关联体系。它适用于用户提供功能需求或想法、要求创建或编写 PRD、想要澄清或记录需求、来自 /devdocs-feature 的增量需求委托、需要补充项目背景信息（尤其是 retrofit 后），以及提供参考资料、领域知识、技术约束等场景。

主要能力

• 需求扩写：将简短需求扩展为包含功能点（F-XXX）、用户故事（US-XXX）、验收标准（AC-XXX）的详细文档。
• 编号体系：功能点使用 F-XXX，用户故事使用 US-XXX，验收标准使用 AC-XXX，全局顺序编号、不嵌套，通过追溯矩阵表达关联关系，编号一旦分配不可复用。
• 追溯矩阵：展示 F → US → AC 的关联关系。
• 多模式运行：支持自动检测模式、增量模式、背景信息模式和 --fast 模式。
• 质量检查：用户故事遵循 INVEST 原则（Independent、Negotiable、Valuable、Estimable、Small、Testable），验收标准可量化可验证，每个用户故事至少 2 条验收标准。
• 上下文管理：按功能点分批扩写，以首个功能点的 US/AC 作为质量锚点，每个功能点完成后执行一致性自检。
• 语言规则：支持中英文提问，统一中文回复，使用中文生成文档。

使用方式

运行模式：

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

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

初始模式工作流程：收集原始需求（记录用户原话或关键表述、标记来源、记录日期）→ 理解需求并探索代码库 → 进入 Plan 模式呈现需求拆解方案（功能点划分、边界范围、优先级）→ 用户审批 Plan → 退出 Plan 模式生成需求文档，识别功能点 → 编写用户故事 → 编写验收标准 → 生成追溯矩阵 → 用户确认。

增量模式工作流程：扫描现有编号（读取 01-requirements.md，获取 F/US/AC 最大编号）→ 收集新增原始需求（追加到 ## 0. 原始需求 表格）→ 理解新增需求 → 追加功能点/用户故事/验收标准（延续现有编号，标注增量版本和日期）→ 更新追溯矩阵 → 用户确认 → 返回新增编号列表。

背景信息模式工作流程：读取现有文档（检查 01-requirements.md 是否存在，提取现有“背景与目标”章节内容）→ 收集背景信息（引导用户提供、接收直接输入、从文件路径提取、从 URL 提取摘要）→ 整合信息到“背景与目标”“技术约束”“参考资料”子章节 → 更新文档 → 用户确认。

输出文件：主文件为 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. 风险与假设。

适用场景

• 新功能需求：被 /devdocs-feature 调用，新功能触发需求追加。
• 洞察转化：被 /devdocs-insights 调用，改进建议转化为需求。
• Bug 暴露需求：被 /devdocs-bugfix 调用，Bug 修复发现需求缺失。
• 项目改造：被 /devdocs-retrofit 调用，逆向推导生成需求。
• 改造后补充背景：逆向完成后用 --context 补充背景。
• 设计阶段：需求确认后进入 /devdocs-system-design。
• 上下文生成：背景信息会被提取到上下文摘要（/devdocs-onboard）。

限制

• 阶段边界约束（最高优先级）：本 Skill 仅产出文档，严禁编写或生成任何实现代码（源代码、脚本、配置变更）。Write 工具仅用于写入 docs/devdocs/ 下的 Markdown 文档。编码实现由 /devdocs-dev-workflow 负责。
• 功能点约束：每个功能点必须有唯一编号 (F-XXX)，必须标注优先级 (P0/P1/P2)，描述应简洁明确。
• 用户故事约束：每个用户故事必须关联到功能点，必须遵循“作为...我希望...以便...”格式，每个功能点至少有 1 个用户故事。
• 验收标准约束：每个验收标准必须有唯一编号 (AC-XXX)，每个用户故事至少有 2 条验收标准，必须可量化、可验证，必须描述验证方式。格式选项包括表格格式（默认，适合简单条件）和 Given-When-Then（适合复杂行为场景）。
• 追溯约束：必须提供追溯矩阵，所有功能点必须有对应的用户故事，所有用户故事必须有对应的验收标准。
• 增量模式约束：必须先扫描现有编号并延续编号，追加内容必须标注增量版本和日期，不得删除或覆盖现有内容，完成后必须返回新增编号列表。
• 原始需求约束：初始模式必须在 F/US/AC 精化前收集原始需求并写入 ## 0. 原始需求；增量模式新增需求必须追加到该表格；背景信息模式不写入该章节（除非用户提供的是需求原话而非背景补充）；原始需求应保留原话或最小必要改写；历史文档若无该章节，标注“缺失历史原始需求”后继续。
• 背景信息模式约束：必须先读取现有“背景与目标”章节内容，不得删除或覆盖现有背景信息，新增内容必须标注更新日期，URL 引用必须使用 WebFetch 提取摘要，文件引用必须使用 Read 验证文件存在，敏感信息（密钥、密码、内部 URL）不得写入文档，参考资料必须注明用途和关联性。
• Plan 模式约束：初始模式理解需求并探索代码后必须进入 Plan 模式，Plan 必须包含功能点划分和范围边界，用户审批 Plan 后才能开始编号分配和文档写入，用户要求调整时更新 Plan 后重新审批，增量模式和背景信息模式不使用 Plan 模式。
• 确认约束：必须与用户确认功能点是否完整，不得添加用户未提及且未确认的功能。
• 上下文管理约束：后批次 US/AC 详细程度不低于首批次，每个功能点完成后执行一致性自检。

子 Agent 摘要格式

当本 Skill 作为子 Agent 运行时，返回结构化摘要，包含 skill、mode（initial | incremental）、new_ids（features、stories、acceptance）、status、output_files 等字段。

下一步建议

• 初始模式：/devdocs-system-design 进入系统设计。
• 增量模式：/devdocs-system-design 增量设计或 /devdocs-test-cases 补充测试。
• 背景信息模式：继续 /devdocs-requirements 定义功能点，或 /devdocs-system-design 设计。
• 文档变更较大时，建议运行 /agent-memory 同步记忆文件。