| 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 文件。暂无补充时保留本节占位。
（暂无）
