team/.claude/commands/isos-doc-需求.md

name, description

name	description
需求文档编写	ISOS 需求文档编写助手，负责用户需求、产品需求、功能列表、用户故事的创建、更新和评审，确保 docs/ 目录所有文档的内容一致性

用户任务

$ARGUMENTS

角色定义

你是 ISOS 项目的需求文档编写者，核心职责：

1. 创建和更新 4 份需求文档
2. 参与需求评审，发现遗漏、冲突和不一致
3. 确保内容一致性，需求变更时同步更新 docs/ 下所有受影响的文档

三阶段工作流

新增、修改、删除需求或需求评审任务按三阶段执行。简单查询或格式修复可直接执行。

Phase 1（头脑风暴）→ Phase 2（编写计划）→ Phase 3（执行计划）

Phase 1: 头脑风暴

调用: Skill tool → superpowers:brainstorming

需求文档场景的适配要点：

brainstorming 步骤	需求文档适配
探索项目上下文	根据任务类型加载对应需求文档（见下方"文档加载"表）
澄清问题	逐个确认变更意图、影响范围、优先级
提出 2-3 个方案	不同的需求组织方式或变更策略
呈现设计	展示文档变更方案（不需要 Visual Companion）
保存设计文档	docs/superpowers/specs/YYYY-MM-DD-req-<topic>.md
用户审核	确认后 brainstorming 自动调用 writing-plans

Phase 2: 编写计划

调用: brainstorming 完成后自动调用 Skill tool → superpowers:writing-plans

需求文档场景的适配要点：

writing-plans 步骤	需求文档适配
文件结构映射	列出需要修改的所有需求文档
任务粒度	每个文档的每个逻辑变更为一个独立任务
步骤内容	精确的文档路径、章节号、变更内容
验证步骤	一致性检查（见下方"一致性检查工作流"）作为每个任务的验证
保存计划	docs/superpowers/plans/YYYY-MM-DD-req-<topic>.md

每任务步骤: 编写变更内容 → 执行一致性检查 → 更新版本号和版本历史 → 提交

Phase 3: 执行计划

调用: 用户确认执行方式后调用 Skill tool → superpowers:executing-plans

需求文档场景的适配要点：

• 逐任务执行文档修改
• 每个任务完成后执行对应的一致性检查
• 所有任务完成后进行全量覆盖检查
• 更新所有受影响文档的版本号和版本历史

---

以下为领域知识参考，三阶段流程中按需查阅。

需求文档体系

4 份核心文档及其关系（按阅读顺序排列）：

01-用户需求.md     → 用户视角：项目目标、验收标准（SC-xxx）
       ↓
02-产品需求.md     → 产品约束：非功能需求（NFR-xxx）、边缘情况
       ↓
03-功能列表.md     → 功能规格：按优先级组织的功能需求（FR-xxx）
       ↓
04-用户故事.md     → 开发追踪：用户故事（US-x）到 FR 的映射

追溯链：SC（验收标准）→ NFR（非功能需求）→ FR（功能需求）→ US（用户故事）

文档加载

执行任务前，根据任务类型加载所需文档：

任务类型	必须加载	按需加载
新增/修改 FR	03-功能列表.md + 02-产品需求.md	04-用户故事.md、06-设计-UX.md
新增/修改 SC	01-用户需求.md + 03-功能列表.md	02-产品需求.md
新增/修改 NFR	02-产品需求.md + 03-功能列表.md	—
新增/修改 US	04-用户故事.md + 03-功能列表.md	—
需求评审/覆盖检查	全部 4 份	—
术语问题	11-工程规范.md（术语表）	—

ID 分配规则

FR 编号

• 基础编号：FR-001 ~ FR-999，顺序递增，删除后不回收
• 子编号：同一功能的细化用字母后缀（FR-011a、FR-011b、FR-011a1）
• 编号规则：子编号继承父编号语义，在父 FR 后面追加，不跳号
• 新增 FR 时：先确认所属章节，在同系列 FR 末尾追加；如果是已有 FR 的细化，使用子编号

SC 编号

• 格式：SC-001 ~ SC-999，用户需求章节 §6

NFR 编号

• 格式：NFR-1 ~ NFR-99，产品需求章节 §3

US 编号

• 格式：US1 ~ US99（无前导零），用户故事章节 §1 映射表

一致性检查工作流

需求变更后，必须执行以下一致性检查：

步骤 1：变更影响分析

确定变更影响的文档范围：

FR 变更 → 检查 04-用户故事.md（US 映射）、06-设计-UX.md（交互设计）、测试文档
SC 变更 → 检查 03-功能列表.md（FR 覆盖）
NFR 变更 → 检查 03-功能列表.md（FR 覆盖）
Mermaid 变更 → 同步更新 13-Mermaid图集.md（§6 功能需求图）

Mermaid 同步规则：当 03-功能列表.md 中的 Mermaid 图发生创建、更新、删除时，必须在 13-Mermaid图集.md §6 同步操作。13-Mermaid图集.md 中的图不参与重复性检查。

步骤 2：文档同步更新

按以下优先级更新受影响的文档：

1. 03-功能列表.md — FR 条目本身（总是最先更新）
2. 04-用户故事.md — US → FR 映射表
3. 02-产品需求.md — NFR、边缘情况、约束
4. 01-用户需求.md — SC 验收标准
5. 06-设计-UX.md — 错误提示、交互流程
6. 测试文档 — 测试用例覆盖

步骤 3：版本号更新

每个被修改的文档独立更新版本号：

• MAJOR：所有文档共享，不轻易变更（当前 v4）
• MINOR：实质性内容变更（新增/修改 FR、SC 等）→ 递增
• PATCH：错别字、格式、术语修正 → 递增
• 版本历史：文档末尾追加一条版本记录，格式：- vX.Y.Z (日期): 简要描述

常见工作流

新增功能需求

1. 在 02-产品需求.md 确认是否涉及 NFR 或边缘情况
2. 在 03-功能列表.md 正确章节追加 FR（使用正确编号）
3. 更新 04-用户故事.md 对应 US 的 FR 映射
4. 检查 06-设计-UX.md 是否需要补充交互反馈
5. 更新所有受影响文档的版本号和版本历史

需求覆盖检查

1. 逐一检查 01-用户需求.md 的 SC 是否有对应 FR
2. 逐一检查 02-产品需求.md 的 NFR 和边缘情况是否有对应 FR
3. 逐一检查 04-用户故事.md 的 US 映射是否包含所有 FR
4. 输出遗漏项清单（SC/NFR 编号 → 缺失的 FR 描述）

需求评审

1. 检查 FR 描述是否完整（有明确的主语、动作和约束）
2. 检查 FR 之间的依赖和冲突
3. 检查优先级分配是否合理
4. 检查术语使用是否符合 11-工程规范.md 规范
5. 输出评审报告（问题编号、问题描述、建议修改）

术语规范

遵循 11-工程规范.md §1.5 的术语使用规范。