engineering-rapid-prototyper

快速原型开发指南

概述

本指南介绍如何快速开发概念验证和创建 MVP。构建原型以验证假设、设置 A/B 测试，或选择优先考虑部署速度而非生产级强化的快速开发技术栈时，可参考本指南。

技术栈选择指南

如何选择工具

• 需要身份验证时，使用 Clerk 或 NextAuth 即可快速设置；切勿为原型构建自定义身份验证。如果原型无需用户账户即可验证假设，则完全跳过身份验证。
• 需要数据库时，使用 Prisma + Supabase，即可快速完成托管、架构管理和行级安全设置。如果原型仅需存储 <100 条测试记录，则使用 JSON 文件或 localStorage；不要设置数据库。
• 需要部署时，使用 Vercel，即可快速托管，并为每个 PR 提供预览 URL。项目启动后必须在 2 小时内完成首次部署。
• 如果无代码/低代码方案可以满足需求，就使用它；快速验证比自定义代码更重要。
• 构建时，先实现核心功能，再处理润色和边缘情况。如果你在端到端的正常流程尚未跑通前就开始编写错误处理，请停下来。

范围决策规则

• 数据库表最多 5 张。如果架构需要 >5 张表，就说明你做得过头了——缩减范围或简化数据模型。
• 功能最多 3-5 个。如果功能列表超过 5 个，按对假设的影响排序，并删掉优先级最低的功能。原型应该是验证一个假设，而不是拙劣地验证五个假设。
• 页面/路由最多 8 个。如果需要更多页面/路由，就合并视图或删减功能。
• 不编写自定义 UI 组件——使用 shadcn/ui、Radix 或类似方案。如果组件库中没有所需组件，就简化设计以适配现有组件。
• 除 CRUD + 一条业务规则外，不编写自定义后端逻辑。如果原型需要复杂的后端处理（队列、定时任务、多步骤工作流），就用一个返回逼真模拟数据的简单端点来模拟。
• 不做优化。不使用缓存，不配置 CDN，不添加数据库索引，不做懒加载，不做代码分割。这些都属于生产环境的考量。原型只需足够快，能用于演示即可——无需做得更多。

停止条件

• 如果设置过程（项目初始化 → 首次部署）耗时 >3 小时，说明技术栈过于复杂。换用更简单的方案。
• 如果 2 天后仍无法通过原型测试核心假设，就重新设计原型，而不是假设。
• 如果单个功能需要 >1 天才能实现，说明该功能对原型来说过于复杂。简化功能，或用静态数据模拟。
• 如果你开始编写测试，就说明已经脱离原型模式。原型是一次性的，测试是为打算保留的代码编写的。

推荐技术栈

• 框架：Next.js 14+（App Router）
• UI：shadcn/ui + react-hook-form + Zod 验证
• 状态管理：Zustand（仅在需要客户端状态时使用——优先采用服务端组件 + 服务端操作）
• 数据库：Prisma + Supabase（仅在测试假设需要持久化时使用）
• 身份验证：Clerk 或 NextAuth（仅在用户身份属于假设的一部分时使用）
• 动画：Framer Motion（仅用于演示——仅做内部测试时跳过）
• 部署：Vercel

完整的 package.json 和 shadcn/ui 安装命令，请参阅 技术栈设置。

工作流

第 0-2 小时：假设与设置

• 用一句话写下假设：“我们认为 [用户] 会 [采取某项行动]，因为 [原因]，并通过 [指标] 衡量。”如果你写不出这句话，就还没准备好开始构建。
• 使用 scripts/scaffold.sh 或 npx create-next-app 搭建项目。安装 shadcn/ui。将空项目部署到 Vercel。必须在 <2 小时内完成。
• 如果需要身份验证，配置 Clerk（15 分钟）。如果需要数据库，创建 Supabase 项目并运行 prisma db push（20 分钟）。如果验证假设两者都不需要，则都跳过。

第 2-8 小时：核心流程（第 1 天）

• 端到端构建最重要的单一用户流程：入口 → 核心操作 → 可见结果。不做旁支功能、设置或边缘情况。
• 使用服务端组件和服务端操作获取数据。只有在需要交互时才添加客户端组件。
• 假设之外的内容一律写死。使用种子数据、占位图片和逼真的模拟内容。如果某项功能需要尚未配置的外部 API，就从服务端操作返回模拟数据。
• 在第 1 天结束时部署到 Vercel。第 1 天就必须让真实用户能够点击使用原型。

第 8-20 小时：辅助功能（第 2-3 天）

• 一次添加 2-4 个辅助功能。每添加一项功能就部署一次。如果某项功能导致部署失败，立即回滚——不要花超过 30 分钟调试。
• 添加反馈机制：可以使用简单表单（shadcn/ui textarea + 将数据写入 Supabase 的服务端操作），也可以使用 Hotjar/PostHog 代码片段（3 行代码）。
• 如果需要 A/B 测试，请使用 Vercel Edge Config 或基于 Cookie 的简单分流，不要使用完整的实验平台。

第 20-24 小时：测试并决策（第 3-4 天）

• 与 5-10 名目标用户分享。观察或收集 24-48 小时的反馈。
• 根据第 0 小时定义的假设指标进行衡量。如果指标为正面结果，就规划生产版本的构建。如果为负面结果，就决定是调整假设还是终止原型。
• 绝不对原型迭代超过 1 周。1 周后，要么投入资源重建高质量生产版本，要么将其归档。

请参阅代码示例，了解反馈表单组件和 A/B 测试钩子。

验证反馈闭环

原型的存在是为了回答一个问题。请使用以下流程确保它确实能做到：

• 开始构建前：写下假设、指标以及成功/失败的阈值。例如：“如果 >30% 的测试用户无需帮助就能完成结账流程，则验证 UX 假设成立。”
• 构建期间：每完成一项功能就部署，并检查真实用户能否测试该功能。如果无法从头到尾点击使用，就说明还没完成。
• 第 1 天检查点：将已部署的原型分享给 1 个人（你自己或一位队友）。他们能否在没有说明的情况下完成核心流程？如果不能，说明流程有问题——先修复，再添加功能。
• 第 2-3 天检查点：与 5-10 名目标用户分享。观察或收集反馈。如果用户在同一个步骤上感到困惑，这就是阻碍——只修复这一步，不要添加更多功能。
• 决策点（第 3-5 天）：衡量假设指标。可能有三种结果：
  • 达到指标：假设得到验证。记录经验教训，归档原型，并使用生产技能开始生产规划。
  • 接近指标但未达到：允许迭代一次。找出最大的单一阻碍，修复后再让 5 名用户测试。如果仍未达到，就终止。
  • 远未达到目标：假设被否定。记录原因。决定是调整方向（新假设、新原型）还是终止（彻底转向另一个想法）。

自我验证流程

原型不需要测试套件，但需要基本验证：

• 应用能从主分支成功部署到 Vercel（或同等平台）。如果部署失败，其他一切都无关紧要。
• 核心流程端到端可用：新用户无需遇到错误页面或死胡同，就能完成主要操作。
• 反馈机制正常工作：提交测试反馈并确认其已被记录（检查 Supabase 表、Hotjar 录制或 PostHog 事件）。
• A/B 分流（如果有）正常工作：切换分流 Cookie/标记，确认两个变体都能正常呈现。
• 测试用户看不到任何占位文本（“Lorem ipsum”、“TODO”、“test”）——这会损害可信度并使反馈失真。
• 原型在移动网络下的加载时间应少于 3 秒（在 DevTools 中将网络限速设为 “Fast 3G” 并验证）。加载缓慢的原型会在假设得到验证前就被用户放弃。

脚本

• scripts/scaffold.sh -- 创建包含最少样板文件的 Next.js + TypeScript + Tailwind 项目结构（不运行 npm install）。运行时添加 --help 可查看选项。

反模式（发现自己在做以下事情时，请立即停止）

• 为原型代码编写单元测试或集成测试。
• 设置 CI/CD 流水线、lint 规则或 pre-commit 钩子。
• 创建设计系统、自定义主题或组件库。
• 构建管理面板、设置页面或用户个人资料页面（除非它们属于假设验证的内容）。
• 添加错误边界、重试逻辑、加载骨架屏或空状态。
• 为了“整洁”而重构代码——原型代码是一次性的。
• 花超过 15 分钟讨论技术选型——选择默认技术栈并继续。
• 添加“顺便做一下”的功能，但它们不在 3-5 项功能清单中。

过渡到生产环境

假设得到验证并决定正式构建后：

• 不要将原型重构为生产代码。请使用生产开发技能（engineering-frontend-developer、engineering-backend-architect 等）从头开始。
• 从原型中提取：已验证的用户流程、数据模型结构、API 契约和 UI 截图。这些是生产构建的规格说明。
• 归档原型仓库。它已经完成了使命。

参考资料

• 技术栈配置 -- package.json 和 shadcn/ui 安装命令。
• 代码示例 -- 反馈表单组件和 A/B 测试钩子。
• 全栈集成 -- Prisma schema、Supabase + Clerk 身份验证、服务端操作、tRPC、文件上传，以及使用 Resend 发送邮件。
• UI 模式 -- 使用 shadcn/ui 实现数据表格、命令面板、表单向导、仪表盘布局、toast 通知和加载骨架屏。