# Rapid Mvp
> 从零想法到可运行MVP代码的端到端开发方法论。通过交互式对话引导用户细化需求、自动生成PRD， 再经由多Agent并行协作（设计→评审→优化→修复→编码）输出后端+前端+运维+QA完整代码。 运维工程师全程参与：PRD阶段绘制网络拓扑与部署架构图，后续负责CI/CD自动化脚本与容器化部署。 触发词：快速MVP、并行开发MVP、多Agent开发、从想法到代码、从PRD到代码、交互式PRD、 软件快速成型、帮我做个系统、快速出原型。适用于用户有产品想法但无PRD的场景。
- Skill: `oliverpanda/rapid-mvp` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add oliverpanda/rapid-mvp`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oliverpanda/rapid-mvp/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: OliverPanda (https://skillmd.com/u/oliverpanda)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/oliverpanda/rapid-mvp
---
# rapid-mvp — 交互式 PRD 生成 → 多 Agent 并行 MVP 开发
## 核心方法论：业务闭环保障流程
```
用户: "我想做一个XX系统"
↓
🔄 Phase 0: 交互式 PRD 生成（与用户对话，逐步细化）
→ 澄清问题 → 功能梳理 → 🔴核心闭环定义 → API确认 → 部署架构规划(运维工程师介入) → 🔍GitHub开源项目调研 → PRD生成 → 用户确认
🛑 用户确认 PRD（含核心闭环技术链路表 + 开源基座项目选型）定稿后继续
↓
Phase 1: 设计产出 (3-4 Agent 并行)
→ 多Agent架构总览 + DB设计(ER图+DDL) + UI/UX视觉定稿 + 运维架构设计(网络拓扑+部署图+CI/CD)
→ 设计围绕核心闭环展开
🛑 确认设计产出质量
↓
Phase 2: 跨角色评审 (6 Agent 并行)
→ PM/后端/前端/UI/QA/运维 评审报告（每角色≥3 Blocker）
→ 重点评审闭环链路的完整性和可实现性
🛑 确认 Blocker 清单
↓
Phase 3: 优化方案 + 协调 (6+1 Agent)
→ 6角色优化 + 跨角色冲突检测
🛑 确认冲突和优化方向
↓
Phase 4: 冲突修复 (4 Agent)
→ API统一 + 运维填补 + 安全修复 + 时间线裁定
🛑 锁定全部裁定（之后不改设计）
↓
Phase 4.5: 设计文档终稿整合 (1 Agent)
→ 将 Phase 2-4 全部修订合并回所有设计文档，产出终稿版作为唯一真相来源
🛑 确认终稿文档一致性：每个修订可溯源、跨文档无矛盾
↓
Phase 5: 核心路径优先编码（两阶段 5+5 Agent）
→ Phase 5.1: 核心闭环编码（先完成闭环链路表的 ✅ API 和页面，确保可联通）
→ Phase 5.2: 外围功能编码（P1/P2 模块补充）
🛑 确认核心闭环 + 外围功能均已交付
↓
🔴 Phase 5.5: 业务闭环自动检测与验证（AI 驱动，MVP 可用性最终门禁）
→ 静态代码分析(自动扫描断裂点) → 自动修复 → E2E测试 → 动态运行验证 → 失败修复循环
🛑 闭环全部节点 PASS 后才交付（检测/修复全程自动，用户只看报告）
↓
输出: PRD终稿 + 终稿设计文档 + 🔴闭环验证通过的可运行代码
```
---
## 核心原则：业务闭环优先 (Business Closure First)
MVP 的核心衡量标准**不是文件数量**，而是**用户能否走通一个完整的核心业务流程**。
> ⚠️ **重要**: 闭环的定义、检测、修复全部由 AI 自动完成。用户不需要懂技术，不需要自己梳理闭环——AI 根据用户描述的功能自动推断核心流程，Phase 5.5 自动分析代码找出断裂点并修复。用户只需要在 Phase 0 确认"这个流程对吗"、在 Phase 5.5 看最终的 ✅/❌ 报告。
### 什么是业务闭环？
```
用户入口 → 核心操作 → 数据持久化 → 反馈展示 → 用户出口
↑ ↓
└──────────── 可以再次进入循环 ─────────────────┘
```
**闭环通过标准**（Phase 5.5 自动验证，必须全部满足）：
1. ✅ 用户可以完成从入口到出口的完整操作（不卡在任何一步）
2. ✅ 每一步都有**真实的代码支撑**（禁止 mock/stub/TODO 占位核心路径）
3. ✅ 数据在前后端之间正确流转（前端请求 → API → 数据库 → 响应 → 前端渲染）
4. ✅ 错误情况有合理处理（不会白屏或崩溃，有用户可理解的错误提示）
5. ✅ 闭环中的每个 API 都有对应的前端调用方，每个前端交互都有对应的后端实现
### AI 自动检测闭环断裂（Phase 5.5 静态分析，无需用户参与）
闭合检测其实非常容易自动化——不需要用户来发现，AI 直接扫描代码就能找出所有断裂点：
| 检测项 | 检测方法 | 示例断裂 |
|--------|---------|---------|
| API 缺失 | 前端 HTTP 调用 ↔ 后端路由定义 交叉对比 | 前端调了 `/api/v1/orders` 但后端没定义 → 🔴 |
| 死交互 | 前端 form/button handler 是否有 API 调用 | 注册表单的 handleSubmit 只有 console.log → 🔴 |
| 无持久化 | 后端 Service 层是否有 DB 操作 | POST API 只 return {success:true} 不写库 → 🔴 |
| 导航断裂 | 前端路由 ↔ 页面组件的映射关系 | /product/:id 指向了 ProductEdit 组件 → 🔴 |
| 字段不匹配 | 前端请求体字段 ↔ 后端 DTO/Schema 字段 | 前端发 `{userName}` 后端收 `{username}` → 🔴 |
### 闭环节杀反模式（必须避免）
| 反模式 | 为什么导致闭环失败 |
|--------|------------------|
| 前端页面做好了，API 没实现 | 用户点击按钮无响应 → 闭环断裂 |
| API 实现了，前端没调用 | 后端代码成为"孤儿"→ 无法验证 |
| 数据库表建了，但 API 没连接数据库 | 数据不持久化 → 刷新即丢失 |
| 所有模块独立完成但互不联通 | 每个模块都是孤岛 → 无法串联成流程 |
| 用 mock 数据填充核心路径 | 看起来能跑，实际业务不通 |
| 只有 Happy Path，无错误处理 | 一个异常就卡死整个流程 |
### 闭环保障机制（AI 驱动，贯穿全流程）
```
Phase 0: AI 自动推断核心闭环（根据项目类型+功能描述套模板，用户只确认）
↓
Phase 1-4.5: 设计评审中持续校验闭环完整性
↓
Phase 5.1: 核心路径优先编码（闭环链路先完成，外围功能后补充）
↓
Phase 5.5.0: AI 静态代码分析（自动扫描前后端代码，交叉对比找出所有断裂点）
↓
Phase 5.5.1: AI 自动修复断裂点（补全缺失 API、补充死交互、修正导航）
↓
Phase 5.5.3: 动态运行验证（启动全栈 → 逐步骤测试核心闭环 → 不通过不交付）
```
---
## Phase 0: 交互式 PRD 生成（🔄 与用户对话）
**目标**: 从用户的一句想法开始，通过结构化问答逐步生成一份完整的 PRD。
**核心原则**: 不问无关问题、不假设答案、每个问题都有默认推荐、用户可随时说"先用默认的继续"。
### Step 0.1: 理解项目方向（1-2 轮对话）
用户说出想法后，Agent 先用自己的话复述理解，然后提出第一组关键问题：
```markdown
我理解你想做一个 **[一句话概括]**。在开始细化之前，先确认几个方向性问题：
**1. 这是什么类型的产品？**
A. 内部管理后台（如运营Dashboard、CRM） ← 默认
B. 面向用户的产品（如电商App、社区）
C. API/后端服务（无前端界面）
D. AI/Agent 驱动的自动化系统
**2. 目标用户是谁？**
A. 个人用户（C端）
B. 企业/团队（B端/内部工具） ← 默认
C. 两者都有
**3. 项目当前阶段？**
A. 只有想法，需要从零开始 ← 默认
B. 已有粗略需求文档
C. 已有详细PRD（→ 直接跳到 Phase 1）
```
🛑 **Phase 0.1 确认**: 用户回答了方向性问题 → Agent 复述理解 → 等用户说"对"或纠正 → 进入 Step 0.2。
### Step 0.2: 功能模块梳理（2-3 轮对话）
根据项目类型，引导用户列出功能模块：
```markdown
好的。现在我们来梳理核心功能。请按以下格式告诉我系统需要哪些功能模块：
**主线功能（用户必须完成的闭环）**:
例: 用户登录 → 浏览商品 → 下单 → 支付 → 发货
**辅助功能（锦上添花）**:
例: 数据统计、消息通知、权限管理
---
💡 如果暂时不确定，可以先告诉我最核心的 3-5 个功能，
我会帮你补充常见的辅助模块，你再来确认。
```
Agent 根据用户回答，自动将功能归类为 M1~MN 模块，并判断哪些是 P0（MVP必须）、哪些是 P1/P2。
**🔴 MVP 核心闭环自动推断**（AI 驱动，用户只确认）:
用户已经描述了功能模块，Agent 此时**自动推断** MVP 的核心闭环——不需要用户自己梳理。
**推断方法**（Agent 内部执行，对用户透明）：
```
根据项目类型，套用对应的闭环模板：
电商/交易类:
注册/登录 → 浏览[核心资源]列表 → 查看[核心资源]详情 → 加入购物车/下单 → 支付 → 查看订单/状态
内容/社区类:
注册/登录 → 浏览[内容]列表 → 查看[内容]详情 → 发布[内容] → 互动(评论/点赞) → 查看个人主页
管理后台类:
登录 → 查看[资源]列表 → 搜索/筛选[资源] → 新增[资源] → 编辑[资源] → 查看统计Dashboard
工具/SaaS类:
注册/登录 → 创建[项目/任务] → 配置/编辑[核心功能] → 查看结果/输出 → 导出/分享
AI/自动化类:
注册/登录 → 配置[数据源/参数] → 触发[自动化任务] → 查看执行状态 → 查看结果/输出
通用兜底模板（项目类型不明确时使用）:
注册/登录 → 创建[用户的核心资源] → 查看[核心资源]列表 → 查看[核心资源]详情 → 编辑[核心资源]
```
Agent 将推断结果转化为**自然语言**展示给用户确认（不展示技术细节，只展示用户能看懂的操作流程）：
```markdown
根据你刚才描述的功能，我帮你梳理了一下。你的 MVP 做出来后，用户应该能走通下面这个流程：
**你的 MVP 核心流程**:
第1步: 打开首页，看到[核心内容]
第2步: 注册一个账号
第3步: 登录
第4步: [核心操作——根据项目类型自动填充]
第5步: [核心操作——根据项目类型自动填充]
第6步: 查看操作结果
我标记了 🔴 的步骤是 MVP 必须完整实现的——只要这几步能跑通，你的 MVP 就成功了。
其余功能（如通知、统计、设置等）可以先做简化版。
**你看这个流程对吗？**
A. "对，就按这个来" → 继续
B. "第 X 步应该改成 XXX" → 修改后重新确认
C. "我觉得还缺了 XXX 这一步" → 补充后重新确认
```
> ⚠️ **关键原则**：Agent 主动推断、用户被动确认。不要让用户自己想闭环——用户正是因为梳理不出来才用这个工具。Agent 根据项目类型+功能描述自动套模板，用户只需要说"对"或指出一处调整。
Agent 在用户确认后，将闭环转化为**可追踪的技术链路表**（这是后续所有 Phase 的检验标准）：
```markdown
## MVP 核心闭环技术链路
> 以下 ✅ 标记的项构成 MVP 不可裁剪的核心路径。Phase 5 编码时必须优先完成这些，
> Phase 5.5 验证时逐项检查是否通过。
| 步骤 | 用户操作 | 前端页面/组件 | API 调用 | 数据变更 | 闭环必须 |
|------|---------|-------------|---------|---------|---------|
| 1 | 打开首页 | HomePage | GET /api/v1/products | - | ✅ |
| 2 | 注册账号 | RegisterPage | POST /api/v1/auth/register | INSERT users | ✅ |
| 3 | 登录 | LoginPage | POST /api/v1/auth/login | - | ✅ |
| 4 | 浏览商品 | ProductList | GET /api/v1/products | - | ✅ |
| 5 | 查看详情 | ProductDetail | GET /api/v1/products/{id} | - | ✅ |
| 6 | 加入购物车 | CartDrawer | POST /api/v1/cart | INSERT cart_items | ✅ |
| 7 | 提交订单 | CheckoutPage | POST /api/v1/orders | INSERT orders + order_items | ✅ |
| 8 | 支付 | PaymentPage | POST /api/v1/payments | UPDATE orders.status | ✅ |
| 9 | 查看订单 | OrderList | GET /api/v1/orders | - | ✅ |
> 🔴 上表中的 ✅ 项是 **MVP 不可裁剪的核心路径**。Phase 5 采用核心路径优先策略，
> 确保这些 API 和页面首先完成并可互通，其余功能后续补充。
>
> **闭环节点总数: N | 涉及 API: M 个 | 涉及前端页面: K 个**
```
此链路图贯穿后续所有 Phase——设计时围绕它展开，评审时检查它的完整性，编码时优先实现它，验证时用它作为检查清单。
**Agent 在此时自动做以下推断**（展示给用户确认，不自行决定）：
- 根据项目类型匹配 AI Native 技术栈（见 Step 0.3 技术选型表）
- 根据功能模块推断数据实体（如"订单"→需要 orders 表、order_items 表）
- 根据项目规模推断 Agent 数（小型/中型/大型）
- 根据项目类型和功能规模推断部署方案（如内部后台→单机 Docker Compose，面向用户产品→预留 K8s 迁移路径，AI/Agent 系统→需 GPU/大内存规划）
🛑 用户确认模块清单和优先级后进入 Step 0.3。
### Step 0.3: 技术选型——AI Native 还是传统技术栈？（1 轮对话）
这是影响 MVP 代码质量和闭环成功率的关键决策。**不同的技术栈，AI 生成的代码质量天差地别。**
```markdown
现在来确认技术选型方式。这个选择直接影响生成的代码质量和前后端联调的成功率——
**1. 技术选型方式：**
A. 🚀 AI Native 全栈（强烈推荐） ← 默认
AI 帮你选最合适的技术栈——选的是 AI 训练数据最多、最擅长、
前后端集成模式最成熟的技术组合。生成的代码 bug 最少，闭环成功率最高。
B. 🎯 你指定技术栈
你告诉我要用什么（如"Java Spring Boot + Vue"），我来适配。
注意：非主流组合可能导致更多集成问题，需要更多修复轮次。
C. 🤷 无所谓，你帮我选
同 A，走 AI Native。
💡 如果你不确定选什么，直接选 A 就行。AI Native 不是为了追新技术，
而是选 AI 最熟悉、写出 bug 最少的组合。
```
**选 A/C（AI Native）时，Agent 根据项目类型自动确定技术栈**：
| 项目类型 | 前端 | 后端 | 数据库 | ORM | 认证 | UI 组件库 |
|---------|------|------|--------|-----|------|----------|
| Web 全栈（默认） | Next.js 14+ / TypeScript | Next.js API Routes / Server Actions | PostgreSQL 15 | Prisma | NextAuth / Auth.js | Tailwind CSS + shadcn/ui |
| 移动端 App | React Native / Expo / TypeScript | Supabase / Firebase | PostgreSQL (Supabase) | Supabase SDK | Supabase Auth | NativeWind / Tamagui |
| 管理后台 | React 18+ / TypeScript / Vite | Node.js + Express / FastAPI | PostgreSQL 15 | Prisma / SQLAlchemy | JWT + bcrypt | Ant Design 5 / shadcn/ui |
| API 服务（无前端） | - | FastAPI / Python 3.12+ | PostgreSQL 15 | SQLAlchemy 2.0 | JWT + OAuth2 | - |
| AI/自动化系统 | 可选：Streamlit / Next.js | FastAPI / Python 3.12+ | PostgreSQL 15 + Redis | SQLAlchemy 2.0 | JWT | Tailwind CSS |
**为什么 AI Native 能显著提高闭环成功率？**
| 维度 | AI Native 栈 | 传统栈 |
|------|------------|--------|
| AI 训练数据量 | 🔥 极大（GitHub 上最多的示例代码） | ⚠️ 相对少 |
| 前后端集成模式 | 标准化（Server Actions/tRPC/REST） | 需要手动约定 |
| 类型安全 | 端到端（TypeScript → Prisma → DB） | 断裂（后端 Java 类型 vs 前端 JS） |
| 项目结构 | 约定大于配置（AI 不需要猜目录结构） | 千人千面，AI 生成结构不一致 |
| 常见 bug 修复 | AI 见过大量同类 bug，修复快 | AI 训练数据少，修复可能引入新问题 |
| Phase 5.5 静态分析 | 统一技术栈 → 检测规则精准 | 混合栈 → 需要 N 套检测规则 |
**选 B（用户指定）时，Agent 的处理方式**：
```markdown
收到，你指定的技术栈是: [用户指定的前后端/数据库]
⚠️ 温馨提示：
- 这个组合如果不是 AI 训练数据中最主流的技术栈，生成的代码可能需要更多 Phase 5.5 修复轮次
- 如果前后端用了两个 AI 不太熟悉的框架组合，集成断裂的风险会更高
- 我会尽力适配，但最终闭环成功率取决于这个技术栈在 AI 训练数据中的覆盖度
确认使用这个技术栈吗？
```
🛑 用户确认技术选型后进入 Step 0.35（部署架构规划）。
> ⚠️ **关键原则**：AI Native 不是为了"用新技术"，而是**选择 AI 最擅长的工具链**——这意味着更少的 bug、更顺畅的前后端集成、更高的闭环一次性通过率。对于不确定技术选型的用户，默认为 AI Native 是最安全的选择。
### Step 0.35: 部署架构与网络拓扑规划（运维工程师介入，1-2 轮对话）
在 API 和数据模型方向确认后，运维工程师开始规划系统的基础设施层面：
```markdown
现在来规划部署架构。根据你的项目类型和规模，我来给出建议：
**部署环境**:
- 开发环境 (Dev): 本地 Docker Compose ← 默认
- 测试环境 (Staging): 单机/云服务器部署
- 生产环境 (Prod): 根据规模选择
**容器化方案**:
- Docker + Docker Compose (单机部署) ← MVP 默认
- Docker + K8s (中大型项目，需要自动扩缩)
- 直接部署 (极简原型，可跳过容器化)
**CI/CD 工具链**:
- GitHub Actions ← 默认（免费额度够用）
- GitLab CI（自建 GitLab 时推荐）
- Jenkins（需要更复杂的流水线控制）
- 手动部署（极简原型可跳过）
**反向代理与网络**:
- Nginx 反向代理 ← 默认
- Caddy（自动 HTTPS，更轻量）
- 是否需要 CDN？（面向用户的产品推荐开启）
- 是否需要 WAF？（处理敏感数据时推荐开启）
**监控与告警**:
- 日志: Docker logs + 文件日志 / ELK / Loki
- 监控: Prometheus + Grafana（中大型）/ 云监控（小型）
- 告警: 飞书/钉钉/企业微信 Webhook 通知
```
运维工程师基于用户选择，自动生成两个关键架构图：
**① 网络拓扑图**（Mermaid flowchart）— 展示公网入口 → 反向代理 → 应用服务 → 数据服务的完整链路、端口映射和协议：
````markdown
## 网络拓扑图
```mermaid
graph TD
subgraph 外部访问层
Client([用户: Browser/App])
end
subgraph 安全与加速层
CDN[CDN 加速]
WAF[WAF 防火墙
可选]
end
subgraph 反向代理层["Nginx :80/:443"]
Nginx[Nginx 反向代理
SSL Termination]
end
subgraph 应用层["Docker Network: app-net"]
BE[后端 API :8080
FastAPI / Express]
FE[前端静态资源
Nginx 容器 :80]
Worker[Celery Worker
异步任务]
end
subgraph 数据层["Docker Network: data-net"]
PG[(PostgreSQL :5432
Volume: pgdata)]
Redis[(Redis :6379
Volume: redisdata)]
end
subgraph 运维层
Prometheus[Prometheus :9090]
Grafana[Grafana :3001]
end
Client -->|HTTPS| CDN
CDN --> WAF
WAF -->|HTTPS :443| Nginx
Nginx -->|/api/*| BE
Nginx -->|/| FE
BE -->|TCP :5432| PG
BE -->|TCP :6379| Redis
BE -.->|任务分发| Worker
Worker -->|TCP| PG
Worker -->|TCP| Redis
Prometheus -.->|Pull Metrics| BE
Prometheus -.->|Pull Metrics| Nginx
Grafana -->|Query| Prometheus
```
````
**② 部署架构图**（Mermaid graph）— 展示容器编排、数据卷挂载、CI/CD 集成和健康检查关系：
````markdown
## 部署架构图
```mermaid
graph TB
subgraph CI/CD["CI/CD Pipeline (GitHub Actions)"]
GitPush[Git Push] --> LintTest[Lint + TypeCheck + Test]
LintTest --> Build[Build Docker Images]
Build --> Push[Push to Registry]
Push --> Deploy[SSH Deploy / Webhook]
end
subgraph DockerHost["Docker Host"]
subgraph PublicContainers["公共服务"]
NginxCont["nginx:alpine
Ports: 80, 443
Volume: ./nginx/nginx.conf"]
end
subgraph AppContainers["应用服务"]
BECont["backend:latest
Port: 8080
Health: /api/health"]
FECont["frontend:latest
Port: 80
Served via Nginx"]
WorkerCont["worker:latest
Health: heartbeat"]
end
subgraph DataContainers["数据服务"]
PGCont["postgres:15
Port: 5432
Volume: pgdata"]
RedisCont["redis:7-alpine
Port: 6379
Volume: redisdata"]
end
subgraph MonitorContainers["监控"]
PromCont["prom/prometheus
Port: 9090"]
GrafCont["grafana/grafana
Port: 3001"]
end
end
Deploy -->|"docker compose up -d"| DockerHost
NginxCont -->|proxy_pass| BECont
NginxCont -->|serve static| FECont
BECont -->|SQL| PGCont
BECont -->|Cache| RedisCont
WorkerCont -->|SQL| PGCont
WorkerCont -->|Cache| RedisCont
PromCont -.->|scrape| BECont
GrafCont -->|query| PromCont
```
````
运维工程师最后汇总部署决策，供 PRD 引用：
```markdown
**部署架构确认摘要**:
- 部署方案: [Docker Compose / K8s / VPS 直接部署]
- 容器数量: ~N 个 (Nginx + 后端 + 前端 + Worker + PostgreSQL + Redis + 监控)
- CI/CD 工具: [GitHub Actions / GitLab CI / 手动]
- 监控方案: [Prometheus+Grafana / 云监控 / 轻量日志]
- MVP 预估资源: 2Core CPU / 4GB RAM / 50GB Disk
```
🛑 用户确认部署架构后进入 Step 0.36（GitHub 开源项目调研）。
### Step 0.36: GitHub 开源项目调研——寻找可复用基座（1-2 轮对话）
在技术方案确认后、PRD 最终定稿前，调研 GitHub 上是否有可复用的开源框架、脚手架或库，作为 MVP 的开发基座。
**核心理念**: 避免重复造轮子。如果已有成熟的开源项目覆盖 MVP 大部分需求，基于它做二次开发远比从零开始高效——既能节省大量基础代码编写时间，又能降低前后端集成出错的概率。
**调研时机**: 此时已完成功能模块梳理（Step 0.2）、技术栈选型（Step 0.3）和部署架构规划（Step 0.35），有足够信息进行精准搜索。
**调研范围**（Agent 根据项目类型和技术栈自动生成搜索关键词）:
| 项目类型 | 搜索关键词示例 | 优先寻找 |
|---------|-------------|---------|
| 电商/交易类 | `nextjs ecommerce starter`、`react storefront template` | 含商品管理 + 购物车 + 支付的完整脚手架 |
| 内容/社区类 | `nextjs blog cms`、`forum community starter` | 含用户系统 + 内容发布 + 互动的模板 |
| 管理后台类 | `react admin dashboard`、`nextjs admin panel template` | 含 CRUD 生成 + 权限管理 + 数据面板的框架 |
| 工具/SaaS类 | `nextjs saas starter`、`saas boilerplate open source` | 含多租户 + 订阅计费 + 用户管理的模板 |
| AI/自动化类 | `ai agent framework open source`、`llm workflow engine` | 含 LLM 调用链 + 任务编排 + 结果输出的框架 |
| API 服务 | `fastapi boilerplate production`、`express api starter` | 含认证 + 权限 + 日志 + 测试的骨架 |
**评估维度**（Agent 自动评估，MECE 原则全覆盖）:
| 维度 | 权重 | 评估内容 | 数据来源 |
|------|:---:|---------|---------|
| 需求覆盖度 | 🔴 40% | 该项目的功能与 MVP 核心闭环的重合度（逐项对比技术链路表） | 项目 README + 文档 + Demo |
| 技术栈兼容度 | 🔴 25% | 是否与 Step 0.3 选定的技术栈一致或可低摩擦适配 | 项目 package.json / go.mod / requirements.txt |
| 社区活跃度 | 🟡 15% | Stars 数、最近 commit 时间（≤1月为佳）、Issue 响应速度 | GitHub API + Insights |
| 代码质量 | 🟡 10% | TypeScript 严格模式、测试覆盖率、文档完整度、CI 配置 | 源代码抽查 + README 质量 |
| 许可证合规 | 🔴 10% | MIT / Apache 2.0 / BSD 等宽松许可证优先；GPL/AGPL 需评估法律风险 | LICENSE 文件 |
**调研流程**（Agent 自动执行，用户只需看结论）:
```
1. Agent 根据项目类型 + 技术栈自动生成 3-5 组搜索关键词
2. Agent 在 GitHub 上按 Stars 排序搜索，筛选 Top 3-5 候选项目
3. 对每个候选项目执行五维度评估，生成候选对比表
4. 展示 Top 2 推荐给用户，附详细覆盖分析和推荐理由
5. 用户做出选择（或全部不采用）
```
**Agent 展示格式**（用户确认用）:
```markdown
## 🔍 GitHub 开源项目调研报告
根据你的项目类型（[电商/管理后台/SaaS/...]）和技术栈（[Next.js + PostgreSQL]），
我调研了 GitHub 上的高匹配度开源项目：
### 候选项目对比
| 项目 | Stars | 许可证 | 需求覆盖 | 技术栈兼容 | 社区活跃 | 综合分 |
|------|------:|--------|:------:|:--------:|:------:|:----:|
| **[项目A]** | 8.2k | MIT | ⭐⭐⭐⭐⭐ 85% | ⭐⭐⭐⭐⭐ 100% | ⭐⭐⭐⭐ | **92** |
| **[项目B]** | 15k | Apache 2.0 | ⭐⭐⭐⭐ 70% | ⭐⭐⭐⭐ 90% | ⭐⭐⭐⭐⭐ | **85** |
| **[项目C]** | 3.1k | MIT | ⭐⭐⭐ 50% | ⭐⭐⭐⭐⭐ 100% | ⭐⭐⭐ | **65** |
### 🥇 推荐: [项目A]（[GitHub URL]）
**项目简介**: [一句话描述项目是什么]
**核心功能覆盖分析**（对照 MVP 核心闭环技术链路表）:
- ✅ 用户注册/登录 — 项目A 自带 Auth 模块，与选定技术栈完全一致
- ✅ 商品管理 CRUD — 项目A 自带 Admin Dashboard，含完整 CRUD 示例
- ✅ 购物车 — 项目A 含购物车模块
- ⚠️ 支付集成 — 项目A 仅含 Stripe 示例，需扩展支付宝/微信支付
- ❌ 订单状态推送 — 项目A 不含 WebSocket，需自行添加
**采用预估**: 基于项目A 开发，预计可节省 **~60% 基础代码**，只需重点实现支付扩展和消息推送。
**不采用的风险**: 从零开始预计增加 3-5 天基础框架搭建，且前后端集成出错概率更高。
### 你的选择:
A. "用项目A 作为基础" → PRD 和后续设计围绕项目A 的架构进行
B. "用项目B 作为基础" → 同上
C. "我看中了其他项目: [URL]" → Agent 评估新项目后重新展示
D. "全部不采用，从零开始" → 按原计划执行
```
**如果用户选择基于某开源项目开发**:
Agent 需立即做以下调整，贯穿后续所有 Phase：
1. **在 PRD 中补充「基础项目（Base Project）」章节**（见 Step 0.4 PRD 骨架第 0 章）:
- 项目名称、GitHub URL、许可证、Stars 数
- 已覆盖的功能清单（✅ 直接复用 / ⚠️ 需修改 / ❌ 需新增）
- 技术架构说明（与基础项目的集成方式：Fork / Submodule / Template）
2. **调整 Phase 1 设计范围**:
- 数据库设计：在基础项目的数据模型上**扩展**，新增字段和表，而非全新设计
- UI 设计：在基础项目的组件库上**定制**主题和新增页面，而非全新设计系统
- 运维架构：**沿用**基础项目的容器化方案，按需调整 Dockerfile 和服务配置
3. **调整 Phase 5 编码策略**:
- 后端：Fork 基础项目 → 添加新模块 → 修改现有模块适配 PRD 需求
- 前端：Fork 基础项目 → 定制页面主题 → 新增闭环页面
- 每个编码 Agent 的 Prompt 中附加基础项目的**架构文档**和**关键代码路径**，确保 Agent 理解现有代码结构
- 编码产出必须是「在基座上的增量」，而非「覆盖基座的替换」
4. **Phase 5.5 闭环验证调整**:
- 静态分析范围包含基础项目的原有代码（避免引入新断裂）
- E2E 测试覆盖「基础项目原有功能 + 新增功能」的串联路径
**如果用户选择从零开始**:
Agent 按原流程继续，不做调整。但调研报告保留在项目目录中，作为「为什么不基于开源项目」的决策记录。
🛑 用户确认选择后进入 Step 0.4（PRD 自动生成）。
### Step 0.4: PRD 自动生成
Agent 基于以上所有对话，自动生成一份结构化 PRD，写入项目目录。
**PRD 骨架**（Agent 自动填充内容）:
```markdown
# [项目名称] — 产品需求文档 (PRD)
## 0. 基础项目（Base Project）—— 如果 Step 0.36 选定了开源基座
- 项目名称、GitHub URL、许可证、Stars
- Fork 策略与集成方式
- 已有功能覆盖清单: ✅ 直接复用 / ⚠️ 需修改 / ❌ 需新增
- 技术架构说明（基座项目的目录结构、数据模型、组件体系概述）
## 1. 产品概述
- 产品定位、目标用户、产品边界
## 2. 系统架构
- 技术栈选型、模块关系图、网络拓扑图、部署架构图
- 如果基于开源基座: 标注基座已有的架构与本次新增部分的边界
## 3. 功能模块
- M1~MN 每个模块的功能概述、API 接口定义、核心数据模型
- 如果基于开源基座: 标注每个模块是「复用基座」还是「新增/修改」
## 4. MVP 优先级
- P0/P1/P2/P3 分级表
- **MVP 核心闭环链路**（Phase 0.2 技术链路表，标注每个步骤的前端页面、API、数据变更）
- **闭环不可裁剪项**：标记 ✅ 的 API 和页面必须在 Phase 5 第一阶段完成
## 5. 非功能需求
- 性能/安全/可用性要求
## 附录
- 全局错误码、技术约束
```
**PRD 质量标准**:
- API 接口定义包含: 路径、方法、Request/Response JSON 示例
- 数据模型包含: 核心字段、关系、约束
- MVP 范围明确: P0 必须跑通的核心闭环
#### 从功能到 API/数据的推断方法（Agent 内部执行）
这是 Phase 0 最关键的步骤。Agent 按以下规则将用户的功能描述转化为具体的 API 和数据结构：
```
功能动词 → CRUD 映射:
"创建/发布/添加" → POST /api/v1/{resource}
"查看/列表/搜索" → GET /api/v1/{resource}[?page=&size=&keyword=]
"查看详情" → GET /api/v1/{resource}/{id}
"修改/编辑/更新" → PUT /api/v1/{resource}/{id}
"删除/下架/取消" → DELETE /api/v1/{resource}/{id}
"批量操作" → POST /api/v1/{resource}/batch/{action}
功能名词 → 数据实体推断:
"用户/账号/成员" → users 表 (id, username, password_hash, role, ...)
"商品/产品/物品" → products 表 (id, title, price, status, ...)
"订单/交易" → orders 表 (id, buyer_id, item_id, amount, status, ...)
"评论/评价" → reviews 表 (id, user_id, target_id, rating, content, ...)
"消息/通知" → notifications 表 (id, user_id, type, content, read, ...)
"文件/图片/附件" → files 表 / OSS 存储
"设置/配置" → settings 表 (key-value) 或 JSONB 配置字段
关系推断:
"用户有多个订单" → orders.user_id FK → users.id (1:N)
"订单包含多个商品" → order_items 中间表 (N:M)
"商品属于一个分类" → products.category_id FK → categories.id (N:1)
```
**PRD 推断示例**（展示给用户确认的格式）:
```
根据你的功能描述，我推断以下 API 和数据模型：
功能: "用户注册和登录"
→ POST /api/v1/auth/register (注册)
→ POST /api/v1/auth/login (登录)
→ users 表: id, username, password_hash, role, created_at
功能: "发布和管理商品"
→ POST /api/v1/products (发布)
→ GET /api/v1/products (列表)
→ PUT /api/v1/products/{id} (编辑)
→ DELETE /api/v1/products/{id} (下架)
→ products 表: id, user_id, title, description, price, status, images, created_at
以上推断是否正确？你可以说"没问题"确认，或指出需要调整的部分。
```
### Step 0.5: 用户 Review → 迭代
Agent 展示 PRD 文件路径和关键内容摘要，让用户确认：
```markdown
PRD 初版已生成: `[项目名]-PRD.md` (约 XXX 行)
**核心内容**:
- 功能模块: N 个 (M1~MN)
- P0 MVP 接口: ~XX 个
- 数据表: ~XX 张
- 技术栈: [后端] + [前端] + [数据库]
- 部署架构: [容器方案] + [CI/CD工具] + ~N个容器
- 🔍 开源基座: [项目名 (GitHub URL)] / 无（从零开始） ← Step 0.36 调研结果
**请确认**:
A. "没问题，继续进入设计阶段" → Phase 1
B. "需要修改 [具体哪些部分]" → 修改后重新确认
C. "有些功能我不确定，帮我细化" → 继续对话细化
```
🛑 **Phase 0 最终确认**: PRD 定稿，进入设计阶段。
---
## Phase 1-5: 设计与开发
> 每个子 Agent 启动时必须注入 `agents.md` 中对应角色的代码规范和工作流约束（详见下方「agents.md 注入机制」）。
> 以下为各 Phase 的职责矩阵和执行概要。
### Phase 1: 设计产出（3-4 Agent 并行）
**前置**: Phase 0 PRD 已定稿
| Agent | 产出 | 要求 |
|-------|------|------|
| 后端架构师 | `数据库设计-ER图与数据流.md` | 完整 ER 图(Mermaid) + 关键表 DDL + 数据流图 + 索引策略 + Redis 设计，3000+ 行 |
| UI/UX 设计师 | `UI-UX视觉设计定稿.md` | 设计系统 + 页面线框图 + 交互组件 + 动效规范，3000+ 行 |
| 运维工程师 | `运维架构设计-网络拓扑与部署架构.md` | 网络拓扑图(细化版) + 部署架构图(细化版) + CI/CD 流水线设计 + 容器化方案(Dockerfile模板) + 监控告警方案 + 环境配置矩阵(dev/staging/prod)，2000+ 行 |
| 主 Agent | `多Agent架构总览.md` | Agent 拆分全景 + 职责矩阵 + 通信协议 |
🛑 验证文件达标后确认。
### Phase 2: 跨角色评审（6 Agent 并行）
**前置**: Phase 1 产出 + Phase 0 PRD
6 个评审 Agent（PM/后端/前端/UI/QA/**运维**），每个 Agent 必须阅读**全部**文档，每个角色至少发现 **3 个 Blocker**。运维工程师重点评审：部署架构可行性、CI/CD 流水线合理性、容器化安全（端口暴露、密钥管理）、监控覆盖度、资源规格匹配度。
🛑 统计 Blocker/Major 数量，确认评审深度。
### Phase 3: 优化方案 + 协调（6+1 Agent 并行）
**前置**: 6 份评审报告
6 个优化 Agent + 1 个协调 Agent。协调 Agent 负责检测 4 类冲突（API/数据模型/范围/时间线）。运维优化 Agent 负责：优化容器镜像体积（多阶段构建、Alpine 基础镜像）、调整资源配置上限、提升 CI/CD 流水线并行度、补充健康检查与重启策略。
🛑 审查冲突清单和依赖图。
### Phase 4: 冲突修复（4 Agent 并行）
**前置**: 协调报告的 P0 冲突清单
4 个修复 Agent（API统一/**运维填补**/安全/时间线），解决所有 P0 冲突。运维填补 Agent 负责：
- 填补基础设施缺口：如异步任务缺少消息队列、文件上传缺少对象存储
- 修正 CI/CD 流水线：确保所有服务有 Dockerfile、docker-compose.yml 完整、触发条件正确
- 安全加固：确保密钥不进镜像、端口不必要暴露、数据卷正确挂载
- 健康检查补全：确保每个服务配置了健康检查端点
- 环境一致性：确保 dev/staging/prod 环境定义对齐
🛑 **锁定全部裁定，之后不允许改设计。**
### Phase 4.5: 设计文档终稿整合（1 Agent 串行整合）
**前置**: Phase 4 全部裁定 + Phase 1 原始设计文档 + Phase 2 评审报告 + Phase 3 优化方案
**目标**: 将 Phase 2-4 所有评审意见、优化方案和裁定 **合并回设计文档**，产出终稿版，消除「原始文档 + 散落修订」的碎片化问题。
**为什么需要这一步**: 不整合的后果是 Phase 5 编码 Agent 需要同时查阅 16+ 份文档——Phase 1 的 4 份设计稿 + Phase 2 的 6 份评审 + Phase 3 的 6 份优化 + Phase 4 的 4 份修复。任何一个遗漏都可能导致编码偏离已批准的方案。
**整合 Agent（主 Agent 担任）**:
| 输入 | 来源 | 用途 |
|------|------|------|
| `[项目名]-PRD.md` | Phase 0 | 终稿修订 |
| `数据库设计-ER图与数据流.md` | Phase 1 | 终稿修订 |
| `UI-UX视觉设计定稿.md` | Phase 1 | 终稿修订 |
| `运维架构设计-网络拓扑与部署架构.md` | Phase 1 | 终稿修订 |
| `多Agent架构总览.md` | Phase 1 | 终稿修订 |
| 6 份评审报告 | Phase 2 | 提取 Blocker 和 Major 建议 |
| 6 份优化方案 | Phase 3 | 提取具体修改措施 |
| 协调报告（冲突检测） | Phase 3 | 确保跨文档无矛盾 |
| 4 份修复裁定 | Phase 4 | 法定修改，必须全部纳入 |
**整合规则**:
1. **逐文档修订**：对每份设计文档，从上到下逐节检查，将 Phase 2-4 中涉及该节的修改合并进去
2. **溯源标注**：每个修改处追加 `` 注释，确保可追溯
3. **冲突优先**：同一处有多个修改建议时，以 Phase 4 裁定为准
4. **一致性校验**：修订完成后，交叉检查终稿文档之间是否存在矛盾：
- PRD 中的 API 定义 ↔ DB 设计中的表结构
- DB 设计中的实体关系 ↔ 架构总览中的数据流
- UI 设计中的交互组件 ↔ PRD 中的功能描述
- 运维架构中的容器配置 ↔ DB/后端技术选型
5. **未被采纳的修订**：如果有 Phase 2-3 提出的建议但在 Phase 3-4 被拒绝/替代，在整合报告中列出「未采纳清单」并说明原因
**产出**:
| 文件 | 说明 |
|------|------|
| `[项目名]-PRD-FINAL.md` | PRD 终稿，API 定义 + 数据模型 + 部署摘要全部是最新裁定版本 |
| `数据库设计-ER图与数据流-FINAL.md` | DB 设计终稿，ER 图 + DDL + 索引 + Redis 全部按裁定更新 |
| `UI-UX视觉设计定稿-FINAL.md` | UI 设计终稿，组件 + 交互 + Design Token 全部按裁定更新 |
| `运维架构设计-FINAL.md` | 运维终稿，网络拓扑 + 部署架构 + CI/CD + 容器方案全部按裁定更新 |
| `多Agent架构总览-FINAL.md` | 架构总览终稿，Agent 拆分 + 通信协议全部按裁定更新 |
| `修订整合报告.md` | 整合日志：每个修订的来源追溯 + 未采纳清单 + 跨文档一致性检查结果 |
🛑 **Phase 4.5 确认**: 展示整合报告——多少条修订已合并、多少条未采纳及原因、一致性检查结果 → 用户确认后，**终稿文档成为 Phase 5 的唯一输入**。
### Phase 5: 核心路径优先编码（两阶段）
**前置**: Phase 4.5 终稿设计文档（**唯一真相来源**，编码 Agent 禁止查阅 Phase 1-4 原始文档）
**🔴 核心原则**：先确保业务闭环能跑通，再补充外围功能。不追求文件数量，追求闭环质量。
#### Phase 5.1: 核心闭环编码（5 Agent 并行，聚焦核心路径）
从 Phase 0.2 的「MVP 核心闭环技术链路表」中提取标记 ✅ 的 API 和页面，**只编码这些**：
**每个编码 Agent 的 Prompt 必须包含以下闭环约束**：
```markdown
## 🔴 业务闭环约束（不可违反）
你正在编码的是 MVP 核心闭环路径上的代码。以下是必须确保的集成契约：
### 你的前端页面必须调用的 API（前端 Agent）:
| 你的页面 | 必须调用的 API | 请求方式 | 请求体/参数 |
|---------|--------------|---------|------------|
| [页面名] | [API 路径] | [方法] | [参数说明] |
### 你的 API 必须访问的数据库表（后端 Agent）:
| 你的 API | 必须读写的表 | 操作类型 | 关键字段 |
|---------|------------|---------|---------|
| [API 路径] | [表名] | [CRUD] | [字段列表] |
### 集成检查清单（编码完成后自查）:
- [ ] 前端发送的请求体字段名与后端 API 定义的字段名一致（含大小写）
- [ ] 前端对 API 响应的字段访问路径与后端实际返回结构一致
- [ ] API 返回的 HTTP 状态码与前端错误处理逻辑匹配
- [ ] 认证 Token 在前端存储方式与后端验证方式一致（Header/Body/Cookie）
- [ ] 前端路由参数（如 /products/:id）与后端路径参数（/api/v1/products/{id}）对应
```
**5 个编码 Agent 分工**：
| Agent | 职责（仅核心闭环） | 产出要求 |
|-------|------------------|---------|
| 后端基础 | 项目骨架 + 数据库 Migration + 核心闭环数据表 + 认证/中间件 | 可运行的 API 服务骨架 |
| 后端 API | **仅闭环链路表中的 ✅ API** + 全局异常处理 + 请求验证 | 每个 API 有完整的 Controller→Service→Repository |
| 前端基础 | 项目骨架 + 路由 + 状态管理 + API 客户端（含 Token 管理） + 通用组件 | 可运行的前端骨架 |
| 前端页面 | **仅闭环链路表中的 ✅ 页面** + 页面间导航 | 每个页面完整可交互 |
| 运维 | Dockerfile + docker-compose.yml + nginx 配置 + 部署脚本 | 一键启动全栈 |
**Phase 5.1 完成后立即验证**（主 Agent 执行）：
```bash
# 1. 启动全栈
docker compose up -d
# 2. 等待健康检查通过
docker compose ps # 确认所有容器 healthy
# 3. 验证前后端联通
curl http://localhost/api/v1/health # 后端可访问
curl http://localhost/ # 前端可访问
```
→ 只有容器全部 healthy 且前后端可访问，才进入 Phase 5.2。
#### Phase 5.2: 外围功能编码（5 Agent 并行）
Phase 5.1 验证通过后，编码闭环之外的功能（P1/P2 优先级模块）：
| Agent | 职责（外围功能） |
|-------|----------------|
| 后端基础 | 非核心数据表 Migration + 定时任务 + 消息队列 |
| 后端 API | 非闭环 API（管理后台/统计/通知等） |
| 前端基础 | 管理后台路由 + 高级组件 |
| 前端页面 | 非闭环页面（仪表盘/设置/通知等） |
| 运维 | CI/CD 流水线 + 监控 + 日志收集 + DEPLOY.md |
🛑 **Phase 5 最终验证**：
| 检查项 | 标准 | 验证方式 |
|--------|------|---------|
| 闭环 API 全部实现 | 技术链路表中每个 ✅ API 存在且可调用 | curl 逐个测试 |
| 闭环页面全部实现 | 技术链路表中每个 ✅ 页面存在且可渲染 | 浏览器访问 |
| 前后端联通 | 前端页面能成功调用后端 API（含认证流程） | 手动走通 1 个完整闭环 |
| 数据持久化 | API 写入的数据重启容器后仍存在 | docker compose down && up -d 后验证 |
| 代码质量 | 各角色代码符合 `agents.md` 对应规范 | 抽查命名/分层/类型/测试 |
| 可部署 | `docker compose up -d` 一键启动 | 全新环境执行 |
| 项目约束 | `AGENTS.md` 已输出到项目根目录 | 文件存在性检查 |
| 外围功能 | P1/P2 功能按裁量级别达标 | 按模块清单核对 |
→ 全部通过后进入 Phase 5.5（业务闭环验证）。
---
### Phase 5.5: 业务闭环自动检测与验证（AI 驱动——解决"无法闭环"问题的关键）
**前置**: Phase 5 全部通过（核心闭环 + 外围功能均已编码完成，容器可启动）
**核心思路**: 闭环断裂点不需要用户来发现——AI 通过**静态代码分析 + 动态运行验证**自动检测，自动修复。
---
#### Step 5.5.0: 静态代码分析——自动检测集成断裂点（主 Agent 执行，无需用户参与）
这是整个闭环保障机制的核心。主 Agent 在**不启动容器的情况下**，直接分析所有已生成的代码文件，自动检测以下四类断裂点：
**检测 1: 前端调用了不存在的 API**
```
扫描范围: 所有前端代码文件（.tsx/.vue/.js/.jsx）
提取方法: 搜索 fetch(、axios.、api.、request( 等 HTTP 调用模式
提取目标: URL 路径 + HTTP 方法 + 请求体字段
对比: 后端代码中实际定义的路由（搜索 @Post、@Get、app.post、router.get 等）
→ 前端调用了 /api/v1/orders/export 但后端没有任何文件定义此路由
→ 断裂点: orders/export API 缺失，前端"导出订单"按钮点击后必报 404
```
**检测 2: 后端 API 没有前端调用方（孤儿 API）**
```
扫描范围: 所有后端路由定义
对比: 前端代码中的 API 调用列表
→ 后端定义了 DELETE /api/v1/admin/users/{id} 但前端没有任何代码调用此接口
→ 孤儿 API: 代码存在但无法通过正常用户操作触发，可能是遗漏的前端功能
```
**检测 3: 前端表单/按钮没有连接任何 API（死交互）**
```
扫描范围: 前端代码中的