prd-manager

Imported from kociii/prd-manager (SKILL.md). Install upstream with npx skills add kociii/prd-manager. Copyright stays with the author.

PRD 管理器

统一管理 docs/prd/ 目录下版本化产品需求文档的 Skill。

它同时覆盖两类场景：

• 生成模式：从零产出完整项目文档（PRD → 设计 → 计划 → 技术文档）
• 管理模式：维护 docs/prd/<version>/ 下的版本化文档（增删查改 + 对比 + 搜索 + 归档）

文档边界规范

每个文档有且只有一个关注点，严禁跨界：

原则：prd.md 中出现"使用 X 框架"是越界；dev.md 中出现"用户希望..."是越界；plan.md 中出现"数据表字段"是越界。

目录结构规范

docs/prd/
├── README.md       # 版本摘要索引（倒序，最新版本在最上方）
├── v0.2.0/
│   ├── prd.md      # 产品需求文档（做什么、为什么）
│   ├── plan.md     # 开发计划（何时做、谁来做）
│   ├── design.md   # 界面设计文档（长什么样，前端项目必含）
│   ├── dev.md      # 技术开发文档（如何实现）
│   ├── sql/        # 数据库变更脚本（新增表或字段时必含）
│   │   ├── DDL.sql     # 表结构变更（建表、加字段、加索引等）
│   │   └── DML_init.sql # 初始化数据（字典数据、模板数据等）
│   └── ...         # 其他文档（auth.md、api.md 等）
├── v0.2.1/
│   └── ...
└── _archive/       # 已归档版本
    └── v0.1.0/

项目类型差异

根据项目类型，文档侧重点不同：

前端项目：

• design.md 为必含文档，描述界面设计、交互流程、组件设计
• dev.md 侧重前端技术方案（组件结构、状态管理、路由设计）

后端项目：

• dev.md 为核心文档，必须包含「接口影响清单」板块（见下方规范）
• design.md 可选，后端通常不需要界面设计
• 涉及数据库变更时必须生成独立 SQL 脚本文件

操作指南

0. 从零生成完整文档

当用户提出“创建一个 PRD”“生成项目文档”“给新版本做需求和设计”等需求时，直接使用本 Skill 完成完整工作流：

阶段 1：生成 prd.md 并等待确认

1. 收集用户需求、目标用户、优先级和范围
2. 使用 assets/prd_template.md 生成 PRD
3. 补全以下核心内容：
   • 项目目标与成功指标
   • 功能列表、优先级、用户故事、验收标准
   • 非功能需求
   • 约束条件与术语说明
4. 保存文件，向用户展示 PRD
5. 明确等待用户确认，未收到确认前不继续生成后续文档

阶段 2：生成设计与技术文档（用户确认 prd.md 后）

用户确认 PRD 后，生成设计和技术文档，完成后等待用户确认 dev.md：

前端项目：design.md → 项目审查 → dev.md

后端项目：项目审查 → dev.md（含接口影响清单）→ SQL 脚本（如有数据库变更）

项目审查（生成 dev.md 前必须执行）：

1. 读取项目目录结构，了解整体组织方式
2. 读取配置文件（package.json、go.mod 等），确认实际技术栈和依赖版本
3. 读取核心入口文件，了解现有架构
4. 检查本次涉及的相关模块现有实现
5. 确认方案与现有代码的命名规范、组织模式一致

审查原则：技术方案必须基于实际代码，而非模板假设。

生成 dev.md 后，向用户展示，等待用户明确确认后再进入下一阶段。

阶段 3：生成 plan.md（用户确认 dev.md 后）

基于已确认的 prd.md 和 dev.md 生成开发计划：

1. 使用 assets/plan_template.md
2. 仅包含：任务拆解、里程碑时间线、负责人、风险与依赖
3. 不得出现技术架构、数据模型、接口定义等内容（已在 dev.md 中）
4. 完成后更新 docs/prd/README.md 的版本摘要

规则：流程为 prd.md（确认）→ design/dev（确认）→ plan.md → README 摘要；prd.md 和 dev.md 两个节点需要用户确认。

1. 初始化

当 docs/prd/ 目录不存在时，先引导用户初始化：

1. 提示用户 PRD 目录尚不存在
2. 创建 docs/prd/ 目录
3. 建议从 v0.1.0 开始，或由用户指定版本号
4. 继续执行创建版本流程

2. 列出版本

ls -la docs/prd/

展示汇总信息（语义化排序），包含状态总览：

📊 PRD 状态总览
────────────────────
v0.3.0  ⏳ 规划中    3 个需求  (P0:1 P1:2)
v0.2.4  🔄 进行中    5 个需求  (P0:2 P1:2 P2:1)
v0.2.3  ✅ 已完成    4 个需求
────────────────────
共 3 个版本 | 1 个归档

3. 查看结构

find docs/prd/<version> -name "*.md" | sort

汇总存在的文档及其用途。

4. 创建版本

1. 确定版本号（根据现有版本自动建议下一个语义化版本）
2. 冲突检测：若 docs/prd/<version>/ 已存在，提示用户选择：覆盖 / 换版本号 / 取消
3. 创建目录：mkdir -p docs/prd/<version>
4. 生成文档（默认至少生成 prd.md；前端项目补 design.md，后端项目补 dev.md，完整模式下再生成 plan.md）
5. 从 assets/ 目录加载对应模板，填入用户提供的上下文
6. 更新 docs/prd/README.md 中的版本摘要，采用倒序排列，最新版本放在最上方
7. 保存文件并确认位置

模板文件位于 assets/ 目录：

• assets/prd_template.md — 产品需求文档（含用户故事格式、优先级引用）
• assets/plan_template.md — 开发计划（含状态标记规范）
• assets/design_template.md — 界面设计文档（ASCII 布局图）
• assets/dev_template.md — 技术开发文档（架构、数据模型、API）
• assets/readme_template.md — docs/prd/README.md 版本摘要模板

5. 扩展版本

1. 读取现有的 prd.md
2. 追加新需求章节（使用用户故事格式）
3. 如需则更新 plan.md、design.md、dev.md
4. 若版本摘要发生变化，同步更新 docs/prd/README.md

6. 对比版本

读取两个版本的文档，生成结构化对比：

版本对比: v0.2.0 vs v0.3.0
─────────────────────────────
新增需求:
  + 需求名称 (P0)

删除需求:
  - 需求名称

优先级变更:
  需求名称: P1 → P0

时间线变更:
  阶段 2 预计时间: 5d → 8d

也可使用 git diff docs/prd/<version-a>/prd.md docs/prd/<version-b>/prd.md 进行原始对比。

7. 归档版本

1. 确认要归档的版本号
2. 创建归档目录（如不存在）：mkdir -p docs/prd/_archive/
3. 移动版本：mv docs/prd/<version> docs/prd/_archive/<version>
4. 更新 docs/prd/README.md，移除或调整对应版本摘要
5. 确认归档完成

9. 更新版本摘要 README

每当新增、扩展、归档版本后，都要同步维护 docs/prd/README.md。

要求如下：

1. 采用倒序排列：最新版本必须放在最上面
2. 摘要信息精简清晰：每个版本至少包含版本号、状态、日期、核心变更摘要
3. 路径可点击：摘要中应链接到对应版本目录或核心文档
4. 归档版本单独分组：如需展示历史归档版本，放在 README 下方单独区块

推荐格式示例：

# PRD 版本索引

## 当前版本

- `v0.3.0`｜⏳ 规划中｜2026-04-09
  - 摘要：新增会员体系与支付能力设计
  - 文档：[`prd.md`](./v0.3.0/prd.md) / [`design.md`](./v0.3.0/design.md) / [`plan.md`](./v0.3.0/plan.md)

- `v0.2.4`｜🔄 进行中｜2026-03-28
  - 摘要：优化订单流转与通知机制
  - 文档：[`prd.md`](./v0.2.4/prd.md) / [`plan.md`](./v0.2.4/plan.md)

## 已归档

- `v0.1.0`｜✅ 已归档
  - 文档：[`archive`](./_archive/v0.1.0/)

8. 跨版本搜索

grep -r "<关键词>" docs/prd/ --include="*.md" -l

展示匹配的版本和文件列表。

使用模式

快速创建：用户说"创建一个 v0.3.0 PRD"→ 检查版本 → 创建目录 → 生成模板 → 确认

查看状态：用户说"显示所有 PRD 版本"→ 列出版本 → 展示状态总览

扩展需求：用户说"在 v0.2.3 中添加功能"→ 读取现有文档 → 追加需求 → 更新关联文档

归档旧版：用户说"归档 v0.1.0"→ 确认版本 → 移动到 _archive/ → 确认完成

搜索需求：用户说"搜索认证相关的需求"→ 跨版本 grep → 展示结果

最佳实践

• 始终使用语义化版本（v0.2.0, v1.0.0）
• 新建项目或新版本时，优先走完整生成流程：prd.md → design.md → plan.md → 项目审查 → dev.md
• 每次生成、扩展、归档版本后，都要同步更新 docs/prd/README.md
• 文档边界原则：
  • prd.md 中出现技术选型/框架/接口是越界 → 移至 dev.md
  • plan.md 中出现数据模型/架构图是越界 → 移至 dev.md
  • dev.md 中出现"用户希望"/"业务目标"是越界 → 移至 prd.md
• 技术方案必须基于实际代码：生成 dev.md 前，先读取项目现有代码，确保方案与实际架构一致
• 在 plan.md 中使用状态标记：⏳ 规划中 | 🔄 进行中 | ✅ 已完成 | ❌ 已取消
• 已完成或废弃的版本及时归档到 _archive/

后端项目 dev.md 必含板块：接口影响清单

后端项目的 dev.md 必须包含「接口影响清单」板块，明确记录当前版本对所有接口的影响，包含三部分：

1. 新增接口

2. 改动接口

必须列出字段级别的调整说明：

3. 删除接口

注意：如果没有某类变更（如无删除接口），填写"无"即可，不可省略板块。

SQL 脚本规范

涉及新增数据库表、新增字段或初始化数据时，必须在版本目录下生成独立的 SQL 脚本文件：

docs/prd/<version>/sql/
├── DDL.sql          # 表结构变更
└── DML_init.sql     # 初始化数据

DDL.sql 包含：

• CREATE TABLE 建表语句（含完整字段、索引、约束、注释）
• ALTER TABLE 新增字段、新增索引语句

DML_init.sql 包含：

• 字典数据初始化（如权益类型、角色模板等）
• 历史数据迁移/回填语句（注释形式，按需执行）
• 执行前提说明（如"先执行 DDL.sql"）

注意：SQL 脚本应可直接在 MySQL 8.0+ 环境执行，字段注释使用 COMMENT，表引擎使用 InnoDB。

资源文件

• assets/prd_template.md — 产品需求文档模板
• assets/plan_template.md — 开发计划模板
• assets/design_template.md — 界面设计文档模板
• assets/dev_template.md — 技术开发文档模板
• assets/readme_template.md — PRD 版本索引 README 模板
• references/ascii_design_patterns.md — ASCII 原型设计参考
• references/priority_definitions.md — P0-P3 优先级定义