Prd Style

---
name: prd-style
description: 本项目的 PRD 框架与写作风格——工序形态 / 章节结构 / 各章写法 / 范式表 / 标注习惯的唯一事实源。写改 PRD（core prd-writer 工作流）时自动叠加加载；与 core 通用写作纪律冲突时以本文件为准（机器契约除外）。
when_to_use: |
  写或改 prd.md 时（core prd-writer 前置依赖自动读取；不走完整 prd-writer 流程的 PRD 小改也应加载）；
  确认本项目 PRD 的章节结构 / 工序形态 / 标注习惯时；建立或调整本项目 PRD 风格时。
  通用写作纪律在 core `prd-writer/writing-guide.md`，图件 / 原型能力库在 core
  `prd-writer/{diagram-guide,html-prototype}.md`；本文件管本项目的框架与风格，
  冲突时以本文件为准（机器契约 §0 除外）。
---

# {{PROJECT_NAME}} · PRD 框架

> **这份文件属于你的项目**：装机时由框架放入（出厂默认版），之后框架**不再覆盖**。
> 想让 PRD 长成你习惯的样子——章节怎么排、要不要流程图、用不用原型——直接改这份文件，
> 下一次写需求即生效。改坏了想回默认：从框架模板重新复制一份即可——
> `$(cat .claude/workframe-state/plugin-root.txt)/templates/project-skills/prd-style/SKILL.md`。
>
> 与 core 的分工：core `prd-writer` 管**工作流骨架与通用写作纪律**（怎么协作、怎么写得清楚），
> 本文件管**本项目的框架与风格**（写成什么样）。两边冲突时**以本文件为准**，但下方
> 「机器契约红线」除外。

## §0 机器契约红线（本文件不可覆盖的部分）

以下内容由 core 保证跨项目一致，改了会断索引 / 断 QA 链路，**本文件的任何声明不覆盖它们**：

| 契约 | 归属 |
|---|---|
| frontmatter 必填字段与落盘路径（`projects/modules/.../prd.md`） | `document-norms` §1 §2 |
| 需求资产包结构（`prototypes/` `assets/` `test-cases/` 等） | modules-template |
| 验收标准的 `AC-{序号}` 编号 | QA `test-case-design` 的输入，编号全文档唯一递增 |
| 「变更与决策记录」章的**存在**（frontmatter 无 version 字段，正文「变更与决策记录」是唯一版本史） | prd-writer 落盘契约（表的格式可改，章不能没有） |

## §1 工序形态声明

core `prd-writer` 的六段工作流骨架（理解 → 骨架确认 → 填充 → 落盘 → 附属产物 → 发布）
在以下工序点读本节取值。**每行都可改**：换形态直接改「取值」，停用整个工序把「取值」改为「不启用」。

| 工序点 | 本项目取值 |
|---|---|
| S2 范围确认形态 | Mermaid 思维导图（只呈现核心模块与关键子模块，不展开实现细节——字段 / 接口 / 文件 / 失败分类 / 配置值等一律不入图；主干与总行数按需求大小合理控制） |
| S2 结构确认图件 | 启用——流程图（选型判据与图纪律见 core `prd-writer/diagram-guide.md`） |
| S2 页面骨架确认（V1 时） | 启用——简洁文字描述（区域布局 / 核心元素 / 空状态），不生成 HTML |
| S3 填充波次 | 两波：先「头部元信息（如启用）+ 需求背景与目标 + 方案概览」校准方向，再其余全部章节 |
| S5 附属产物（V1 时） | HTML 交互原型（规范见 core `prd-writer/html-prototype.md`）；已有拍板 demo 时走「demo 先行变体」 |

## §2 维度开关（按产品形态裁剪章节）

写作前按需求推断以下维度，决定启用哪些章节。维度**可增删**（如硬件产品可加「供应链/认证」维度并映射到自建章节）：

| # | 维度 | 推断信号 | 影响 |
|---|------|---------|---|
| V1 | 有 UI 页面/用户操作流程？ | 含"页面/列表/按钮/弹窗/表单/菜单"（"配置/管理/操作"不单独作数——CLI、管道类需求同样高频用这些词） | 启用「需求路径」章；需求详情按前端模块分层；启用页面骨架确认与原型工序 |
| V2 | 需向研发/算法说明实现方案？ | 含"模型/算法/LLM/接口/训练/管道" | 启用「技术方案」章；「上线策略」章 V2 或 V3 任一启用即写 |
| V3 | 分期交付或多团队协作？ | 含"一期/二期/阶段/跨团队"或规模较大 | 启用「项目管理」章；头部输出相关负责人 |
| V4 | 有字段设计或数据结构？ | 含"字段/表结构/导入/导出/数据定义" | 需求详情含字段说明表 |
| V5 | 需跨角色问题追踪？ | 涉及多方沟通或历史有多轮确认 | 启用「附录」章 |

## §3 章节总览与输出顺序

标准章节序列（按维度裁剪后**连续重编号**，不跳号）：

| 章节 | 必选/维度 | 说明 |
|------|----------|------|
| 头部元信息 | 按需 | 相关负责人仅多团队协作时输出；更新记录并入「变更与决策记录」 |
| 一、需求背景与目标 | 必选 | 背景 / 目标 / 边界 三小节 |
| 二、方案概览 | 必选 | 分点文字，一目了然 |
| 三、需求路径 | V1 | 平台 > 菜单 > 页面/弹窗 > 动作；无 UI 的需求（CLI / API / 数据管道）不设本章 |
| 四、业务流程与逻辑 | 必选 | 流程图双格式 + 产品视角后端逻辑 |
| 五、需求详情 | 必选 | V1 主导时题为「前端交互详情」，按前端模块分级 |
| 六、验收标准 | 必选 | AC 表格 |
| 七、技术方案 | V2 | 面向研发/算法 |
| 八、上线策略 | V2/V3 | 灰度 / 回滚 |
| 九、项目管理 | V3 | 里程碑 |
| 倒数第二章、待确认项 | 按需 | 仅用户明确提出的未决事项；无则不设 |
| 最后一章、变更与决策记录 | 必选（契约） | 版本 + 拍板合并表 |
| 附录 | V5 | 参考文档 / 团队分工 |

**不设「非功能需求」章节**：性能、安全、兼容类约束没有实质业务含义的（拍脑袋指标、通用
浏览器兼容等）不写；确有实质约束的，按真边界进「一、需求背景与目标 · 边界」，或就近写入
对应功能模块 / 验收标准。

## §4 各章写法

### 头部：元信息

**相关负责人**（V3 按需）：多团队协作、需要明确对接人时输出（Markdown 表格，从模块
overview 或历史文档提取，未确定人选用 `[待确认]`）；单人主导的需求不输出。
更新记录不单设头部表格——统一进文档末尾「变更与决策记录」。

### 一、需求背景与目标

三个小节，合计不超过一屏；链路构成、字段细节留给正文章节，不在本章预写。

- **背景**：分点陈述，每点一句，回答"为什么要做"——现状 / 痛点（谁在什么场景遇到什么
  问题、后果是什么）/ 改进机会（可选）。不描述方案、不量化指标
- **目标**：bullet list，每条 15-30 字，动词开头（构建 / 实现 / 提供 / 释放人力 / 提高效率…）
- **边界**：全局性真边界集中声明（判别见 core 通用纪律「否定句裁剪」），每条一句。只放
  影响全局的（数据写入边界、生效范围、用途定位）；模块局部规则不上提

### 二、方案概览

分点文字总结本次要做的核心内容，3-6 个要点，每点一两句；某点逻辑复杂时在该点下再短分点。

- 不放图（流程图归「四、业务流程与逻辑」）
- 不展开字段与交互细节（归「需求详情」）
- 写法上对应「需求详情」的一级模块划分，让概览即目录

### 三、需求路径（V1）

声明本次需求落在哪些系统/平台、哪条菜单路径、做什么动作：

```
{平台/系统} > {一级菜单} > {页面/弹窗} > {本次动作}
```

- 多个位置时多条罗列
- 涉及权限系统的（如需新增权限配置项控制功能可见性）在本章一并标注；明确不控权也写一句，
  避免评审追问
- **平台/系统枚举是项目事实，在下方 §6 补充**；未补充前向用户询问平台/系统名，不虚构

### 四、业务流程与逻辑

让技术清晰看到功能的状态流转与系统间动作。

- 流程图选型、双格式落点（PNG + Mermaid 源码）、同步纪律、图组织纪律：
  见 core `prd-writer/diagram-guide.md`（本项目已在 §1 启用图件）
- **核心后端逻辑（产品视角）**：影响实现方向的后端规则（数据一致性口径、复用哪条线上
  链路、并发与时序约束等）在本章子节写明，并在流程图对应节点标注。只写产品约束，不介入
  技术实现细节；需要深入接口/模型细节时启用「技术方案（V2）」章——本章管"流转与口径"，
  技术方案章管"输入输出与实现要求"。**运行时机制用「流程 + 表」不用散文**：异常场景 /
  处理策略两列表格，研发直接对照实现

### 五、需求详情

**分层方式**：

| 主导形态 | 分层 |
|---------|------|
| UI 功能（V1） | 章题可写「前端交互详情」；按前端模块分级：页面 → 区域/弹窗 → 字段/状态 |
| 无 UI 技术（V2） | 按处理阶段，或旧方案 vs 新方案对比 |
| 数据 / 管道（§2 无对应维度，按需自建） | 按业务流程环节（采集→入库→查询→优化） |
| 分期迭代（V3） | H1 一期 / 二期，各期内按上述方式展开 |

**场景枚举类需求按纵向场景主轴组织**（如多类时间场景、多类状态场景）：公共约定前置
（表结构 / 标签 / 阈值 / 通用识别要求）→ 逐场景单元展开（每场景固定小节：识别触发 /
生成表行 / 场景特有规则 / 注意事项 / 相关 AC 引用行）→ 跨场景组合规则集中一节（冲突裁决）
→ 端到端装配示例集中收尾；**不按横向主题**（颗粒度 / 标签 / 识别各一节）切碎规则。重组
存量 PRD 时 AC 编号不动、只调分组（test-cases 回指依赖编号，见 §0）。

**分级原则（严格遵守）**：同一功能的需求不跨同层级铺开；往子层级有序、按类型理清。一个
字段的列表来源、初始化、显隐条件、禁用时机，全部写进该字段所在表格行，不为单个字段独立开节。

**V1 重交互模块的两张表（范式）**：

字段与交互表（每个交互模块必备）：

```markdown
| 元素 | 说明 | 初始状态 | 交互逻辑 |
|---|---|---|---|
| {控件名} | {功能说明；候选来源/显隐条件} | {默认值/默认态} | {点击/切换行为；禁用时机；联动规则} |
```

控件 × 状态矩阵（有状态机时，替代多张界面示意图）：

```markdown
| 控件 | {状态A} | {状态B} | {状态C} |
|---|---|---|---|
| {控件名} | {该状态下的表现} | … | … |
```

矩阵后用 1-2 句补充状态进入/退出条件与记忆规则。列可按需调整 / 拓展 / 缩减，核心是条理化
展现完整信息。**视觉细节由 HTML 原型承载**（本项目 §1 已启用），表内只写影响开发逻辑的
状态与规则；不画 ASCII 界面示意图。不同结果形态（单条 / 多条 / 空 / 失败）在同一小节内
分点或分表写明，不拆散到平级章节。

复杂配置类需求（≥3 维矩阵、多条件命中）另见 core 通用纪律「多维配置类交互设计」能力节。

**字段说明表（V4）**：统一 Markdown 表格（不论行数），七列：

```markdown
| 序号 | 字段名 | 类型 | 必填 | 示例值 | 说明 | 备注/约束 |
```

### 六、验收标准

格式遵循 core `acceptance-criteria` skill（GWT 场景式 gherkin 块 / 规则式清单，
`AC-{序号}: {标准名称}`）。组织上：

- 按「需求详情」的模块**分组**，每组前加一行分组说明
- AC 编号全文档唯一递增（机器契约，见 §0）——QA 测试用例引用与 bug 回指依赖它

### 七、技术方案（V2）

面向研发/算法，从 PM 视角说明：模型/接口的输入输出（数据格式，不需要代码细节）/
核心处理逻辑（文字描述或引用「四、业务流程与逻辑」流程图）/ 评估指标（如有）/
对研发的关键约束（性能/兼容性）。

### 八、上线策略（V2 或 V3）

```markdown
- **上线范围**：全量 / 灰度（比例：XX%）/ AB 实验
- **灰度条件**：按地区/账号/用户分层
- **验证指标**：[待确认]
- **回滚预案**：[待确认]
```

### 九、项目管理（V3）

```markdown
| 里程碑 | 负责人 | 计划完成 | 状态 | 交付物 |
```

### 倒数第二章：待确认项（按需）

准入纪律（只收用户明确提出的未决事项、禁止模型自行归档）见 core 通用纪律。表结构：

```markdown
| # | 事项 | 影响 | 责任方 | 状态 |
```

- 事项确认后：结论融入正文对应位置（变更三步）+ 变更与决策记录表留痕，本表删行
- 无用户提出的待确认事项时，本章不输出

### 最后一章：变更与决策记录（必选，存在性是契约）

文档版本史与需求拍板史合并为一张表，每版本一行：

```markdown
| 日期 | 版本 | 背景 | 内容 |
|------|------|------|------|
| {YYYY-MM-DD} | v1.0 | 初版 | {范围一句话} |
| {YYYY-MM-DD} | v1.1 | {为什么改} | {改了什么；同版本多个决策分点} |
| {YYYY-MM-DD} | — | 评审拍板（不改正文） | {拍板结论} |
```

- 同版本多个变更/决策在「内容」单元格内分点
- 纯拍板、不产生正文修改的决策也进表，版本列写「—」
- 初版即建此表；追加不删历史

### 附录（V5）

- **参考文档**：从上下文历史文档提取相关链接，不确定的标 `[待确认]`
- **问题记录**：Markdown 表格——`| 问题描述 | 提出人 | 日期 | 状态 | 结论 | 相关人 |`
- **团队分工**（多团队时）：`| 负责方 | 角色 | 分工说明 |`

## §5 标注与编号习惯

标注一律用通用编辑器可解析的原生 Markdown 语法（格式基线与禁用 HTML 标签的底线见
core 通用纪律）：

| 场景 | 写法 |
|------|------|
| 关键数字/约束/权限 | `**内容**`（加粗） |
| UI 控件/功能名 | `【导入】按钮`、`【任务列表】页面` |
| 术语强调 | `**术语**` 或 `` `术语` ``（行内代码） |
| 重要说明 | `> 💡 内容`（引用块） |
| Prompt 设计展示 | ` ```text ... ``` `（围栏代码块） |
| 表格单元格内换行 | `<br>`（GFM 通用兼容，唯一允许的 HTML 标签） |

**编号习惯**：章节标题与正文**不使用** `FR-x` / `BR-x` / `ASMP-x` 等需求编号前缀——
语义化标题 + 层级结构本身就是锚点；编号刚性会导致变更时不敢动结构、只能尾插新编号。
唯一保留 `AC-{序号}`（机器契约，见 §0），且编号只出现在验收表格行内，不污染标题。
（你的团队若用编号管理需求，可改本节——AC 编号除外。）

## §6 本项目补充口径（装机后按需填写）

> 平台/系统枚举（「三、需求路径」用）、权限标注方式、demo 视觉基线等**项目事实**写在这里，
> 或在本目录加 reference 文件。暂无补充时保留本节占位。

（暂无）