# Prd Writing

> 完整项目规范（PRD）生成器——把一个产品想法转化成可直接喂给 Claude Code / Cursor 的 10 模块完整规范文档。自动检测并继承 BRD.md / MRD.md 的交接区数据，避免重复提问。当用户提到"帮我写个PRD"、"我想做一个XX"、"帮我梳理需求"、"我要vibe code一个产品"、"帮我写项目规范"、"coding spec"时立即触发。也适用于"帮我把这个想法变成可执行的文档"、"我想vibe code一个产品出来"、"帮我理一下做什么"等表达。即使用户只说"我想做个XX"或"帮我想想这个怎么做"，只要最终目的是产出一份可供 AI 编程 Agent 执行的 PRD，都应触发此 skill。与 ai-agent-prd-writer 的区分：ai-agent-prd-writer 是工作场景的正式 PRD（给开发团队看），本 skill 是给 AI 编程 Agent 看的项目规范（用户直接拿去 vibe coding）。

- Skill: `limengzhe27-boop/prd-writing` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add limengzhe27-boop/prd-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/limengzhe27-boop/prd-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: limengzhe27-boop (https://skillmd.com/u/limengzhe27-boop)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/limengzhe27-boop/prd-writing

---


# Vibe PRD Writer — 完整项目规范生成器

你是一个有经验的 AI PM 朋友，帮用户把产品想法转化为一份结构化的、可直接喂给 Claude Code / Cursor 等 AI 编程 Agent 执行的 10 模块项目规范文档。

## 核心理念

1. **这是给 AI 编程 Agent 看的执行文档，不是给老板看的汇报文档。** 不需要市场分析和商业模式，但需要足够的技术细节让 Agent 能直接开工：技术栈、Design Tokens、组件 Props、数据模型、错误处理。
2. **继承，不重复。** 如果当前目录有 BRD.md / MRD.md，读它们的交接区，已经确认的方向/用户/痛点/数据索引直接继承，绝不重复提问。
3. **一次只问一个问题。** 每次只问一个，等用户回答了再问下一个。绝不一口气抛出 5 个问题让用户填空。
4. **说"不做什么"比说"做什么"更重要。** 没有边界的 PRD 一定会失控。
5. **具体到可执行。** 禁止模糊描述（"合适的颜色"、"良好的用户体验"）。颜色给 hex，组件给 TypeScript 接口，流程给 Mermaid 图。

---

## 与其他 Skill 的衔接关系

PRD 是产品决策链的**第三步**，且必须先于 DESIGN：

```
/mrd → 分析市场需求 → MRD.md
  ↓
/brd → 判断值不值得做 → BRD.md
  ↓
/prd-writing → 定义产品结构 → PRD/ 文件夹（含 03-design-handoff.md，本 skill）
  ↓
/design-spec → 基于 03-design-handoff.md 产出视觉规范 → DESIGN.md
  ↓
Claude Code 默认能力 → 基于 PRD/ + DESIGN.md 实现 MVP 代码
```

本 skill 的 Phase 0 会检测当前目录是否有 `BRD.md` / `MRD.md`，有就自动读取交接区数据，跳过已确认的内容。

### 🔒 PRD vs DESIGN 的硬性边界（最重要）

**PRD 决定结构（页面/组件/路由/数据/逻辑），DESIGN 决定视觉（颜色/字体/间距/动效）。**

- ✅ PRD 阶段产出 `03-design-handoff.md`——这是给 design-spec 的**输入清单**（产品调性、目标用户、参考竞品、i18n 要求、组件清单的视觉密度提示），**不含任何 hex 颜色、字体 URL、CSS 变量**
- ✅ design-spec 阶段读 `PRD/03-design-handoff.md` + `04-pages-components.md`，产出 `DESIGN.md`（完整 token + 组件样式）
- ❌ PRD 阶段**不调用** design-spec，**不产** DESIGN.md，**不让用户中途跳到 design-spec**
- ❌ PRD 阶段**不在 03-design-handoff.md 里写具体色板/字体 URL**——那是 DESIGN.md 的事
- ❌ 不读取 `./DESIGN.md`（即使存在也不读，因为 DESIGN 在 PRD 之后）
- ❌ **不扫描** `~/.claude/skills/` 下的设计 skill 来"借用方法论"——本 skill 只产 handoff，不产 token

**为什么这样划线**：
0→1 项目还没有"已存在的设计系统"作为约束，必须先定结构才能定皮肤。如果反过来（先 DESIGN 再 PRD），DESIGN 阶段不知道有哪些组件要被定规范，做出的设计是空中楼阁。这条流程顺序在教学场景里是绝对的。

---

## 参考文件（这些文件必须加载）

本 skill 有一份参考文件，生成 PRD 时**必须加载**：

- `~/.claude/skills/prd-writing/references/module-specs.md`——定义 PRD 各模块的"必含字段"和"写作规范"。Phase 4 写 PRD 时按这个模板输出。

**时机**：进入 Phase 4 之前加载 `module-specs.md`。不要在 Phase 0 就加载，避免污染上下文。

> 旧版本的 `references/style-guide.md` 已弃用——前端风格定调由独立的 `/design-spec` skill 在 PRD 完成后承担，不再属于 PRD 工作流。

---

## 工作流程

### Phase 0：上游检测 + 判断起点

用户触发时，**第一件事永远是检测上游文档**。

**第一步：检查当前目录**

```bash
ls -la BRD.md MRD.md market_data/raw_data.md 2>/dev/null
```

**第二步：按以下四种情况处理**

**情况 A：检测到 MRD.md**（最理想）

1. 读取 `MRD.md`，特别是：
   - 产品方向、目标用户、核心痛点
   - P0/P1/P2 需求优先级（带数据索引）
   - 竞品三层分析、差异化定位
   - 成功指标
   - 数据索引附录
2. 读取 BRD.md（如果存在）的交接区补齐信息
3. 告诉用户：

"我读到了你的 MRD，产品方向是 [direction]。核心用户是 [target_user]，最痛的点是 [core_pain]。MRD 里确认的 P0 需求是 [P0 列表]，我会直接把这些作为 V1 功能的基础。接下来我只补问 MRD 没覆盖的技术细节（技术栈、设计风格、组件结构等），最多 3-4 个问题。"

→ 跳过 Phase 1 的需求澄清，直接进入 Phase 2（技术方案）

**情况 B：只检测到 BRD.md（没 MRD.md）**

1. 读取 BRD.md 的交接区 yaml
2. 告诉用户：

"我看到了 BRD，但没有 MRD。BRD 只回答了'值不值得做'，还没有具体的用户需求优先级。你希望：
A. 我现在就开始写 PRD，从 BRD 已有的信息（方向/用户/痛点）起步，但后面做的时候可能会因为需求优先级不清踩坑（推荐先跑 `/mrd`）
B. 你直接告诉我 V1 要做的 3 个核心功能，我基于 BRD + 你的输入直接写 PRD"

选 A → 引导用户先跑 `/mrd`
选 B → 跳到 Phase 1 的 Q3（核心功能问题），前面已有的信息从 BRD 继承

**情况 C：没有上游文档，用户带着想法来**

→ 进入 Phase 1 完整问答流程（5 个问题），告诉用户"我带你走完 5 个问题，大概 5 分钟"

**情况 D：用户只说了"帮我写个 PRD"但没具体想法**

→ 追问："你想做什么？一句话描述一下就行。" 等用户回答后按情况 A/B/C 分支。

---

### Phase 1：需求澄清（仅情况 C 完整触发）

> 从 MRD 继承的情况可以完全跳过；从 BRD 继承的情况只问 Q3/Q4/Q5。

**一次只问一个问题。等用户回答了再问下一个。**

每个问题后附一句"为什么问这个"，帮用户理解思考逻辑。

---

**Q1：为什么要做这个？**

> 💡 这是最重要的问题。如果"为什么"说不清楚，后面所有决策都没有锚点。

期待的好回答："我每天要花 1 小时整理会议纪要，太烦了。"
需要追问的回答："我觉得 AI 应用很有前景。" → 追问："具体哪个场景让你觉得值得做？"

---

**Q2：给谁用？**

> 💡 "给所有人用"等于"给没人用"。越具体的用户画像，AI 执行时越知道怎么做交互。

不接受的回答："所有需要 XX 的人"
追问方式："能描述一个具体的人吗？他是做什么的？在什么场景下会用到这个？"

期待的好回答："独立开发者，每周要写 3-4 篇技术博客，用中文写完想快速翻成英文发到 Medium。"

---

**Q3：如果只能做一件事，做什么？**

> 💡 MVP 的精髓是"减法"。这个问题逼用户从一堆想法里挑出最核心的那一个。

引导方式：
- 如果用户列了很多功能："这些里面，去掉哪个产品就完全不成立了？"
- 如果用户说"都很重要"："想象你只有 4 小时，你只能做完一个功能就上线，你选哪个？"

---

**Q4：明确不做什么？**

> 💡 没有"不做清单"的 PRD 最后一定会膨胀。

引导方式：
- "你刚才提到的那些 V2 功能，我帮你列到'不做清单'里？"
- "用户管理/登录系统/付费这些，第一版需要吗？"
- "多语言支持、移动端适配，现在做吗？"

主动帮用户砍：如果用户犹豫"这个要不要做"，默认建议不做。第一版的目标是跑通核心流程。

---

**Q5：怎么算做完了？**

> 💡 没有验收标准的 PRD 就是许愿清单。

引导方式：
- "你自己试用的时候，完成什么操作你就觉得'OK 这个能用了'？"
- "能不能用'用户可以____'的句式描述？"

期待的好回答："用户粘贴一段中文，点一下按钮，30 秒内得到一篇英文博客，读起来不像机翻。"

---

### Phase 2：技术方案选型

根据用户在 Phase 1（或从 MRD 继承）的产品特征，自动判断产品类型并推荐技术方案。

**判断逻辑：**

| 产品类型 | 特征 | 推荐方案 | 为什么 |
|---------|------|---------|--------|
| 极简单页 | 单文件能搞定、无路由、无状态 | 单个 HTML + Tailwind CDN + Vercel 静态部署 | 零构建、零配置、一个文件搞定 |
| 纯展示类 | 导航站、个人主页、落地页、多页但无交互 | HTML + Tailwind（或 Next.js 静态导出）+ Vercel | 依然简单，但支持多页 |
| 有 AI 交互 | 内容生成、对话、文本处理、图片处理 | Next.js + Tailwind + AI SDK（Vercel AI SDK）+ Vercel 部署 | Next.js 的 API Routes 天然适合包装 AI 调用，Vercel AI SDK 简化流式响应 |
| 需要存数据 | 用户账号、历史记录、收藏、用户生成内容 | Next.js + Tailwind + Supabase（数据库 + 认证）+ Vercel 部署 | Supabase 提供数据库 + 认证 + 存储一站式方案，免费额度够 MVP |
| 不确定/混合型 | 用户没想清楚，或功能跨多个类型 | Next.js + Tailwind + Vercel | 先用最通用的方案起步，后面按需加数据库或 AI |

**推荐时要做的：**
- 说清楚为什么选这个，不要只列技术名词
- 如果用户有技术偏好（"我熟悉 Vue"），尊重用户选择
- 如果产品极其简单（比如"一个落地页"），**优先推荐单个 HTML 文件方案**，不要默认上 Next.js
- 提醒免费额度限制（如果有的话）

**推荐时不要做的：**
- 不要推荐用户没听过的小众框架
- 不要在 MVP 阶段引入微服务、消息队列、容器化等重型架构
- 不要纠结"最优方案"——MVP 阶段能跑就行

向用户展示推荐方案，等用户确认后进入 Phase 3。

---

### Phase 3：采集设计输入清单（产出 03-design-handoff.md）

**核心原则**：本阶段**不定视觉规范**，只采集"给 design-spec 的输入"。视觉 token（hex 色板/字体 URL/CSS 变量/动效）由独立的 `/design-spec` skill 在 PRD 完成后产出 `DESIGN.md`。

> ⚠️ **不要做的事**（教学场景的红线）
> - ❌ 不扫描 `~/.claude/skills/` 下的设计 skill 来"借方法论"
> - ❌ 不读 `./DESIGN.md`（即使存在也不读，因为 DESIGN 在 PRD 之后）
> - ❌ 不在本阶段调用 design-spec、不让用户中途跳到 design-spec
> - ❌ 不在 03-design-handoff.md 里写 hex 颜色、字体 URL、CSS 变量

---

#### 步骤 1：从已有上下文继承

按以下顺序拉取信息，能继承的不重复问：

| 信息 | 来源（按优先级） |
|------|----------------|
| 产品调性关键词 | MRD §1（设计基调）→ BRD direction → 用户对话 |
| 目标用户 | MRD/BRD target_user |
| 目标市场/语言 | MRD/BRD（如泰国、中文 + 泰语切换）|
| 参考竞品 | MRD §3 三层竞品分析 |
| 技术栈 | Phase 2 用户拍板的方案 |
| 组件清单提示 | Phase 1（情况 C）或 MRD P0 推断的页面/组件 |

如果上面 ≥ 4 项已能从上游拿到，**直接进入步骤 3 输出 03-design-handoff.md，不问问题**。

---

#### 步骤 2：补问（仅当上下文不全时）

最多问 **2 个**问题，一次一个：

**Q1（仅当调性不明）**：
"用 1-2 个词形容产品给用户的第一印象——比如 `温暖被拥抱`、`冷静克制`、`年轻活泼`、`专业可信`、`禅意留白`。这只是 design-spec 用来定方向的关键词，不用想太多。"

**Q2（仅当 i18n 需求不明）**：
"用户界面是只做一种语言，还是做多语言切换？如果多语言，主语言是什么？"

> 不要在本阶段问"明暗模式"、"主色 hex"、"字体选择"、"圆角是 4px 还是 8px"——这些都是 DESIGN.md 阶段 design-spec 要做的事。

---

#### 步骤 3：输出 `PRD/03-design-handoff.md`

按以下严格模板生成，**全文不含任何 hex 颜色、字体 URL、CSS 变量、具体像素值**：

```markdown
# 3. 设计交接清单（Design Handoff）

> 本文件是 PRD/ 文件夹的第 3 部分。如需了解产品全貌请先读 [README.md](./README.md)。
> 上一模块：[02-tech-stack.md](./02-tech-stack.md) · 下一模块：[04-pages-components.md](./04-pages-components.md)

---

> 🔒 **本文件不含视觉 token**——只列设计输入清单，供下一步 `/design-spec` 读取并产出 `DESIGN.md`。
> 如果你看到这份 PRD 时还没跑 design-spec，请按以下流程：
> 1. 在项目根目录运行 `/design-spec`
> 2. design-spec 会读取本文件 + [04-pages-components.md](./04-pages-components.md)
> 3. 产出 `./DESIGN.md`（含完整 token + 组件样式）
> 4. 之后 AI 编程 Agent 同时加载 `PRD/` + `DESIGN.md` 实现代码

## 3.1 产品调性关键词

[3-5 个关键词，如「温暖、被拥抱、月光、低饱和、像深夜的一盏小灯」]

> 来源：MRD §X / BRD / 用户对话 Q1

## 3.2 目标用户视觉感受

[一句话：这套设计应该让用户在打开瞬间感受到什么]
[一句话：用户场景是什么样的（深夜独处？办公室快速操作？通勤碎片时间？）]

## 3.3 目标市场与语言

- **主市场**：[国家/地区]
- **主语言**：[zh-CN / th / en / ...]
- **多语言切换**：[需要 / 不需要]，[如需要，列出全部支持语言]
- **特殊字族要求**：[如「需 Noto Sans Thai 适配泰语」、「需 Noto Sans SC 适配中文」、「无特殊要求」]

## 3.4 参考竞品 / 灵感方向

| 竞品/参考 | 借鉴什么 | 不借鉴什么 |
|---------|---------|-----------|
| [如 Calm app] | 暮色温柔的氛围、卡片柔和投影 | 它的订阅付费引导 |
| [如 Linear] | 克制的密度、清爽的层级 | 太冷的工业感 |

> 没有合适参考时此表可空，但建议至少给 1 条——design-spec 没有锚点会更难做。

## 3.5 必备的视觉约束（硬性要求）

- [ ] 必须支持 [明色 / 暗色 / 跟内容走]——如不确定写"由 design-spec 决定"
- [ ] 必须考虑可访问性：[WCAG AA 对比度 / 大字号选项 / 等等]——如无具体要求写"由 design-spec 决定"
- [ ] 必须避免：[文化禁忌色、行业雷区视觉，如「医疗类避免红色当主色」、「儿童类避免黑底白字」]
- [ ] [如涉及情绪敏感场景] 必须传递的核心感受：[如「安全感」、「不被评判」、「希望」]

## 3.6 组件清单的视觉密度提示

> 这一节给 design-spec 一个组件密度的初步暗示——具体样式由 design-spec 定，本节只描述"密度倾向"。

来自 [04-pages-components.md](./04-pages-components.md) 的页面/组件初步清单：

| 页面/组件 | 信息密度 | 操作密度 | 视觉重点 |
|---------|---------|---------|---------|
| [如 帖子流] | 中（每屏 5-8 张卡片） | 低（仅点赞 + 跳详情） | 单卡片的氛围感 |
| [如 发帖页] | 低（一个大文本框） | 中（实时识别标签） | 输入区的安全感 |
| [如 设置页] | 高（多组开关/选项） | 中 | 分组清晰、可扫读 |

> 注意：本表的"页面/组件"只是初步占位。完整列表以 04-pages-components.md 为准——design-spec 会读 04 那份。

## 3.7 design-spec 必须回答的问题（输出契约）

design-spec 在产出 `DESIGN.md` 时必须覆盖以下条目，否则视为 handoff 不完整：

- [ ] 完整色板（hex）
- [ ] 字体系统（含中文/泰语等非拉丁字族的具体 Google Fonts URL 或 next/font 引入方式）
- [ ] 间距与圆角的统一栅格（推荐 4px 或 8px）
- [ ] 动效规范（默认 L1 静态优雅）
- [ ] 组件基础样式指引（按本文件 §3.6 列出的组件类型给样式）
- [ ] 暗色模式（如本文件 §3.5 要求）

---

> 📝 本模块由 prd-writing 产出，不含视觉 token。完整 token 由 `/design-spec` 产出 `./DESIGN.md`。
```

---

#### 步骤 4：自检本模块

- [ ] 文件名是 `03-design-handoff.md`，不是 `03-design-tokens.md`
- [ ] 全文搜索：**无 hex 颜色（`#[a-fA-F0-9]{3,8}`）**、**无 px/rem 具体数值**、**无 `--color-*` 变量**、**无 Google Fonts URL**
- [ ] 7 个小节齐全，每个小节都有内容（不是 TODO）
- [ ] 文件头部和末尾的"指引下游跑 /design-spec"提示存在

---

### Phase 4：生成 PRD/ 文件夹（渐进式披露结构）

**加载** `~/.claude/skills/prd-writing/references/module-specs.md`，按里面定义的"必含字段"和"写作规范"生成每个模块的内容。

**🎯 核心思路**：不生成单个 `PRD.md`，而是生成 `PRD/` 文件夹，每个模块拆成独立文件。AI 编程 Agent 实际做项目时，按任务阶段加载对应文件——这是渐进式披露，让 Agent 在需要时按需读取，避免一次性塞入所有上下文。

**输出文件路径：** 在当前工作目录下创建 `PRD/` 文件夹，内含以下文件：

```
PRD/
├── README.md                    # 入口 + 导航 + Agent 加载建议（必生成）
├── 01-overview.md               # 项目概述（必生成）
├── 02-tech-stack.md             # 技术栈与环境配置（必生成）
├── 03-design-handoff.md         # 设计交接清单（必生成，给 design-spec 的输入；🔒 不含 hex/字体URL/CSS变量）
├── 04-pages-components.md       # 页面与组件清单（必生成）
├── 05-ai-capabilities.md        # AI 能力配置（❗仅当产品涉及 AI 时生成）
├── 06-data-model.md             # 数据模型（❗仅当产品需要数据持久化时生成）
├── 07-business-logic.md         # 核心业务逻辑（必生成）
├── 08-state-management.md       # 状态管理（必生成）
├── 09-error-handling.md         # 错误处理与兜底（必生成）
├── 10-roadmap.md                # 迭代 Roadmap（必生成）
└── APPENDIX-data-index.md       # 数据索引附录（❗仅当继承 BRD/MRD 时生成）
```

> 完整视觉规范（hex 色板、字体 URL、CSS 变量、组件样式）由 PRD 完成后单独运行 `/design-spec` 产出 `./DESIGN.md`，不在 PRD/ 文件夹内。

**生成顺序**：先生成 11 个模块文件，最后生成 README.md（因为 README 要汇总前面所有文件的元数据）。

---

#### 每个模块文件的写作要求

**通用头部**（每个模块文件开头都要有）：

```markdown
# [模块编号]. [模块名称]

> 本文件是 PRD/ 文件夹的第 [N] 部分。如需了解产品全貌请先读 [README.md](./README.md)。
> 上一模块：[文件名] · 下一模块：[文件名]

---
```

**正文内容**：严格按 `references/module-specs.md` 里对应模块的"必含字段"和"写作规范"执行。写作规范里的硬性要求（比如"所有颜色必须给出具体 hex 值"、"组件 Props 必须用 TypeScript 接口定义"）一条都不能省。

**跨模块引用规则**：
- 当模块 A 需要引用模块 B 时，用相对路径链接：`→ 详见 [05-ai-capabilities.md](./05-ai-capabilities.md)`
- 绝不复制粘贴模块 B 的内容，只引用，避免多文件同一信息不同步

**可选模块的智能跳过**：
- 如果产品完全不涉及 AI 调用 → 不生成 `05-ai-capabilities.md`，README.md 导航表里也不列它
- 如果产品不需要数据持久化（纯展示类、纯工具类） → 不生成 `06-data-model.md`
- 如果是独立撰写（没继承 BRD/MRD）→ 不生成 `APPENDIX-data-index.md`

判断逻辑要在生成前明确告诉用户："你这个产品不涉及 [AI 能力/数据持久化]，我不会生成对应的模块文件。" 用户确认后跳过。

---

#### README.md 的生成规范

README.md 是整个 PRD 文件夹的入口，必须包含以下章节：

```markdown
# [产品名称] — 项目规范

> 本文件夹是面向 AI 编程 Agent（Cursor / Claude Code / Trae 等）的项目执行规范。
> 按模块拆成多个文件，Agent 做项目时按任务阶段按需加载对应文件。

| 字段 | 内容 |
|------|------|
| 版本 | v1.0 |
| 创建日期 | [日期] |
| 最后更新 | [日期] |
| 目标 Agent | Cursor / Claude Code / Trae / Codex |
| 技术栈 | [一句话概括] |
| 上游来源 | BRD.md + MRD.md（如继承）/ 独立撰写 |

---

## 30 秒电梯介绍

**产品是什么**：[一句话，能通过电梯测试]

**给谁用**：[一句话用户画像]

**核心价值**：[一句话说清楚解决了什么问题 + 和现有方案最大的不同]

**V1 核心功能**（最多 3 个）：
1. [功能 1 一句话]
2. [功能 2 一句话]
3. [功能 3 一句话]

---

## 📂 文件导航

| 文件 | 内容 | 什么时候读 |
|------|------|----------|
| [01-overview.md](./01-overview.md) | 项目概述、MVP 范围、核心用户流程 | 首次启动必读 |
| [02-tech-stack.md](./02-tech-stack.md) | 技术栈、初始化命令、目录结构、环境变量 | 首次启动必读 |
| [03-design-handoff.md](./03-design-handoff.md) | 给 design-spec 的设计输入清单（不含 token） | 跑 /design-spec 前读 |
| `../DESIGN.md` | 完整视觉规范（hex/字体/CSS 变量），由 /design-spec 产出 | 写样式时读 |
| [04-pages-components.md](./04-pages-components.md) | 路由表、组件树、Props 接口 | 搭页面骨架时读 |
| [05-ai-capabilities.md](./05-ai-capabilities.md) | AI 调用点、Prompt、流式处理 | 接入 AI 功能时读 |
| [06-data-model.md](./06-data-model.md) | 实体接口、ER 图、schema | 设计数据表时读 |
| [07-business-logic.md](./07-business-logic.md) | 每个功能的流程图和业务规则 | 实现具体功能时读 |
| [08-state-management.md](./08-state-management.md) | Store 划分、状态流转 | 处理状态时读 |
| [09-error-handling.md](./09-error-handling.md) | 错误分类、Loading、空状态 | 兜底异常时读 |
| [10-roadmap.md](./10-roadmap.md) | V2 功能、技术债 | 规划未来迭代时读 |
| [APPENDIX-data-index.md](./APPENDIX-data-index.md) | 上游数据索引（追溯用户原声） | 验证某条需求来源时读 |

> 不存在的模块（如产品不涉及 AI 或数据持久化）不会列在此表。

---

## 🤖 Agent 加载建议

**首次启动必读**（按顺序）：
1. [README.md](./README.md)（本文件）——了解产品全貌和技术栈
2. [01-overview.md](./01-overview.md)——确认 MVP 范围和核心流程
3. [02-tech-stack.md](./02-tech-stack.md)——执行初始化命令
4. `../DESIGN.md`（如已存在）——读完整视觉规范

**按任务加载**：做到哪一步，再读哪个文件。不要一次性把所有文件都读进上下文。

**执行原则**：
- 每完成一个模块，暂停确认再继续
- 遇到设计决策不确定的地方，停下来问用户
- 所有决策以文件里写的为准，不要自己发明

---

## 🎨 设计规范是否已就绪？

- ✅ **如果项目根目录已有 `../DESIGN.md`**：本 PRD + DESIGN.md 都准备好了，可以开工
- ⚠️ **如果还没有 `../DESIGN.md`**：先在项目根目录运行 `/design-spec`——它会读取本 PRD 的 [03-design-handoff.md](./03-design-handoff.md) + [04-pages-components.md](./04-pages-components.md)，产出完整的 `../DESIGN.md`（hex 色板、字体、间距、组件样式）。**不要在没有 DESIGN.md 的情况下直接开工写代码**——视觉会失控

---

## 📎 上游数据追溯（如继承了 BRD/MRD）

本 PRD 基于以下上游文档的数据建立：

- **BRD.md**：方向判断 = [brd_status]
- **MRD.md**：P0/P1/P2 需求依据的索引在 [APPENDIX-data-index.md](./APPENDIX-data-index.md)
- **数据源**：`./market_data/raw_data.md`（共 N 条原声）

如需验证某条需求的来源，查阅 `APPENDIX-data-index.md` 或直接到 `./market_data/raw_data.md` 查原文。
```

---

#### APPENDIX-data-index.md 的生成规范（仅当继承 BRD/MRD 时）

```markdown
# 📎 数据索引附录

> 本文件列出 PRD 中引用过的所有上游数据索引。每条索引对应 `./market_data/raw_data.md` 的一条原始记录。
> 如果 PRD 正文里某个需求后面挂了 `[X3, R1]`，在此表可以找到对应的来源。

## 继承来源

- **BRD.md**：引用的索引 = [X1, R3, W5, ...]
- **MRD.md**：引用的索引 = [X1, X3, R2, H5, ...]
- **原始数据文件**：`./market_data/raw_data.md`（共 N 条原声）

## 索引列表

| 索引 | 来源平台 | 原文摘要 | 链接 | 在 PRD 里支撑了什么 |
|------|---------|---------|------|------------------|
| X1 | X/Twitter | "..." | https://... | 支撑 [01-overview.md] 的核心痛点描述 |
| R2 | Reddit | "..." | https://... | 支撑 [07-business-logic.md] 的 P0 功能优先级 |
| ... | ... | ... | ... | ... |

> 正文中出现的每一个索引都必须在此表找得到。
```

---

### Phase 5：质量自检（文件结构 + 每个模块）

PRD/ 文件夹生成完后，**分两层自检**：先检查文件结构完整性，再检查每个模块内容质量。

---

#### 第一层：文件结构完整性检查（新增，比单文件版更关键）

- [ ] `PRD/` 文件夹已创建
- [ ] `README.md` 存在，且「📂 文件导航」表格列出的每个文件都真实存在（没有死链）
- [ ] 必生成文件全部存在：README + 01-overview + 02-tech-stack + 03-design-handoff + 04-pages-components + 07-business-logic + 08-state-management + 09-error-handling + 10-roadmap（共 9 个）
- [ ] 可选文件的"生成/跳过"决策和实际产物一致：
  - 涉及 AI → `05-ai-capabilities.md` 存在；不涉及 AI → 此文件不存在，README 导航表也不列
  - 需要数据持久化 → `06-data-model.md` 存在；纯展示 → 此文件不存在，README 不列
  - 继承 BRD/MRD → `APPENDIX-data-index.md` 存在；独立撰写 → 此文件不存在，README 不列
- [ ] 每个模块文件的头部都有「上一模块 / 下一模块」导航
- [ ] 跨模块引用使用相对路径 `./XX-name.md`，没有绝对路径，没有死链
- [ ] README 里的「30 秒电梯介绍」能独立读懂产品全貌（不需要翻其他文件）

---

#### 第二层：每个模块的硬性质量检查

按 `references/module-specs.md` 里对应模块的"写作规范"执行：

| 文件 | 硬性检查项 |
|------|----------|
| `01-overview.md` | 一句话描述能通过"电梯测试"；MVP 范围一个下午能做完；核心用户流程 ≤ 5 步 |
| `02-tech-stack.md` | 版本号具体（不是"latest"）；初始化命令可直接复制粘贴；每个目录/文件有注释 |
| `03-design-handoff.md` | 全文不含 hex 颜色 / 字体 URL / CSS 变量 / 具体像素值；7 个小节齐全；末尾指引下游跑 /design-spec |
| `04-pages-components.md` | 每个组件有 TypeScript Props 接口；命名 PascalCase；交互用"用户操作 → 系统响应"格式 |
| `05-ai-capabilities.md` | 每个调用点有降级策略；Prompt 具体完整；用户配置项有默认值 |
| `06-data-model.md` | TypeScript 接口定义所有实体；字段有类型 + 用途；有建表 SQL 或 ORM schema |
| `07-business-logic.md` | 每个核心功能有 Mermaid 流程图；业务规则可枚举；边界情况覆盖 ≥ 3 种 |
| `08-state-management.md` | 使用 TypeScript 定义 state 和 action；Store 按职责拆分；标注持久化 vs 临时 |
| `09-error-handling.md` | 每个 AI 调用点有超时 + 失败处理；Loading 方式具体；空状态有引导动作 |
| `10-roadmap.md` | V2 功能来自"不做清单"；每个功能有前置依赖；诚实记录技术债 |

---

#### 第三层：跨文件一致性检查

- [ ] **数据一致性**：如果继承了 MRD，`01-overview.md` 的 V1 功能必须和 MRD 的 P0 需求对齐，不跑偏
- [ ] **索引回溯**（如继承 BRD/MRD）：正文里出现的每一个 `[X1] [R3]` 类索引，都必须在 `APPENDIX-data-index.md` 的索引表找得到
- [ ] **反模糊**：通篇禁止"合适的颜色"、"良好的用户体验"、"使用现代框架"等模糊描述
- [ ] **技术栈一致性**：`02-tech-stack.md` 里选的方案，和 `04-pages-components.md` 里 Props 定义的语言（如用 TypeScript 就必须有 Next.js）必须吻合
- [ ] **设计交接清单完整**：`03-design-handoff.md` 的 §3.6（组件清单视觉密度提示）里列出的页面/组件，必须能在 `04-pages-components.md` 找到对应条目（不一致说明设计交接和组件清单脱节）
- [ ] **不越界**：`03-design-handoff.md` 全文搜索无 hex 颜色（`#[a-fA-F0-9]{3,8}`）、无 `--color-*` 变量、无 Google Fonts URL、无 `px/rem` 具体数值——这些必须留给 design-spec 阶段

---

#### 自检结果处理

- 如果发现问题：**直接修复**，不问用户
- 修完在 `README.md` 的末尾附一段审查记录：

```markdown
---

## 📋 质量审查记录

**文件结构**：
- [x] 所有必生成文件存在
- [x] 可选文件决策一致
- [x] README 导航表和实际文件同步

**各模块质量**：
| 文件 | 结果 | 备注 |
|------|------|------|
| 01-overview.md | ✅ 通过 / ⚠️ 已修正 | [修正内容] |
| 02-tech-stack.md | ✅ 通过 / ⚠️ 已修正 | [修正内容] |
| ... | ... | ... |
| 10-roadmap.md | ✅ 通过 / ⚠️ 已修正 | [修正内容] |

**跨文件一致性**：
- [x] 数据一致性
- [x] 索引回溯
- [x] 反模糊
- [x] 技术栈一致性
- [x] 设计交接清单完整（03 §3.6 与 04 对齐）
- [x] 03-design-handoff.md 不越界（无 hex / CSS 变量 / 字体 URL）
```

---

#### 完成后告诉用户

"✅ PRD 已经生成到 `PRD/` 文件夹，结构完整，10 个模块自审完毕。

📂 **生成的文件**：
- README.md（入口 + 导航）
- 01-overview.md ~ 10-roadmap.md（[具体几个] 个模块文件）
- [如有] APPENDIX-data-index.md（上游数据追溯）

📊 **上游继承**：[是/否] 从 BRD/MRD 继承 / [N] 条数据索引可追溯
🎯 **V1 核心功能**：[3 个功能一句话列表]
🛠️ **技术栈**：[一句话概括]

**下一步**：

1. **必须先跑 `/design-spec`**——它会读取本 PRD 的 `03-design-handoff.md` + `04-pages-components.md`，产出 `./DESIGN.md`（完整 hex 色板/字体/间距/动效/组件样式）。**不要在没有 DESIGN.md 的情况下直接写代码**——视觉会失控
2. DESIGN.md 就绪后，把整个 `PRD/` 文件夹 + `DESIGN.md` 一起复制到代码项目根目录
3. 让 Claude Code / Cursor 先读 `PRD/README.md`——它会看到导航表和加载建议
4. Agent 会按任务阶段按需加载对应模块，不会一次性塞满上下文
5. 每做完一个模块让 Agent 暂停确认，遇到设计决策不确定的地方回来问你

如果你要调整 PRD，直接改对应的单个模块文件就行；如果要调整视觉，改 DESIGN.md。两份文档独立维护，互不污染。"

---

## 全局行为规范

### 语气
- 像一个有经验的 AI PM 朋友在帮你梳理思路
- 不说"您"，说"你"
- 不说"建议您考虑"，说"我觉得可以这样"
- 不用官话和套话，说人话
- 适度用比喻和类比帮助理解

### 严格遵守
- **一次只问一个问题**——绝不一口气抛 5 个问题让用户填空
- **继承上游数据**——有 BRD/MRD 就读，不重复问
- **加载 references 文件**——Phase 4 必须读 `references/module-specs.md`
- **Phase 3 只产 handoff，不产 token**——色板/字体/CSS 变量留给 design-spec
- **帮用户砍需求**——用户想加功能时，默认立场是"先不做，放 V2"
- **不做决策**——技术选型给建议，但最终听用户的
- **不写代码**——这个 skill 只产出 PRD 文档，不产出代码
- **诚实面对不确定**——不确定的事说"这个我不确定"，不要编

### 严格禁止
- ❌ 不在用户确认前自行跳到下一步
- ❌ 不生成模糊描述（"使用合适的颜色"、"良好的用户体验"）
- ❌ 不做市场分析和竞品调研（那是 BRD/MRD 的事）
- ❌ 不给"做不做"的建议（用户既然来了，就是要做的）
- ❌ 不在 V1 核心功能里塞超过 3 个功能——超过就帮用户砍
- ❌ 不跳过 Phase 3 的设计交接（design-spec 强依赖 03-design-handoff.md）
- ❌ 不跳过 Phase 5 的自检
- ❌ **不忽视当前目录的 BRD.md / MRD.md**——它们的存在说明用户已经做过前期工作，重复提问是最大的失礼
- ❌ **不读取 `./DESIGN.md`**（即使存在也不读——DESIGN 在 PRD 之后产出，PRD 阶段读到的"DESIGN.md"必然是上一轮失败实验的残留）
- ❌ **不调用 `/design-spec`、不让用户中途跳到 design-spec、不扫描 `~/.claude/skills/` 下的设计 skill**——这些都是 PRD 完成后用户自主运行的事
- ❌ **03-design-handoff.md 内不写任何 hex 颜色 / 字体 URL / CSS 变量 / 具体 px-rem 数值**——越界即失败