PRD Writing

写 / 改 / 重构 / 统一口径 需求文档时遵循本 skill。

1.1. 需要查产品体系 / 模块定位 / 业务领域知识 → 读 references/example-domain.md（示例文件，用户应替换为自己产品的领域知识）。 1.2. 需要完整反例 / 正例对照 → 读 references/examples.md（正文只留极简示例，多场景对照在那里）。 1.3. 动笔前 / 交付前检查清单 → references/checklist.md。 1.4. HTML 原型生成 → 用 html-prototype skill（视觉规范在那里，本 skill 只管文档）。

一、写作流程

2.1. 先确认上下文

动笔前只拉与当前任务直接相关的最小上下文：

1. MEMORY.md。
2. 当前系统 / 相关 PRD / 现有需求文档。
3. 涉及的同类模块（对齐口径用）。

不展开冗长背景考古。

2.2. 锁定对象粒度

写细节前先回答清楚：

1. 这是新对象，还是现有对象下的新类型 / 新能力？
2. 入口在哪一层？一级菜单、二级页、详情页、弹窗，还是已有流程中的一步？
3. 用户操作链路是什么？
4. 复用现有页面框架，还是新增页面？
5. 哪些现状约束不能打破？

新模块设计前，先拉通同层已有模块的概念边界，确认定位不与已有模块重叠。例如系统已有"结构化字段"类型模块，新模块就别再用同一抽象，要找自身独特定位。

以上不清楚之前，不要急着列字段表或算法。

2.3. 文档骨架

Planning / Roadmap PRD：

1. 需求概述。
2. 菜单结构 / 页面结构 / 产品结构。
3. 需求详情。
4. Roadmap。

Feature PRD：

1. 背景。
2. 目标。
3. 竞品对比。
4. 入口与结构定位。
5. 页面与交互。
6. 字段设计。
7. 规则 / 边界 / 异常处理。
8. 涉及 Agent / 算法时：后端与算法交互流程 + 算法处理流程。
9. 数据埋点 / 上线前确认 / 上线后观测。

数据类 PRD（看板 / 列表 / 详情）：

1. 需求概述（背景 / 目标）—— 涉及组默认不写；确需跨组协调时作者自己补。
2. 入口与产品结构。
3. 功能需求。
   1. 功能清单。
   2. 页面流转。
   3. 各页面 / 区域详情（按下方「层次原则」组织）。
   4. 指标口径定义（数据看板必备）。
4. 数据埋点。
5. 上线前确认 / 上线后观测。
6. 历史数据影响 / 与老系统迁移对照（迁移类必备）。

层次原则：按「页面 → 区域 → 模块 → 分支」逐层下钻，不要把不同层级的模块平铺到同一层。范例见 references/examples.md。

不写「方案价值」「范围说明」章节。功能边界由功能清单本身（列出本期做什么）隐含表达。

不写非功能 / 性能类需求：不写「非功能需求」表（性能 / 兼容性 / 可用性 SLA）、不在「上线后观测」放性能监控项（首屏 P95 之类）。上线后观测只留使用类（PV/UV、查询 / 导出 / 配置等操作频次）。性能 SLA 研发自有标准，PRD 不背书。

功能需求章节内部顺序：

1. 功能清单（overview table，列出所有模块及引用节号）。
2. 页面流转 / 跳转。
3. 各功能模块详情节（按功能清单顺序逐一展开）。

不要跳过功能清单和页面流转直接进详情。

2.4. 需与线上一致的内容：去抓，不要猜

迁移类需求、或正文要求"与线上一致"的要素（指标 ⓘ tooltip、线上既有文案 / 口径 / 命名），不要猜、不要拿别处口径浓缩顶替——抓线上原文：

1. 用 chrome-devtools MCP（默认）或可选高速工具 browser-cap（装了 BROWSER_CAP_DIR 才有），登录后台、打开目标页。
2. evaluate_script 在已渲染页面执行 JS 抓 DOM；多数 tooltip 文案在隐藏节点 / 属性里，直接读 DOM 即可，不必真 hover；读不到再派发 hover 事件。
3. 一字照搬线上，名实矛盾也照抄 + 标注"待确认是否纠正"，不替线上圆话。措辞看着不合当前页也照抄：那也是该页自己的正版线上文案——照抄进 ⓘ 文案列，不要删列、不要质疑它是 bug、不要花轮次考据"像是从 X 页 copy 来的"（那是钻牛角尖）。名实存疑只口头跟 PM 提一句，文案本身原样进表。

WebFetch 抓不到（SPA 空壳、无登录态）。完整浏览器接管 / 验收流程见 feature-acceptance skill。

二、通用排版规则

这四条贯穿全文，每条都附「为什么」——理解了原因才能在边界场景自己判断，而不是机械套规则。

3.1. 短句子 + 有序序号是基线

PRD 全文（正文、字段表说明列、操作逻辑、注释、blockquote）一律短句子。

1. 每条 ≤ 30 字，超过就拆。
2. 复合长句一律拆成有序序号。
3. 子条件用中文括号 1）2）3） 内联，避免多层 markdown 嵌套。
4. 不写隐含的系统行为（"阻止查询""联动刷新"这种从校验失败语义就能推出的行为）。

极简对照：

✗ 点击查询时，超 90 天则阻止并提示 X，结束时间早于开始也阻止并提示 Y，通过则刷新全页。
✓ **点击「查询」时**：
  1. 时间 >= 90 天，提示「X」
  2. 结束时间：1）早于开始，提示「Y」。2）等于开始，提示「Z」
  3. 满足全部验证项，校验通过

为什么：短句让评审快速断句，序号让评审精确指代到某条。复合长句让人漏掉关键边界，口径事故就藏在并列从句里。这是强偏好，不要软化。

3.2. 分项内容全部用有序序号，不用 bullet

PRD 正文里任何分项内容都用有序数字序号 1./2./3.，子项嵌套也用 1./2./3.，不用 - / * bullet。

含「分组标题层」：像校验里按字段分组（"同义词组名称""标准词"）、操作按场景分组这种分组标题本身也要序号，不能用 - 当分组项。从最外层到最内层全是数字序号，整份文档（含示例代码块）不出现任何 - / * 作分项符号。例：

1. **同义词组名称**：
   1. 为空时，提示"..."
   2. 超过 50 字符时，提示"..."
2. **标准词**：
   1. 某行为空时，提示"..."

这条同样适用于「表格单元格内」：表格说明 / 口径 / 校验 / 操作类列里任何分条的值都用 1./2./3. + <br> 显式分隔；不准粘成一段、用句号 / 分号连接、或粗体标签平铺堆砌。

判断标准：单元格里出现 ≥ 2 个粗体小标题，或 ≥ 2 个语义独立句子，就换成编号格式。

为什么：评审要能精确指代到某条（"第 6.3.2 个例子"），bullet 做不到。表格里粗体平铺，运营分不清边界。强偏好，违反等于口径事故。

完整反例 / 正例（含表格单元格编号对照）见 references/examples.md →「分项序号」。

3.3. 不主动加用户没要求的解释性 / 重申性提示语

只写用户明确要求的内容，不要为"让读者理解"擅自加解释性 blockquote、复述性提示、衍生性总结。

典型反例：重申矩阵已表达的事实 / 已在标题说过的正文又重述 / 无歧义的跨节引用 / 非关键风险的「注意」callout。

正文不写"为什么这么做"的目的 / 理由描述：如"加粗高亮便于运营人员快速定位""默认近 7 天方便用户对比""分组展示提升可读性"。需求只描述行为本身（"好评率、差评率加粗 + 颜色高亮"），不解释意图。

正文不写数据 / 文案来源与对齐说明：如"ⓘ 文案取自线上 X 页""与线上一致""口径沿用老系统，待确认""按 3.7 浓缩"。来源是写作过程，不进交付文档。线上既有的命名 / 口径矛盾若需提请确认，口头告诉 PM，不写进正文。

正文不写章节导读 / 定位元说明：如"本节是唯一口径源""3.3 / 3.4 只负责展示，以本节为准""下表汇总所有指标"。章节归属和优先级靠结构本身表达，引用处写"见 3.7.2"即可。

正文不写计数 / 分类括号注释：如"（共 11 张）""（4 项，无环比）""（3 项，含环比）"。数量读者数得出；无环比 / 含环比在指标口径总表「环比方向」列已表达。展示类章节只用有序序号列出支持指标，不加这类括号。

章节标题（### / ####）只写名称，不带括号补充说明：如"会话流向图（桑基图）""字段列表（默认全选，共 18 列）""核心指标（11 张卡）"。页面形态 / 计数 / 默认态等补充信息归正文或操作逻辑，标题保持干净。

例外（可以加）：

1. 用户明确要求"这里加一句提示"。
2. 关键不可逆操作的风险警告（删除、重置、不可撤销）。
3. 跨节强引用且不显式引用会有歧义。

为什么：PRD 是给评审 / 实现读的精炼规范，不是教学材料；同一信息在矩阵 / 表格 / 标题已表达，重述只增加维护成本（一处改了忘改另一处就口径不一致）。

自检：写 blockquote / 提示句前，问自己——这条信息用户要求过吗？没要求就删。

完整反例清单见 references/examples.md →「重申提示语」。

3.4. 系统提示词里不写 markdown 表格

系统提示词里的分流规则、流程步骤、子情况清单一律有序序号，不要用 | 列1 | 列2 | 表格。

为什么：

1. 提示词是 LLM 流式阅读的，表格在嵌套和长字段时视觉密集、断行混乱。
2. 步骤间天然有顺序（步骤 1 → 步骤 2），表格抹掉这个语义。
3. 评审改动时，表格一行内含多句逻辑，不如每条编号清晰。

何时可用表格：文档正文里真正的二维对照数据（指标 × 目标值 × 度量方式、事件名 × 标识 × 说明）。即便允许，能用序号写清就优先序号。

反例 / 正例见 references/examples.md →「提示词不用表格」。

三、各章节写法

4.1. 背景

回答三件事：当前方式是什么、为什么不够用、本期要解决什么问题。不要把背景写成解决方案。

4.2. 目标

具体回答：本期要做什么、解决什么问题、达到什么效果（预期改善或衡量标准）。避免"提升用户体验"这种空话。

4.3. 竞品对比

放在目标之后，覆盖：竞品如何解决相同问题、优势、局限。格式用表格或结构化对比，2–4 个竞品，附真实文档链接。目的是把决策放进市场现实，不是仅靠内部判断。

4.4. 结构与入口

先结构后细节。明确：对象层级、入口位置、页面之间关系、与现有模块的边界。

功能若在现有容器内，显式说清。例："表格知识是知识库中的一种新增知识内容类型，而不是新的知识库类型。"

4.5. 页面与交互

每个页面 / 模块按顺序写，子节作为 #### 标题时一律带章节号（如 #### 3.2.1 字段列表、#### 3.2.2 操作逻辑），不留无编号裸标题：

1. 入口。
2. 主要内容区块。
3. 字段列表。
4. 操作逻辑。

不写「页面目标」小节——目标在文档「目标」章节已统一表达，每节再写一遍是重申。

结构图 / 页面流转节点只写功能名词。节点写"全局筛选""导出""自定义展示字段"这种功能名，不写"→ 改条件 → 点查询 → 全页刷新"这种操作流程串（流程细节归操作逻辑）。图顶不写"A > B > C（默认展示）"导航路径行；图后也不拖"点导航默认展开 X 选中 Y 加载全页"这种默认行为说明句——点导航进默认页是显然的，不写。

原型 / 结构图后不写散列描述 bullet。ASCII 原型、菜单结构图、跳转图后面，不要再拖一串描述性 bullet（"全局常驻 / 默认首页 / 折叠收起" 等）——同一信息在图、bullet、操作逻辑三处冗余，口径难维护。

分流规则：

1. 用户可见字段（标题、状态、分组依据）→ 字段列表。
2. 系统行为、点击响应、入口逻辑、默认态、跳转、折叠 / 展开 → 操作逻辑（按"用户操作"为粒度）。
3. 纯结构信息（菜单层级、模块归属）→ ASCII 图已表达，不再 bullet 重复。
4. 风格 / 样式参考（"对齐 X 侧边栏"、圆角、宽度）→ 由设计交付，不写入正文。

元素与交互分开写：字段 / 展示元素清单只写"有什么元素"（"指标名称旁带 ⓘ 图标"），元素的交互行为（悬停展开、点击跳转）归操作逻辑写一次。不要在展示清单里写"含 ⓘ 悬停展开口径"、操作逻辑里又写"悬浮 ⓘ 展开口径"——同一交互两处描述就是冗余。

自检：写完每个 ASCII 图块，看下方有没有拖散列 bullet。有就分流到字段列表或操作逻辑；找不到合适位置说明信息冗余，删除。同文档其他原型位置联动检查。

反例 / 正例见 references/examples.md →「原型后不写 bullet」。

4.6. 字段

轻量字段设计——格式 / 长度限制 / 校验在字段表里收敛，不散落到多个章节。

推荐列：字段 / 配置项、是否必填、格式 / 限制、校验规则、说明。

涉及 AI 创建 / 调优能力时，字段表追加「调优可改」列（是 / 否 / 创建后不可改），「创建后不可改」一律收敛到这列，正文不再额外说明。

字段字符上限基准（英文 / 中文）按产品面向用户群决定。面向海外产品建议按英文长度为基准。

4.7. 指标口径定义

数据类 PRD（看板 / 列表 / 详情）的指标口径集中到一张表，不散落到原型示意、卡片说明、操作逻辑、备注里。

列顺序固定：指标 | 历史名称 | 口径 | 环比方向 | 展示格式 | ⓘ 文案

1. 指标：新口径名。
2. 历史名称：仅迁移、且新旧指标名确有差异时才加；指标名相比老系统没变化（即便是迁移），或非迁移的数据需求，去掉这列。
3. 口径：业务定义 + 公式整合在一列，不拆"口径""公式"两列。能量化的写"X = a + b"；纯比率直接写公式（别再写"占 Y 比例"这种和指标名重复的废话）；多条用 1./2./3. + <br> 分隔。
4. 环比方向：仅需求涉及环比时加这列（上升为正向绿色 ↑ / 上升为负向红色 ↑）；不涉及环比就去掉。
5. 展示格式：整数 / 百分比保留 X 位小数 / 金额单位等。
6. ⓘ 文案：放最后一列，页面上该指标 hover tooltip 的线上原文，逐条照线上抄（去线上抓，见 2.4）；线上无 ⓘ 的指标填 —。措辞看着不合当前页也照抄，不删列不质疑（见 2.4 第 3 条）。

业务线 / 渠道 / 场景 / 评分制式映射差异并入对应指标的口径单元格（如"无效会话数"按在线 / 呼叫 / 工单，"好评数"按 5 星制 / 10 分制的映射），不单开"差异说明 / 映射表"小节让读者跳着拼。并入时只列差异本身，不抄无关背景铺垫。

异常处理统一写在表后脚注，不在指标行内堆描述：

1. 分母为 0 时：显示「--」，环比不渲染。
2. 上期值为 0 时：环比不渲染。
3. 整段无数据时：图表 / 卡片显示空状态。
4. 上期开始时间早于账号开通时间：环比不渲染。

为什么：同一指标的多份信息散在四处时一处改了别处忘改，口径漂移；评审 / 算法 / 前端各自只看一张表就能对齐；异常处理整体复用，不需要每个指标重复。

4.8. 操作逻辑

用「操作逻辑」统一承载交互描述和处理条件，不分「交互规则」和「处理逻辑」两节。

写法规则：

1. 按用户操作顺序排列，每条以操作名称为标题（加粗）。
2. 每条操作下，用编号子列表写条件分支和系统响应。
3. 异常处理内嵌在对应操作末尾，不单独开节。
4. 保存 / 提交的校验按字段分组（字段名加粗作分组标题），不平铺为多行"当 XX 为空时"；顺序按页面字段从上到下。

基本格式 + 校验类写法的反例 / 正例见 references/examples.md →「操作逻辑」。

4.9. 功能清单

功能清单是功能需求章节的第一个子节（如 3.0），代替独立的「范围说明」章节。它定义本期做什么，隐含也说明边界。

必须包含的列：功能模块 | 说明 | 详见。每行一个模块，说明列一句话概括核心能力，详见列指向详情节号。

粒度 = 页面 + 页面内的操作，不是把页面内每个展示区块（筛选区 / 图表 / 指标卡 / 明细表）拆成一行。单页面 PRD 的功能清单通常 2–4 行：页面本身 1 行 + 导出 / 订阅 / 批量操作等各 1 行。文档章节（如"指标口径定义"）不进功能清单。

不写「本期不做」表格、不写「本期范围原则」段落。边界由"清单里列出来的就是本期做的"隐含表达。不做的功能要写时，放对应模块的操作逻辑里就近说明（"X 本期不做"），不单开汇总表。

4.10. 数据埋点

命名规则：产品线_菜单_功能_用户动作

1. 产品线：用户自定义（如 ai_agent / live_chat / knowledge_center / chatbot 等）。
2. 菜单：左侧导航二级菜单名（snake_case）。
3. 功能：触发埋点的具体功能名；与菜单语义重复时可省略其一。
4. 用户动作：统一用 click（含回车）；仅统计页面访问时可省略。

用表格 事件 | 事件标识 | 说明。事件标识全小写 snake_case，说明列写用户动作 + 触发条件。

4.11. Agent / 算法类需求补充

涉及 Agent / 算法的需求不能止于产品页面和规则，需补两个流程：

1. 后端与算法交互流程：谁发起请求、后端传给算法什么、算法返回什么、后端如何承接并返回前台 / 写记录 / 展示调试信息。
2. 算法处理流程：输入是什么、关键判断步骤、命中 / 未命中 / 兜底怎么处理、最终输出给后端什么。

写到产品 / 研发 / 算法都能看懂的粒度，写清阶段和输入输出，不展开成过细的代码实现。

Agent 功能强依赖路由 / 召回 / 生成 / 转人工 / 可追溯 / 变量映射 / 工作流执行时，这两个流程是必需，不是可选。

4.12. 多分支 / 流程 / 算法逻辑

复杂流程类内容（多路径算法、多场景分支、多步骤系统逻辑、生成 / 召回 / 路由）要满足两条：好理解 + 格式清晰。读者单读一节就能看懂，不需要在不同章节之间跳。

结构原则：

1. 每个分支 / 路径独立成节，单节内自包含。
2. 参数值（倍率、阈值、字符长度）直接写进对应步骤，不建独立"默认参数"章节让读者跳转。
3. 边界 / 异常就近写进会触发它的步骤，不单开"边界处理表"列末尾。
4. 共用内容（如 prompt 模板）才用引用——其他规则、参数值都展开。
5. 字段命名用源数据本来的名字（"接待记录数""数据条数"），不起内部实现术语（"种子数""候选数 × 倍率"）。

层级写法：主步骤用 粗体标题：描述 引出，用嵌套编号拉层级（1 → 1.1 → 1.1.1），多场景对比用表格。

基本格式模板见 references/examples.md →「多分支流程」。

四、交付前自检

5.1. 现状已确认，对象粒度清晰，入口与页面结构先行。 5.2. 没把技术实现混进正文。 5.3. 字段约束收敛在字段表，规则归操作逻辑，结构靠图自表达。 5.4. 同类模块口径一致；用户指过的问题已联动复查（不只局部打补丁）。 5.5. 多分支 / 流程 / 算法节自包含，参数和边界就近内联，没有"同 X 第 N 步"散落。 5.6. 原型、流程图、正文口径一致。 5.7. Agent / 算法相关需求已补「后端与算法交互流程」和「算法处理流程」。 5.8. 看起来像正式 PRD，不像聊天整理或讨论记录。

五、高频错误

6.1. 没查现状就开写。 6.2. 先写理想方案，后面对齐现状导致返工。 6.3. 把需求文档写成技术方案或能力脑暴。 6.4. 页面结构没想清楚就先列字段和规则。 6.5. 用户给了关键现状后只局部补丁，不整体重整。 6.6. 一处术语变了，其他章节没同步。 6.7. 原型 / 结构图后拖散列 bullet（信息三处冗余）。 6.8. 多分支 / 算法流程写成"共享章节 + 跨节引用"，读者要跳来跳去。 6.9. 用内部实现术语（"种子数 / 候选池"）替代源数据真名。

References

7.1. references/checklist.md — 执行检查清单（动笔前 / 写作中 / 交付前）。 7.2. references/examples.md — 反例 / 正例对照 + 整体重排示例。 7.3. references/example-domain.md — 领域知识示例（示例文件，用户应替换为自己产品的领域知识）。