Vibe Coding 的“驾驶”指南：从“失控屎山”到“精准驯服”

Vibe Coding 的“驾驶”指南：从“失控屎山”到“精准驯服

前言：Vibe Coding 的魔咒

如果你正在尝试 Vibe Coding（氛围编程），你一定经历过这样的“过山车”：

• 初期：爽！跟 AI 聊几句，一个功能就出来了，感觉自己无所不能。
• 中期：嗯？这里怎么有个 Bug？让 AI 改一下。
• 后期：改一个地方，坏了三个地方。代码越改越乱，逻辑互相打架。最终，你获得了一座崭新的——屎山。

问题出在哪？是 AI 不够强吗？不，GPT-4、Claude 3.5 Sonnet 已经足够聪明。

问题在于，你把 Vibe Coding 当成了“甩手掌柜”式的魔法，而它实际上是一场“人机结对编程”的越野拉力赛。你需要的不再是单纯的代码能力，而是驾驭 AI 的工程化能力，或者说，Harness Engineering（harness：驾驭/套索）。

本文将带你构建一套完整的 Vibe Coding 工作流，像 Vite 之于前端工程化一样，让你的 AI 开发之旅不再失控。

一、基础工具：Git 的“后悔药”与“时光机”

在正式聊 Vibe Coding 流程前，我们必须先精通版本控制的底层逻辑。因为 AI 生成的代码经常跑偏，回退是高频操作。

1. HEAD 指针：你的“现在”在哪里？

在 Git 的世界里，HEAD 是一个指针，它指向你当前所在的本地分支的最新提交（或者说，当前工作目录是基于哪个提交构建的）。

• 理解指针：它不是文件夹，而是一个引用。在 .git/HEAD 文件中，通常存储着 ref: refs/heads/main，表示指向 main 分支。
• 分离 HEAD：如果你 git checkout 到一个具体的 commit hash，HEAD 就不再指向分支，而是直接指向提交，这就进入了“分离 HEAD”状态，此时任何修改都容易被丢弃，需谨慎。

2. git reset：带着记忆“穿越”

reset 命令是 Vibe Coding 中最强的“反悔”工具，它能移动 HEAD 指针的位置。它的核心区别在于如何处理工作区（Working Directory）和暂存区（Staging Area）。

# 回退到上一个提交，并丢弃所有本地修改（慎用！）
git reset --hard HEAD^

# 回退到上一个提交，但保留工作区的修改
git reset --soft HEAD^

为了理解 --hard 和 --soft，我们需要引入 Git 的“三棵树”概念（这也是面试高频题）：

1. 工作区 (Working Directory)：你电脑上能看到的文件。
2. 暂存区 (Index/Staging Area)：git add 后存放的地方，准备打包提交。
3. 本地仓库 (Repository/HEAD)：git commit 后存储的永久快照。

参数	移动 HEAD (仓库)	更新暂存区 (Index)	更新工作区 (Working Directory)	Vibe Coding 适用场景
--soft	✅ 是	❌ 否 (保留原有暂存状态)	❌ 否 (保留所有修改)	AI 生成的代码太多，想合并成几个 Commit，重新组织提交记录。
--hard	✅ 是	✅ 是 (覆盖)	✅ 是 (覆盖)	AI 写崩了，完全跑不起来，代码全是红叉，直接丢弃，回到上一个稳定版本，重新写 Prompt。

解析 --soft 的妙用：执行 git reset --soft HEAD^ 后，你的代码修改还在工作区，并且被自动 git add 放回了暂存区。

3. git restore vs git checkout：精准“丢弃”

Git 2.23 引入了 restore 命令，专门用来撤销修改，因为它比 checkout 职责更单一。

# 1. 将文件从暂存区移除 (Unstage)，但保留工作区的修改
# 等同于 git reset HEAD readme.md
git restore --staged readme.md

# 2. 丢弃工作区的修改 (危险！无法找回)
# 等同于 git checkout -- readme.md
git checkout -- readme.md

底层解析：git checkout -- readme.md 的本质是用暂存区（或 HEAD）中的同名文件覆盖工作区的文件。如果工作区的文件是新创建的且从未 add，Git 找不到该文件的索引记录，checkout 会报错或无法操作，此时只能手动删除。

二、Vibe Coding 的“驾驶舱”建设

理解了油门（写代码）和刹车（回退），我们来看看怎么规划路线。这是本文的核心——开发前的 9 大步骤。

第一阶段：定图纸（规划阶段）

不要上来就写代码，Vibe Coding 的 Prompt 不是聊天，而是需求沟通。

1. 导需求：像和朋友聊天一样“倒苦水”

不要用专业的 PRD 语言，而是用最自然、感性的语言跟 AI 描述。

• 痛点：什么事让你特别难受？（例如：每天整理 Excel 表格汇总数据太累了）
• 目标用户：谁需要这个？（例如：运营小白，不懂 SQL）
• 核心功能：你理想中它应该长什么样？

思考深度：这一步不是让 AI 写代码，而是让 AI 建立业务上下文（Context）。没有上下文，AI 写的代码只是“语法正确的废话”，有上下文才是“解决问题的良药”。

2. 整理 PRD：给 AI 戴上“紧箍咒”

让 AI 将刚才的聊天记录整理成结构化的 PRD.md。

关键动作：定义完成标准（Definition of Done, DoD）。千万不要只写“登陆功能”。要写死边界条件。

为什么必须这么做？如果没有验收标准，AI 会默认使用最通用的逻辑（比如失败就弹个 alert）。随着代码变多，AI 会为了“适配”某个模糊逻辑而“发散”，导致代码逻辑互相矛盾。

3. 预定视觉：避免 UI 的“反复横跳”

让 AI 生成代码时，最头疼的是它经常为了修一个按钮样式，把整个布局推倒重来（因为 React/Vue 的样式和 DOM 结构耦合）。

措施：在项目初期，找 2-3 个参考网站，或者让 AI 生成几种设计风格，讨论确定后，生成一份 DESIGN.md。

• 布局：左侧导航？顶部导航？
• 风格：极简主义？赛博朋克？
• 色彩：主色是什么？（例如：#00B4D8）

这样做的好处：将 UI 决策前置。在后续开发中，AI 只需按照 DESIGN.md 的约束去实现，不再需要“创新”，创新意味着变数。

第二阶段：打地基（技术选型与架构）

图纸画好了，现在要打桩了。

4. 明确非功能需求（NFRs）：决定“天花板”

功能需求决定它能做什么，非功能需求决定它能活多久。这四个维度只要没写清楚，后面必定返工。

• 安全性：有没有用户数据？需不需要 HTTPS？需不需要防 SQL 注入？
• 性能：页面加载时间接受几秒？首屏加载（LCP）要求是多少？
• 可用性：是给自己用（99% 可用性）还是给全球用户用（99.99%）？
• 成本：服务器预算多少？这决定了你用不用得起 AI 大模型 API。

5. 锁定技术栈：越“标准”越好

Vibe Coding 最怕折腾环境配置。适合的就是最好的。

推荐栈：React + TypeScript + Tailwind CSS + Vite。

• React：生态最全，遇到 AI 答不出的问题，社区一定有答案。
• TypeScript：强制类型约束。AI 写 JS 很容易写成 any 大法，TS 能让 AI 自己约束自己，减少运行时 Bug。
• Tailwind CSS：Utility-first。AI 不需要理解复杂的 CSS 类名继承关系，直接在 className 里堆砌样式即可，极大降低 AI 理解 CSS 的复杂度。

深化：现在许多 AI 支持 claude.md 或 .cursorrules 文件。你需要在项目根目录创建这个文件，告诉 AI：“你必须使用这个技术栈，且必须使用函数式组件。”

6. 轻量级架构草案：分层与模型

不需要画复杂的 UML 图，但必须让 AI 输出一份 ARCH.md，哪怕只有 200 行。

• 目录结构：/components, /pages, /hooks, /utils, /services/api。
• 数据模型：用户表 User 有哪些字段？文章表 Post 有哪些字段？
• 组件依赖：哪些是纯 UI 组件（无状态），哪些是容器组件（有状态）？

第三阶段：立规矩（开发规范与持久化）

地基打好了，现在要立规矩，不然工人（AI）会乱来。

7. 固化成文档：AI 的“永久记忆”

现在的 Agent 交互，核心机制是 RAG（检索增强生成）或长上下文（Long Context）。我们需要在项目根目录维护几个永不删除的全局上下文文件：

my-project/
├── PRD.md          # 产品需求（告诉 AI 在做什么）
├── DESIGN.md       # 设计系统（告诉 AI 长什么样）
├── ARCH.md         # 系统架构（告诉 AI 怎么组织代码）
├── PROJECT.md      # 当前进度（告诉 AI 做到哪一步了，下一步干什么）
└── .cursorrules    # IDE 级别规则

解析：每次开启新对话时，必须手动把这几个文件拖拽给 AI（或通过 IDE 插件自动加载）。这能保证即使 AI 的上文窗口丢失，它也能迅速恢复对项目的全局认知。

8. 定开发规范与参考资料

给 AI 提供“样本”参考，能显著提升代码质量。

• 代码规范：提供一段你满意的组件代码，告诉 AI “所有组件都按这个风格写”。
• 错误处理：统一 API 返回格式。例如：{ code: 0, data: {}, msg: ' }。
• Restful 规范：告诉 AI 路由设计原则。

9. 配置 Git 与质量闸门（Quality Gate）

这是最后一道物理防线。在 AI 提交代码前，必须通过静态检查。

• Pre-commit Hook：使用 husky + lint-staged。
• 流程：AI 生成代码 -> 运行 eslint --fix -> 运行 prettier -> 自动修复格式 -> 如果还有 Error，阻断提交，AI 必须修复后才能提交。

命令示例：

// package.json
{
  "lint-staged": {
    "*.{js,jsx,ts,tsx}": ["eslint --fix", "prettier --write"]
  }
}

这样做能让 AI 学会在提交前自我审查格式问题，减少 Code Review 的噪音。

三、开发中的 5 个“定海神针”（简要概括）

由于篇幅限制，笔记中提到的“开发中 5 个关键点”我在这里做个升华补充，帮你构建完整的思维导图：

1. 单一职责原则 (SRP)：每个组件只做一件事。如果 AI 写了一个 500 行的大组件，立刻让它拆分。
2. 状态管理下沉：能用局部状态（useState）别用全局状态（Redux/Zustand），避免 AI 滥用 Context 导致无限渲染。
3. 契约先行 (Contract First)：写 UI 前，先让 AI 把 API 的 types.ts 定义好，UI 层直接调用类型。
4. 日志埋点：让 AI 在关键路径（如支付、登录）加上 console.log 或简易日志，方便调试黑盒逻辑。
5. 小步快跑，频繁提交：每完成一个功能点（即使它有点丑），立刻 git commit。方便随时 reset --hard 回到上一个“虽不完美但可用”的状态。

总结：Vibe Coding 是“骑手”与“烈马”的共舞

Vibe Coding 不是魔法，它是 AI 驱动的增量式开发。

• 底层逻辑：它依赖于上下文工程（Context Engineering）。你把上下文（PRD, ARCH）喂得越精准，AI 输出的代码越可控。
• 本质：你不是在写代码，你是在做架构决策和质量验收。Git 是你的“缰绳”，文档是你的“地图”，质量闸门是你的“马鞍”。

希望这份“驾驶指南”能帮你驯服那匹野马，在 AI 编程的时代，真正成为驾驭代码的骑手，而不是被屎山吞噬的“铲屎官”。

（完）