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 重交互模块的两张表（范式）：

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

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

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

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

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

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

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

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

六、验收标准

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

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

七、技术方案（V2）

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

八、上线策略（V2 或 V3）

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

九、项目管理（V3）

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

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

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

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

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

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

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

| 日期 | 版本 | 背景 | 内容 |
|------|------|------|------|
| {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 文件。暂无补充时保留本节占位。

（暂无）