req-doc-writer

name	req-doc-writer
version	2
description	需求文档撰写技能。从资料分析→初稿撰写(直接写精简版)→多轮自审自改→交付确认的完整流程。 核心理念：初稿即精简，不做"先复杂再精简"的绕路。 适用于：业务需求文档、产品需求文档（PRD）、AI场景需求文档等。 触发词：写需求文档、撰写需求、需求文档初稿、PRD、写需求。
trigger	["写需求文档","撰写需求","需求文档初稿","PRD","写需求","需求初稿","requirement document"]
agent_created	true

需求文档撰写技能（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 审查维度

每轮审查聚焦不同维度：

轮次	审查重点	具体检查项
第1轮	结构与完整性	① 章节是否按模板完整 ② 表格列是否齐全 ③ 截图是否都嵌入 ④ 版本记录是否正确 ⑤ 章节编号是否连续 ⑥ 非功能需求是否定性为主 ⑦ 附录是否从简（无堆砌） ⑧ 文档末尾是否有署名 ⑨ 正文篇幅是否精简合理
第2轮	内容逻辑与一致性	① 非功能需求与验收标准的数值是否一致 ② 场景之间是否矛盾 ③ 功能需求的优先级是否合理 ④ 术语是否全文统一 ⑤ "待确认"标记是否遗漏 ⑥ 场景分类维度是否统一（如按查询策略分类 vs 按数据源分类，不同维度的场景不应混在同一列表中，需明确标注维度关系） ⑦ 多通道/多数据源场景：性能指标和验收标准是否逐通道标注（不能一个数值覆盖所有通道） ⑧ 入口/集成点一致性：§4.4 交互设计、§4.5 系统集成、§6 验收标准中关于入口位置的描述是否一致
第3轮	表达与细节	① 截图前后的衔接文字是否通顺 ② 是否有空话/套话（如"提升用户体验"）需替换为具体描述 ③ 场景是否从用户痛点出发而非技术能力出发 ④ 文档版本记录概要是否准确反映所有变更 ⑤ 架构扩展性检查：当需求提到"同时支持X和Y"时，是否在功能需求中明确了抽象层设计、适配器模式、路由策略，并在验收标准中加入了可行性验证项

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修改时，应在版本记录中新增一行，不覆盖用户的修改记录

---

六、踩坑经验

#	踩坑	教训
1	说"草稿已完成"但没写文件	写完立即写入文件，不要只停留在对话中
2	场景二写了"OCR提取行程单"但用户没有这个诉求	场景定义从用户痛点出发，不是从AI能力出发。判断方法：去掉AI技术，需求是否仍然存在？
3	非功能需求写≥95%，验收标准写≥90%	同一指标在两处出现时数值必须一致，写完后要交叉校对
4	4.4/4.5章节顺序错乱	多次 Edit 后要通读确认编号连续，写完必须 Read 全文验证
5	版本记录每个修改都新增一行	初稿阶段所有变更合并在同一行，正式评审后才升级版本号
6	截图只在附录列出，正文没有	截图嵌入正文对应位置，附录只做索引
7	验收标准逐条罗列功能需求的每一点	验收标准按模块聚合，如"AI理解准确率"一个模块覆盖多个功能点
8	.docx 文件 Read 工具无法直接读取	用 Bash 解压 docx 读取 word/document.xml，或用 pandoc 转换
9	PDF 文件 Read 工具有时无法读取	先尝试 Read，失败后用 pypdf 提取文本，再失败则基于文件名和上下文推断内容
10	场景四是"按数据源分类"却被放在"按查询策略分类"的场景列表里	场景分类维度要统一：不同分类维度（查询策略 vs 数据源类型 vs 用户角色）的场景不应混在同一层级。若存在多维度场景，应明确标注各维度的正交关系
11	用户要求"同时支持数据库和MCP"但初稿只写了API结构化参数	多通道/多数据源需求：当用户说"同时支持X和Y"时，必须（a）在功能需求中明确数据源抽象层和适配器设计、（b）增加数据源路由策略、（c）在验收标准中加入可行性验证项、（d）性能指标逐通道标注
12	用户修改入口位置后，§4.4/§4.5/§6中入口描述不一致	入口/集成点一致性检查：修改入口位置时，必须同步检查§4.4交互设计、§4.5系统集成、§6验收标准、§7交付物中所有涉及入口/集成点的描述
13	V1 定稿后直接在原文件上改 V2，旧版丢失	定稿后复制为新文件再改，如 xxx-需求文档V2.md，旧版文件不动作存档
14	用户说"去掉准确率"但非功能需求/验收标准中仍有残留	用户明确说"去掉XX"时，全文搜索该关键词（用 Grep），确保零遗漏
15	用户替换示例场景后，§3/§4/§6 仍有旧场景名残留	场景替换是全局操作，需搜索旧场景名出现的所有位置并逐一修改
16	用户修改文档后 markdown 表格与标题合并损坏	每次用户修改文档后必须全文重读验证，检查表格完整性、标题层级、编号连续性
17	删节后附录编号断裂（如附录B表格尾部合并到标题行）	删节后逐节检查编号连续性，包括附录编号和表格行结构

---

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

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