bitcjm/workbuddy-skills/req-doc-writer

需求文档撰写技能（req-doc-writer）

一、总览

本技能定义了从「收到参考资料」到「交付确认版需求文档」的完整流程，核心原则：

初稿即精简。 不在第一阶段写复杂版、第二阶段再大幅删改——浪费资源且绕路。从初稿就按最终交付标准写。

AI 先自审自改 3 轮，再交给用户确认。 用户收到的是经过打磨的文档，不是粗稿。

流程分为 4 个阶段：

阶段1: 资料分析 → 阶段2: 初稿撰写 → 阶段3: 多轮自审自改(3轮) → 阶段4: 交付确认

二、阶段1：资料分析

2.1 读取所有参考资料

用户通常会提供：

• 参考模板（.docx/.pdf/.md）——决定了文档的结构和格式
• 业务资料（截图、PDF、说明文档）——决定了文档的内容
• 口头补充说明——用户的补充要求

动作清单：

1. 列出用户指定目录下的所有文件（用 Glob）
2. 逐一读取：图片用 Read（支持多模态识别）、文档用对应 skill（docx/pdf）或 Bash 解压读取
3. 如果某个文件读取失败，记录下来但不阻塞，继续处理其他文件

2.2 分析模板结构

从参考模板中提取：

• 章节结构：有哪些一级/二级/三级标题
• 表格格式：版本记录表、需求表、验收表等的列定义
• 特殊段落：引用块、代码块、注意事项等的格式
• 文档元信息：版本号规则、变更记录方式

输出：在心里形成模板骨架，后续写作严格按此骨架填充。

2.3 分析业务内容

从业务资料中提取：

• 核心实体：涉及哪些系统、角色、流程
• 字段清单：表单有哪些字段，哪些必填哪些选填
• 交互细节：字段的填写方式（下拉选择/树形展开/搜索/手动输入）
• 业务规则：字段的约束条件、依赖关系、默认值
• 截图信息：每张截图展示的界面，与表单字段的对应关系

关键原则：场景定义要从「用户真实痛点」出发，不是从「AI能做什么」出发。

三、阶段2：初稿撰写

3.1 标准文档结构

根据模板和业务分析结果，按以下结构撰写（可按模板调整）：

# 文档标题
 
## 文档版本记录
  - 表格：序号 | 版本 | 变更人 | 变更时间 | 变更内容概要
  - 规则：初稿阶段所有变更合并在同一行，版本号不变；正式评审后才升级版本号
  - 预留5行空白行供后续填写
 
## 1. 项目背景
  - 现状描述（精确到数字：月单量、耗时、错误率）
  - 痛点列表（每个痛点有具体表现，不说空话）
  - 引入方案的简述
 
## 2. 需求目标
  - 编号列表（R1, R2, R3...），每条目标一句话，可验证、可量化
  - 不需要优先级列（P0/P1/P2），所有目标都应是要达成的
  - 如需标注核心程度，在编号后加注即可（如 `R1【核心】`），不另开一列
 
## 3. 业务场景
  - 每个场景包含：场景描述、输入示例、AI/系统需处理的字段或逻辑、截图（如有）
  - 场景之间说明关系（互斥/叠加/依赖）
  - 场景定义原则：从用户痛点出发，不从技术能力出发
  - **多数据源/多通道提示**：如果场景涉及数据源选择，需标注（a）数据源类型、（b）路由策略、（c）降级方案
 
## 4. 功能需求
  - 按4.1~4.N分小节，每节用表格：功能点 | 说明 | 优先级（可选）
  - 优先级列按需使用，非必填；功能点同等重要时省略该列
  - 在相关功能点旁嵌入截图（用相对路径：![alt](截图/xxx.jpg)）
 
## 5. 非功能需求
  - 表格：类别 | 要求
  - **定性优先**：以定性描述为主（如"响应流畅"、"数据准确"），避免"准确率≥99%"等无法验证的定量指标
  - 如必须写定量指标，确保与验收标准数值一致且可验证
 
## 6. 验收标准
  - 两种格式可选：
    - **表格式**：验收模块 | 验收标准 | 验收方式（适合验收项少、结构简单的场景）
    - **编号制**：编号 | 验收项 | 验收方式与指标（适合验收项多、需精确追溯的场景，如差旅申请、智能体矩阵）
  - 按模块聚合，不逐条罗列功能需求的每一点
  - 验收标准中的数值必须与非功能需求一致
 
## 7. 项目交付物
  - 编号列表
 
## 8. 附录
  - 附图索引：序号 | 文件名 | 内容描述 | 正文引用位置
  - **从简**：只保留必要的附图索引和术语表（按需），不堆砌流程图、架构图、知识库清单等非必需内容

3.2 写作规则

1. 版本记录：初稿阶段（v1.0 初稿），无论改多少次，都记在同一行；正式评审后才升版本号
2. 版本升级：定稿后如需出修订版，复制为新文件再改（如 xxx-需求文档V2.md），旧版文件不动作为历史存档。在V2中新增一行版本记录说明变更
3. 截图嵌入：在正文对应位置嵌入，不在文末集中展示；附录只做索引
4. 场景定义：必须从用户痛点出发。判断方法——如果去掉AI这个技术，这个需求还存在吗？如果不存在，就是伪需求
5. 字段映射：如果有表单截图，AI需要填写的每个字段都要在场景中列出提取逻辑
6. 数值一致：非功能需求和验收标准中出现的同一指标，数值必须一致
7. 验收标准：按模块聚合（如"AI理解与填单准确率"、"性能与响应时间"），不逐条罗列功能需求
8. 衔接文字：截图前后要有衔接描述，不能凭空出现一张图
9. 篇幅控制：初稿即精简，正文控制在合理篇幅内；避免过度展开技术实现细节（除非用户明确要求）
10. 定性优先：非功能需求以定性描述为主，不写"准确率≥99%"之类无法验证的定量指标
11. 附录从简：只保留必要的附图索引和术语表，不堆砌流程图/架构图/知识库清单等内容
12. 联系人署名：文档末尾统一署约定的部门名称或联系人信息，不用个人姓名

3.3 写完初稿后

• 立即写入文件，不要只在对话中说"草稿已完成"
• 文件命名：{场景名}-需求文档初稿.md
• 写入后用 Read 工具确认文件内容完整

四、阶段3：多轮自审自改（3轮）

核心原则：用户不应该看到粗稿。AI 必须自己先打磨 3 轮，再交给用户。

3.1 审查维度

每轮审查聚焦不同维度：

3.2 审查方法

每轮审查的执行步骤：

1. 用 Read 工具通读全文，按上述检查项逐条核对
2. 列出发现的问题（编号清单，在对话中展示）
3. 用 Edit 工具逐条修复
4. 修复后再次 Read 确认修改到位

3.3 修改规则

• 每轮修改后更新文档版本记录的"变更内容概要"（初稿阶段仍为同一行，追加修改说明）
• 不改变已确认的内容方向，只修结构和表达
• 如果发现需要用户决策的问题（如"是否需要OCR场景"），在文档中标注"待确认"，不要自行决定

五、阶段4：交付确认

5.1 交付物

• Markdown 文件（主交付物）
• 截图已嵌入正文（相对路径引用）

5.2 交付时告知用户

1. 文件路径
2. 已完成的自审轮次和主要修改
3. 文档中标注"待确认"的位置列表
4. 确认文档末尾已署名（约定的部门名称或联系人信息）
5. 询问用户是否有修改意见

5.3 用户确认后的修改

• 用户提出的修改意见，直接修改文件
• 修改后再次 Read 确认
• 修改过程中不变更用户已确认的内容方向
• 用户修改后必须全文重读：用户改过文档后（无论是直接编辑还是提修改意见），用 Read 工具全文重读，检查：
• markdown 表格是否完整（有无行合并到标题）
• 标题层级是否连续
• 章节编号是否断裂
• 新旧内容是否有残留（用户删掉的内容是否在其它章节还有旧版本）
• 全局替换意识：用户说"把场景X换成场景Y"时，不能只改场景列表，要搜索旧场景名称出现的所有位置并逐一修改
• 版本记录处理：用户修改后再由AI修改时，应在版本记录中新增一行，不覆盖用户的修改记录

六、踩坑经验

七、快速检查清单（交付前必过）

• [ ] 文件已实际写入磁盘（不是只说了"已完成"）
• [ ] 章节结构与模板一致
• [ ] 版本记录正确（初稿合并一行）
• [ ] 截图已嵌入正文对应位置
• [ ] 附录有附图索引，标注正文引用位置
• [ ] 非功能需求与验收标准的数值一致
• [ ] 验收标准按模块聚合
• [ ] 无空话/套话（每条描述都可验证）
• [ ] 场景从用户痛点出发
• [ ] 非功能需求以定性为主，无可验证的定量指标
• [ ] 附录从简，无堆砌内容（流程图/架构图/知识库清单等）
• [ ] 文档末尾署名（约定的部门名称或联系人信息）
• [ ] 正文篇幅精简，无过度展开的技术实现细节
• [ ] 用户修改后已全文重读验证结构完整性
• [ ] 全局替换操作（如场景替换）已搜索所有出现位置
• [ ] 场景分类维度统一（不同维度的场景已标注正交关系）
• [ ] 多通道/多数据源场景：性能指标逐通道标注，验收标准含可行性验证
• [ ] 入口/集成点在§4.4/§4.5/§6中描述一致
• [ ] "待确认"标记已列出
• [ ] 3轮自审已完成