원클릭으로 Manus에서 모든 스킬 실행

시작하기

prd

스타4

포크0

업데이트2026년 6월 21일 14:39

当用户提到「PRD」「需求文档」时触发。基于 IMAP / 原型输出 PRD 亦触发。 PRD 形态为 md（含本地截图，推 Confluence 时脚本自动上传图片）。

설치

Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.

Manus에서 실행

출처

CaufieldZ

CaufieldZ/pm-workspace-public

GitHub 저장소 열기 Creator 저장소 보기

다운로드

Manus에서 실행

PRD Skill（产品需求文档，md 版）

触发与定位

收到新需求 → 先按 CLAUDE.md「收到需求路由」过 PM-GATE 4 风险扫描 + 复杂度判链路，再进 Step 0。

做什么：scene-list / IMAP / prototype 之后的最终行为规格 md 文档（md + 本地截图，推 Confluence 时图片自动上传）。自包含、PM 与研发 / 设计 / QA AI 都能直接消化。承载业务对象词典 / 业务动作区块表 / 通用文案清单 / 信息层次矩阵。

何时触发：用户说「PRD / 需求文档」；IMAP / prototype 完成后输出 PRD 亦触发。

写给谁（立场）：PRD 首先要 PM 自己读得懂。全文讲人话——契约层（§3.2 业务对象词典 / §3.3 状态机）也用中文业务名（写「主播 TRTC 标志」不写 trtc_enabled）。spec coding 能力靠业务语义精度达成（类型 / 约束 / 枚举 / 状态全集写全），不靠技术黑话，研发 AI 自己反推 key / SQL / 事件。唯一英文标识符例外 = 埋点事件 / 属性名（神策外部契约，已注册 key 不可翻译，详见 §三点八）。业务方案专名（TRTC / OBS / RTMP 等行业通用词）保留。

链路分流（复杂度判定走 CLAUDE.md，本表只列 PRD 专属形态）：

single 模式 → 场景 ≤ 10，单 md
split 模式 → 场景 > 10，主骨架 + scenes/，gen_prd_skeleton.py 自动判
散件链路（biweekly 内 / 单功能点 / 小修，≤ 50 行 md）→ 不走 12 章骨架，用 6 章紧凑模板（见 projects/biweekly/README.md §4），自检仍跑 check_prd_md.sh
方案型项目（跨 ≥ 2 系统 / 资金流转 / 多团队 / 纯后端）→ 不走 pipeline，PM 自定章节，文档仍 md（详见 § 注意事项）
老项目持续迭代（baseline 文档集模型）：产品线已立 prd-{产品线}-baseline.md → 本轮需求写 delta（gen_prd_skeleton.py --profile delta），上线后 ① 补 baseline changelog 行 ② 反向合并进 baseline 模块章（手动 Edit 不重跑骨架）。baseline / delta 都要达 spec coding 规范。详见 Step 5 + artifact-conventions.md §六
老项目 docx 维护 → 从零写新 md v{N+1} 推覆盖原 wiki 页，老 docx 进 archive/legacy-docx/

不做：UI 视觉规范（设计稿 + design system 承载）/ 技术方案（归 architecture-diagrams）/ 实现细节（不写 SQL / 接口 schema / 框架状态）。

改脚本前 30 秒

hook 守的是「Read 过本文件」不看读了多少行。改 scripts/.py 用 Read 此文件 limit=80（§1+§2 即够）。改产出物（prd-.md）建议全文。

Public API（不可改签名）：

python3 gen_prd_skeleton.py -p {产品线/项目} -v {N} [--mode single|split] [--profile baseline|delta] — 新建空骨架（baseline 落产品线根无版本号 / delta 落 deliverables / 缺省普通 12 章）
python3 prd_compose.py <prd.md> -o composed.md — split → 单页（push 前自动调用）
python3 read_prd_section.py <prd.md> --toc | -s 5.1 | --grep 关键词 — 按章节读 / TOC / grep
python3 split_prd.py <prd.md> — single → split 一次性迁移
python3 screenshot_for_prd.py --imap <html> -o <assets_dir> — IMAP 模式截图
bash check_prd_md.sh <prd.md> [--skeleton] — md 自检（FAIL/WARN 分级；死链查按是否有 -scenes/ 判 split，单文件 delta / baseline 豁免）
python3 cold_read.py --prepare <prd.md> [--targets 3.1,4.1,5.1] — 交付前冷读打包（context 文件 + 探针 prompt + 报告模板），实际冷读派子代理跑
from humanize.md_scan import scan_human_voice_md, scan_prd_structural_md — md 扫描
from core.md_renderer import MdWriter, scene_5section_card — md 输出原语
from sections_md import build_full_skeleton, build_baseline_skeleton, build_delta_skeleton, build_scene_file, SceneInfo — 骨架编排

会拦你的 hook（真实 gate 名，dispatcher 在 lib/post-checks.sh / lib/checkers.sh / lib/pre-writeedit-guards.sh）：

script-syntax-gate / cjk-punct — 写 .py/.sh + md 自动跑
prd-check-gate — gen_prd*.py 后自动跑 check_prd_md.sh --skeleton
prd-cross-check-gate — PRD 写入后自动跑 7 维结构校验
plain-language-gate — 扫正文裸编号 / 锚点 / 翻译腔
pm-visual-gate — 扫视觉越界 + 散件 leftright
baseline-fresh-gate — 编辑 baseline / delta 后查反向合并新鲜度
skill-load-gate — 改 prd-*.md / prd-*-scenes/*.md 必先 Read 本 SKILL.md + info-ownership.md

改完跑啥：

bash .claude/skills/prd/scripts/check_prd_md.sh projects/{项目}/deliverables/prd-*.md

深入读什么：完整章节归属 Read references/prd-chapter-rules.md；场景模板 Read references/prd-scene-templates.md（写 5/6/7 章前）；自检规则 grep -A 15 "^## 自检清单" SKILL.md。

硬规则（FAIL 即拦）

写 PRD 前脑里装 4 条正文红线（踩一条 check_prd_md.sh 就 FAIL）： ① 禁裸场景编号 A-1 / B-2（除标题 / 2.1 表 / 截图名 / 埋点名），引用用「章节号 + 白话名」或纯白话。单文件豁免（baseline + single delta 都是单文件，模块树按编号索引合法）——死链只在 split（有 -scenes/）查 ② 禁章节锚点 §5.1 / §X.Y（章节号锚点 split 拼页后是死链，PRD 正文直接用白话名「见『发帖』章节」）。单文件豁免（baseline + single delta 内 §具名锚点是合法内跳）——死链只在 split 查 ③ 全文讲人话，契约层也用中文：§3.2 业务对象 / §3.3 状态机写中文字段名 + 类型 + 约束 + 枚举（不写 trtc_enabled，写「主播 TRTC 标志｜布尔｜默认关」）。唯一例外 = 埋点章：PM 起事件英文名 + 属性英文名，既有事件抄神策真名（走 probe_event_properties.py），新事件按 §三点八命名约定 ④ 禁「（新增）」「（变更）」行内版本标签（会被 date_tag_hits 抓）。版本 delta 统一写在 1.4 章集中列

10 条核心硬规则

全文讲人话，不写技术黑话 — 全文（含契约层 §3.2/3.3）禁 snake_case 研发字段（trtc_enabled / card_id）+ 禁 触发 / 读 / 写 / 事件 / API schema / DB schema。PM 用业务语义描述（「新增一条帖子记录」），研发 AI 自己反推 SQL / 事件名 / key。唯一例外 = 埋点章事件 / 属性英文名（神策外部契约）。业务方案专名（TRTC / OBS / RTMP）保留。完整禁用清单 references/prd-scene-templates.md
正文禁裸场景编号 + 禁 §X.Y 章节锚点（见红线 ①②，单文件 = baseline + single delta 同样豁免，死链只在 split 查）— A-1 / B-2 / M-1 / F-1 和 §5.1 / §4.1 只能在章节标题、第 2.1 场景地图表、截图文件名、埋点事件名、md 链接里出现。正文跨章引用用「章节号 + 白话名」（见 4.1 一帖一卡）或「编号 + 白话名」（F-1 推荐加权）或纯白话名。plain-language-gate hook + check_prd_md.sh 兜底
5/6/7 章子场景必须扁平 — 禁 5.1.1 / 5.1.2 嵌套。一件事需要拆就拆并列 5.1 / 5.2。split_prd.py 检测嵌套直接报错
同一字段只写一次 — 跨场景共用规则进第 4 章，场景独有进 5/6/7.x 系统检查；通用文案进第 8 章，场景文案进 5/6/7.x；状态机进 3.3，场景状态分支进 5/6/7.x；异常场景共性进第 4 章「全局异常降级总则」（接口超时 / 缓存兜底 / 全站规则继承 / 承载方边界），场景文件只留 1–3 条独有项 + 一行豁免注释。异常表 4 不写规则见 references/prd-scene-templates.md §4.3.1。完整归属矩阵 references/prd-chapter-rules.md §二
CJK 标点 + 圈数字 — CJK 旁禁半角 ,:;()，禁圈数字 ①②③。check_cjk_punct.py --strict + humanize/md_scan.py 兜底
禁 mermaid / PlantUML / HTML 注释 — Confluence markdown 宏不渲染，写了在 wiki 上看到源码。流程图改「起点 / 终点 / 触发 / 延迟」表 + 一句路径文字；状态机改「起始状态 / 触发事件 / 终止状态 / 谁触发」表。必须图走 flowchart skill 出 SVG / PNG 后 ![](./assets/xxx.svg) 引用。详见 references/prd-chapter-rules.md §三点五
禁具体 URL / 路由 — PM 定业务不定技术实现。出现 /activity-center /user/profile = 越权。业务语义用「独立页 / 独立路由 / 独立落地页」描述，具体路径让前端决定。唯一例外：M-2 编辑页讲运营填"相对路径"字段（字段含义说明）。check_prd_md.sh 兜底
PM 角色越界禁词 — 禁词分类：① JS 事件（hover / onclick）② DOM API（DOM / display:none）③ 国际化（i18n key）④ 缓存（cache / localStorage）⑤ 框架状态（dirty / pristine）⑥ UI 英文（modal / chip / tooltip 用「弹窗 / 胶囊 / 提示」）⑦ 像素断点（<768px / @media）⑧ 技术变量名（topicData / tag.hot 驼峰）。埋点章节是 PM 必写区：事件英文名 / 属性英文名 / 数据类型 / 触发机制 PM 必填，10 列模板见 references/prd-chapter-rules.md §三点八
禁 --- 水平线分隔符 — Confluence 不渲染 md 水平线且显示丑（横线断裂 / 撑满整宽），章节靠 # / ## 标题自然分隔。MdWriter.hr() 为 no-op（禁用入口），check_prd_md.sh 扫单独成行 --- → FAIL；表格分隔符 |---| 不受影响（含 |）
禁 > 引用块 — Confluence blockquote 渲染丑（左竖线 + 灰底 + 缩进，破坏文档流）。业务故事（章节 / 场景定调）改 **业务故事**：正文（「业务故事」加粗、正文不加粗），章首不要定调金句。MdWriter.pullquote() 为 no-op、chapter_story() 已改粗体引导，check_prd_md.sh 扫 ^> → FAIL（baseline 历史 living 文档豁免，等迭代消化）

核心输出规范

PRD 是 baseline 决策的集中体现，不是重新发明。md 形态保证：自包含 / 人读友好 / AI 可消费。

模式判定

模式	触发	结构
Single	场景数 ≤ 10	`prd-{简称}-v{N}.md`（单文件，12 章全在内）+ `assets/`
Split	场景数 > 10 / `--mode split` 强制	`prd-{简称}-v{N}.md`（主骨架）+ `prd-{简称}-v{N}-scenes/`（每场景一个 md，~80-150 行）+ `assets/`

模式自动判定：gen_prd_skeleton.py 读 scene-list.md 数场景数。single → split 用 split_prd.py，反向用 prd_compose.py。

章节归属表（行为规格 / 页面结构落位）

PRD md 是单一权威产出物，下列类型信息直接写进对应章节：

类型	落位
业务对象词典（属性 / 生命周期 / 数据来源 / 关系）	第 3.2 章
业务动作（UI 场景）	5/6/7.x 子场景的「页面元素 & 规则」区块表 4 列
业务动作（横切策略 / 后端流程）	5/6/7.x 子场景的粗体段 + bullet
条件分支业务规则（可断言形式 · 可选档）	第 4 章「给定｜当｜则」三列表（含分支 / 阈值 / 多业务态时用，见 `references/prd-scene-templates.md §4.5`；`branch_prose_hits` WARN 兜底）
状态机	第 3.3 章
非功能性 SLA	第 10 章
优先级 P0/P1/P2	第 2.2 章
通用文案清单	第 8 章
场景独有文案	区块表「文案」列
信息层次 / 数据来源	区块表「数据来源」列
视觉调性	不单独记录（UI 设计稿 + design system 承载）

流程图政策

PRD 里禁写 mermaid / PlantUML 源码——Confluence 不渲染。按复杂度分档：

简单二端流程（≤ 3 节点 / 单分支）→ 起点 / 终点 / 触发 / 延迟表，骨架默认生成在 §2.3 / §3.3
多角色 / 多分支 / 跨系统（内审 L58 硬指标必填）→ 走 flowchart skill 出 drawio + SVG，PRD 用 ![](./assets/flow-XX.svg) 引图

详见 references/prd-chapter-rules.md §三点五。

执行步骤

写 §1 PR-FAQ 前 → Read .claude/runbooks/pm-methodology.md §三 Outcome over Output（含 PR-FAQ 自检）。写 delta §6 决策段 → Read pm-methodology.md §二决策段四段法。

Step 0：新建 PRD（scaffold + 手填）

python3 .claude/skills/prd/scripts/gen_prd_skeleton.py -p {产品线/项目} -v {N}

生成空骨架（含 {{ 待填：... }} 占位符）。PM + AI 按章节填，截图放 deliverables/assets/，md 用 ./assets/xxx.png 相对路径。

填充顺序（自上而下，编号规则 → artifact-conventions.md §一，回读上下文 → §三）：

第 1 章背景目标（对照 baseline 概览 / 术语章 + projects/product-lines.md）
- 1.4 核心变更的基线是「当前线上」，不是「之前的 PRD 版本」。线上无此功能 → 全部【新增】，不写【变更】；元数据「线上基线」字段也写「无（本期全新增）」
- 1.5 用户角色写真实角色（发帖者 / 阅读者 / 运营 / 数据分析）+ 可见 / 可操作范围，不凑没上的角色
第 2 章场景地图（已自动从 scene-list 填好，PM 调整优先级）
第 3 章术语 + 业务对象
- 3.2 业务对象只写本期新增对象，既有对象（帖子 / 评论 / 作者等社区线上已有实体）一句「沿用线上现状，本 PRD 不重新定义」带过，不脑补状态机 / 字段 / 生命周期
- 3.3 状态机同理：只画本期新对象，既有对象状态沿用现状
第 4 章全局业务规则（先定 contract）
第 5/6/7 章子场景（按模板逐个填，可并行；UI 场景走区块表 4.1，横切策略走粗体段 4.2，详见 references/prd-scene-templates.md）
第 8/9/10 章（文案 / 埋点 / SLA，并行）
第 11/12 章（排期 + 附录，最后）

每填完一段跑一次 check_prd_md.sh <md> --skeleton（宽松模式跳占位符 / 截图 / freshness）。终态推 Confluence 前去 --skeleton 跑严格。

Step 1：升版（直接改 md）

md 是源文件，PM 直接 VS Code / Edit 改。改完跑 check_prd_md.sh 过则推。不需要 gen_prd_v{N+1}.py 这种 per-project 生成器。

split 模式：

改主骨架（1-4 / 8-12 章）→ 直接编辑 prd-xxx-v{N}.md
改某场景 → 编辑 prd-xxx-v{N}-scenes/{view}-{编号}-{名}.md
加新场景 → 主 md 的 5/6/7 章 bullet 加链接 + scenes/ 目录建新 md
删场景 → 主 md 删链接行 + 删 scenes/ 文件

Step 2：重生骨架的 stale 清理（--force 陷阱）

gen_prd_skeleton.py --force 会覆盖生成的文件，但不会清理以下 stale：

scene-list 把旧场景标 ⚠ 已迁移 / 挪到 J 系列后 → 老子场景 md 仍在 {scenes-dir}/
scene-list View 分组调整（如 back → cross 前缀）→ 旧 back-X-N-*.md 没删
PM 手动 mv 重命名骨架后再 --force → 脚本再生一份，二次 mv 可能嵌套

重生前固定流程：

# 1. 看现状
ls projects/{项目}/deliverables/prd-*-v{N}-scenes/
# 2. 对照 scene-list 期望（去掉 ⚠ 已迁移 行）
# 3. 强烈建议先删主 md + scenes 目录
rm -f projects/{项目}/deliverables/prd-*-v{N}.md
rm -rf projects/{项目}/deliverables/prd-*-v{N}-scenes/
# 4. 跑 gen
python3 .claude/skills/prd/scripts/gen_prd_skeleton.py -p {项目} -v {N}
# 5. 如要 rename（骨架短名 → 项目全称），单步 mv 别累加

别 --force 一把跑完——旧 stale 会被拼进 compose，check_prd_md.sh 会抓裸编号 / 消失场景引用 / 类型错位。

Step 3：截图回填

何时必须重拍（任一触发）：源 HTML 改了 / 新增 / 修改 / 删除场景编号 / 改设备布局 / 视觉规范 / 截图覆盖范围。

优先级 & 调用：

项目内有 projects/{项目}/scripts/screenshot_for_prd*.py → 直接调，不自己写：
```
python3 projects/{项目}/scripts/screenshot_for_prd.py
```
历史项目脚本多是 wrapper（保留项目 SCENE_MAP 白名单 + 调 framework shoot_from_imap）；原型截图模式自管的（如 activity-center），应 import framework helpers
IMAP 模式新项目 → framework CLI：
```
python3 .claude/skills/prd/scripts/screenshot_for_prd.py --imap <imap.html> -o deliverables/assets/
```
省略 --scenes 时按 .st h2 discover 全截；白名单格式 --scenes "scene-A-1.png=A-1 · 完整全貌,..."
原型模式新项目 → 写项目脚本 import framework helpers（launch_page / dismiss_all_overlays / fix_dpi / assert_screenshots_fresh），不从零起步：
```
sys.path.insert(0, "<repo>/.claude/skills/prd/scripts")
from screenshot_for_prd import launch_page, dismiss_all_overlays, fix_dpi
```

源 HTML 探测：discover_source_html 合并 prototype + IMAP 候选（*原型*.html / proto-*.html / *交互大图*.html / imap-*.html），取 mtime 最新。任一源动了 → PNG stale。archive / deprecated 子串排除。

命名 / 路径：

文件 scene-{编号}.png（如 scene-A-1.png / scene-D-0-mylive.png）
输出 deliverables/assets/，md 引用 ![alt](./assets/xxx.png)（split 子场景用 ../assets/）

自动守门：check_prd_md.sh --assert-fresh 比对源 HTML mtime（实为 .freshness.json hash 判定 .flow DOM 子树，无关 CSS / 注释不再误报；缺 manifest 降级 mtime），FAIL raise + 列过期清单。

推 Confluence：图片由 scripts/md_to_confluence.py 自动上传 attachment（扫 ./assets/），PM 无需手调。

Step 3.5：交付前冷读（叶子完整性反测 · 推 Confluence / 交付研发前必跑）

机械自检（check_prd_md.sh + cross-check 7 维）抓「形」——编号 / 术语 / 字段格式 / 死链。叶子完整性盲区（实时字段刷新触发点没写、快照字段生命周期模糊、展示窗口与数据保留期不对齐、跨章口径打架）是单文档语义缺口，机械抓不到，靠冷读反测。7 类盲区权威定义在 references/prd-scene-templates.md §4.6。

硬约束：冷读判断必须派干净上下文子代理（Agent 工具）——同 session 已读上下文会脑补，测不出盲点。脚本只打包探针，不调 Agent。

打包探针：
```
python3 .claude/skills/prd/scripts/cold_read.py --prepare <prd.md> [--targets 3.1,4.1,5.1]
```
省略 --targets 时自动选「静态」实体 / 规则 / 状态机章（最易埋叶子洞的章）。脚本产出：① context 文件（compose 全文 + scene-list，落 /tmp）② 每个 target 一段 === PROBE === 探针 prompt ③ cold-read-{date}.md 盲点清单模板（落 PRD 同目录）。
派干净子代理逐 target 跑：把每段 PROBE prompt 原样喂 Agent 工具（Explore / general-purpose），N 个 target 并行派。子代理 prompt 已内置隔离铁律（只 Read context 文件、禁读写 session-state、不脑补作者本意）。
回填盲点清单：把各子代理返回的盲点聚合进 cold-read-{date}.md，每条四件套（位置 + 盲区类别 + 冷读者会怎么误读 + 建议补法）。
逐条 triage：每条标「补文档 / 留版本 / 误报」。补 = 回 PRD 对应章补一句 / 一列 / 一行（业务语言）；属承重不变量则同步反向合并进 baseline（走 §9 指引）。补完重跑 check_prd_md.sh。

cross-check skill 的 Reader Testing 终验时调用本工序（不在 cross-check 复述机制）。

Step 4：推 Confluence

split 模式：脚本检测到 -scenes/ 强制 PM 选推送方式（不再静默 compose 推单页）。

方式 A · 1 父页 + N 章节子页（推荐 split 项目）：

# 新建
python3 scripts/md_to_confluence.py <prd.md> --split-children-by-chapter --parent-id <PARENT_SPACE_ID>
# 更新
python3 scripts/md_to_confluence.py <prd.md> --split-children-by-chapter --update-id <PARENT_PAGE_ID>

父页含 §1-3 + §8-12 全文 + §4-7 章节链接到子页；子页 = 该章全部场景内容。更新模式按子页 title 自动匹配（子页名固定「{Part 0/1/2/3 白话标题}」）。

方式 B · 单页 compose（场景少 / 历史页已是单页）：

python3 scripts/md_to_confluence.py <prd.md> --no-split --parent-id <id>
python3 scripts/md_to_confluence.py <prd.md> --no-split --update-id <id>

--no-split 绕开 split 门强制 compose 单页；single 模式 PRD（无 -scenes/）不需要此 flag。

single 模式 PRD：

python3 scripts/md_to_confluence.py <prd.md> --parent-id <id>
python3 scripts/md_to_confluence.py <prd.md> --update-id <id>

自动行为（所有模式）：

本地图片：扫 ![](./assets/...) → 上传 attachment → md 路径改写为 attachment 文件名（DEFAULT_IMAGE_WIDTH=360px）
区块表自动渲染：识别 4 列表头 → 整段切走转原生 storage <table> + <ul><li> bullet（按 cell 内 ； 切）。source 写 ； 串多条规则即可，不要手敲 <br> / bullet
推送前剥离内部内容：① 顶级标题含「反向合并指引」的整章（delta §9，PM 上线后 checklist）② 文档头元信息块（H1 与首章之间，仅当全为元信息行）。源 md 不动只裁推送版，wiki 上是干净的 §1-§8 规格。--exclude-section <关键词> 追加排除 / --keep-preamble 保留头部（细节见 cli-cheatsheet）

推送方式选择规则：

split 项目首推 → AI 必须问 PM 选 A / B 再执行
split 项目复推 → 默认 A 方式（保持 1 父 N 子结构）
父子页结构一旦上线就不要轻易变（B 转 A 要手工删旧子页或反之）

首推同名冲突：--parent-id create 时若 space 下已有同名页，Confluence 返回 HTTP 400。脚本在 create 前已做 search_pages 同名预检，命中会打印同名页 URL + 提示 PM 三选一：

新建新版页：加 --title "示例社区交易卡片 PRD（2026-05-12）" 改名（带日期 / 版本号 / 场景范围）
覆盖历史页：改用 --update-id <历史 pageId> 覆盖推
历史页先归档：手工 wiki 把历史页移到 archive 空间 / 加后缀「- 历史版本」，再跑原命令

AI 在 PM 推之前主动问一次。

Step 5：老项目迭代（baseline / delta 循环）

产品线已立 prd-{产品线}-baseline.md 时，迭代不重写 baseline，走文档集循环（模型全貌见 artifact-conventions.md §六）：

baseline 首建（仅迁移 / 首建一次）：gen_prd_skeleton.py -p {产品线} -v 1 --profile baseline，落产品线根、无版本号、living。此后绝不重跑骨架（--force 会 clobber 已填内容），反向合并一律手动 Edit。
写本轮 delta：gen_prd_skeleton.py -p {产品线} -v {版本} --profile delta --quarter 2026Q3 生成 delta 骨架，脚本直接落 deliverables/{季度}/{版本}/（季度 = 2026Q3 格式，按季度 KPI 聚集；一个季度下多版本，如 deliverables/2026Q3/2.1.1/）。该目录整包装该轮 delta PRD + imap + prototype + 该版 assets。只写本轮 N 需求 + WHY，术语 / 模块树 / 未变规则引 baseline 不重复，跨引 baseline 锚场景编号 / 业务规则 ID。
上线后承重不变量（顺序不可乱）：先在 baseline 变更记录章写 changelog 行（日期｜触及模块｜delta 链接｜状态=已登记）→ 反向合并进 baseline 对应模块章（手动 Edit）→ 状态推进「已合并」→ 整季度/版本文件夹归 archive/{季度}/。
新鲜度：check_baseline_fresh.py {产品线} + baseline-fresh-gate hook 守第一层（已上线 delta 未合并报红）；baseline 模块章头 最后核对线上: 日期 / 人 守第二层（超 60d 报黄）。

骨架真实产出章节集：baseline = 概览 / 术语 / 模块树 / 全局规则 / N 个模块章 / 文案 / 非功能 / 变更记录；delta = 9 章树（§1 背景价值 / §2 本轮需求 / §3 业务对象增量 / §4 状态机增量 / §5 全局规则增量 / §6 决策记录 / §7 埋点 / §8 排期 / §9 反向合并指引）。

delta 迭代档位（--tier，决定 §2 行文）：一份 delta 先认档位，再按档位组织 §2 本轮需求。

档位	`--tier`	触发	版本号	§2 行文
补丁包	`patch`	散修复 + 小调，互不依赖	x.y.z 三段	出 §2.0 索引表（轴 = 跟版边界）+ 按轴分组，不强求叙事
内聚特性	`feature`（默认）	单一能力，有新对象 / 状态机	x.y 两段	平铺，按用户旅程叙事
集合体 / 多团队	`bundle`	N 个松耦合需求跨模块 / 团队	x.y 两段	强制 §2.0 索引表 + 按单轴分组 H2

patch / bundle 自动吐 §2.0 本轮需求索引表（编号 / 需求 / 分组 / 反向合并目标 / 优先级），分组只许沿一条轴（模块 > 用户旅程 > 跟版边界 > 团队，选读者跨引最少的一条），详见 prd-chapter-rules.md §2 行文。

--tier（§2 组织）与四支柱填充（§3/§4/§5）正交，是两根独立的轴：

§3/§4/§5 不需要二级开关——全新能力 delta 填实即与 baseline 对应章（§3.2 业务对象 / §3.3 状态机 / §4 全局规则）同构、反向合并直接搬章；只动既有场景的 delta 本轮无该支柱变更直接删空章（符「迭代只写真有改动」铁律）。
--tier 只管 §2 怎么排版（索引 + 分组 vs 平铺叙事），不决定四支柱有没有内容。两者各管各的，别混。

反向合并映射唯一落在 §9 表：骨架正文不吐「本轮无 X 则删本章 / 上线后反向合并进 baseline §X」这类章首导语（plumbing 进不了交付物）。哪章可删、合并到 baseline 哪章，看 §9 反向合并指引表（推 Confluence 时 §9 自动剥离，见 Step 4）。

API 速查

# 输出 md 字符串
from core.md_renderer import MdWriter, scene_5section_card, bold, italic
w = MdWriter()
w.h1("1. 项目背景与目标")
w.h2("1.1 背景")
w.bullet_list(["痛点 A", "痛点 B"])
w.field_bullet("业务描述", "用户点「发布」把内容发到社区")
w.field_bullet_list("前置条件", ["已登录", "未被禁言"])
w.table(headers=["编号", "场景"], rows=[["A-1", "发帖"]])
w.image("./assets/scene-A-1-wireframe.png", alt="发帖低保真")
md = w.render()

# 12 章骨架编排
from sections_md import build_full_skeleton, build_scene_file, SceneInfo
md = build_full_skeleton(info={"project_name": "xxx", "version": "1", "scenes": [...]})

# 解析现有 md
from humanize.md_scan import scan_human_voice_md, scan_prd_structural_md
voice_hits = scan_human_voice_md(md_text)
struct_hits = scan_prd_structural_md(md_text, scene_count=10)

自检清单（PM 交付前过一遍）

结构合规：bash check_prd_md.sh <prd.md> exit 0（§X.Y 锚点 + 裸场景编号死链查只对 split 开，单文件 = baseline + single delta 天然豁免；profile 仅控 baseline 其他行为）
截图齐全：./assets/ 下所有引用文件存在
模板字段名锁定：grep -E "^- \*\*(触发|读|写|事件|API)" <md> 无命中（UI 场景统一走区块表）
裸编号清查：正文（非 heading / 非表格）grep [ABCDEFM]-[0-9] 仅出现在「编号 + 白话名」组合或链接里（单文件 = baseline + single delta 豁免，仅 split 拦）
占位符清掉：grep {{ 待填 无命中（终态）
CJK 标点：python3 scripts/check_cjk_punct.py <md> --strict exit 0
跨章引用合规：见 X.Y 白话名 而非裸 见 X.Y / 见 A-1
全文讲人话：契约层（§3.2/3.3）无 snake_case 研发字段（用中文业务名），唯埋点章事件 / 属性英文名例外
结构化优先（禁分号滥用 · WARN）：单行 ≥ 2 个分号（； / ;）= 子句堆一坨，拆成 bullet 或 1. 2. 3. 编号；表格行豁免（cell 内 ； 是 Confluence 切 bullet 的约定分隔符）
禁长句 run-on（拆句优先 · WARN）：句段（。！？； 之间）≥ 100 字 = 一口气读不完，拆句或转列表；表格行豁免。与分号校验互补（分号管「；」串，长句管「，」串）
叶子完整性：实时 / 快照字段标清生命周期与刷新触发点，阈值标端点（含不含），状态机穷举（含自环 / 离线再上线），展示窗口与数据保留期对齐。交付 / 推 Confluence 前跑「交付前冷读」Step（cold_read.py + 派干净子代理），盲点逐条 triage。7 类盲区见 references/prd-scene-templates.md §4.6
禁水平线 ---：grep -cE '^-{3,}\s*$' <md> = 0（单独成行连字符 = Confluence 丑水平线；表格 |---| 不算）。章节用 h1/h2 分隔
禁引用块 >：grep -cE '^\s*>' <md> = 0（Confluence blockquote 渲染丑；业务故事改 **业务故事**：正文；baseline 例外）

References 索引

必读（写 PRD 前加载）：

references/prd-chapter-rules.md — 章结构 / 字段归属矩阵 / 编号 - 人话分层 / Confluence 渲染约束 / PM 越界禁词 / single-vs-split / 自检清单

按需读（命中具体步骤再加载）：

references/prd-scene-templates.md — 写第 5/6/7 章场景前加载（UI 场景区块表 / 横切策略模板 / 数据影响写法）
references/prd-optional-sections.md — §1.6 竞品调研 / §1.7 多方案对比模板，PM 加可选章节时 copy
references/metrics-framework.md — 写 §9 埋点 / §1.4 北极星指标时加载
讲人话共性铁律见 .claude/runbooks/human-voice-rules.md，PRD 形态规则在 prd-chapter-rules §三 / §三点八

注意事项

可选章节（按需 copy）

gen_prd_skeleton.py 默认生成 12 章骨架。以下两节按需追加在 §1.5 后、§2 前：

§1.6 竞品调研：项目首次涉足某场景 / 内审要求竞品参照 / 决策依据需向 leader 说明时加。简单迭代不加
§1.7 多方案对比：本期有 2+ 候选方案 / 技术路径有分歧 / 需说明为何选 A 不选 B 时加。单方案需求不加

模板见 references/prd-optional-sections.md，骨架不默认生成，PM 觉得需要时从模板 copy 进 PRD md。

方案型项目（不走标准 pipeline）

判定信号（任一）：

涉及独立 mid-office + 业务系统 + 风控系统跨系统对接
含资金路径 / 跨账户结算
涉及法务 / 合规批复路径
仅后端架构无 UI 流（如打分引擎 / 数据 pipeline）

不强制 12 章。PM 自定章节（建议对标共建 PRD 模板），文档仍 md，仍走 md_to_confluence.py 推 wiki。

文档分工建议：方案概览 / 系统拓扑 / 各系统职责 / 接口 schema / 资金对账 / 风险与回滚 / 灰度计划。

name	prd
description	当用户提到「PRD」「需求文档」时触发。基于 IMAP / 原型输出 PRD 亦触发。 PRD 形态为 md（含本地截图，推 Confluence 时脚本自动上传图片）。
type	pipeline
output_format	.md
output_prefix	prd-
pipeline_position	5
depends_on	["scene-list"]
optional_inputs	["interaction-map","prototype"]
consumed_by	["cross-check"]
owns	["字段口径","池策略全局规则","埋点事件属性","状态机","跳转规则文字"]
forbids	["视觉规范","技术实现","状态机交互细节"]
scripts	{"gen_prd_skeleton.py":"新建 PRD 空骨架 — python3 gen_prd_skeleton.py -p {产品线/项目} -v 1 [--mode single\|split] [--profile baseline\|delta] [--tier patch\|feature\|bundle]（baseline 落产品线根无版本号 / delta 落 deliverables 有版本号；缺省 = 普通 PRD。--tier 仅 delta 生效，定迭代档位 + §2 行文，见下文 delta 档位）","prd_compose.py":"split 模式拼接成完整 md（push 前自动调用）— python3 prd_compose.py <prd.md> -o composed.md","read_prd_section.py":"按章节读 / TOC / grep — python3 read_prd_section.py <prd.md> --toc \| -s 5.1 \| --grep 关键词。--toc 给每章标 [静态]/[动态]（动态 = 变更记录/决策/排期等演化章）","split_prd.py":"single → split 一次性迁移 — python3 split_prd.py <prd.md>","screenshot_for_prd.py":"PRD 截图 framework（IMAP 模式 shoot_from_imap + 截图同步落 .freshness.json manifest（v2：hash 而非 mtime，按 .flow DOM 子树 hash 判定，无关 CSS/注释/reformat 不再误报；缺 manifest 自动降级 mtime）+ 通用 helpers）— python3 screenshot_for_prd.py --imap <html> -o <assets_dir>；项目原型脚本 import shoot_from_imap / dismiss_all_overlays / assert_screenshots_fresh。--assert-fresh 模式供 check_prd_md.sh 调用","check_prd_md.sh":"md 自检（FAIL/WARN 分级，--skeleton 模式跳占位符 + 截图 + freshness）— bash check_prd_md.sh <prd.md> [--skeleton]。§X.Y 锚点 + 裸场景编号死链查只对 split（有 `-scenes/` 子目录）开，单文件（single delta / baseline）天然豁免；profile（按文件名 prd-*-baseline.md 判）只控 baseline 其他行为","cold_read.py":"交付前冷读反测打包（叶子完整性 7 类盲区）— python3 cold_read.py --prepare <prd.md> [--targets 3.1,4.1,5.1]。compose 全文 + 附 scene-list 落 context 文件 + 生成 N 个干净子代理探针 prompt + 落 cold-read-{date}.md 盲点清单模板。脚本只打包，实际冷读由「交付前冷读」Step 派 Agent 子代理跑","humanize/md_scan.py":"md 版扫描 — scan_human_voice_md(md_text) / scan_prd_structural_md(md_text)","core/md_renderer.py":"md 输出原语 — MdWriter / scene_5section_card / 等（被 sections_md.py 调用）","sections_md.py":"章节骨架生成函数（被 gen_prd_skeleton.py 调用）：build_full_skeleton（普通 12 章）/ build_baseline_skeleton（baseline 模块树）/ build_delta_skeleton（delta 单轮迭代）","check_baseline_fresh.py":"baseline 反向合并新鲜度校验（根 scripts/，非本 skill 目录）— python3 scripts/check_baseline_fresh.py {产品线}。已上线 delta 未合并报红 + 模块章超期报黄"}

PRD Skill（产品需求文档，md 版）

触发与定位

收到新需求 → 先按 CLAUDE.md「收到需求路由」过 PM-GATE 4 风险扫描 + 复杂度判链路，再进 Step 0。

何时触发：用户说「PRD / 需求文档」；IMAP / prototype 完成后输出 PRD 亦触发。

链路分流（复杂度判定走 CLAUDE.md，本表只列 PRD 专属形态）：

single 模式 → 场景 ≤ 10，单 md
split 模式 → 场景 > 10，主骨架 + scenes/，gen_prd_skeleton.py 自动判
散件链路（biweekly 内 / 单功能点 / 小修，≤ 50 行 md）→ 不走 12 章骨架，用 6 章紧凑模板（见 projects/biweekly/README.md §4），自检仍跑 check_prd_md.sh
方案型项目（跨 ≥ 2 系统 / 资金流转 / 多团队 / 纯后端）→ 不走 pipeline，PM 自定章节，文档仍 md（详见 § 注意事项）
老项目持续迭代（baseline 文档集模型）：产品线已立 prd-{产品线}-baseline.md → 本轮需求写 delta（gen_prd_skeleton.py --profile delta），上线后 ① 补 baseline changelog 行 ② 反向合并进 baseline 模块章（手动 Edit 不重跑骨架）。baseline / delta 都要达 spec coding 规范。详见 Step 5 + artifact-conventions.md §六
老项目 docx 维护 → 从零写新 md v{N+1} 推覆盖原 wiki 页，老 docx 进 archive/legacy-docx/

不做：UI 视觉规范（设计稿 + design system 承载）/ 技术方案（归 architecture-diagrams）/ 实现细节（不写 SQL / 接口 schema / 框架状态）。

改脚本前 30 秒

hook 守的是「Read 过本文件」不看读了多少行。改 scripts/.py 用 Read 此文件 limit=80（§1+§2 即够）。改产出物（prd-.md）建议全文。

Public API（不可改签名）：

python3 gen_prd_skeleton.py -p {产品线/项目} -v {N} [--mode single|split] [--profile baseline|delta] — 新建空骨架（baseline 落产品线根无版本号 / delta 落 deliverables / 缺省普通 12 章）
python3 prd_compose.py <prd.md> -o composed.md — split → 单页（push 前自动调用）
python3 read_prd_section.py <prd.md> --toc | -s 5.1 | --grep 关键词 — 按章节读 / TOC / grep
python3 split_prd.py <prd.md> — single → split 一次性迁移
python3 screenshot_for_prd.py --imap <html> -o <assets_dir> — IMAP 模式截图
bash check_prd_md.sh <prd.md> [--skeleton] — md 自检（FAIL/WARN 分级；死链查按是否有 -scenes/ 判 split，单文件 delta / baseline 豁免）
python3 cold_read.py --prepare <prd.md> [--targets 3.1,4.1,5.1] — 交付前冷读打包（context 文件 + 探针 prompt + 报告模板），实际冷读派子代理跑
from humanize.md_scan import scan_human_voice_md, scan_prd_structural_md — md 扫描
from core.md_renderer import MdWriter, scene_5section_card — md 输出原语
from sections_md import build_full_skeleton, build_baseline_skeleton, build_delta_skeleton, build_scene_file, SceneInfo — 骨架编排

会拦你的 hook（真实 gate 名，dispatcher 在 lib/post-checks.sh / lib/checkers.sh / lib/pre-writeedit-guards.sh）：

script-syntax-gate / cjk-punct — 写 .py/.sh + md 自动跑
prd-check-gate — gen_prd*.py 后自动跑 check_prd_md.sh --skeleton
prd-cross-check-gate — PRD 写入后自动跑 7 维结构校验
plain-language-gate — 扫正文裸编号 / 锚点 / 翻译腔
pm-visual-gate — 扫视觉越界 + 散件 leftright
baseline-fresh-gate — 编辑 baseline / delta 后查反向合并新鲜度
skill-load-gate — 改 prd-*.md / prd-*-scenes/*.md 必先 Read 本 SKILL.md + info-ownership.md

改完跑啥：

bash .claude/skills/prd/scripts/check_prd_md.sh projects/{项目}/deliverables/prd-*.md

硬规则（FAIL 即拦）

写 PRD 前脑里装 4 条正文红线（踩一条 check_prd_md.sh 就 FAIL）： ① 禁裸场景编号 A-1 / B-2（除标题 / 2.1 表 / 截图名 / 埋点名），引用用「章节号 + 白话名」或纯白话。单文件豁免（baseline + single delta 都是单文件，模块树按编号索引合法）——死链只在 split（有 -scenes/）查 ② 禁章节锚点 §5.1 / §X.Y（章节号锚点 split 拼页后是死链，PRD 正文直接用白话名「见『发帖』章节」）。单文件豁免（baseline + single delta 内 §具名锚点是合法内跳）——死链只在 split 查 ③ 全文讲人话，契约层也用中文：§3.2 业务对象 / §3.3 状态机写中文字段名 + 类型 + 约束 + 枚举（不写 trtc_enabled，写「主播 TRTC 标志｜布尔｜默认关」）。唯一例外 = 埋点章：PM 起事件英文名 + 属性英文名，既有事件抄神策真名（走 probe_event_properties.py），新事件按 §三点八命名约定 ④ 禁「（新增）」「（变更）」行内版本标签（会被 date_tag_hits 抓）。版本 delta 统一写在 1.4 章集中列

10 条核心硬规则

全文讲人话，不写技术黑话 — 全文（含契约层 §3.2/3.3）禁 snake_case 研发字段（trtc_enabled / card_id）+ 禁 触发 / 读 / 写 / 事件 / API schema / DB schema。PM 用业务语义描述（「新增一条帖子记录」），研发 AI 自己反推 SQL / 事件名 / key。唯一例外 = 埋点章事件 / 属性英文名（神策外部契约）。业务方案专名（TRTC / OBS / RTMP）保留。完整禁用清单 references/prd-scene-templates.md
正文禁裸场景编号 + 禁 §X.Y 章节锚点（见红线 ①②，单文件 = baseline + single delta 同样豁免，死链只在 split 查）— A-1 / B-2 / M-1 / F-1 和 §5.1 / §4.1 只能在章节标题、第 2.1 场景地图表、截图文件名、埋点事件名、md 链接里出现。正文跨章引用用「章节号 + 白话名」（见 4.1 一帖一卡）或「编号 + 白话名」（F-1 推荐加权）或纯白话名。plain-language-gate hook + check_prd_md.sh 兜底
5/6/7 章子场景必须扁平 — 禁 5.1.1 / 5.1.2 嵌套。一件事需要拆就拆并列 5.1 / 5.2。split_prd.py 检测嵌套直接报错
同一字段只写一次 — 跨场景共用规则进第 4 章，场景独有进 5/6/7.x 系统检查；通用文案进第 8 章，场景文案进 5/6/7.x；状态机进 3.3，场景状态分支进 5/6/7.x；异常场景共性进第 4 章「全局异常降级总则」（接口超时 / 缓存兜底 / 全站规则继承 / 承载方边界），场景文件只留 1–3 条独有项 + 一行豁免注释。异常表 4 不写规则见 references/prd-scene-templates.md §4.3.1。完整归属矩阵 references/prd-chapter-rules.md §二
CJK 标点 + 圈数字 — CJK 旁禁半角 ,:;()，禁圈数字 ①②③。check_cjk_punct.py --strict + humanize/md_scan.py 兜底
禁 mermaid / PlantUML / HTML 注释 — Confluence markdown 宏不渲染，写了在 wiki 上看到源码。流程图改「起点 / 终点 / 触发 / 延迟」表 + 一句路径文字；状态机改「起始状态 / 触发事件 / 终止状态 / 谁触发」表。必须图走 flowchart skill 出 SVG / PNG 后 ![](./assets/xxx.svg) 引用。详见 references/prd-chapter-rules.md §三点五
禁具体 URL / 路由 — PM 定业务不定技术实现。出现 /activity-center /user/profile = 越权。业务语义用「独立页 / 独立路由 / 独立落地页」描述，具体路径让前端决定。唯一例外：M-2 编辑页讲运营填"相对路径"字段（字段含义说明）。check_prd_md.sh 兜底
PM 角色越界禁词 — 禁词分类：① JS 事件（hover / onclick）② DOM API（DOM / display:none）③ 国际化（i18n key）④ 缓存（cache / localStorage）⑤ 框架状态（dirty / pristine）⑥ UI 英文（modal / chip / tooltip 用「弹窗 / 胶囊 / 提示」）⑦ 像素断点（<768px / @media）⑧ 技术变量名（topicData / tag.hot 驼峰）。埋点章节是 PM 必写区：事件英文名 / 属性英文名 / 数据类型 / 触发机制 PM 必填，10 列模板见 references/prd-chapter-rules.md §三点八
禁 --- 水平线分隔符 — Confluence 不渲染 md 水平线且显示丑（横线断裂 / 撑满整宽），章节靠 # / ## 标题自然分隔。MdWriter.hr() 为 no-op（禁用入口），check_prd_md.sh 扫单独成行 --- → FAIL；表格分隔符 |---| 不受影响（含 |）
禁 > 引用块 — Confluence blockquote 渲染丑（左竖线 + 灰底 + 缩进，破坏文档流）。业务故事（章节 / 场景定调）改 **业务故事**：正文（「业务故事」加粗、正文不加粗），章首不要定调金句。MdWriter.pullquote() 为 no-op、chapter_story() 已改粗体引导，check_prd_md.sh 扫 ^> → FAIL（baseline 历史 living 文档豁免，等迭代消化）

核心输出规范

PRD 是 baseline 决策的集中体现，不是重新发明。md 形态保证：自包含 / 人读友好 / AI 可消费。

模式判定

模式	触发	结构
Single	场景数 ≤ 10	`prd-{简称}-v{N}.md`（单文件，12 章全在内）+ `assets/`
Split	场景数 > 10 / `--mode split` 强制	`prd-{简称}-v{N}.md`（主骨架）+ `prd-{简称}-v{N}-scenes/`（每场景一个 md，~80-150 行）+ `assets/`

模式自动判定：gen_prd_skeleton.py 读 scene-list.md 数场景数。single → split 用 split_prd.py，反向用 prd_compose.py。

章节归属表（行为规格 / 页面结构落位）

PRD md 是单一权威产出物，下列类型信息直接写进对应章节：

类型	落位
业务对象词典（属性 / 生命周期 / 数据来源 / 关系）	第 3.2 章
业务动作（UI 场景）	5/6/7.x 子场景的「页面元素 & 规则」区块表 4 列
业务动作（横切策略 / 后端流程）	5/6/7.x 子场景的粗体段 + bullet
条件分支业务规则（可断言形式 · 可选档）	第 4 章「给定｜当｜则」三列表（含分支 / 阈值 / 多业务态时用，见 `references/prd-scene-templates.md §4.5`；`branch_prose_hits` WARN 兜底）
状态机	第 3.3 章
非功能性 SLA	第 10 章
优先级 P0/P1/P2	第 2.2 章
通用文案清单	第 8 章
场景独有文案	区块表「文案」列
信息层次 / 数据来源	区块表「数据来源」列
视觉调性	不单独记录（UI 设计稿 + design system 承载）

流程图政策

PRD 里禁写 mermaid / PlantUML 源码——Confluence 不渲染。按复杂度分档：

简单二端流程（≤ 3 节点 / 单分支）→ 起点 / 终点 / 触发 / 延迟表，骨架默认生成在 §2.3 / §3.3
多角色 / 多分支 / 跨系统（内审 L58 硬指标必填）→ 走 flowchart skill 出 drawio + SVG，PRD 用 ![](./assets/flow-XX.svg) 引图

详见 references/prd-chapter-rules.md §三点五。

执行步骤

写 §1 PR-FAQ 前 → Read .claude/runbooks/pm-methodology.md §三 Outcome over Output（含 PR-FAQ 自检）。写 delta §6 决策段 → Read pm-methodology.md §二决策段四段法。

Step 0：新建 PRD（scaffold + 手填）

python3 .claude/skills/prd/scripts/gen_prd_skeleton.py -p {产品线/项目} -v {N}

生成空骨架（含 {{ 待填：... }} 占位符）。PM + AI 按章节填，截图放 deliverables/assets/，md 用 ./assets/xxx.png 相对路径。

填充顺序（自上而下，编号规则 → artifact-conventions.md §一，回读上下文 → §三）：

第 1 章背景目标（对照 baseline 概览 / 术语章 + projects/product-lines.md）
- 1.4 核心变更的基线是「当前线上」，不是「之前的 PRD 版本」。线上无此功能 → 全部【新增】，不写【变更】；元数据「线上基线」字段也写「无（本期全新增）」
- 1.5 用户角色写真实角色（发帖者 / 阅读者 / 运营 / 数据分析）+ 可见 / 可操作范围，不凑没上的角色
第 2 章场景地图（已自动从 scene-list 填好，PM 调整优先级）
第 3 章术语 + 业务对象
- 3.2 业务对象只写本期新增对象，既有对象（帖子 / 评论 / 作者等社区线上已有实体）一句「沿用线上现状，本 PRD 不重新定义」带过，不脑补状态机 / 字段 / 生命周期
- 3.3 状态机同理：只画本期新对象，既有对象状态沿用现状
第 4 章全局业务规则（先定 contract）
第 5/6/7 章子场景（按模板逐个填，可并行；UI 场景走区块表 4.1，横切策略走粗体段 4.2，详见 references/prd-scene-templates.md）
第 8/9/10 章（文案 / 埋点 / SLA，并行）
第 11/12 章（排期 + 附录，最后）

每填完一段跑一次 check_prd_md.sh <md> --skeleton（宽松模式跳占位符 / 截图 / freshness）。终态推 Confluence 前去 --skeleton 跑严格。

Step 1：升版（直接改 md）

md 是源文件，PM 直接 VS Code / Edit 改。改完跑 check_prd_md.sh 过则推。不需要 gen_prd_v{N+1}.py 这种 per-project 生成器。

split 模式：

改主骨架（1-4 / 8-12 章）→ 直接编辑 prd-xxx-v{N}.md
改某场景 → 编辑 prd-xxx-v{N}-scenes/{view}-{编号}-{名}.md
加新场景 → 主 md 的 5/6/7 章 bullet 加链接 + scenes/ 目录建新 md
删场景 → 主 md 删链接行 + 删 scenes/ 文件

Step 2：重生骨架的 stale 清理（--force 陷阱）

gen_prd_skeleton.py --force 会覆盖生成的文件，但不会清理以下 stale：

scene-list 把旧场景标 ⚠ 已迁移 / 挪到 J 系列后 → 老子场景 md 仍在 {scenes-dir}/
scene-list View 分组调整（如 back → cross 前缀）→ 旧 back-X-N-*.md 没删
PM 手动 mv 重命名骨架后再 --force → 脚本再生一份，二次 mv 可能嵌套

重生前固定流程：

# 1. 看现状
ls projects/{项目}/deliverables/prd-*-v{N}-scenes/
# 2. 对照 scene-list 期望（去掉 ⚠ 已迁移 行）
# 3. 强烈建议先删主 md + scenes 目录
rm -f projects/{项目}/deliverables/prd-*-v{N}.md
rm -rf projects/{项目}/deliverables/prd-*-v{N}-scenes/
# 4. 跑 gen
python3 .claude/skills/prd/scripts/gen_prd_skeleton.py -p {项目} -v {N}
# 5. 如要 rename（骨架短名 → 项目全称），单步 mv 别累加

别 --force 一把跑完——旧 stale 会被拼进 compose，check_prd_md.sh 会抓裸编号 / 消失场景引用 / 类型错位。

Step 3：截图回填

何时必须重拍（任一触发）：源 HTML 改了 / 新增 / 修改 / 删除场景编号 / 改设备布局 / 视觉规范 / 截图覆盖范围。

优先级 & 调用：

项目内有 projects/{项目}/scripts/screenshot_for_prd*.py → 直接调，不自己写：
```
python3 projects/{项目}/scripts/screenshot_for_prd.py
```
历史项目脚本多是 wrapper（保留项目 SCENE_MAP 白名单 + 调 framework shoot_from_imap）；原型截图模式自管的（如 activity-center），应 import framework helpers
IMAP 模式新项目 → framework CLI：
```
python3 .claude/skills/prd/scripts/screenshot_for_prd.py --imap <imap.html> -o deliverables/assets/
```
省略 --scenes 时按 .st h2 discover 全截；白名单格式 --scenes "scene-A-1.png=A-1 · 完整全貌,..."
原型模式新项目 → 写项目脚本 import framework helpers（launch_page / dismiss_all_overlays / fix_dpi / assert_screenshots_fresh），不从零起步：
```
sys.path.insert(0, "<repo>/.claude/skills/prd/scripts")
from screenshot_for_prd import launch_page, dismiss_all_overlays, fix_dpi
```

命名 / 路径：

文件 scene-{编号}.png（如 scene-A-1.png / scene-D-0-mylive.png）
输出 deliverables/assets/，md 引用 ![alt](./assets/xxx.png)（split 子场景用 ../assets/）

推 Confluence：图片由 scripts/md_to_confluence.py 自动上传 attachment（扫 ./assets/），PM 无需手调。

Step 3.5：交付前冷读（叶子完整性反测 · 推 Confluence / 交付研发前必跑）

机械自检（check_prd_md.sh + cross-check 7 维）抓「形」——编号 / 术语 / 字段格式 / 死链。叶子完整性盲区（实时字段刷新触发点没写、快照字段生命周期模糊、展示窗口与数据保留期不对齐、跨章口径打架）是单文档语义缺口，机械抓不到，靠冷读反测。7 类盲区权威定义在 references/prd-scene-templates.md §4.6。

硬约束：冷读判断必须派干净上下文子代理（Agent 工具）——同 session 已读上下文会脑补，测不出盲点。脚本只打包探针，不调 Agent。

打包探针：
```
python3 .claude/skills/prd/scripts/cold_read.py --prepare <prd.md> [--targets 3.1,4.1,5.1]
```
省略 --targets 时自动选「静态」实体 / 规则 / 状态机章（最易埋叶子洞的章）。脚本产出：① context 文件（compose 全文 + scene-list，落 /tmp）② 每个 target 一段 === PROBE === 探针 prompt ③ cold-read-{date}.md 盲点清单模板（落 PRD 同目录）。
派干净子代理逐 target 跑：把每段 PROBE prompt 原样喂 Agent 工具（Explore / general-purpose），N 个 target 并行派。子代理 prompt 已内置隔离铁律（只 Read context 文件、禁读写 session-state、不脑补作者本意）。
回填盲点清单：把各子代理返回的盲点聚合进 cold-read-{date}.md，每条四件套（位置 + 盲区类别 + 冷读者会怎么误读 + 建议补法）。
逐条 triage：每条标「补文档 / 留版本 / 误报」。补 = 回 PRD 对应章补一句 / 一列 / 一行（业务语言）；属承重不变量则同步反向合并进 baseline（走 §9 指引）。补完重跑 check_prd_md.sh。

cross-check skill 的 Reader Testing 终验时调用本工序（不在 cross-check 复述机制）。

Step 4：推 Confluence

split 模式：脚本检测到 -scenes/ 强制 PM 选推送方式（不再静默 compose 推单页）。

方式 A · 1 父页 + N 章节子页（推荐 split 项目）：

# 新建
python3 scripts/md_to_confluence.py <prd.md> --split-children-by-chapter --parent-id <PARENT_SPACE_ID>
# 更新
python3 scripts/md_to_confluence.py <prd.md> --split-children-by-chapter --update-id <PARENT_PAGE_ID>

父页含 §1-3 + §8-12 全文 + §4-7 章节链接到子页；子页 = 该章全部场景内容。更新模式按子页 title 自动匹配（子页名固定「{Part 0/1/2/3 白话标题}」）。

方式 B · 单页 compose（场景少 / 历史页已是单页）：

python3 scripts/md_to_confluence.py <prd.md> --no-split --parent-id <id>
python3 scripts/md_to_confluence.py <prd.md> --no-split --update-id <id>

--no-split 绕开 split 门强制 compose 单页；single 模式 PRD（无 -scenes/）不需要此 flag。

single 模式 PRD：

python3 scripts/md_to_confluence.py <prd.md> --parent-id <id>
python3 scripts/md_to_confluence.py <prd.md> --update-id <id>

自动行为（所有模式）：

本地图片：扫 ![](./assets/...) → 上传 attachment → md 路径改写为 attachment 文件名（DEFAULT_IMAGE_WIDTH=360px）
区块表自动渲染：识别 4 列表头 → 整段切走转原生 storage <table> + <ul><li> bullet（按 cell 内 ； 切）。source 写 ； 串多条规则即可，不要手敲 <br> / bullet
推送前剥离内部内容：① 顶级标题含「反向合并指引」的整章（delta §9，PM 上线后 checklist）② 文档头元信息块（H1 与首章之间，仅当全为元信息行）。源 md 不动只裁推送版，wiki 上是干净的 §1-§8 规格。--exclude-section <关键词> 追加排除 / --keep-preamble 保留头部（细节见 cli-cheatsheet）

推送方式选择规则：

split 项目首推 → AI 必须问 PM 选 A / B 再执行
split 项目复推 → 默认 A 方式（保持 1 父 N 子结构）
父子页结构一旦上线就不要轻易变（B 转 A 要手工删旧子页或反之）

新建新版页：加 --title "示例社区交易卡片 PRD（2026-05-12）" 改名（带日期 / 版本号 / 场景范围）
覆盖历史页：改用 --update-id <历史 pageId> 覆盖推
历史页先归档：手工 wiki 把历史页移到 archive 空间 / 加后缀「- 历史版本」，再跑原命令

AI 在 PM 推之前主动问一次。

Step 5：老项目迭代（baseline / delta 循环）

产品线已立 prd-{产品线}-baseline.md 时，迭代不重写 baseline，走文档集循环（模型全貌见 artifact-conventions.md §六）：

baseline 首建（仅迁移 / 首建一次）：gen_prd_skeleton.py -p {产品线} -v 1 --profile baseline，落产品线根、无版本号、living。此后绝不重跑骨架（--force 会 clobber 已填内容），反向合并一律手动 Edit。
写本轮 delta：gen_prd_skeleton.py -p {产品线} -v {版本} --profile delta --quarter 2026Q3 生成 delta 骨架，脚本直接落 deliverables/{季度}/{版本}/（季度 = 2026Q3 格式，按季度 KPI 聚集；一个季度下多版本，如 deliverables/2026Q3/2.1.1/）。该目录整包装该轮 delta PRD + imap + prototype + 该版 assets。只写本轮 N 需求 + WHY，术语 / 模块树 / 未变规则引 baseline 不重复，跨引 baseline 锚场景编号 / 业务规则 ID。
上线后承重不变量（顺序不可乱）：先在 baseline 变更记录章写 changelog 行（日期｜触及模块｜delta 链接｜状态=已登记）→ 反向合并进 baseline 对应模块章（手动 Edit）→ 状态推进「已合并」→ 整季度/版本文件夹归 archive/{季度}/。
新鲜度：check_baseline_fresh.py {产品线} + baseline-fresh-gate hook 守第一层（已上线 delta 未合并报红）；baseline 模块章头 最后核对线上: 日期 / 人 守第二层（超 60d 报黄）。

delta 迭代档位（--tier，决定 §2 行文）：一份 delta 先认档位，再按档位组织 §2 本轮需求。

档位	`--tier`	触发	版本号	§2 行文
补丁包	`patch`	散修复 + 小调，互不依赖	x.y.z 三段	出 §2.0 索引表（轴 = 跟版边界）+ 按轴分组，不强求叙事
内聚特性	`feature`（默认）	单一能力，有新对象 / 状态机	x.y 两段	平铺，按用户旅程叙事
集合体 / 多团队	`bundle`	N 个松耦合需求跨模块 / 团队	x.y 两段	强制 §2.0 索引表 + 按单轴分组 H2

--tier（§2 组织）与四支柱填充（§3/§4/§5）正交，是两根独立的轴：

§3/§4/§5 不需要二级开关——全新能力 delta 填实即与 baseline 对应章（§3.2 业务对象 / §3.3 状态机 / §4 全局规则）同构、反向合并直接搬章；只动既有场景的 delta 本轮无该支柱变更直接删空章（符「迭代只写真有改动」铁律）。
--tier 只管 §2 怎么排版（索引 + 分组 vs 平铺叙事），不决定四支柱有没有内容。两者各管各的，别混。

API 速查

# 输出 md 字符串
from core.md_renderer import MdWriter, scene_5section_card, bold, italic
w = MdWriter()
w.h1("1. 项目背景与目标")
w.h2("1.1 背景")
w.bullet_list(["痛点 A", "痛点 B"])
w.field_bullet("业务描述", "用户点「发布」把内容发到社区")
w.field_bullet_list("前置条件", ["已登录", "未被禁言"])
w.table(headers=["编号", "场景"], rows=[["A-1", "发帖"]])
w.image("./assets/scene-A-1-wireframe.png", alt="发帖低保真")
md = w.render()

# 12 章骨架编排
from sections_md import build_full_skeleton, build_scene_file, SceneInfo
md = build_full_skeleton(info={"project_name": "xxx", "version": "1", "scenes": [...]})

# 解析现有 md
from humanize.md_scan import scan_human_voice_md, scan_prd_structural_md
voice_hits = scan_human_voice_md(md_text)
struct_hits = scan_prd_structural_md(md_text, scene_count=10)

自检清单（PM 交付前过一遍）

结构合规：bash check_prd_md.sh <prd.md> exit 0（§X.Y 锚点 + 裸场景编号死链查只对 split 开，单文件 = baseline + single delta 天然豁免；profile 仅控 baseline 其他行为）
截图齐全：./assets/ 下所有引用文件存在
模板字段名锁定：grep -E "^- \*\*(触发|读|写|事件|API)" <md> 无命中（UI 场景统一走区块表）
裸编号清查：正文（非 heading / 非表格）grep [ABCDEFM]-[0-9] 仅出现在「编号 + 白话名」组合或链接里（单文件 = baseline + single delta 豁免，仅 split 拦）
占位符清掉：grep {{ 待填 无命中（终态）
CJK 标点：python3 scripts/check_cjk_punct.py <md> --strict exit 0
跨章引用合规：见 X.Y 白话名 而非裸 见 X.Y / 见 A-1
全文讲人话：契约层（§3.2/3.3）无 snake_case 研发字段（用中文业务名），唯埋点章事件 / 属性英文名例外
结构化优先（禁分号滥用 · WARN）：单行 ≥ 2 个分号（； / ;）= 子句堆一坨，拆成 bullet 或 1. 2. 3. 编号；表格行豁免（cell 内 ； 是 Confluence 切 bullet 的约定分隔符）
禁长句 run-on（拆句优先 · WARN）：句段（。！？； 之间）≥ 100 字 = 一口气读不完，拆句或转列表；表格行豁免。与分号校验互补（分号管「；」串，长句管「，」串）
叶子完整性：实时 / 快照字段标清生命周期与刷新触发点，阈值标端点（含不含），状态机穷举（含自环 / 离线再上线），展示窗口与数据保留期对齐。交付 / 推 Confluence 前跑「交付前冷读」Step（cold_read.py + 派干净子代理），盲点逐条 triage。7 类盲区见 references/prd-scene-templates.md §4.6
禁水平线 ---：grep -cE '^-{3,}\s*$' <md> = 0（单独成行连字符 = Confluence 丑水平线；表格 |---| 不算）。章节用 h1/h2 分隔
禁引用块 >：grep -cE '^\s*>' <md> = 0（Confluence blockquote 渲染丑；业务故事改 **业务故事**：正文；baseline 例外）

References 索引

必读（写 PRD 前加载）：

references/prd-chapter-rules.md — 章结构 / 字段归属矩阵 / 编号 - 人话分层 / Confluence 渲染约束 / PM 越界禁词 / single-vs-split / 自检清单

按需读（命中具体步骤再加载）：

references/prd-scene-templates.md — 写第 5/6/7 章场景前加载（UI 场景区块表 / 横切策略模板 / 数据影响写法）
references/prd-optional-sections.md — §1.6 竞品调研 / §1.7 多方案对比模板，PM 加可选章节时 copy
references/metrics-framework.md — 写 §9 埋点 / §1.4 北极星指标时加载
讲人话共性铁律见 .claude/runbooks/human-voice-rules.md，PRD 形态规则在 prd-chapter-rules §三 / §三点八

注意事项

可选章节（按需 copy）

gen_prd_skeleton.py 默认生成 12 章骨架。以下两节按需追加在 §1.5 后、§2 前：

§1.6 竞品调研：项目首次涉足某场景 / 内审要求竞品参照 / 决策依据需向 leader 说明时加。简单迭代不加
§1.7 多方案对比：本期有 2+ 候选方案 / 技术路径有分歧 / 需说明为何选 A 不选 B 时加。单方案需求不加

模板见 references/prd-optional-sections.md，骨架不默认生成，PM 觉得需要时从模板 copy 进 PRD md。

方案型项目（不走标准 pipeline）

判定信号（任一）：

涉及独立 mid-office + 业务系统 + 风控系统跨系统对接
含资金路径 / 跨账户结算
涉及法务 / 合规批复路径
仅后端架构无 UI 流（如打分引擎 / 数据 pipeline）

不强制 12 章。PM 自定章节（建议对标共建 PRD 模板），文档仍 md，仍走 md_to_confluence.py 推 wiki。

文档分工建议：方案概览 / 系统拓扑 / 各系统职责 / 接口 schema / 资金对账 / 风险与回滚 / 灰度计划。

prd

이 저장소의 다른 Skills

PRD Skill（产品需求文档，md 版）

触发与定位

改脚本前 30 秒

硬规则（FAIL 即拦）

10 条核心硬规则

核心输出规范

模式判定

章节归属表（行为规格 / 页面结构落位）

流程图政策

执行步骤

Step 0：新建 PRD（scaffold + 手填）

Step 1：升版（直接改 md）

Step 2：重生骨架的 stale 清理（--force 陷阱）

Step 3：截图回填

Step 3.5：交付前冷读（叶子完整性反测 · 推 Confluence / 交付研发前必跑）

Step 4：推 Confluence

Step 5：老项目迭代（baseline / delta 循环）

API 速查

自检清单（PM 交付前过一遍）

References 索引

注意事项

可选章节（按需 copy）

方案型项目（不走标准 pipeline）

PRD Skill（产品需求文档，md 版）

触发与定位

改脚本前 30 秒

硬规则（FAIL 即拦）

10 条核心硬规则

核心输出规范

模式判定

章节归属表（行为规格 / 页面结构落位）

流程图政策

执行步骤

Step 0：新建 PRD（scaffold + 手填）

Step 1：升版（直接改 md）

Step 2：重生骨架的 stale 清理（--force 陷阱）

Step 3：截图回填

Step 3.5：交付前冷读（叶子完整性反测 · 推 Confluence / 交付研发前必跑）

Step 4：推 Confluence

Step 5：老项目迭代（baseline / delta 循环）

API 速查

自检清单（PM 交付前过一遍）

References 索引

注意事项

可选章节（按需 copy）

方案型项目（不走标准 pipeline）

이 저장소의 다른 Skills