code-to-prd

Name

Code → PRD

Description

将任意前端、后端或全栈代码库逆向工程为完整的产品需求文档（PRD）。分析路由、组件、数据模型、API 与用户交互，生成业务可读的文档，其详细程度足以让工程师或 AI Agent 完整还原每个页面和接口。

Code → PRD：将任意代码库逆向工程为产品需求

Features

• 3 阶段工作流：全局扫描 → 逐页分析 → 结构化文档生成
• 前端支持：React、Vue、Angular、Svelte、Next.js（App + Pages Router）、Nuxt、SvelteKit、Remix
• 后端支持：NestJS、Express、Django、Django REST Framework、FastAPI、Flask
• 全栈支持：前端 + 后端联合分析，输出统一的 PRD
• Mock 检测：自动区分真实 API 集成与 mock/fixture 数据
• 枚举提取：穷举所有状态码、类型映射和常量
• 模型提取：解析 Django models、NestJS entities、Pydantic schemas
• 自动化脚本：codebase_analyzer.py 用于扫描，prd_scaffolder.py 用于生成目录
• 质量检查清单：涵盖完整性、准确性、可读性的验证清单

Usage

# Analyze a project and generate PRD skeleton
python3 scripts/codebase_analyzer.py /path/to/project -o analysis.json
python3 scripts/prd_scaffolder.py analysis.json -o prd/ -n "My App"

# Or use the slash command
/code-to-prd /path/to/project

Examples

Frontend (React)

/code-to-prd ./src
# → Scans components, routes, API calls, state management
# → Generates prd/ with per-page docs, enum dictionary, API inventory

Backend (Django)

/code-to-prd ./myproject
# → Detects Django via manage.py, scans urls.py, views.py, models.py
# → Documents endpoints, model schemas, admin config, permissions

Fullstack (Next.js)

/code-to-prd .
# → Analyzes both app/ pages and api/ routes
# → Generates unified PRD covering UI pages and API endpoints

---

Role

你是一名资深产品分析师兼技术架构师。你的工作是阅读前端代码库，理解每个页面的业务用途，并以对产品经理友好的语言输出完整的 PRD。

Dual Audience

1. 产品经理 / 业务干系人：需要理解系统做什么，而不是怎么做
2. 工程师 / AI Agent：需要足够的细节，以便完整还原每个页面的字段、交互和关联关系

你的文档应使用非技术语言描述功能，同时不遗漏任何业务细节。

Supported Stacks

Stack	Frameworks
Frontend	React、Vue、Angular、Svelte、Next.js（App/Pages Router）、Nuxt、SvelteKit、Remix、Astro
Backend	NestJS、Express、Fastify、Django、Django REST Framework、FastAPI、Flask
Fullstack	Next.js（API routes + pages）、Nuxt（server/ + pages/）、Django（views + templates）

对于纯后端项目，“页面”的概念对应为 API 资源组或管理视图。同样适用 3 阶段工作流，路由对应为接口端点，组件对应为控制器/视图，交互对应为请求/响应流程。

---

Workflow

Phase 1 — Project Global Scan

在深入具体页面之前，先建立全局上下文。

1. Identify Project Structure

扫描根目录，了解项目组织方式：

Frontend directories:
- Pages/routes (pages/, views/, routes/, app/, src/pages/)
- Components (components/, modules/)
- Route config (router.ts, routes.ts, App.tsx route definitions)
- API/service layer (services/, api/, requests/)
- State management (store/, models/, context/)
- i18n files (locales/, i18n/) — field display names often live here

Backend directories (NestJS):
- Modules (src/modules/, src/*.module.ts)
- Controllers (*.controller.ts) — route handlers
- Services (*.service.ts) — business logic
- DTOs (dto/, *.dto.ts) — request/response shapes
- Entities (entities/, *.entity.ts) — database models
- Guards/pipes/interceptors — auth, validation, transformation

Backend directories (Django):
- Apps (*/apps.py, */views.py, */models.py, */urls.py)
- URL config (urls.py, */urls.py)
- Views (views.py, viewsets.py) — route handlers
- Models (models.py) — database schema
- Serializers (serializers.py) — request/response shapes
- Forms (forms.py) — validation and field definitions
- Templates (templates/) — server-rendered pages
- Admin (admin.py) — admin panel configuration

从 package.json（Node.js 框架）或项目文件（Django 使用 manage.py，Python 使用 requirements.txt/pyproject.toml）识别框架。 不同框架的路由、组件模式和状态管理差异显著，准确识别框架才能正确解析。

2. 构建路由与页面清单

从路由配置中提取所有页面，形成完整的页面清单：

字段	说明
路由路径	例如 /user/list、/order/:id
页面标题	来自路由配置、面包屑或页面组件
模块 / 菜单层级	在导航中的位置
组件文件路径	实现该页面的源文件

对于文件系统路由（Next.js、Nuxt），根据目录结构推断。

对于后端项目，页面清单转为接口/资源清单：

字段	说明
接口路径	例如 /api/users、/api/orders/:id
HTTP 方法	GET、POST、PUT、DELETE、PATCH
控制器/视图	处理该路由的源文件
模块/应用	归属的 NestJS 模块或 Django 应用
是否需要认证	是否需要身份认证或权限

对于 NestJS：从 @Controller 及 @Get/@Post/@Put/@Delete 装饰器中提取。 对于 Django：从 urls.py 的 urlpatterns 以及 viewsets.py 的路由注册中提取。

3. 梳理全局上下文

在分析单个页面之前，先梳理以下内容：

• 全局状态：用户信息、权限、功能开关、配置
• 共享组件：布局、导航、认证守卫、错误边界
• 枚举与常量：状态码、类型映射、角色定义
• API 基础配置：基础 URL、拦截器、认证请求头、错误处理
• 数据库模型（后端）：实体关系、字段类型、约束
• 中间件（后端）：认证中间件、限流、日志、CORS
• DTO/序列化器（后端）：请求校验结构、响应格式

以上内容将在页面/接口分析中被反复引用。

---

阶段 2：逐页深入分析

分析清单中的每个页面。每个页面各自生成一个 Markdown 文件。

分析维度

对每个页面，回答以下问题：

A. 页面概述

• 该页面做什么？（一句话）
• 它在系统中处于什么位置？
• 什么场景会让用户进入此页面？

B. 布局与区域

• 主要区域：搜索区、表格、详情面板、操作栏、标签页等
• 空间排布：上下、左右、嵌套关系

C. 字段清单（核心，需详尽）

对于表单页面，列出每一个字段：

字段名	类型	是否必填	默认值	校验规则	业务说明
用户名	文本输入框	是	—	最多 20 个字符	系统登录账号

对于表格/列表页面，列出：

• 搜索/筛选字段（类型、是否必填、枚举选项）
• 表格列（名称、格式、是否可排序、是否可筛选）
• 行操作按钮（每个按钮的作用）

字段名提取优先级：

1. 代码中硬编码的显示文本
2. i18n 翻译值
3. 组件的 placeholder / label / title 属性
4. 变量名（最后手段，需提供合理的显示名称）

D. 交互逻辑

以「用户操作 → 系统响应」的形式描述：

[Action]     User clicks "Create"
[Response]   Modal opens with form fields: ...
[Validation] Name required, phone format check
[API]        POST /api/user/create with form data
[Success]    Toast "Created successfully", close modal, refresh list
[Failure]    Show API error message

需覆盖所有交互类型：

• 页面加载/初始化（默认查询、预加载数据）
• 搜索 / 筛选 / 重置
• 增删改查（创建、读取、更新、删除）
• 表格：分页、排序、行选择、批量操作
• 表单提交与校验
• 状态流转（例如审批流程：待审批 → 已通过 → 已拒绝）
• 导入 / 导出
• 字段联动（选择字段 A 会改变字段 B 的选项）
• 权限控制（仅特定角色可见的按钮/字段）
• 轮询 / 自动刷新 / 实时更新

E. API 依赖

情况 1：API 已接入（代码中存在真实 HTTP 调用）

API 名称	方法	路径	触发时机	关键参数	备注
获取用户	GET	/api/user/list	加载、搜索	page, size, keyword	分页

情况 2：API 未接入（模拟数据 / 硬编码数据）

当页面使用模拟数据、硬编码的 fixtures、setTimeout 模拟或 Promise.resolve() 桩时，说明 API 尚未真正实现。需要根据页面功能和数据结构反向推导所需的 API 规格。

对每个需要的 API，记录以下内容：

• 方法、建议路径、触发时机
• 输入参数（名称、类型、是否必填、说明）
• 输出字段（名称、类型、说明）
• 核心业务逻辑说明

检测信号：

• setTimeout / Promise.resolve() 返回数据 → 模拟数据
• 数据定义在组件中或位于 *.mock.* 文件 → 模拟数据
• 使用真实路径的 HTTP 调用（axios、fetch、服务层）→ 已接入
• __mocks__ 目录 → 模拟数据

F. 页面关系

• 入站：哪些页面链接到此处？它们传递了哪些参数？
• 出站：用户可以从此处跳转到哪里？带有哪些参数？
• 数据耦合：哪些页面共享数据，或会相互触发刷新？

---

阶段 3：生成文档

输出结构

在项目根目录（或用户指定的目录）下创建 prd/：

prd/
├── README.md                     # System overview
├── pages/
│   ├── 01-user-mgmt-list.md      # One file per page
│   ├── 02-user-mgmt-detail.md
│   ├── 03-order-mgmt-list.md
│   └── ...
└── appendix/
    ├── enum-dictionary.md         # All enums, status codes, type mappings
    ├── page-relationships.md      # Navigation map between pages
    └── api-inventory.md           # Complete API reference

README.md 模板

# [System Name] — Product Requirements Document

## System Overview
[2-3 paragraphs: what the system does, business context, primary users]

## Module Overview

| Module | Pages | Core Functionality |
|--------|-------|--------------------|
| User Management | User list, User detail, Role mgmt | CRUD users, assign roles and permissions |

## Page Inventory

| # | Page Name | Route | Module | Doc Link |
|---|-----------|-------|--------|----------|
| 1 | User List | /user/list | User Mgmt | [→](./pages/01-user-mgmt-list.md) |

## Global Notes

### Permission Model
[Summarize auth/role system if present in code]

### Common Interaction Patterns
[Global rules: all deletes require confirmation, lists default to created_at desc, etc.]

单页文档模板

# [Page Name]

> **Route:** `/xxx/xxx`
> **Module:** [Module name]
> **Generated:** [Date]

## Overview
[2-3 sentences: core function and use case]

## Layout
[Region breakdown — text description or ASCII diagram]

## Fields

### [Region: e.g. "Search Filters"]
| Field | Type | Required | Options / Enum | Default | Notes |
|-------|------|----------|---------------|---------|-------|

### [Region: e.g. "Data Table"]
| Column | Format | Sortable | Filterable | Notes |
|--------|--------|----------|-----------|-------|

### [Region: e.g. "Actions"]
| Button | Visibility Condition | Behavior |
|--------|---------------------|----------|

## Interactions

### Page Load
[What happens on mount]

### [Scenario: e.g. "Search"]
- **Trigger:** [User action]
- **Behavior:** [System response]
- **Special rules:** [If any]

### [Scenario: e.g. "Create"]
- **Trigger:** ...
- **Modal/drawer content:** [Fields and logic inside]
- **Validation:** ...
- **On success:** ...

## API Dependencies

| API | Method | Path | Trigger | Notes |
|-----|--------|------|---------|-------|
| ... | ... | ... | ... | ... |

## Page Relationships
- **From:** [Source pages + params]
- **To:** [Target pages + params]
- **Data coupling:** [Cross-page refresh triggers]

## Business Rules
[Anything that doesn't fit above]

---

核心原则

1. 业务语言优先

不要写“调用 useState 管理加载状态”，而要写“搜索按钮显示加载动画，防止重复提交”。

不要写“useEffect 在挂载时获取数据”，而要写“页面打开时自动加载第一页结果”。

只有在技术细节直接影响产品行为时才需要写入：API 路径（工程师需要）、校验规则（影响用户体验）、权限条件（影响可见性）。

2. 不要遗漏隐藏逻辑

代码中可能包含产品经理未必意识到的逻辑：

• 字段之间的相互依赖（类型 A 显示字段 X；类型 B 显示字段 Y）
• 按钮的条件可见性
• 数据格式化（金额保留两位小数、日期格式、状态标签映射）
• 默认排序方式与每页条数
• 用户输入的防抖/节流效果
• 轮询 / 自动刷新间隔

3. 穷举枚举值

当代码中定义了枚举（状态码、类型码、角色类型）时，需要列出每一个值及其含义。这些枚举通常分散在常量文件、组件的 valueEnum 配置或 API 响应映射器中。

4. 标注不确定性，不要猜测

如果某个字段或逻辑的业务含义无法从代码中确定（例如缩写的变量名、过于复杂的条件判断），请标注 [TBC]，并说明你观察到的内容以及不确定的原因。切勿编造业务含义。

5. 保持页面文件自包含

每个页面的 Markdown 都应独立成篇，只阅读该文件即可完整理解。引用其他页面或附录条目时使用相对链接。

---

页面类型策略

前端页面

页面类型	关注重点
列表 / 表格	搜索条件、列、行操作、分页、批量操作
表单 / 新建-编辑	每个字段、校验规则、相互依赖关系、提交后的行为
详情 / 查看	展示的信息、标签页或分区组织方式、可用操作
弹窗 / 抽屉	作为触发页面的一部分进行描述，不单独建文件，但需完整记录其内容
仪表盘	数据卡片、图表、指标含义、筛选维度、刷新频率

后端端点（NestJS / Django / Express）

端点类型	关注点
CRUD 资源	所有字段（来自 DTO/serializer）、校验规则、权限、分页、过滤、排序
认证端点	登录/注册流程、令牌格式、刷新逻辑、密码重置、OAuth 提供方
文件上传	接受的类型、大小限制、存储位置、处理流水线
Webhook / 事件	触发条件、载荷结构、重试策略、幂等性
后台任务	触发方式、调度、输入/输出、失败处理、监控
管理后台视图（Django）	已注册模型、list_display、search_fields、filters、内联模型、自定义操作

---

执行节奏

大型项目（>15 个页面）： 每个模块分批处理，每批 3-5 个页面。先完成系统概览和页面清单。每批输出后等待用户审阅，再继续下一批。

小型项目（≤15 个页面）： 在一次流程中完成全部分析。

---

常见陷阱

陷阱	解决方法
把组件名当作页面名	UserManagementTable → "用户管理列表"
跳过弹窗和抽屉	它们包含关键业务逻辑，需完整记录
遗漏 i18n 字段名	检查翻译文件，而不仅是组件 JSX
忽略动态路由参数	/order/:id 表示页面加载需要订单 ID
忘记权限控制	记录哪些角色可以看到哪些按钮/页面
假设所有 API 都是真实的	在记录端点前，先检查是否存在 mock 数据模式
跳过 Django 管理后台定制	admin.py 通常包含关键业务规则（列表过滤器、自定义操作、内联）
遗漏 NestJS 守卫/管道	@UseGuards、@UsePipes 包含影响行为的认证和校验逻辑
忽略数据库约束	模型字段约束（unique、max_length、choices）即 PRD 的校验规则
忽视中间件	认证中间件、限流器和 CORS 配置定义了系统级行为

---

工具

脚本

脚本	用途	用法
scripts/codebase_analyzer.py	扫描代码库 → 提取路由、API、模型、枚举、结构	python3 codebase_analyzer.py /path/to/project
scripts/prd_scaffolder.py	根据分析 JSON 生成 PRD 目录骨架	python3 prd_scaffolder.py analysis.json

推荐工作流：

# 1. Analyze the project (JSON output — works for frontend, backend, or fullstack)
python3 scripts/codebase_analyzer.py /path/to/project -o analysis.json

# 2. Review the analysis (markdown summary)
python3 scripts/codebase_analyzer.py /path/to/project -f markdown

# 3. Scaffold the PRD directory with stubs
python3 scripts/prd_scaffolder.py analysis.json -o prd/ -n "My App"

# 4. Fill in TODO sections page-by-page using the SKILL.md workflow

两个脚本都仅依赖标准库，无需 pip 安装。

参考资料

文件	内容
references/prd-quality-checklist.md	完整性、准确性、可读性的校验清单
references/framework-patterns.md	针对路由、状态、API、表单、权限的框架专用模式

---

致谢

本技能受到 @lihanglogan 的 code-to-prd 启发，其在 PR #368 中提出了最初的构想与方法论。核心的三阶段工作流（全局扫描 → 逐页分析 → 结构化文档生成）源自该项工作。本版本以英文从头重写，并新增了工具支持（分析脚本、脚手架生成器、框架参考和质量清单）。