# pencil-prd-generator

**Repository Path**: vicoproplus/pencil-prd-generator

## Basic Information

- **Project Name**: pencil-prd-generator
- **Description**: pencil文件.pen反推PRD
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-07-08
- **Last Updated**: 2026-07-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# pencil-prd-generator

> Pencil 设计文件(.pen) → PRD 反向同步生成器

---

## 介绍

在产品设计流程中，设计产物（Pencil 原型文件 `.pen`）和需求文档（PRD）往往由不同角色分别维护——产品经理写 PRD，设计师画原型。当设计迭代后，需求文档容易与设计脱节，导致开发拿到的是过时的需求。

**pencil-prd-generator** 解决这一痛点：解析 Pencil 原型设计产物，与初版 PRD.md 进行语义映射与合并，自动生成符合规范模板的最终 PRD-final.md。

### 核心工作流

```
.pen 设计文件 ──┐
                 ├──→ 解析 → 语义映射合并 → 校验 → 渲染 → PRD-final.md
初版 PRD.md ────┘
```

| 步骤 | 做什么 | 工具 |
|------|--------|------|
| **解析** | 从 `.pen` 提取页面结构、便签说明、交互节点；从初版 PRD.md 提取结构化需求 | `parse_pen.py` + `parse_prd.py` |
| **映射合并** | 将设计便签按语义归入 PRD 对应章节，以设计为权威来源合并回填，冲突项记录到附录 | LLM 决策 + `references/note-mapping-guide.md` |
| **校验渲染** | 校验合并数据完整性，按模板渲染输出 | `validate_prd_data.py` + `generate_final_prd.py` |

### 核心原则

- **以 `.pen` 为准**：设计产物作为权威来源回填 PRD，初版 PRD 作为结构基底与未设计项保留来源
- **不覆盖初版**：生成新文件 `PRD-final.md`，初版 `PRD.md` 原样保留
- **冲突可追溯**：设计与 PRD 不一致时，以设计为准，但必须在附录「冲突项」中记录原值
- **禁止编造**：无明确信号的项标记「待补充」，不臆造字段或功能

---

## 目录结构

```
├── SKILL.md                        # AI Skill 指令（供 LLM 使用的工作流定义）
├── scripts/
│   ├── parse_pen.py                # 解析 .pen 设计文件
│   ├── parse_prd.py                # 解析初版 PRD.md
│   ├── validate_prd_data.py        # 校验合并后的 PRD 数据
│   └── generate_final_prd.py       # 渲染最终 PRD.md
├── references/
│   ├── PRD-template.md             # PRD 输出模板规范
│   ├── pen-structure.md            # .pen 文件结构参考（供 LLM 理解）
│   └── note-mapping-guide.md       # 便签→PRD 章节映射指南（供 LLM 决策）
└── README.md
```

---

## 在编程工具中使用 Skill（AI 工作流）

本项目内置完整的 AI Skill 指令文件 [`SKILL.md`](./SKILL.md)，可在支持 AI Skill 机制的编程工具（IDE / AI Coding Agent）中一键触发，实现从设计产物到 PRD 的端到端自动生成。

### 支持的编程工具

#### AtomCode

[AtomCode](https://atomgit.com/atomcode) 是 AtomGit 推出的 AI 编程助手，支持 Skill 机制。

**使用方法**：

1. 在 AtomCode 中打开本项目目录
2. 输入以下任一触发指令：

| 触发指令 | 说明 |
|---------|------|
| 根据 .pen 生成 PRD | 标准触发，指定 .pen 文件路径 |
| 把设计回填到 PRD | 指定 .pen + 初版 PRD.md 路径 |
| 根据设计产物更新需求文档 | 同上 |
| 用 .pen 和初版 PRD 出最终 PRD | 同上 |
| 反向同步设计到需求 | 同上 |

3. AtomCode 会自动读取 `SKILL.md` 中的工作流定义，按 3 阶段执行：
   - **S1 解析**：询问并确认 `design.pen` 与初版 `PRD.md` 路径 → 调用 `parse_pen.py` + `parse_prd.py` 解析 → 展示解析结果摘要
   - **S2 映射合并**：LLM 依据映射指南将便签归入 PRD 章节 → 按冲突裁决规则合并 → 补全页面结构与数据字段 → 展示合并摘要并请求用户确认
   - **S3 生成**：组装合并数据 → `validate_prd_data.py` 校验 → `generate_final_prd.py` 渲染 → 输出 `PRD-final.md` 并展示结果

#### Trae

[Trae](https://www.trae.com/) 是字节跳动推出的 AI 编程 IDE，支持自定义 Prompt / Agent 工作流。

**使用方法**：

1. 在 Trae 中打开本项目目录
2. 将 `SKILL.md` 作为系统指令 / Agent Prompt 配置给 AI
3. 通过对话交互，描述你的需求（如"帮我根据 design.pen 和 PRD.md 生成最终 PRD"）
4. Trae 会引导你完成三步工作流，每一步与你确认后继续

> 建议在 Trae 的 Agent 模式中使用，以获得更好的多步工作流体验。



## 参与贡献

1. Fork 本仓库
2. 新建 Feat_xxx 分支
3. 提交代码
4. 新建 Pull Request