Prd Writing

PRD 写作规范（本项目唯一完整版）

【强制】撰写或大幅修改 PRD 前，须完整阅读本文件全文，再动笔。

项目根目录 .cursorrules 仅作入口说明，具体条文以本 skill 为准。

溯源：飞书「我的 PRD 写作规范」。

一、撰写流程

新 PRD 建议按序执行：

1. 历史文档：若有参考文档，阅读飞书或既有 PRD，对齐术语与逻辑
2. 复习规范：通读本文件全文，保证风格与格式一致
3. 本地草稿：创建或更新符合规范的 Markdown
4. 确认修改：与需求方对齐内容后定稿
5. 发布飞书：【强制】所有 PRD 完成后必须以用户名义创建或更新对应飞书文档，优先使用当前可用的飞书文档工具（如 lark-doc / lark-cli docs --api-version v2）；长文档按章节分段写入或精准更新，使用飞书 XML 结构化块（如 <table>、<callout>、<grid>）保证可读性

二、文档模版

路由判断

若用户要把已经完成 / 已经搓好的 Agent Skill 归档需求化，并交给 Agent 研发同学接入，使用「Skill 类 PRD」分支。

典型触发信号：

• Quokka Agent
• skill 需求
• Agent Skill
• skill 归档
• skill 接入
• SKILL.md
• skill 包
• goodcase
• 已完成的 skill 需要需求化 / 交给 Agent 研发接入

Skill 类 PRD 只介绍单个 skill 本身：它是什么、解决什么场景、内部结构、建议如何接入、跑出的 goodcase。不要展开为「如何制作 skill」的研发方案，也不要额外增加交互规范、错误安全、工程化验收等模块；Agent 运行约束由系统层处理。

Skill 类 PRD 模版

飞书文档标题：【Quokka Agent】 + 最终 skill zip 文件名去掉 .zip 后的完整 basename

Markdown 正文结构：

## 基础信息

## 需求背景
### 为什么
### 是什么

## 需求详情
### Skill 完整内容
### Skill 能力说明
### Skill 内部结构
### Skill Case展示

标题 / 附件命名对齐：

• 文档标题的 skill 名称部分必须与最终 zip 文件名去掉 .zip 后完全一致，包括大小写、连字符和 -final 等后缀
• 示例：最终附件为 storyboard-production-skill-final.zip → 飞书标题为 【Quokka Agent】storyboard-production-skill-final
• 不要把标题写成展示名、空格名或拼写不同的名称，例如 Storyboard Production、storyboard-roduction-skill-final

基础信息为文档维度，复用普通 PRD 的变更记录表，不写成 skill metadata：

需求背景保持精简准确：

• 为什么：说明该 skill 解决什么高频场景；没有该 skill 时，Agent 在该场景下存在什么问题，如输出不稳定、步骤重复、依赖用户多次解释、素材或流程不易复用
• 是什么：用一句话说明 skill 定位，并写清适用场景

需求详情按以下模块组织：

• Skill 完整内容：直接插入完整最终版 .zip 压缩包作为飞书附件；附件文件名必须与飞书文档标题的 skill 名称部分对齐；正文不展开 skill 名称、版本、包大小、包含文件、接入建议等信息表，除非用户明确要求。若暂时无法插入附件，只写「最终版 skill zip 附件待补充」，不要用冗长说明替代附件
• Skill 能力说明：用表格写清适用场景、输入内容、输出结果、能力边界
• Skill 内部结构：展示目录树，并用短句说明 SKILL.md、references/、scripts/、assets/ 等目录用途；只说明接入所需结构，不展开实现细节
• Skill case 展示：展示搓 skill 过程中已经实际评测验证通过的 goodcase，表格仅保留测试场景、用户输入、输出结果；不要把 eval-cases.md 里的回归测试清单、未来待验证场景或自己推演的 expected case 当作 goodcase；不要粘贴完整执行日志；多模态输入 / 输出素材要直接写入对应表格单元格中，形成可见图片、视频或文件资源块，不要只写本地路径或另放在表格外

Skill 能力说明推荐表格：

Skill case 展示推荐表格：

Skill case 展示取材规则：

• 优先使用当前工作目录、历史对话、飞书记录或用户明确指出的已跑通 case
• case 必须是「已评测验证通过 / 用户认可 / 作为 goodcase 保留」的真实产物，例如 story skill 中的小孩骑龙、女神睫毛、假发展示等已跑通样例
• references/eval-cases.md 只作为回归测试参考，不能直接改写成 PRD 的 goodcase 表
• 多模态素材必须直观可见且放在表格对应位置：输入图片 / 视频放在「用户输入」单元格，输出故事板 / 视频 / 截图放在「输出结果」单元格；表格里不允许只写 /tmp/...、/Users/... 这类本地路径，也不要把素材另放在表格外再写「见下方」
• 表格内插入图片时必须显式设置符合原图比例的 width 和 height；不要只写 width，否则飞书可能给图片块填默认高度，导致 16:9 故事板下方出现大片空白
• 若使用 docs +media-insert 上传多模态素材，只把它当作获取图片 src / 文件 token 的中间态；最终必须把资源写回对应表格单元格，并删除或避开表格外的临时素材块
• 表格内媒体默认不要加 caption，除非用户明确要求；caption 会在飞书中形成额外标签，容易违背“用户输入 = 素材 + prompt / 输出结果 = 多模态结果”的简洁展示
• 飞书同步后必须最终拉取飞书 XML 核验：三列表头正确、无「行为摘要」、无「见下方」、无 /Users/ 或 /tmp/、无「素材 / Prompt / 故事板 / 视频」等额外小标题、表格内媒体无多余 caption、图片 width / height 合原图比例、无 height="512" 这类默认撑高值
• 若只找到测试输入但找不到真实输出，不要写成“预期输出”；应向用户确认或标注输出待补充

普通 PRD：需求背景

• 前置背景：简明说明问题、痛点或机会
• 流程梳理：非必需；需求复杂时附流程图（如 Mermaid）
• 原型概览：非必需；涉及前端改动时附原型或示意图；整体原型概览图必须放在「需求背景」内，优先放在「方案概览 / 流程梳理」附近，不要放在「产品方案」表格之后

普通 PRD：需求详情

• 产品方案：必需，拆分需求点，写清逻辑、边界与异常
• 数值策略：非必要且未经允许不写
• 技术方案：非必要且未经允许不写；若写须附技术调研或开发文档依据
• 设计方案 / 审核策略 / 埋点方案：非必要且未经允许不写

三、产品方案写法

核心原则

产品方案不是需求点清单。写表格前必须先梳理：

• 主链路：上游入口 → 页面状态 → 用户操作 → 系统反馈 → 下游结果
• 模块边界：按页面 / 功能模块拆行，不按零散需求点拆行
• 状态分层：复杂能力必须拆空态、有效态、上限态、异常态、回填态
• 规则来源：模型、参数、价格等配置类信息单独成表；产品方案只说明页面如何消费这些配置
• 确认状态：已确认的信息写入正文规则；只把真正未知的信息放入「后续补充项」

需求详情表格内结构

标准表格仍为三列，但「需求详情」单元格内必须结构化，禁止平铺罗列。

反例警戒：如果一个「需求详情」单元格只是把用户口述需求改成连续 bullet，例如“新增入口 / 点击进入 / 支持上传 / 支持下载 / 支持分享”，这仍然是不合格的需求点平铺。遇到这种情况必须重写。

合格写法必须做到：

• 先说明该模块在主链路中的定位
• 再按信息层级分组，而不是按用户说话顺序堆叠
• 每组只承载一类问题：页面长什么样、用户能做什么、系统如何响应、异常怎么兜底、下游带什么数据
• 读者只看小标题，也能理解该模块的产品逻辑框架

推荐按需使用以下小标题：

• 场景定位 / 生效场景
• 页面结构
• 展示逻辑
• 交互逻辑
• 状态逻辑
• 下游逻辑
• 边界 case / 兜底逻辑
• 已确认口径

复杂模块至少包含「展示逻辑 / 交互逻辑 / 下游逻辑 / 边界 case」中的 3 类。

结构化改写模板

当原始需求是零散需求点时，先在脑中改写成以下框架，再落表：

1. 场景定位：这个页面 / 模块解决什么问题，位于哪条链路
2. 页面结构 / 展示逻辑：页面有哪些区域、组件、文案、默认值
3. 状态逻辑：空态、有效态、上限态、禁用态、异常态、回填态
4. 交互逻辑：用户点击 / 输入 / 切换后发生什么
5. 下游逻辑：提交、跳转、入库、回填、计费、埋点等后续影响
6. 边界 case / 兜底逻辑：超过限制、不满足条件、无可用配置、失败重试等

如果某行需求详情写完后无法归入上述任一层级，大概率是在写“事项清单”，需要重新组织。

同类任务写法参考

涉及生成、编辑、参数面板、模型切换、资产流转等链路时，优先按以下方式组织：

• 入口模块：入口位置、卡片 / 按钮文案、点击后跳转、权限或灰度
• 创作页模块：页面结构、输入状态、按钮状态、关闭挽留、提交内容
• 输入模块：0 个输入、未达上限、达到上限、超过限制、删除 / 替换 / 回填
• 模型与参数模块：默认值、可选范围、不可用项展示、切换后的参数刷新
• 计费模块：单价、数量变化、总价刷新、余额不足
• 结果模块：结果展示、基础操作、二次入口、资产库入库、重做回填
• 兼容模块：与现有模式的差异、复用逻辑、不展示项、跨链路跳转

文案写法

• UI 文案不要单独起一张文案表，除非用户明确要求
• 文案必须写在对应交互或展示规则里，用「」标识
• 例：图片输入空态文案为「Add images」
• 例：系统自动切换模型后展示轻提示「Switched to a supported model」
• 文案待定时，可先给功能精简版初稿，并在「后续补充项」写最终文案待 UI 定稿

四、文本规范

严控技术细节

除非用户或文档明确要求，否则禁止编造技术实现细节。

语言

• 列表项末尾不使用中文或英文句号
• 用符号（如 →）代替冗长连接词（「即」「变为」等）
• 复杂逻辑用多级列表，避免大段文本
• 优先短语，避免冗长完整句

标题与正文

飞书文档标题（不写入 Markdown 正文）：

• 格式：【Quokka】 + 标题内容
• Skill 类 PRD 格式：【Quokka Agent】 + Skill 具体名称

Markdown 正文：

• 不要使用 H1；普通 PRD 从 ## 需求背景 起笔，Skill 类 PRD 从 ## 基础信息 起笔
• H2：主章节（如「需求背景」「需求详情」），不带数字序号
• H3：次级模块（如「前置背景」「产品方案」），不带数字序号
• 若小节内需要编号，用有序列表或更深级标题，不强行给 H3 加「一、二、」

普通 PRD 需求详情表格（标准三列）

普通 PRD 以表格呈现需求详情，列名固定为：

说明：历史文档中的「需求点」「示意」与上表「功能/页面」「参考图」同义，新稿统一用本表列名。

Skill 类 PRD 不强制使用「功能/页面 | 需求详情 | 参考图」三列表，按「Skill 类 PRD 模版」中的 Skill 能力说明与 Skill case 展示表格组织。

原型图摆放规则：

• 整体原型概览图、整套页面串联图、完整画板截图 → 放在「需求背景」的「原型概览 / 方案概览」位置
• 产品方案表格的「参考图」列 → 只放单页面局部参考、历史 UI 说明，或写「见需求背景原型概览」
• 不要在「产品方案」表格后单独追加整套原型概览图，避免阅读路径倒置

表头在定稿中加粗（含飞书）。

飞书同步：表格单元格内需要无序列表且要在飞书正确渲染时，用飞书 Docx XML 的标准 <table> 结构写入，并保持表头加粗、表头底色、单元格内分组标题等可读性。

参考链接：用引用块等清晰格式，避免裸链散落。

五、交付前自查清单

格式

• H2 为主章节，无数字序号
• H3 为次级标题，无数字序号（主结构）；子级编号用列表或更深标题
• 普通 PRD 的需求详情为表格，三列为 功能/页面 | 需求详情 | 参考图
• Skill 类 PRD 已使用 基础信息 / 需求背景 / 需求详情 结构，飞书标题为 【Quokka Agent】 + 最终 skill zip 文件名去掉 .zip 后的完整 basename
• 对比类表头已加粗
• 参考链接格式规范
• 文件命名符合项目习惯

内容

• 背景简明（约 2～4 段）
• 普通 PRD 的需求详情含边界与异常
• 普通 PRD 的产品方案表格不是需求点平铺，单元格内有场景、状态、交互、下游、兜底等结构
• 普通 PRD 的每个复杂模块「需求详情」不是连续 bullet 清单，至少包含 3 个结构小标题
• 普通 PRD 的每个结构小标题下信息类型单一，没有把展示、交互、异常、下游混在同一组
• 普通 PRD 的复杂链路已按「上游 → 操作 → 页面变化 → 下游」写清楚
• 普通 PRD 的复杂状态已拆空态、有效态、上限态、异常态、回填态等必要状态
• 普通 PRD 的配置类信息与页面消费逻辑分开，避免同一规则重复写多套口径
• 已确认信息已写入正文规则，未继续保留在「待确认 / 后续补充项」
• UI 文案已嵌入对应展示或交互规则，并用「」标识
• 字段要求明确（必填/可选、格式等）
• 技术方案仅在允许且有依据时出现
• 上线计划仅在适用时出现
• Skill 类 PRD 已写清 Skill 完整内容、Skill 能力说明、Skill 内部结构、Skill Case展示
• Skill 类 PRD 的 Skill 完整内容模块已直接插入最终版 .zip 附件，且文档标题与 zip 文件名去掉 .zip 后完全对齐，未用包大小 / 文件清单 / 版本信息表替代附件
• Skill 类 PRD 未扩写成「如何制作 skill」的研发方案
• Skill 类 PRD 的 goodcase 来自搓 skill 过程中实际评测验证通过的 case，而不是未来待验证场景或 eval-cases.md 回归清单
• Skill 类 PRD 的 goodcase 表格仅保留 测试场景 / 用户输入 / 输出结果 三列；缺少真实输出时已标注待补充，未编造预期输出
• Skill 类 PRD 的多模态 goodcase 素材已直接插入对应表格单元格形成可见图片、视频或文件资源块，未只用本地路径替代素材，未另放表格外再用「见下方」指代
• Skill 类 PRD 的 case 表格已清除「素材 / Prompt / 故事板 / 视频」等额外小标题和表格内媒体 caption，输出结果单元格直接展示多模态产物
• Skill 类 PRD 的飞书 XML 已最终拉取核验，图片 width / height 符合原图比例，未出现默认撑高造成的空白

完整性

• 必要章节齐备
• 整体原型概览图已放在「需求背景」内；产品方案表格后没有重复追加整套原型图
• 参考图已提供或标注「待补充」
• Skill 类 PRD 已插入完整最终版 skill 压缩包，或明确标注附件待补充
• 相关文档链接已添加
• 术语使用一致

撰写 PRD 时必须严格遵守本文件。