Vibe Coding 工程化最佳实践：从 Prompt 到可用应用

写在前面

差不多可以这么说，我的 AICoding经验，几乎是以近乎惨烈的踩坑方式和大量的充值来获得的。

这些惨烈的代价包含：

Base44 的高级月度套餐，在 1 个星期内，额度全部用完。

每月固定充值一个 AICoding 工具；费用 20 美金，额度捉襟见肘。

Kiro、Cursor、Codebuddy、GeminiCLI、claudecode、AntiGravity 轮番换。

在一个在用项目升级功能，因为失误导致数据库被重置 3 次以上，孩子积累了 1 个月的错题一夜之间全部清零（他倒是挺开心的）。

总体来说，AICoding对于我而言，就像刚拿驾照（甚至没有驾照）我开 F1 赛车。

车很快，轻轻点一下油门就弹射出去。

点击执行后，我只能坐在旁边祈求，不要出错。我永远不知道，等待我的坑还有多少。

稍微一不小心，又有一种白干一年的感觉。

在 AI模型编程能力突飞猛进的情况下，我开始思考，我是否也应该一起升级，沉下心来补全自己的开发认知能力？

如何将AICoding 的超速度与实际开发的严谨相结合。让 AI在安全能力边界允许的情况下，发挥最大的创造价值？

于是，我用了一个月时间，开始慢慢梳理 AI开发应用的坑与经验。

本文章作为个人记录，也跟所有想尝试AICoding或者已经开始的同学一个参考。

太长不看版

这是一套将“高级工程师思维”注入 AICoding 的作战手册。核心在于分层解耦和风险控制。

⚡️ 三大黄金法则 (Golden Rules)

1. 🛡️ GitHub 是底裤：在写第一行代码前，先初始化 Git。这是你唯一的后悔药。

2. 🎨 前端决定后端：先画出界面，用 Mock（模拟） 数据跑通交互。UI 怎么长，决定了后端数据库怎么建。

3. 👮♂️ 治理大文件：当 AI 行代码时，立刻提醒拆分。不要让 AI 试图吞下一头大象。

🎯 核心流程图 (Workflow Map)

本指南不仅仅是一套开发流程，更是 高级工程师思维 (Senior Mindset) 的结晶。 既然我们已经拥有了 AI 这一超级生产力，我们的核心能力就必须从“写代码”升级为**“定义产品(PM) -> 设计架构(Architect) -> 指挥 Agent(Manager)”**。

核心理念 (Core Philosophy)

1. 分层解耦: 避免"一窝蜂"全栈开发导致的上下文混乱。让 AI 在每个阶段专注于单一目标。
2. 高级工程师思维 (Senior Mindset): 你的核心技能不再是写代码，而是任务分配和Agent 管理。你是指挥官，并行管理多个 AI Agent（初级工程师）协作。
3. 拥抱重构 (Refactoring): AI 喜欢生成巨型文件。必须强制要求其进行组件化拆分，保持代码整洁。

阶段零：业务梳理与提示词设计 (Business Analysis & Prompt Design)

目标：像产品经理一样思考，清晰定义“是什么(What)”、“为谁做(Who)”和“为什么做(Why)”，产出高质量的初始 Prompt。

1. 四大核心原则

   • 清晰具体 (Be Clear and Specific)：直白描述目标用户和核心功能。
     • 正例：“我想要一个帮助个人健身教练管理客户训练计划和追踪每周进展的应用。”
   • 聚焦用户旅程 (Focus on the User's Journey)：描述用户交互的关键步骤，帮助 AI 构建结构。
     • 正例：“用户注册后，可以创建新项目，为项目设定里程碑，并每日追踪进度。”
   • 关注“是什么”，而非“怎么做” (What, not How)：专注于功能体验，不限制技术实现（如数据库设计）。
     • 正例：“应用需要能存储用户数据，加载速度快，并且设计风格要简洁现代。”
   • 迭代和优化 (Iterate and Refine)：Prompt 只是起点，通过对话不断微调。

2. 三大提示词框架 (Prompt Frameworks)

   • Who/What/Why 框架（经典起点）：
     • 示例：“WHO：独立咨询顾问。WHAT：管理客户项目和合同的仪表盘。WHY：节省时间，不错过交付。”
   • 用户故事框架 (User Story)：
     • 示例：“作为一个自由设计师，我想要发送带有品牌标识的发票给客户并追踪支付状态，以便于我更好地管理我的现金流。”
   • 功能分解框架 (Feature Breakdown)（适用于功能迭代）：
     • 示例：“1. 添加和组织潜在客户；2. 追踪联系状态；3. 添加备注和跟进提醒。”

3. 高级技巧：迭代与分层构建

   • 微提示词调整：做加减法（“添加评论区”）、做改变（“颜色改成炭灰色”）、找参考（“像 Notion 的风格”）。
   • 分层构建 (Prompt Pathways)：对于复杂应用，不要试图一步到位。
     • 路径：先构建核心功能 -> 然后增加好友挑战 -> 最后增加奖励机制。

4. 工程化准备：技术栈与安全 (Engineering Prep) <-- 核心工程化升级

   • 版本控制与“保险”机制 (Version Control as Insurance)：
     • 不可协商 (Non-negotiable)：GitHub 是代码的“保险”。当 AI 导致代码库崩溃或“幻觉”严重时，它能让你瞬间回滚到 V1, V1.5 等可用状态。
     • 行动：在写第一行代码前，必须初始化 Git 仓库并连接远程 GitHub。推荐使用 IDE (Cursor/VSCode) 自带的 Source Control 面板进行可视化操作。
   • 技术栈锁定与“建筑材料”清单 (Tech Stack Lock & Materials)：
     • 原则：“材料”决定房屋质量。明确告诉 AI 禁止随意引入新库。
     • 推荐黄金组合 (Golden Stack)：
       • Frontend: React + TypeScript (社区验证最充分，AI 对其代码理解能力最强，“像人类语言转机器语言”般顺畅)。
       • Backend: Python (AI 原生兼容性最好) 或 Cloud Functions (将逻辑卸载到云端)。
       • Cloud & DB: Firebase + GCP (专为“Builder/构建者”设计，从 Auth 到 DB 再到 Hosting 一站式解决，长期集成更顺畅)。
   • 环境隔离 (Env Vars Strategy)：明确所有敏感配置（API Key, DB URL）必须通过 .env 文件加载，禁止硬编码。

阶段一：前端优先与交互设计 (Frontend First)

目标：完成高保真的 UI 交互，并同步完成核心业务实体与视觉风格。这个阶段的产出不仅是界面，更是后端开发的规格说明书。

1. 视觉定调与设计规范 (Visual Style & Design System) <-- 新增关键步骤
   • 原则：在写业务代码前，先定好“长什么样”，避免后续反复修改样式导致代码混乱。
   • 如何定义 (How to Define)：
     • 关键词法：Modern (现代), Minimalist (极简), Playful (活泼), Brutalism (新丑/粗野主义)。
     • 对标法 (最佳捷径)："Design style similar to Notion/Linear/Airbnb" 或 "Apple Human Interface Guidelines"。
     • 技术选型：明确指定 CSS 框架（推荐 Tailwind CSS）和组件库（如 Shadcn UI, Radix UI），这能极大保证产出的“高级感”。
   • Prompt 示例："请使用 Tailwind CSS 构建一个极简主义风格的 Dashboard。主色调为靛蓝色 (#6366f1)，背景使用柔和的浅灰色，卡片带有轻微的阴影和圆角。整体风格参考 Linear.app 的设计。"
2. 核心实体建模 (Core Entity Modeling)
   • 在动手写 UI 前，先识别业务中的核心对象（如 User, Order, Product）。
   • 定义每个对象的关键属性（Attributes）和类型（Types）。
   • Prompt 技巧：告诉 AI "请先帮我定义这个页面涉及的 JSON 数据结构（Schema），包含哪些字段和类型，然后再写 UI 代码"。
3. 界面开发 (UI Construction)
   • UI 状态完备性 (UI State Completeness)：拒绝“仅演示可用”。强制要求 AI 实现 Loading (加载中)、Error (加载失败)、Empty (无数据) 三种状态的 UI。
   • 自动文件治理机制 (Automated File Governance)：
     • 痛点：人类常常忘记检查文件长度，直到太晚。
     • 解决方案：在对话一开始，就植入**“治理指令”**。
     • Prompt 模板："系统规则：请主动监控代码复杂度。当任一文件超过 250 行，或包含多个独立的逻辑块（如同时包含复杂的 Types 定义、Mock 数据和 UI 组件）时，请主动询问我：'检测到文件复杂度较高，是否需要将其拆分为子组件（如 components/Header.tsx）或提取配置文件？'。"
   • 专注于组件布局、CSS 样式、响应式设计。
   • 使用基于上述实体定义生成的 Mock Data 填充界面。
4. 交互逻辑 (Interaction Logic)
   • 实现点击、跳转、表单验证、状态切换等前端逻辑。
   • 关键点：前端的状态管理（State Management）应直接映射未来后端的数据库状态。
5. 数据契约定义 (Data Contract Definition)
   • 通过编写 Mock Data，实质上是在定义前后端交互的 API 接口文档。
   • 产出物：一份清晰的 mock_data.js 或 TypeScript 接口定义 (interfaces.ts)，这将在后续直接作为后端数据库设计和 API 开发的规范。

阶段二：后端服务实现 (Backend Implementation)

目标：依据阶段一确定的数据结构，开发真实的后端逻辑。

1. 数据库设计与脚本化 (Database Design & Scripting)
   • 将阶段一确定的 Data Contract (Mock Data) 映射为实际的数据库 Schema。
   • SQL (Relational): 设计表结构 (Tables)、主外键 (Foreign Keys)、索引 (Indexes)。
   • NoSQL (Document): 确定 Collection 结构 (如 Firebase Firestore)。
   • 未来扩展性 (Future Proofing): 设计 Schema 时必须考虑“未来 3 个月的需求”（如：现在是单人，未来会有 Team 吗？如果有，路径应为 /teams/{tid}/projects 而非 /projects）。避免未来的“遗留数据迁移”地狱。
   • File Storage: 图片/PDF 等大文件存入 Object Storage (如 Firebase Storage)，数据库仅存 URL。
   • 可复现性 (Reproducibility)：不要手动建表。要求 AI 生成 setup_db.sql 或 seed.js 脚本，确保数据库结构随时可重建。
2. 方案选型 (Technology Selection)
   • Cloud Functions (Golden Stack 首选)：适用于需要高可扩展性的正规应用。将业务逻辑（如 Auth 触发器、复杂计算）卸载到云端函数运行。
   • n8n Webhook：适用于快速原型验证 (MVP) 或连接第三方 SaaS 的自动化流程（非核心业务逻辑）。
   • 独立 API 服务：适用于极度复杂的 AI 算法服务（如需 GPU 加速的 Python 后端）。
3. 接口开发与空壳先行 (API Stubbing & Implementation)
   • 错误处理设计 (Error Handling Strategy)：不仅返回 200 OK，还要定义 400/401/500 的标准错误 JSON（如 { error: { code: "INVALID", msg: "..." } }）。
   • 策略：空壳优先 (Stub First)：这是极佳的实践。不要一开始就写数据库查询或复杂运算。
     • n8n: 仅拖拽 Webhook 触发器节点和 Respond to Webhook 节点，中间留白。在 Respond 节点中直接填入阶段一的 JSON 数据。
     • Code (Node/Python): 创建 API 路由，不写逻辑，直接 return mockData。
   • 目的：让前端能立刻调通网络请求，验证 HTTP 状态码、Header、鉴权（Auth）以及数据链路是否打通。
   • 逐步实现: 调通后，再在“空壳”内部逐步填充真实的业务逻辑（连接数据库 -> 处理数据 -> 替换 Mock 返回）。
   • 输入输出：始终严格遵守阶段一定义的 Data Contract。

阶段三：前后端集成 (Integration)

目标：剔除 Mock Data，对接真实 API。

1. API Client 封装
   • 创建一个统一的 API 请求层（如 api.js 或 services/ 目录）。
   • 实现拦截器（Interceptors）处理统一的 Auth Token、错误响应。
2. 替换数据源
   • 将组件中的 Mock Data 引用替换为 API 调用。
   • 保留 Mock 模式开关（可选），便于后续回归调试前端。

阶段四：测试与联调 (Testing & QA)

目标：确保业务流程闭环。

1. 测试用例构建 (Test Case Construction)
   • Prompt 技巧：让 AI 根据功能逻辑生成测试用例列表（Happy Path + Edge Cases）。
   • 单元测试：针对核心算法或数据处理逻辑。
2. 联调测试与故障排除 (Integration Testing & Troubleshooting)
   • 手动验证：对照测试用例，逐一验证前后端交互。
   • AI 辅助排错 (AI-Assisted Debugging)：
     • 原则：AI 不知道发生了什么，除非你告诉它。
     • 日志收集行动：
       • 前端：打开浏览器开发者工具 (F12) -> Console 面板，复制红色的错误堆栈。
       • 后端：查看终端输出 (如 localhost:4000 的 Terminal) 或云端日志 (Firebase Functions Logs)。
     • Prompt 技巧：直接把完整的错误日志复制粘贴给 AI，不要自己试图解释。“这是后端报错日志：[粘贴日志]，请分析原因并修复。”
   • 自动化验证 (进阶)：利用 Playwright/Puppeteer 编写简单的端到端 (E2E) 测试脚本，确保核心链路不挂。