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 直接扫描代码就能找出所有断裂点：

闭环节杀反模式（必须避免）

闭环保障机制（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 先用自己的话复述理解，然后提出第一组关键问题：

我理解你想做一个 **[一句话概括]**。在开始细化之前，先确认几个方向性问题：

**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 轮对话）

根据项目类型，引导用户列出功能模块：

好的。现在我们来梳理核心功能。请按以下格式告诉我系统需要哪些功能模块：

**主线功能（用户必须完成的闭环）**:
例: 用户登录 → 浏览商品 → 下单 → 支付 → 发货

**辅助功能（锦上添花）**:
例: 数据统计、消息通知、权限管理

---

💡 如果暂时不确定，可以先告诉我最核心的 3-5 个功能，
   我会帮你补充常见的辅助模块，你再来确认。

Agent 根据用户回答，自动将功能归类为 M1~MN 模块，并判断哪些是 P0（MVP必须）、哪些是 P1/P2。

🔴 MVP 核心闭环自动推断（AI 驱动，用户只确认）:

用户已经描述了功能模块，Agent 此时自动推断 MVP 的核心闭环——不需要用户自己梳理。

推断方法（Agent 内部执行，对用户透明）：

根据项目类型，套用对应的闭环模板：

电商/交易类:
  注册/登录 → 浏览[核心资源]列表 → 查看[核心资源]详情 → 加入购物车/下单 → 支付 → 查看订单/状态

内容/社区类:
  注册/登录 → 浏览[内容]列表 → 查看[内容]详情 → 发布[内容] → 互动(评论/点赞) → 查看个人主页

管理后台类:
  登录 → 查看[资源]列表 → 搜索/筛选[资源] → 新增[资源] → 编辑[资源] → 查看统计Dashboard

工具/SaaS类:
  注册/登录 → 创建[项目/任务] → 配置/编辑[核心功能] → 查看结果/输出 → 导出/分享

AI/自动化类:
  注册/登录 → 配置[数据源/参数] → 触发[自动化任务] → 查看执行状态 → 查看结果/输出

通用兜底模板（项目类型不明确时使用）:
  注册/登录 → 创建[用户的核心资源] → 查看[核心资源]列表 → 查看[核心资源]详情 → 编辑[核心资源]

Agent 将推断结果转化为自然语言展示给用户确认（不展示技术细节，只展示用户能看懂的操作流程）：

根据你刚才描述的功能，我帮你梳理了一下。你的 MVP 做出来后，用户应该能走通下面这个流程：

**你的 MVP 核心流程**:
  第1步: 打开首页，看到[核心内容]
  第2步: 注册一个账号
  第3步: 登录
  第4步: [核心操作——根据项目类型自动填充]
  第5步: [核心操作——根据项目类型自动填充]
  第6步: 查看操作结果

我标记了 🔴 的步骤是 MVP 必须完整实现的——只要这几步能跑通，你的 MVP 就成功了。
其余功能（如通知、统计、设置等）可以先做简化版。

**你看这个流程对吗？**
  A. "对，就按这个来"  → 继续
  B. "第 X 步应该改成 XXX"  → 修改后重新确认
  C. "我觉得还缺了 XXX 这一步"  → 补充后重新确认

⚠️ 关键原则：Agent 主动推断、用户被动确认。不要让用户自己想闭环——用户正是因为梳理不出来才用这个工具。Agent 根据项目类型+功能描述自动套模板，用户只需要说"对"或指出一处调整。

Agent 在用户确认后，将闭环转化为可追踪的技术链路表（这是后续所有 Phase 的检验标准）：

## 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 生成的代码质量天差地别。

现在来确认技术选型方式。这个选择直接影响生成的代码质量和前后端联调的成功率——

**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 根据项目类型自动确定技术栈：

为什么 AI Native 能显著提高闭环成功率？

选 B（用户指定）时，Agent 的处理方式：

收到，你指定的技术栈是: [用户指定的前后端/数据库]

⚠️ 温馨提示：
- 这个组合如果不是 AI 训练数据中最主流的技术栈，生成的代码可能需要更多 Phase 5.5 修复轮次
- 如果前后端用了两个 AI 不太熟悉的框架组合，集成断裂的风险会更高
- 我会尽力适配，但最终闭环成功率取决于这个技术栈在 AI 训练数据中的覆盖度

确认使用这个技术栈吗？

🛑 用户确认技术选型后进入 Step 0.35（部署架构规划）。

⚠️ 关键原则：AI Native 不是为了"用新技术"，而是选择 AI 最擅长的工具链——这意味着更少的 bug、更顺畅的前后端集成、更高的闭环一次性通过率。对于不确定技术选型的用户，默认为 AI Native 是最安全的选择。

Step 0.35: 部署架构与网络拓扑规划（运维工程师介入，1-2 轮对话）

在 API 和数据模型方向确认后，运维工程师开始规划系统的基础设施层面：

现在来规划部署架构。根据你的项目类型和规模，我来给出建议：

**部署环境**:
- 开发环境 (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）— 展示公网入口 → 反向代理 → 应用服务 → 数据服务的完整链路、端口映射和协议：

## 网络拓扑图

```mermaid
graph TD
    subgraph 外部访问层
        Client([用户: Browser/App])
    end

    subgraph 安全与加速层
        CDN[CDN 加速]
        WAF[WAF 防火墙<br/>可选]
    end

    subgraph 反向代理层["Nginx :80/:443"]
        Nginx[Nginx 反向代理<br/>SSL Termination]
    end

    subgraph 应用层["Docker Network: app-net"]
        BE[后端 API :8080<br/>FastAPI / Express]
        FE[前端静态资源<br/>Nginx 容器 :80]
        Worker[Celery Worker<br/>异步任务]
    end

    subgraph 数据层["Docker Network: data-net"]
        PG[(PostgreSQL :5432<br/>Volume: pgdata)]
        Redis[(Redis :6379<br/>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 集成和健康检查关系：

## 部署架构图

```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<br/>Ports: 80, 443<br/>Volume: ./nginx/nginx.conf"]
        end

        subgraph AppContainers["应用服务"]
            BECont["backend:latest<br/>Port: 8080<br/>Health: /api/health"]
            FECont["frontend:latest<br/>Port: 80<br/>Served via Nginx"]
            WorkerCont["worker:latest<br/>Health: heartbeat"]
        end

        subgraph DataContainers["数据服务"]
            PGCont["postgres:15<br/>Port: 5432<br/>Volume: pgdata"]
            RedisCont["redis:7-alpine<br/>Port: 6379<br/>Volume: redisdata"]
        end

        subgraph MonitorContainers["监控"]
            PromCont["prom/prometheus<br/>Port: 9090"]
            GrafCont["grafana/grafana<br/>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 引用：

**部署架构确认摘要**:
- 部署方案: [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 根据项目类型和技术栈自动生成搜索关键词）:

评估维度（Agent 自动评估，MECE 原则全覆盖）:

调研流程（Agent 自动执行，用户只需看结论）:

1. Agent 根据项目类型 + 技术栈自动生成 3-5 组搜索关键词
2. Agent 在 GitHub 上按 Stars 排序搜索，筛选 Top 3-5 候选项目
3. 对每个候选项目执行五维度评估，生成候选对比表
4. 展示 Top 2 推荐给用户，附详细覆盖分析和推荐理由
5. 用户做出选择（或全部不采用）

Agent 展示格式（用户确认用）:

## 🔍 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 自动填充内容）:

# [项目名称] — 产品需求文档 (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 文件路径和关键内容摘要，让用户确认：

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 已定稿

🛑 验证文件达标后确认。

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 担任）:

整合规则:

1. 逐文档修订：对每份设计文档，从上到下逐节检查，将 Phase 2-4 中涉及该节的修改合并进去
2. 溯源标注：每个修改处追加 <!-- 修订来源: Phase X, [角色], [原因] --> 注释，确保可追溯
3. 冲突优先：同一处有多个修改建议时，以 Phase 4 裁定为准
4. 一致性校验：修订完成后，交叉检查终稿文档之间是否存在矛盾：
   • PRD 中的 API 定义 ↔ DB 设计中的表结构
   • DB 设计中的实体关系 ↔ 架构总览中的数据流
   • UI 设计中的交互组件 ↔ PRD 中的功能描述
   • 运维架构中的容器配置 ↔ DB/后端技术选型
5. 未被采纳的修订：如果有 Phase 2-3 提出的建议但在 Phase 3-4 被拒绝/替代，在整合报告中列出「未采纳清单」并说明原因

产出:

🛑 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 必须包含以下闭环约束：

## 🔴 业务闭环约束（不可违反）

你正在编码的是 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 分工：

Phase 5.1 完成后立即验证（主 Agent 执行）：

# 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 优先级模块）：

🛑 Phase 5 最终验证：

→ 全部通过后进入 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（死交互）

扫描范围: 前端代码中的 <form>、onSubmit、handleSubmit、onClick 事件处理函数
检查: 事件处理函数内部是否有 API 调用

→ RegisterPage 的 handleSubmit 函数只有 console.log('submit')，没有实际 API 调用
  → 死交互: 用户填完注册表单点击提交，什么都不会发生

检测 4: API 没有连接数据库（无持久化）

扫描范围: 后端 API 的 Service/Controller 代码
检查: 是否包含数据库操作（Repository/DAO/SQL 查询/mongoose/prisma 调用）

→ POST /api/v1/products 的 Service 层只做了参数验证，return { success: true }
  → 无持久化: API 返回成功但数据从未写入数据库，刷新后数据消失

检测 5: 核心闭环页面间的导航断裂

扫描范围: 前端路由配置 + 页面内的导航代码（<Link>、router.push、navigate）
检查: 闭环链路表中相邻步骤的页面之间是否有导航路径

→ 用户从 ProductList 点击商品后，应该导航到 ProductDetail 页面
  → 但路由配置中 /products/:id 指向的是 ProductEdit 组件，而非 ProductDetail
  → 导航断裂: 用户点进商品详情却看到编辑表单

检测执行方式（主 Agent 自动完成）：

主 Agent 在 Phase 5 代码全部生成后，启动一个代码分析 Agent：

你是一个代码集成分析专家。请分析以下已生成的前后端代码，找出所有集成断裂点。

## 分析方法
1. 读取所有前端代码文件，提取所有 API 调用（URL + Method + 请求体字段）
2. 读取所有后端代码文件，提取所有路由定义（URL + Method）
3. 读取所有前端代码文件，提取所有表单提交/按钮点击处理函数
4. 读取所有后端 Service 层代码，检查是否有数据库操作
5. 读取前端路由配置文件，提取所有路由定义
6. 交叉对比，输出断裂点清单

## 核心闭环技术链路表（验证基准）
[粘贴 Phase 0.2 技术链路表]

## 输出格式
| 断裂类型 | 位置 | 问题描述 | 严重程度 |
|---------|------|---------|---------|
| API缺失 | frontend/src/pages/Orders.tsx:45 → POST /api/v1/orders/export | 前端调用导出API但后端未实现 | 🔴 Blocker |
| 死交互 | frontend/src/pages/Register.tsx:32 handleSubmit | 注册表单提交函数无API调用 | 🔴 Blocker |
| 孤儿API | backend/src/routes/admin.ts:12 DELETE /admin/users/:id | 后端定义了删除用户API但前端无调用 | 🟡 Warning |
| 无持久化 | backend/src/services/productService.ts:20 createProduct | POST产品接口未写入数据库 | 🔴 Blocker |
| 导航断裂 | ProductList → ProductDetail | 路由/product/:id指向错误组件 | 🔴 Blocker |

输出: reports/static-gap-analysis.md（静态集成断裂点分析报告）

Step 5.5.1: 断裂点自动修复（主 Agent 驱动，无需用户参与）

根据 Step 5.5.0 的输出，主 Agent 对每个 🔴 Blocker 级别的断裂点启动修复：

⚠️ 修复只补全缺失的代码，不修改 Phase 4 锁定的设计。如果断裂是因为设计遗漏，标记为"设计缺口"并报告用户。

修复后重新执行 Step 5.5.0 静态分析，确认所有 🔴 Blocker 已清除。

Step 5.5.2: 闭环 E2E 测试脚本生成（1 Agent）

主 Agent 根据 Phase 0.2 的「MVP 核心闭环技术链路表」，生成一份 E2E 测试脚本：

你是一个 E2E 测试工程师。根据以下核心闭环技术链路表，生成一份端到端测试脚本。

要求：
1. 每个闭环节点对应一个测试用例
2. 测试用例必须包含：前置条件 → 操作步骤 → API 调用（或 UI 操作）→ 预期结果
3. 测试用例按闭环顺序编排，上一步的输出作为下一步的输入（如登录后的 Token 用于后续请求）
4. 使用 curl + shell 脚本（后端 API 测试）+ 或 Playwright/Cypress 脚本（前端 UI 测试）
5. 包含错误场景：如 Token 过期、参数校验失败、资源不存在等

技术链路表:
[粘贴 Phase 0.2 的技术链路表]

Agent 产出 tests/e2e/core-loop.spec.sh（后端 API 链路测试）和 tests/e2e/core-loop.spec.ts（前端 UI 链路测试）。

Step 5.5.3: 动态运行验证（主 Agent 自动执行）

# 1. 确保全栈已启动
docker compose up -d --wait

# 2. 执行后端 API 链路测试
bash tests/e2e/core-loop.spec.sh
# → 输出: ✅ Step 1 PASS | ✅ Step 2 PASS | ... | ❌ Step 5 FAIL: 订单创建返回 500

# 3. 执行前端 UI 链路测试（可选，视项目类型）
npx playwright test tests/e2e/core-loop.spec.ts

Step 5.5.4: 失败处理——闭环修复循环

如果任一步骤失败，主 Agent 执行以下修复循环（最多 3 轮）：

测试失败 → 分析失败原因 → 定位责任模块
  → 启动修复 Agent（仅修复该模块，不改设计）
  → 重新执行测试
  → 通过 → 继续下一步
  → 失败 → 再修复（最多 3 轮，超过则标记为已知限制）

Step 5.5.5: 闭环验证报告

闭环通过标准：

• ✅ 静态分析: 无 🔴 Blocker 级别断裂点
• ✅ 动态测试: 全部核心闭环节点 PASS
• ✅ 数据在各步骤间正确传递（上一步的输出是下一步的输入）

🛑 Phase 5.5 最终确认: 展示闭环验证报告（含静态分析发现的断裂点及修复记录）→ 用户确认闭环可用 → 正式交付。

⚠️ 如果闭环验证未通过（有 🔴 Blocker 或动态测试 FAIL），MVP 不得交付。 闭环检测全程由 AI 自动完成——分析代码、发现断裂、自动修复、运行测试。用户不需要懂技术，只需要看最后的 ✅/❌ 报告。

跨角色协作机制

信息注入（每个 Agent Prompt 必须包含）

## ⚠️ 跨角色协作须知
你必须了解以下其他角色的核心发现，确保方案不冲突：
### PM 关注: [...]   ### 后端变更: [...]   ### 前端需求: [...]
### UI 修改: [...]   ### QA 要求: [...]   ### 运维约束: [...]

决策传播链

Phase 2 评审 → Phase 3 优化方案 → Phase 4 裁定 → Phase 4.5 终稿整合（合并回设计文档）
                                                         ↓
                                          Phase 5 编码 Agent 只读终稿文档
                                          → 编码阶段不改设计，也不查阅原始评审/优化报告

agents.md 注入机制（强制性）

每个子 Agent 启动时，必须在其 Prompt 中注入 agents.md 对应章节。注入采用「通用 + 角色」两层模式：

① 注入映射表:

② 注入时机与深度:

③ 注入模板（每个子 Agent Prompt 的开头）:

## ⚠️ 项目约束（来源: agents.md）

以下规范为项目级硬性约束，你产出的所有代码/文档/设计必须严格遵守。违反将导致产出被拒绝。

### 你的角色: [角色名]
[从 agents.md 复制对应角色完整章节]

### 全局约束（所有角色通用）
[从 agents.md 复制 §1 全局上下文 + §3 跨角色协作协议]

④ 交付输出: Phase 5 完成后，agents.md 原文输出到项目根目录 AGENTS.md，作为项目后续迭代的约束文件。该文件与编码产物一起提交到项目仓库。

agents.md 注入效果验证

以"后端登录接口"为例，对比同一编码 Agent 在有无 agents.md 约束下的产出差异：

此对比验证了 agents.md 注入对编码产出的系统性提升——从「能跑就行」到「工业化可交付」的质变，是「实测表现」维度的核心判据。

边界条件处理

关联文档使用指南:

• SKILL.md（本文件）: 执行时读这个——包含完整 Phase 0 对话流程 + Phase 1-5.5 概要 + 业务闭环保障机制 + agents.md 注入机制
• agents.md: 子 Agent 的行为约束——含 PM/UI/FE/BE/DevOps/QA 六角色代码规范、质量门禁、CI/CD 铁律、跨角色协作协议
• 何时查: Phase 0 不需要 agents.md；Phase 1-5.5 启动每个子 Agent 前，从 agents.md 复制对应角色规范注入 Prompt；Phase 5 交付时将 agents.md 输出到项目根目录

主 Agent 执行 Checklist

主 Agent（编排者）在每个 Phase 按以下 Checklist 逐项执行，全部 ✅ 后才能进入下一 Phase：

Phase 0: 交互式 PRD 生成

Step 0.1 — 理解项目方向:

• 用户说出想法 → Agent 用自己的话复述理解
• 提出方向性 3 问（产品类型 / 目标用户 / 当前阶段），每问给默认选项
• 🛑 用户确认方向性回答后进入 Step 0.2

Step 0.2 — 功能模块梳理 + 核心闭环定义:

• 引导用户列出主线功能和辅助功能
• Agent 自动归类为 M1~MN 模块，标注 P0/P1/P2 优先级
• Agent 根据项目类型自动推断 MVP 核心闭环（套模板，用户只确认）
• 用户确认闭环后，Agent 生成「MVP 核心闭环技术链路表」（含 ✅ 标记）
• Agent 自动推断数据实体、Agent 数量、部署方案
• 🛑 用户确认模块清单和优先级后进入 Step 0.3

Step 0.3 — 技术选型:

• 询问技术选型方式：AI Native（默认推荐）/ 用户指定 / 无所谓
• 若选 A/C：根据项目类型自动匹配 AI Native 技术栈表
• 若选 B：确认用户指定的技术栈，告知非主流栈的风险
• 🛑 用户确认技术选型后进入 Step 0.35

Step 0.35 — 部署架构规划（运维工程师介入）:

• 询问部署环境（Docker Compose 默认）、容器化方案、CI/CD 工具、反向代理、监控
• 生成网络拓扑图（Mermaid flowchart）
• 生成部署架构图（Mermaid graph）
• 汇总部署架构确认摘要
• 🛑 用户确认部署架构后进入 Step 0.36

Step 0.36 — GitHub 开源项目调研:

• 根据项目类型 + 技术栈生成 3-5 组 GitHub 搜索关键词
• 搜索并筛选 Top 3-5 候选开源项目
• 按五维度评估（需求覆盖 40% / 技术栈兼容 25% / 社区活跃 15% / 代码质量 10% / 许可证 10%）打分
• 生成候选对比表 + Top 2 详细推荐（含核心功能覆盖分析）
• 展示调研报告，让用户选择：A/B/C/D
• 若用户选定基座项目 → 立即调整 PRD 结构（新增第 0 章）、Phase 1 设计范围、Phase 5 编码策略
• 若用户从零开始 → 保留调研报告作为决策记录
• 🛑 用户确认选择后进入 Step 0.4

Step 0.4 — PRD 自动生成:

• 汇总 Step 0.1-0.36 全部对话信息
• 自动填充 PRD 骨架（含第 0 章基础项目信息，如适用）
• 生成完整 API 定义（路径 + 方法 + Request/Response JSON 示例）
• 生成完整数据模型（字段 + 关系 + 约束）
• 🛑 展示 PRD 文件路径和关键内容摘要，进入 Step 0.5

Step 0.5 — 用户 Review → 迭代:

• 展示 PRD 核心内容摘要（模块数 / P0 API 数 / 数据表数 / 技术栈 / 部署架构）
• 用户选择：确认 / 修改 / 继续细化
• 若修改或细化 → 回到对应 Step 修改后重新确认
• 🛑 PRD 最终定稿，进入 Phase 1

Phase 1: 设计产出

• 读取 Phase 0 定稿的 PRD 全文
• 确认裁量级别（极简/小型/中型/大型），按级别确定 Agent 数量
• 准备各子 Agent Prompt：PRD 摘要 + agents.md 对应角色 §（详见注入机制 ② 轻量级注入）
• 并行启动子 Agent（后端架构师 + UI/UX + 运维 + 架构总览）
• 等待全部完成，验证每个产出文件 ≥ 行数要求
• 🛑 展示产出文件摘要，等用户确认

Phase 2: 跨角色评审

• 收集 Phase 1 全部产出 + Phase 0 PRD
• 准备评审 Agent Prompt：全部文档 + agents.md 对应角色 §（中等注入）+ "至少发现 3 个 Blocker"
• 并行启动 6 个评审 Agent（PM/后端/前端/UI/QA/运维）
• 收集评审报告，统计每个角色的 Blocker 数
• 若某角色 < 3 Blocker → 要求重审
• 🛑 展示 Blocker 统计和关键问题摘要，等用户确认

Phase 3: 优化方案 + 协调

• 收集 6 份评审报告
• 准备优化 Agent Prompt：对应评审报告 + agents.md 角色规范 + 跨角色协作协议（中等注入）
• 并行启动 6 优化 Agent + 1 协调 Agent
• 协调 Agent 输出 4 类冲突检测（API/数据模型/范围/时间线）
• 🛑 展示 P0 冲突清单和优化方向，等用户确认

Phase 4: 冲突修复

• 收集协调报告的 P0 冲突清单
• 准备修复 Agent Prompt：冲突上下文 + agents.md 完整角色规范（完整注入）
• 并行启动 4 修复 Agent（API统一/运维填补/安全/时间线）
• 验证所有 P0 冲突已解决
• 🛑 展示裁定结果 → 用户确认后锁定，之后任何 Agent 不得修改设计

Phase 4.5: 设计文档终稿整合

• 收集全部输入：Phase 0 PRD + Phase 1 四份设计稿 + Phase 2 六份评审 + Phase 3 六份优化 + 协调报告 + Phase 4 四份裁定
• 主 Agent 逐文档修订：对每份设计文档逐节合并 Phase 2-4 的修改，每个改动标注溯源注释
• 交叉一致性校验：

• 生成「未采纳清单」：列出 Phase 2-3 提出但被 Phase 3-4 拒绝的建议及拒绝原因
• 产出 5 份 FINAL 设计文档 + 1 份整合报告
• 🛑 展示整合报告（合并数 + 未采纳清单 + 一致性结果）→ 用户确认后终稿锁定，成为 Phase 5 唯一输入

Phase 5: 核心路径优先编码

• 收集 Phase 4.5 全部终稿设计文档（不使用 Phase 1 原始版本）
• 从 Phase 0.2 的「MVP 核心闭环技术链路表」中提取标记 ✅ 的全部 API 和页面清单
• 准备编码 Agent Prompt：设计文档 + 闭环约束块（前后端集成契约）+ agents.md 完整角色规范
• Phase 5.1（核心闭环编码）:
  • 并行启动 5 编码 Agent（后端基础/后端API/前端基础/前端页面/运维），Prompt 中只包含闭环链路表的 ✅ 项
  • 等待全部完成
  • 启动全栈：docker compose up -d
  • 验证前后端联通：curl localhost/api/v1/health + curl localhost/
• Phase 5.2（外围功能编码）:
  • Phase 5.1 验证通过后，并行启动 5 Agent 编码 P1/P2 功能
  • 等待全部完成
• 逐项验收：

• 🛑 全部验收通过后进入 Phase 5.5

Phase 5.5: 业务闭环自动检测与验证

Step 5.5.0 — 静态代码分析（AI 自动执行，无需用户参与）:

• 启动代码分析 Agent，扫描全部已生成的前后端代码
• 自动检测 5 类断裂点：
  • API 缺失: 前端 HTTP 调用 ↔ 后端路由定义 交叉对比
  • 死交互: 前端 form/button handler 内部是否有 API 调用
  • 无持久化: 后端 Service 层是否有数据库操作
  • 导航断裂: 前端路由 ↔ 页面组件映射是否正确
  • 字段不匹配: 前端请求体字段 ↔ 后端 DTO/Schema 字段
• 输出 reports/static-gap-analysis.md（静态集成断裂点分析报告）
• 若发现 🔴 Blocker 级别断裂点 → 进入 Step 5.5.1 自动修复

Step 5.5.1 — 断裂点自动修复（AI 自动执行，无需用户参与）:

• 对每个 🔴 Blocker 启动对应修复 Agent：
  • API 缺失 → 后端 Agent 补全缺失的 API 端点
  • 死交互 → 前端 Agent 补充 API 调用逻辑
  • 无持久化 → 后端 Agent 补充数据库操作
  • 导航断裂 → 前端 Agent 修正路由/导航
  • 字段不匹配 → 前后端 Agent 对齐字段名
• 修复后重新执行 Step 5.5.0 静态分析，确认 🔴 Blocker 清零
• 若仍有 Blocker → 再修复（最多 3 轮）

Step 5.5.2 — E2E 测试脚本生成:

• 根据 Phase 0.2 技术链路表生成 tests/e2e/core-loop.spec.sh
• 可选：生成 tests/e2e/core-loop.spec.ts（前端 UI 测试）

Step 5.5.3 — 动态运行验证:

• 启动全栈并等待 healthy：docker compose up -d --wait
• 执行后端 API 链路测试：bash tests/e2e/core-loop.spec.sh
• 逐步骤检查测试结果——每个闭环节点必须 PASS

Step 5.5.4 — 失败修复循环（如动态测试失败）:

• 分析失败原因 → 定位责任模块 → 启动修复 Agent → 重新测试
• 最多 3 轮，超过则标记为已知限制并记录

Step 5.5.5 — 闭环验证报告:

• 生成最终报告（含静态分析断裂点 + 修复记录 + 动态测试结果）
• 🛑 闭环全部节点 PASS（静态无 Blocker + 动态全 PASS）→ 展示报告 → 用户确认 → 正式交付
  • ⚠️ 若有 🔴 Blocker 或动态测试 FAIL，MVP 不得交付
  • 💡 整个过程用户只需要看最后的 ✅/❌ 报告，中间的分析和修复全部自动完成

裁量指南

已有 PRD: 跳过 Phase 0，从 Phase 1 开始（但需补充核心闭环技术链路表）。 已有设计: 跳过 Phase 1，从 Phase 2 评审开始。

常见陷阱

…(truncated)