# Prd Writing

> Use when the user asks to write, revise, review, restructure, or sync a PRD, 产品需求文档, 需求文档, 产品方案, or 飞书需求文档, especially when product logic, requirement tables, prototypes, model parameters, pricing, launch scope, Agent Skill 接入归档, skill 需求, SKILL.md, skill 包, or goodcase 展示 are involved.

- Skill: `zane-qin/prd-writing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add zane-qin/prd-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/zane-qin/prd-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: Zane-qin (https://skillmd.com/u/zane-qin)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/zane-qin/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 正文结构**：

```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：

| **时间** | **变更人** | **主要变更内容** |
|----------|------------|------------------|
| 2026-xx-xx | xxx | 初稿 |
| 2026-xx-xx | xxx | 补充 Skill 包 / goodcase / 接入建议 |

**需求背景**保持精简准确：

- **为什么**：说明该 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 |
| 输入内容 | 文本 / 图片 / URL / 文件 / 其他 |
| 输出结果 | Agent 最终交付什么 |
| 能力边界 | 不覆盖哪些场景 |

Skill case 展示推荐表格：

| **测试场景** | **用户输入** | **输出结果** |
|--------------|--------------|--------------|
| case 名称用正文；验证目标用引用格式 | 直接写入当时实际使用的素材 + 用户 prompt；图片、视频、文件等多模态输入素材必须直接放在本单元格内，形成飞书可见资源块；不要加「素材」「Prompt」等额外小标题，不要只写本地路径或写「见下方素材」 | 直接用当时实际产出的多模态结果替代路径说明，如分镜、关键帧板、截图、视频、文件；图片 / 视频 / 文件等多模态输出必须直接放在本单元格内；不要加「故事板」「视频」「输出结果」等额外小标题；需要说明 Agent 行为时合并进简短说明 |

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 时必须严格遵守本文件。