语义级需求文档撰写（Semantic PRD Writing）

为什么叫 semantic

需求文档的缺陷分两层，处理成本差一个量级：

结构层靠模板与清单就能解决，语义层不能。本技能的定位是：把任意形态的输入整理为语义闭合的文档——每个名词有定义，每个数值有来源，每条规则无二义，每处分支不冲突。

与其他技能的分工

下游依赖安装（不在本仓库）：prd-review 与 prd-to-prototype 须通过 SkillHub 安装，说明见 SkillHub 安装与优先源配置。优先使用 skillhub（不可用再回退 clawhub）。安装时必须指定当前 Agent 的 skills 目录，例如：

skillhub install prd-review --dir ~/.cursor/skills/
skillhub install prd-to-prototype --dir ~/.cursor/skills/

（其他客户端将 --dir 换成对应 skills 路径，见安装说明第四节。）

探测与交接（启发式，不可硬失败）：

1. 需要评审或原型前，可检查当前 Agent skills 根下是否存在 prd-review / prd-to-prototype 目录（Cursor 常见为 ~/.cursor/skills/；路径因客户端而异，探测失败不得阻断本技能写 PRD）。
2. 已安装：明确交接——已落盘的 PRD 路径 + 建议用户触发的下一意图（如「用 prd-review 评审这份文档」/「用 prd-to-prototype 澄清并出原型」）；不得含糊说「你可以去评审一下」。
3. 未安装：贴出可复制安装命令（含 --dir 说明），声明本技能可继续写完 PRD，评审/原型可后补；未安装时用阶段 0 最小澄清集或假设/待决推进。
4. 禁止在本仓库空搜这两个 skill 的源码；禁止假装已交接或本技能内冒充独立评审/原型生成。

核心判断标准：文档写完时，产品、UX、UI、前端、后端、测试六个岗位都不需要自行发明业务规则就能开工。

核心原则

1. 先定范围，再写内容。未确定 L1–L4 分级就动手写章节，是本技能最主要的失败模式。
2. 业务单元是承重结构。按业务闭环切分单元，不按页面、章节或按钮切分。单元切分方式决定后续所有章节的组织形式。
3. 不脑补业务决策。凡推断、行业惯例、模型补充的内容，登记到假设表，不得写成已确认事实。
4. 不留空表。每个表项要么填写，要么显式写"不适用"。空白行等于把业务决策推给下游。
5. 每个需求挂指标，每条规则可验收。挂不上指标的需求大概率可以砍掉。
6. 章节写对了不等于文档成立。两处规则各自成立、合起来冲突，是最贵的缺陷形态；交付前必须跨表核对。

阶段总览

阶段 0 定级与打标签     产出：定级结论一行          完成信号：用户确认级别与条件标签
阶段 1 建立全局地图     产出：16 信息域证据状态底稿   完成信号：每域只有四种合法取值之一
阶段 2 切分业务单元     产出：单元清单表             完成信号：每单元能独立走完一个闭环
阶段 3 填写单元规格     产出：10 项规格 × N 个单元    完成信号：十项无空项，异常九类已判定
阶段 4 写横切规格       产出：状态机/权限/口径/消息   完成信号：四类横切表齐备且互不重复
阶段 5 写验收标准       产出：AC 清单（编号唯一）      完成信号：每条可写出三要素
阶段 6 语义闭合与门禁   产出：§5§7 基线 + §14（含 §14.6）门禁  完成信号：脚本 + 六道门禁全通过

工作流

阶段 0：定级与打标签（强制前置）

收到需求后第一步，不做其他事。

判断 L 级别（依据实际影响，不依据篇幅）：

记录条件标签（只记会改变检查标准的）：内部系统/商业化/SaaS｜B 端/C 端/平台基础服务｜新建/迭代/迁移/下线｜Web/Mobile/多端｜含 AI 功能｜外部系统集成｜强监管或敏感数据。

信息不足时的最小澄清集（最多问这三项，不要展开成多轮问卷）：

1. 本次需求覆盖多大范围——改一个配置项、一条规则、一个完整模块，还是一个新系统？
2. 涉及哪些角色，以及哪些使用端？
3. 是否涉及监管合规、资金、敏感数据或不可逆操作？

若用户明确表示"按你判断"，则自行定级并在文档 §0 中标注为待确认。

完成后：输出一行定级结论（如"判定为 L3 模块级，标签：内部系统 / B 端 / 迭代 / 含 AI 功能"），向用户确认后再进入阶段 1。

阶段 1：建立全局地图

读取 references/template-core.md 中的全局信息域基线（§5），用 16 个信息域逐项盘点已有信息。索引入口见 references/template.md；背景/用户等扩展章节见 template-extra.md（按 L/标签再读）。

对每个信息域标注证据状态，只允许四个取值：

• 明确：文档或用户输入中已清晰说明
• 缺失：完成当前范围所必需，但没有任何依据
• 歧义：存在两种以上合理解释，会导致不同实现或验收
• 冲突：两个或多个明确表述不能同时成立

关键禁令：不得把推断写成"明确"。凡来自行业惯例、常识或模型补充的，一律记为「缺失」，并进入阶段 3 的假设表。

盘点结果不写入最终文档（除需向用户说明关键缺口时），仅作为内部工作底稿。

本阶段是收集语义，阶段 6 是核对语义——同一套 16 域，先记状态，末尾复验。

阶段 2：切分业务单元

按业务闭环切分，识别标准是"能形成一个完整的判断闭环"，例如：

• 创建—提交
• 审批—驳回—重提
• 执行—延期
• 验收—关闭

横向单元按条件标签补充，非全量必填：状态机、权限体系、页面族（列表/详情/新增/编辑）、数据与统计口径、消息机制、跨端行为、外部集成、异常与历史数据。

切分禁忌：不要把孤立字段或单个按钮切成独立单元。

完成后：输出单元清单表，向用户确认单元划分与优先级。

阶段 3：填写单元规格

对每个单元，按 10 项链路依次填写。字段定义、填写要点与常见错误见 references/unit-card.md。

进入条件 → 入口与操作 → 输入与校验 → 业务规则
  → 状态变化 → 数据变化 → 页面反馈 → 后续动作 → 异常与边界 → 可验收结果

填写要求：

• 页面反馈必须覆盖五种形态：成功、失败、处理中、无权限、数据已变化
• 异常与边界表（第 9 项）逐项标注"相关/不适用"，不相关写"不适用"，不留空
• 业务规则必须写明条件、约束、计算公式（含精度与舍入）、限额、去重、时效
• 可验收结果（第 10 项）引用验收章节的 AC 编号，形成双向可追溯

阶段 4：写横切规格

集中处理跨单元的内容，避免在单元中重复：

• 状态机：当前状态｜动作/事件｜操作角色｜条件｜目标状态｜数据副作用｜失败结果。必查孤立状态、无入口状态、无出口状态、同一动作多结果、逆向流转、终态重开、超时转换
• 权限矩阵：角色｜对象/页面｜可见数据范围｜允许操作｜状态条件｜字段限制
• 字段与统计口径：同一字段在录入、详情、列表、导出、统计五个场景中的含义必须一致；每个指标必须有唯一编号
• 消息与触达：触发事件｜接收人｜内容要点｜渠道｜时机｜频控｜失败处理

权限描述的硬规则：禁止使用"按权限展示""管理员可操作""相应权限的用户"等笼统表述，必须给出具体角色与条件。

阶段 5：写验收标准

逐条写 Given / When / Then。

自检口径：每条 AC 都应能让测试直接写出「前置条件—操作—预期结果」三要素。写不出来的，说明验收标准尚未定义完成。

编号规则：AC 编号在文档内唯一且连续，被单元规格第 10 项（可验收结果）、用户故事、指标验收引用。引用必须指向真实存在的编号——这是阶段 6 编号闭合检查的一半。

阶段 6：语义闭合与门禁

本阶段做三件事，顺序不变。

6.1 填两张基线表

• §5 全局信息域基线：把阶段 1 的盘点结果落进文档，16 域逐项标证据状态
• §7 全局一致性基线：8 项跨章节复核（术语角色对象状态是否一一对应、每个动作是否有合法前态与结果、图表与正文是否一致、权限矩阵是否与页面按钮一致、字段在五个场景含义是否一致、多端与批量规则是否统一、消息指标是否引用真实对象、新规则是否影响历史数据）

6.2 语义闭合自检（七类不变式）

判据、核对方法与失效后患见 references/semantic-closure.md。速查：

七类中第 1、4 类可由脚本筛查，其余须人工核对。逐章检查发现不了这类缺陷，必须跨表核对。

6.3 跑门禁

六道，详细判级规则见 references/gates.md；文档落点见模板 §14.1–§14.6（其中 §14.6 对应第六道语义闭合）：

1. 好需求 8 个特点（§14.1）
2. P0 门禁清单（8 条阻塞特征）（§14.2）
3. 六岗位开工就绪度（Ready / Conditional Ready / Not Ready）（§14.3）
4. 假完整句式黑名单（§14.4）
5. 证据状态检查（§14.5）
6. 语义闭合门禁（七类不变式逐类判定）（§14.6）

自动校验：文档落盘后运行结构校验脚本：

python scripts/check_prd.py <path/to/prd.md> --level L3

脚本检查章节完整度、未替换占位符、黑名单句式、空表格行、编号族闭合、比值分母闭合、表格列数一致性。悬空编号引用、有比值却无分母 → 默认 P0（硬门禁，无软开关）；逐条修复后重跑，直到无 P0/P1。--level 决定章节要求宽严。建议仅在阶段 6 交付前运行。每条问题末尾带 ｜ 修复：… 短锚点；排障见 references/troubleshooting.md。

机检失败时 Agent 必说清单（禁止只粘贴原始 stdout/stderr）：

1. 阻塞摘要：P0 / P1 计数；有 P0 必须声明不可交付。
2. 人话：用一两句解释最高优先级问题在说什么。
3. 落点：应改的章节、表或编号族。
4. 最小改法：具体改哪一句/补哪一行（可引用脚本锚点）。
5. 重跑命令：同一路径与 --level，改完再跑直至无 P0/P1。
6. 用户仍困惑时，引导打开 troubleshooting.md；需要对照失败形态时打开 examples/broken-prd.md + broken-prd-expected.md。

写作硬规则

完整清单与替代写法见 references/writing-rules.md。以下是不可违反的底线：

1. 禁止假完整句式。机检真源为 scripts/check_prd.py 的 BLACKLIST。写作期可见摘要（无具体规则支撑即为缺陷）：

更多替代写法见 references/writing-rules.md。

2. 禁止把推断写成事实。推断进入假设表：假设内容、依据、若不成立的影响、确认人、状态。
3. 禁止用名词堆砌代替规则。"完善的权限管理体系""灵活的配置能力"属于无约束价值表述。
4. 禁止伪造精确数字。未实际统计过的字数、比例、性能数字不得出现。
5. 禁止用"用户"指代角色。同一系统里"新注册用户"和"老用户"常是两套规则。
6. 不去决定工程实现细节。数据库类型、索引、varchar 长度、API 风格不属 PRD 必填项。

输出规范

• 文件名：{系统或模块名}-PRD-v{n}.md
• 版本迭代：新增内容时复制为新版本号文件（v1 → v2 → v3），不覆盖原文件
• 结构：按 L 级从 references/template-core.md（及按需 template-extra.md）复制章节骨架；索引见 template.md。不自行增减必备章节
• 占位符：模板中以 ___ 或空表格表示待填项，交付前必须全部替换或标注"不适用"
• 交付前：确认 §0 的"整体结论"栏与 §14.3 的岗位就绪度一致

交互原则

• 信息不足时先问，不要编。用阶段 0 的最小澄清集，最多三项问题
• 不在本技能内做多轮选择题追问。需要深度澄清 + 原型时：先按上文探测 prd-to-prototype；已安装则交接路径与下一意图；未安装则贴安装命令并用最小澄清集或假设/待决兜底
• 需要独立评审时：先探测 prd-review；已安装则交接 PRD 路径与「用 prd-review 评审」意图；未安装则贴安装命令，同时可用本技能门禁继续完善文档
• 三个确认点：定级后、单元清单后、门禁自检后各确认一次
• 门禁不过时不粉饰。P0 存在就如实标注 Not Ready，不用其他项的得分抵消
• 机检失败按时清单说明，不要只丢脚本原文
• 发现跨表冲突时不要自行消解。两处规则冲突说明有一处业务决策未定，应转为待决问题交用户拍板，而不是替用户选一个

资源

样例默认只链不灌：不要在阶段 0 把 examples 目录全文加载进上下文。假完整句式机检真源仍是 scripts/check_prd.py 的 BLACKLIST；样例只演示。