Vibe Coding ：在 AI 写代码之前，先把规矩立好

引言：为什么你的 Vibe Coding 项目最后都变成了屎山？

如果你用过 Vibe Coding（让 AI 帮你写代码），大概率经历过这个循环：

第一周：AI 太强了，一天写完登录注册、三天搭完整站框架，爽到飞起。

第二周：开始不对劲了。加新功能时 AI 改了老代码，你也不知道它改了什么，反正功能看起来还能用------直到某个按钮突然不跳转了。

第三周：代码已经变成一团乱麻。同一个逻辑在三个文件里重复出现，错误处理有三种写法，命名风格像精神分裂。你不敢再让 AI 改东西了，因为你不知道它会改崩什么。

一个月后：项目烂尾。你看着那一堆代码，心想"算了，下次重新开始吧"。

如果你的经历和上面有超过 50% 的重合，这篇文章就是为你写的。

---

核心问题：AI 没有记忆，但你可以给它造一个

Vibe Coding 所有问题的根源只有一个：AI 没有记忆。

你昨天跟它说了三个小时的业务逻辑，今天开一个新对话，它什么都忘了。它不知道你的项目为什么选择了 PostgreSQL 而不是 MongoDB，不知道你的登录逻辑为什么把 token 存在 localStorage 而不是 cookie，不知道你上次踩过的坑。

但 AI 有一个巨大的优点：它能读文件。

所以解决思路很简单------把项目知识写进文件，每次让 AI 重新加载。

这就是社区里所有人都在强调的"先写文档，再写代码"。听起来像老派软件工程的做法？对的。但 2025-2026 年的 Vibe Coding 社区把它重新发明了一遍，因为不这么做，项目根本走不远。

---

最小可行文档集：四个文件保你项目不崩

如果你不想搞太复杂，一个项目至少要有这四个文件：

1. CLAUDE.md --- AI 的"入职手册"

这是 Claude Code 启动时自动读取的文件。它告诉 AI：

• 这个项目是做什么的
• 用了什么技术栈（版本号锁定）
• 目录怎么组织的
• 有哪些开发规范
• 每次改动后必须跑哪些检查（format → lint → typecheck）
• 哪些地方不准碰（废弃的文件夹、冻结的模块）

社区星标最高的项目之一 FerroxLabs/agents-md（547⭐，Linux Foundation 托管）就是靠一个文件把 AI 从"实习生"变成了"高级工程师"。

2. PRD.md --- 需求边界

这个文件回答一个问题：做到什么程度算做完？

这里有一个最容易犯的错误。写需求的时候，"登录功能"四个字就够了？不对。你要写清楚：

• 登录成功后跳转到哪个页面？（首页？还是登录前的页面？）
• 登录失败提示什么？（"用户名或密码错误"还是分别提示？）
• 密码输错几次锁账号？
• 要不要支持第三方登录？

没有这些边界条件，AI 就会自己脑补------然后每次都脑补得不一样。 这就是 AI 越写越发散的根本原因。

3. ARCH.md --- 架构约束

告诉 AI 代码应该怎么组织。它至少包含：

• 目录分层（每个目录放什么代码）
• 核心模块清单（每个模块的职责和对外接口）
• 数据模型（有哪些实体，它们之间什么关系）
• 组件树（前端页面的组件层级）

ARCH.md 和其他文档不一样------它是一份"活"文档。 每完成一个 milestone，你都要更新它，让它始终反映项目的真实状态。

4. Reference.md --- AI 的"模仿样本"

这是最被低估但最实用的一个文件。

给 AI 描述你的代码风格："请使用函数式编程风格，错误处理在 service 层做，controller 只做参数校验和响应封装......"------你写了 500 字，AI 还是会写歪。

但如果你在 Reference.md 里放一段标准代码：

// 这就是你期望的 API 调用模板
export async function login(params: LoginParams): Promise<ApiResponse<User>> {
  try {
    const response = await api.post('/auth/login', params);
    return { success: true, data: response.data };
  } catch (error) {
    if (error instanceof ApiError) {
      return { success: false, code: error.code, message: error.message };
    }
    throw error;
  }
}

AI 拿到这段代码后去写新功能，它会自然模仿这个风格------错误处理方式、返回格式、命名规范，全对齐。

核心洞察：AI 是模式匹配机器，不是规则理解机器。给它样本，比给它描述有效 10 倍。

---

进阶：Memory-Bank 模式（社区最推崇）

当你的项目稍微大一点（比如超过 5 个页面、10 个 API），四个文件就不够了。社区演化出了一个叫 Memory-Bank 的文档架构：

memory-bank/
├── design-document.md       # 产品设计文档（PRD 增强版）
├── implementation-plan.md   # 实施计划（纯指令，无代码）
├── architecture.md          # 架构文档（动态更新）
├── tech-stack.md            # 技术栈决策 + 选型理由
└── progress.md              # 执行日志（追加式）

最关键的创新是 implementation-plan.md 和 progress.md。

implementation-plan.md --- 把大需求拆成小步骤

这个文件有两条铁律：

1. 只写指令，不写代码。 每条指令描述"要做什么"和"怎么验证"，不写具体实现。
2. 每一步必须独立可验证。 做完这一步，跑什么测试、看到什么结果，才算完成。

为什么这么重要？因为 AI 的上下文窗口有限。如果你一次让它写 500 行代码，它写到后面会忘记前面。但如果你把需求拆成 10 个独立步骤，每步只生成 50 行，质量会高得多。

progress.md --- AI 的"断点续传"

这是一个追加式日志，格式很简单：

[2026-07-26 10:30] 步骤 1 完成 --- 搭建项目骨架，配置 ESLint + TypeScript
[2026-07-26 11:00] 步骤 2 完成 --- 实现用户注册 API，注册测试通过
[2026-07-26 11:30] 步骤 3 进行中 --- 实现登录 API，token 生成逻辑待调试

AI 每次新对话的第一件事，就是读 progress.md。它知道了上次做到哪、当前在做什么、以及所有已完成步骤的设计决策。

配合 /clear 命令（清空上下文），你可以在每步之间开一个全新的对话。这解决了 AI 的最大问题：对话越长，输出质量越低。 与其一个 50 轮的对话覆盖 5 个功能，不如 5 个 10 轮的对话各覆盖 1 个功能。

---

Spec-Driven：项目再大也不怕

当你的项目继续膨胀（比如 10+ 张数据库表、20+ 个 API 接口、10+ 个页面），单个文档太大，AI 读不过来。这时候就该拆分了：

specs/
├── spec.md               # 主规范（总控，控制在 3000 tokens 以内）
├── spec-database.md      # 数据库设计
├── spec-api.md           # API 接口设计
├── spec-ui.md            # 前端页面设计
├── spec-logic.md         # 核心业务逻辑
├── spec-integration.md   # 第三方集成
└── spec-devops.md        # 部署运维

拆分时机的经验值：单个 spec 文件超过 3000 tokens 就该拆。不是一开始就建全部文件，而是按需生长------项目需要时才新建。

---

开发中的三条铁律

文档只是前提条件。在真正写代码的时候，还有三条铁律能救你的命。

铁律一：一次只做一件事

"帮我加个登录功能，顺便把首页的样式调一下，然后导航栏那个高亮状态好像也不对，你一并看看吧"------这就是屎山的开始。

每次给 AI 的 prompt，只让它做一件事。加功能、修 bug、重构------三选一，不要混。

铁律二：Reference 优于描述

上面已经讲过了，但值得再强调一遍。想让 AI 写出你想要的代码，最省事的方式是在 Reference.md 里放一段样本。以后每次让 AI 写类似代码时，附上一句"参考 Reference.md 里的写法"。

遇到 AI 反复犯同一个类型的错误？把正确做法写进 Reference.md。一劳永逸。

铁律三：测试不是用来找 bug 的，是用来定义"做完"的

在 Vibe Coding 中，测试的真正价值不是发现 bug。它的真正价值是------给 AI 一个明确的、不可反驳的"完成"信号。

"这个注册功能做完了吗？"

• "我看起来觉得写好了"------这不叫做完。
• "测试全部通过了"------这才叫做完。

建议在写功能之前，先让 AI 写测试用例（哪怕只是伪代码）。然后让 AI 去实现功能，直到测试通过。测试没通过就是没做完，没有商量余地。

---

质量阀门：三道防线

每次 AI 改动后，必须跑这三步，顺序固定：

1. Linter（ESLint / Ruff / Prettier）--- 风格一致性
2. 类型检查（TypeScript / MyPy）--- 类型安全
3. 测试 --- 行为正确性

规则写进 CLAUDE.md，明确告诉 AI：这三步不准跳过。

为什么顺序固定？因为 Linter 最快（几秒），类型检查稍慢（十几秒），测试最慢（可能几分钟）。从左到右跑，每一步都能拦住 80% 的低级错误，最后到测试时出问题的概率已经很低。

---

任务分级：不是所有事都要走流程

级别	示例	流程
微改动	typo、改颜色	直接做，无需文档
小任务	单模块、< 100 行	跳过方案文档，仍需自审 + 测试
标准任务	常规功能开发	走完整流程（PRD → Plan → Code → Test → Review）
高风险任务	资金、鉴权、DB 迁移	完整流程 + 强制预审 + 回滚预案

不要教条主义。 改一个颜色也要写 PRD 文档？没必要。但涉及钱或者用户数据的改动，多谨慎都不为过。

---

写在最后

Vibe Coding 给了一个巨大的诱惑：写代码变得太快了。快到让你以为，那些"老派"的软件工程实践------写需求文档、画架构图、定代码规范------都可以跳过了。

但真相是：AI 让代码产出加速了 10 倍，也让代码混乱加速了 10 倍。

写需求文档、画架构图、定代码规范------这些事情不是为了"显得专业"，而是为了让 AI 有边界可循。AI 越强大，约束越重要。

图纸（PRD）、地基（ARCH）、规矩（Reference）、阀门（Test/Lint/Git）。

四样缺一个，项目超过 2000 行就会开始失控。

花在文档上的每一分钟，都会在后续开发中成倍赚回来。

---

参考资源：

• FerroxLabs/agents-md --- 社区最成熟的 AI 开发规范文件
• vanzan01/cursor-memory-bank --- Memory-Bank 模式经典实现
• IgniteUI/ai-repo-structure --- 多层 AI 配置共存参考
• AetherSDR --- 多 AI 工具共用代码库的文档策略
• create-vibe-app --- Vibe Coding 项目脚手架
• vibe-coding-rules --- 通用规范文档套件