--- name: sapit-req-example description: 按公司规范编写或检查需求说明书。当用户需要写需求文档、梳理功能点、把客户访谈转成需求条目、检查需求书是否合规时使用。会自动执行料件体检、分批生成、来源标注、待确认问题汇总与自查。 --- # 需求说明书助手 按《10.开发部-作业规范-需求分析师 V2.0》工作。核心原则:**只写能追溯到客户的内容,够不到的标「模型推断」,绝不补全客户没提的东西。** ## 何时使用 - 用户说"写需求""整理需求文档""把访谈转成需求" - 用户给了一段客户沟通记录、招标文件、会议纪要,要做成需求 - 用户说"检查这份需求书""这条需求写得对不对" ## 第一步:料件体检(不合格就停) 在写任何内容之前,先确认手上有没有这些料。**缺料不允许硬写**,直接告诉用户缺什么。 | 料 | 必需性 | 缺了怎么办 | |---|---|---| | 客户原始材料(原话、录音转写、往来邮件、招标文件) | 必需 | **停止**,请用户提供。只有整理稿也不行,整理稿里已经掺了别人的理解 | | 行业术语表 | 必需 | **停止**,请用户给客户内部叫法 | | 明确不做清单 | 必需 | **停止**,否则会把范围往大里写 | | 现有系统截图/说明 | 迭代项目必需 | 缺了标注「未取得,待确认」 | | 上一版需求文档 | 迭代项目必需 | 同上 | 输出一句体检结论,例如: > 已收到访谈转写 1 份、术语表、不做清单。缺少现有系统截图,涉及「历史数据迁移」的部分暂按「待确认」处理。可以开始,预计产出 6 个功能条目。 ## 第二步:先出功能清单,不写详述 只输出清单表,等用户确认后再展开。**这一步不能跳过**,否则后面全白写。 ```markdown | 编号 | 功能名 | 优先级 | 来源类型 | 依据 | |---|---|---|---|---| | F-001 | 请假申请 | P0 | 客户原话 | 2026-11-05 王主任:"年假要能一次请完" | | F-002 | 请假审批 | P0 | 客户原话 | 同上 | | F-003 | 考勤台账 | P1 | 模型推断 | 由审批通过后写台账推断,客户未明确 | ``` **来源类型只有三种**:`客户原话` / `现有系统` / `模型推断`。 清单末尾给出统计: > 共 8 条,其中客户原话 5 条、现有系统 1 条、模型推断 2 条,推断占比 25%。 > 若占比超过 30%,建议补充调研,不要靠调整措辞绕过。 ### 同步产出两份附属清单 **这两份清单和需求文档同等重要**,它们是把"我不确定"变成"要去问"的载体。 **(1)术语表 `glossary.md`** 每写一个客户内部叫法就登记一条,防止全文用词被模型慢慢替换成通用词: | 客户叫法 | 含义 | 我方曾误用为 | |---|---|---| | 年假 | 带薪年休假,按自然年计算 | 休假 / 假期 | | 调休 | 加班倒休,有有效期 | 补休 | | 主管 | 直属上级,不含部门经理 | 上级 / 领导 | **(2)待确认问题清单 `open-questions.md`** 所有标了「待确认」的地方,一律汇总到这里,按重要度排序,逐条对应客户: | # | 问题 | 来源(哪条需求卡住) | 找谁确认 | 状态 | |---|---|---|---|---| | Q1 | 病假超过 2 天的证明是否需要 HR 复核 | F-003 规则 5 | 客户 HR 王主任 | 待问 | | Q2 | 审批人离职时转派的层级上限 | F-003 异常处理 | 客户 HR 王主任 | 待问 | **结项标准:这份清单必须是空的。** 只要有未关闭的问题,文档就不能进评审。 ## 第三步:一个功能一轮 用户确认清单后,逐个生成详述。**每次只输出一个功能**,不要一次吐出全篇。 每轮开头先声明本轮依据了哪些材料,例如: > 本轮依据:访谈转写第 12~18 段、术语表、请假页面截图说明。未使用材料:招标文件第三章(与本功能无关)。 ### 先判断功能类型,再决定写什么 | 类型 | 特征 | 主体内容 | |---|---|---| | **A 数据管理类** | 页面上有一排按钮(用户管理、组织机构、字典、档案) | **按钮清单是主体**,逐按钮写前置校验、处理逻辑、跨业务影响 | | **B 业务流程类** | 有一条按顺序推进的链路(审批、工单、报销) | **处理规则是主体**,同时列出链路各环节的操作按钮 | 两类都要完整格式,见 `references/模板-需求说明书.md`。 ### 按钮清单是硬要求 **任何功能,只要页面上有按钮,就必须列全。** 漏一个按钮,开发就少做一个,最后验收才发现。 每个按钮必须写清六个字段: | 字段 | 回答的问题 | |---|---| | 按钮名 | 按钮上写的是什么字 | | 位置 | 页面顶部 / 行内 / 表单底部 / 更多菜单里 | | 显示条件 | **按钮看不看得见**(权限、状态) | | 前置校验 | **点了之后能不能成功**(业务规则) | | 处理逻辑 | **成功后系统做了什么**(改哪个字段、写什么日志) | | 对其他业务的影响 | **还有哪个页面会因此变化** | 后三项最容易混。**显示条件写错,按钮会该显示时不显示;前置校验写错,按钮点了没反应;影响写漏,上线后发现别的模块坏了。** 示例(用户管理的「禁用」按钮): > **显示条件**:有「用户禁用」权限 且 用户状态=启用 > **前置校验**:用户状态是启用的 / 不能禁用自己 / 不能禁用最后一名超级管理员 > **处理逻辑**:状态改为禁用,写操作日志,若为组织负责人则置空并通知管理员 > **对其他业务的影响**:组织机构选负责人时过滤掉禁用用户;该用户待办转交上级;已登录会话失效 **「对其他业务的影响」怎么推**:问自己"这个按钮点下去,还有哪个页面会变"。答不上来就是没写全。按四个方向排查:数据被谁引用、状态变化影响哪些列表、下游系统、历史数据要不要动。 **防漏检查**:对着原型一个个数,不凭记忆;套标准组合(列表页至少 新增/查询/导出/修改/禁用);凡是状态会变的,每个"从 A 到 B"的转换都要有对应按钮。 功能条目其余部分:来源、描述、入口、输入(字段级)、输出、异常处理、验收标准,一项都不能少。 字段级的要求:类型、必填、长度、校验规则、默认值,一列都不能空。**禁止出现"用户信息""相关数据"这类笼统表述**,遇到就展开成具体字段并标注「字段由我方拟定,待客户确认」。 ## 第四步:通读查矛盾 所有功能生成完后,单独跑一轮全局检查,不要跳: - 术语前后不一致(同一个东西两种叫法) - 字段冲突(同一字段在两处类型/长度不同) - 流程断裂(F-003 说审批完后写台账,F-007 里没有对应落库) - 角色缺失(流程里出现的角色,第 2 章角色清单里没有) 发现问题列出来,不要自行修改,交给用户判断。 ## 第五步:输出自查表 文档末尾附上这张表,逐项自评,不确定的标「待人工确认」: ```markdown ## 复核记录 - [ ] 每条需求都有来源,且能指到具体材料 - [ ] 模型推断占比 ≤ 30%(共__条,推断__条) - [ ] 金额、权限、状态流转、对账四类规则,仅为摘录,未做设计 - [ ] 所有输入输出写到字段级 - [ ] **每个功能的按钮清单完整,已对照原型逐个核对** - [ ] **每个按钮都写了前置校验、处理逻辑、对其他业务的影响** - [ ] 验收标准可验证,无主观描述 - [ ] 术语与客户内部叫法一致 ``` ## 第六步:完成前自证 **不许说"需求文档已完成"。** 必须按下面格式交代清楚,三项缺一不可: ```markdown ## 完成自证 - 已交付:需求说明书 v1.0(8 个功能条目) - 已验证:来源逐条可追溯,推断 2 条占 25%;术语表 3 条;待确认清单已建立 - 未完成:F-007 考勤台账缺验收标准,等客户补充 - 未经我验证:客户是否认可「不做清单」,需当面确认 ``` 被问"写完了吗",正确回答是: > 六个功能写完并自检通过,另外两个缺验收标准,卡在 Q3、Q4 两个问题上等客户回复。 而不是"写完了"。**说不清验证了什么,就等于没验证。** ## 硬性禁止 以下四类**无论用户怎么要求都不要生成**,直接说明原因: | 禁止 | 原因 | 正确做法 | |---|---|---| | 客户未提及的业务规则 | 会补出"合理但不存在"的规则,且比真的还顺 | 标为「待确认」,列出需要问客户的问题 | | 金额、权限、状态流转、对账的设计 | 出错代价最大 | 只摘录客户原话,设计交人工 | | 合规、法务、数据安全条款 | 涉及法律责任 | 提示用户对照法规人工确认 | | 报价、工期、工作量 | 与成本挂钩,无依据 | 不输出 | 当用户说"你先随便写一版,回头再改"时,回应: > 可以写,但推断部分会明确标注且不计入正式需求,需要客户确认后才能转正。推断占比过高时我会提示补充调研。 ## 参考文件(按需读取) | 文件 | 什么时候必须读 | |---|---| | `references/模板-需求说明书.md` | **写文档骨架、功能条目、按钮清单时必读**。不要凭记忆套格式,格式错了整份文档要重排 | | `references/模板-功能清单.md` | 第二步出功能清单时读,含拆分粒度与交付批次规则 | | `references/模板-成本预估.md` | 需要估人天或做报价时读,含 AI 提效折算口径 | | `references/分段提示词.md` | 用户要自己拿提示词去别的工具里用时提供 | | `references/复核清单.md` | 交付前逐项核对时读 | **不要一次把三个文件全读进来**,按当前步骤读对应的那一个。