Vibe Coding 方法论 · 第 1 节

为什么要给 AI 立规矩

Vibe Coding 指靠自然语言让 AI 直接产出代码的开发方式。它的问题出在质量：没有规矩的 AI 会返工、漏改、悄悄删代码、留下永久技术债。这一节先看事故长什么样，再看约束怎么注入才最稳。

四类典型事故

下面四类事故在 AI 协作中反复出现，根源是同一件事：约束没有进入上下文。

01

理解偏差返工

AI 拿到需求就开始写，写了 200 行才发现理解有偏差，回滚重来。更糟的情况是改了 7 个文件之后才发现思路错了，逐个 revert 成本极高。

02

选型漂移

不同对话里 AI 会选不同框架：今天 Express，明天 Fastify。数据库一会儿 MongoDB 一会儿 PostgreSQL。技术栈没有锁定，项目就在漂移中失去一致性。

03

善意破坏

AI 重构时会清理它认为多余的代码，事后才发现那段代码有用。善意的清理变成了破坏性操作。

04

永久技术债

要一个完整认证系统，AI 说先做简版登录、后续再加 OAuth。结果后续永远不会来，简版代码成了永久的技术债。

交互演示一 · 同一个需求，两条时间线

同一句「帮我做个登录」，在无规矩和有规矩两种模式下会走向完全不同的结局。点击「下一步」，两条时间线同步推进。

无规矩
有规矩
交互演示二 · 三种注入方式的存活测试

给 AI 传达约束有三种常见方式。点击切换，看同一条约束（「数据库用 PostgreSQL」）在三个时点是否还生效。

一个 Rule 文件长什么样

frontmatter 控制生效方式

---
alwaysApply: true   # 所有对话自动生效
---
# 开发约束与配置规范
以下是用户重要的约束，请务必严格遵循。

true 用于全局编码规范；false 用于写作规范这类按需引用的文件，避免污染编码对话的上下文。

xs_vibe_rules 的三个文件

  • rule-opensource.mdc：主开发规范，14 个章节覆盖全流程
  • writing-style.mdc：中文写作风格，按需手动引用
  • secrets.mdc：API Key 与凭据模板，占位符形式

使用时放入项目的 .cursor/rules/ 目录即可。

拿走这套规则
本节要点

规则的价值不在于多，每条都解决一个真实问题。AI 每反复犯一次错，就把它变成一条规则，这是整个专题的底层方法。约束靠不靠得住，看的是注入机制：写十遍「务必」，都比不过一个每轮自动加载的 Rule 文件。

Vibe Coding 方法论 · 第 2 节

四步流程：复述、PRD、确认、编码

把软件工程的需求确认环节搬进人机协作：AI 动手之前必须复述需求、写出 PRD、拿到明确许可。再加上批量修改断点和查重规则，把爆炸半径控制在动手之前。

交互演示一 · 五步流程模拟器

一个真实需求「帮我加一个导出报表功能」，走一遍完整流程。点击「推进一步」，注意第 4 步：你不点「批准」，AI 就不会写代码。

STEP 1
思考提问
STEP 2
复述需求
STEP 3
编写 PRD
STEP 4
等待许可
STEP 5
开始开发
点击「推进一步」开始
为什么必须给具体步骤

「请先确认理解后再编码」这句话太模糊。AI 会自己判断「我已经理解了」，然后直接动手。写明「写 PRD、等待许可」这类具体动作，AI 才会真的停下来。实际使用中，简单的一行改动 AI 会自己判断不需要 PRD，这套流程主要拦截多文件变更和新功能开发，也就是返工成本最高的那类任务。

交互演示二 · 批量修改断点

规则原文：「修改超过 3 个文件时，必须先列出修改计划并等待用户确认后再动手。」拖动滑块，改变本次要动的文件数，看断点什么时候触发。

2 个文件
修改计划的三要素
01

要改哪些文件

完整的文件清单。人先看范围对不对，再看内容。清单本身就能暴露「怎么这个需求要动配置文件」这类异常。

02

每个文件改什么

逐文件写清楚改动内容。避免 AI 借着一次需求「顺手」做无关的重构和清理。

03

改动之间的依赖关系

先改哪个、后改哪个、谁依赖谁。防止连续改一串文件后发现思路有误，回滚成本过高。

阈值可以按项目调整：3 个文件是作者项目里的经验值，谨慎的项目可以调成 1，快速原型可以放宽到 5。

新增功能前的查重规则

问题：AI 不知道项目里已经有轮子

AI 的上下文只有当前对话，它看不到三个月前另一个对话里写的工具函数。不加约束，同一个 formatDate 会被写四遍，每遍行为还略有不同。

规则：先搜索，再动手

  • 新增功能前，必须先搜索项目中是否已有类似实现
  • 搜索范围：相关目录的函数名、类名、工具方法
  • 找到已有实现时，优先复用或扩展
本节要点

断点要设在动手之前。复述和 PRD 拦截理解偏差，修改计划拦截连锁错改，查重拦截重复造轮子，三道关卡都比事后回滚便宜。

Vibe Coding 方法论 · 第 3 节

PlayGround：组件的试衣间

UI 功能直接写进页面，改一处影响一片，调一个按钮要把整个页面跑起来。解法是先做独立的组件 PlayGround：每个 UI 元素有单独的 demo，调好了再集成进正式页面。

交互演示一 · 现场体验一个迷你 PlayGround

下面就是一个最小的 PlayGround：左边是组件的实时预览，右边是参数控制。随便调，这里怎么改都不会影响页面上任何其他东西，这就是「隔离调试」。

组件预览 · PrimaryButton
参数控制

在 PlayGround 里调

刚才的每一次调整，影响范围只有这一个 demo。样式和业务逻辑互不干扰，调好的参数直接抄进正式组件，集成时它已经是成品。

直接写进页面会怎样

同样是调这个按钮：先把整个页面跑起来，登录、拉数据、切到目标状态，才能看到它一眼。样式和业务逻辑纠缠在一起，圆角改大了可能挤歪旁边的布局，牵一发动全身。

和 Storybook 的关系

思路一致，成本不同。Storybook 是行业标准方案，但配置太重，对 AI 辅助的快速原型项目属于 overkill。PlayGround 取其思路：用一个静态页面把所有组件 demo 排在一起，改组件不影响业务逻辑，调业务逻辑不搞乱组件样式，成本几乎为零。

三条维护规则
何时创建

涉及动效必须先建

涉及页面动效时，必须先创建静态页面 PlayGround，用于自由调整和测试组件，之后才允许写进正式页面。

同步更新

需求变了 demo 跟着变

需求变化后必须同步更新 PlayGround，保证 demo 始终反映组件的最新形态，别让它变成过期的摆设。

只增不删

取消的需求 demo 也保留

demo 组件只增改、不删除。功能需求取消了，对应 demo 也要留着，它是设计过程的历史存档，未来复活需求时直接捡回来用。

交互演示二 · 情景选择题：这条 demo 怎么处理

三个真实情景，点选你认为正确的做法，看判定和理由。

AI 对话项目的特殊要求

必须有对话测试页

项目涉及 AI 对话功能时，PlayGround 中必须实现简单的对话测试页面，脱离完整业务流程也能单独调一轮对话。

列出所有提示词

页面上必须列出项目用到的所有 Prompt。提示词是 AI 产品的核心资产，藏在代码字符串里没法调试，摊开在页面上才能快速对比和调整。

本节要点

组件先在试衣间里调好，再走上台。PlayGround 用一个静态页面的成本，换来组件与业务逻辑的双向隔离。

Vibe Coding 方法论 · 质量底线

样式收敛：一个按钮不要八套 CSS

让 AI 连着做十个功能，你会攒出八个长得差不多的按钮类。它不是不会复用，是每轮对话都不知道你已经有什么。这一节讲样式为什么会增殖、怎么收干净，以及哪些差异该留着。

复用优先design token技术债
交互演示一 · 亲手攒一堆按钮

下面模拟一个真实项目的迭代。每点一次「再加个功能」，就是你开一轮新对话让 AI 做一个页面。注意看它每次是怎么处理按钮的，以及底下四个数字怎么涨。

项目还是空的。点下面的按钮开始迭代。

第 0 轮：还没开始。
0按钮实现
0种主色
0种圆角
0行 CSS

八轮之后再看这堆按钮，你分不清该改哪个——这就是「散装」的手感。

别急着骂 AI，它是被环境逼的

重复造样式不是模型偷懒，是三个结构性原因叠出来的。看懂原因，才知道该在哪儿设闸。

看不见

你的 CSS 不在它眼前

新开一轮对话，上下文里只有你这次给的几个文件。项目里已经有 .btn-primary 这件事，它无从得知，于是按需求现写一个。

更省事

新写比读懂旧的便宜

读懂一套现有样式要把相关文件全看一遍，还得担心改了影响别处。新起一个类名零风险、零阅读成本，这是它的最优解，不是你的。

不敢碰

怕改坏，于是并列一份

需要一个带阴影的按钮时，它宁可写 .btn-primary-new 也不改原来那个——改动别人在用的样式属于高风险操作，它选择了安全但会增殖的做法。

三个原因都指向同一件事：它缺一份「我们已经有什么」的清单。把这份清单写进项目规则文件，它每轮都能看见，增殖才会停。这也是第 8 节把环境事实写进 Rule 的同一个道理，只不过这次写进去的是样式资产。

收敛四步：先盘点，再合并，最后设闸

已经乱掉的项目不要指望一把重构收干净。按下面四步走，每一步都能单独停下来验证。

1

盘点，先只看不改

让 AI 扫全项目的样式，产出一张重复清单：哪几个类在实现同一种控件、散落着多少个颜色值和圆角值。这一步不许动代码，你先看清欠了多少债。

2

定 token，把魔法数字收成档位

从盘点结果里挑出真正在用的值，定成一小套变量：主色、语义色、圆角两三档、间距四档、控件高度。档位要少，少才守得住。

3

分批合并，一次一种控件

先按钮，验证；再卡片，验证；再输入框。每批单独提交，出问题能单独回滚。收敛是等价替换，视觉上应该看不出变化——真需要改样子，那是另一个任务。

4

设闸，防它明天再长出来

把「写新样式前先搜 token 和公共组件，搜到就复用，搜不到才新建并说明搜过什么」写进规则文件。不设这道闸，你三个月后还得再收一遍。

交互演示二 · 该合并，还是合理差异

收敛最容易过头的地方是把该有的区别也抹平了。五组真实的样式差异，你判断哪些是手滑攒出来的、哪些是有理由的。

一条判据：差异有没有名字

判断该不该合并，只问一句：这个差异叫什么？叫得出名字的留着——「次要按钮」「危险操作」「触摸目标下限」「弹层比卡片高一档」，这些是设计决策，理由写进注释就行。叫不出名字的合掉——两个差 2px 的圆角、两个肉眼分不出的蓝，它们不叫什么，它们是当时随手写的。

审美篇讲一致性那节有句话是一个意思：差异不是罪，没理由才是。那一节从设计侧讲怎么定变量表，这一节从代码侧讲已经散了怎么收回来。两节配着看，一节给你标准，一节给你手术方案。

配套阅读：审美工程 · 一致性：系统感从哪来（token 该怎么定）· 上一节 PlayGround（收敛完的组件放哪儿调）

收敛时最容易踩的三个坑

一把梭全量重构

让 AI「把全站样式统一一下」，它会给你一个改了 60 个文件的 diff，你审不完也不敢发。永远按控件分批。

顺手改视觉

收敛过程中它常「顺便优化」一下圆角和配色。这会让你分不清页面变样是合并出的 bug 还是它的审美发挥。收敛只做等价替换。

token 定太细

定出 12 档圆角、9 种灰，等于没定——下次它还是要挑，挑就会挑错。档位少到「几乎没得选」才有约束力。

本节要点

AI 不会复用你没告诉它存在的东西。样式增殖的根因是它每轮都失忆，所以解法有两半：已经乱的按控件分批收进 token，往后的用一条规则挡住——先搜再写。顶上那份 Skill 就是这两半的可执行版本，复制给你的 Agent，它会先给你一张欠债清单，而不是直接开始改。

Vibe Coding 方法论 · 第 4 节

注释三要素与代码保护

AI 写的注释多是功能复述，三个月后回来看代码，想不起当初为什么这样实现。这一节给注释立结构，也给「删代码」立规矩。页面里有两个可动手的演示。

问题在哪

代码只能表达「做了什么」。为什么存在、为什么这样实现、调用时要注意什么，这些信息只有写进注释才能跨时间留存。「写好注释」四个字 AI 执行不了，必须给出固定结构和示例。

三要素结构
1

背景

这个函数为了解决什么业务问题、在什么场景下被调用。没有背景，读代码的人只能看到实现，看不到它为什么存在。

2

设计意图

为什么这样实现，选择这种方案的理由，以及放弃了哪些备选方案。git log 里找不到这些，注释是唯一载体。

3

关键约束

调用方须知：副作用、依赖关系、边界条件等非显而易见的注意点。少了这条，下一个调用者就会踩坑。

交互演示一 · 同一个函数，两种注释

点击切换同一个 merge_chat_history 函数的两种注释写法，对比它们留下的信息量。

chat/history.py
def merge_chat_history(existing: list, incoming: list) -> list: """ 合并两个聊天记录列表，返回合并后的结果。 """ ...
这条注释复述了函数名，读一眼代码就能得到同样的信息。三个月后想知道「为什么以服务端为权威」「为什么丢弃 system 消息」，什么线索都没有。
交互演示二 · 删不删，你来判

三个真实情景，判断 AI 应该怎么做。点选项即时判定，并给出对应的规则依据。

情景 1 · AI 在重构时发现一段兼容旧数据格式的代码，它觉得「看起来没用」，想顺手删掉。
情景 2 · 重构后实现方式变了，原有的「设计意图」注释已经和代码对不上了。
情景 3 · AI 觉得 fetch 比 axios 更轻量，想把项目里的 axios 换成 fetch，顺手改掉 package.json。

已答对 0 / 3 题

两条保护规则

注释保护

重构时禁止以「注释太长」「代码自解释」「顺便清理」为由删除背景和设计意图注释。实现变了导致注释不准确时，必须同步更新内容。判断标准只有一条：未来接手的人，没有这条注释还能理解当初为什么这样做吗？

代码删除声明

删除任何已有功能代码前，必须明确告知用户并说明理由，禁止以「顺手清理」「看起来没用」为由静默删除。认为某段代码该移除时，先标注 // TODO: 建议移除 - 原因：xxx，拿到许可再删。

配套规范 · 错误处理

禁止空 catch。所有 try/catch 和错误分支必须有实质性处理：日志记录 + 用户可见的错误提示，或合理的降级逻辑。仅 console.log(e)、pass、// ignore 都属于静默吞错，一律不允许。

本节要点

注释的使命是留存代码无法表达的决策信息。三要素结构让 AI 写得出来，保护规则让它删不掉，两者配合才能跨越时间。

Vibe Coding 方法论 · 第 5 节

调试铁律：先 Log 再改码

AI 遇到报错的第一反应是猜一个原因改改看，不行再猜一个。这一节立最核心的一条规矩：禁止猜测性修复。下面两个演示，亲手对比两条修 Bug 路径。

核心条款

禁止猜测性修复。无法确认根因时，必须先通过 Log、断点或测试脚本验证假设，禁止「试着改一下看看」。后端在终端打详细日志，前端在浏览器 Console 打日志，无论什么问题，第一步都是加 Log。

交互演示一 · 同一个 Bug，两条修法
Bug 现场：聊天输入框在中文输入法下，用户按回车确认候选词时，半截拼音被当成消息直接发了出去。

点击一条路径，观察修复过程。右侧计数器记录轮数和累计改动行数。

0
修复轮数
0
累计改动行数
待演示
Bug 状态
选择上方任意一条路径开始

猜测性修复 · 战绩

尚未演示

先 Log 再改 · 战绩

尚未演示
交互演示二 · 修复前三问自查器
新 Bug 到达：用户删除一条聊天记录后，会话列表上的未读数没有更新。

规则要求修 Bug 前必须回答三个问题。依次点开三问，全部看完才解锁「开始修复」按钮。

链路是 删除消息 → 更新会话摘要 → 重算未读数 → 推送列表刷新。排查发现「重算未读数」只在收到新消息时触发，删除路径根本没有走到它。只盯着报错点看不到这条链路。
重算时机改动会波及 会话列表、App 角标、多端消息同步 三处。理解上下游依赖再动手，避免按下葫芦起了瓢。规则同时建议：优先启动 SubAgent 并行调研影响范围，确认安全后再修改。
有。「标记已读」和「撤回消息」 走的是同一条更新链路，同样漏了触发重算。同一个坑往往不止一处，这次一起修干净。

前置调研完成，允许动手。修复完成后还有最后一步：声明影响范围，让人知道该回归测试哪些地方。

⚡ 影响范围：会话列表未读数、App 角标、标记已读、撤回消息
交付线 · 两道硬性检查

禁止 Mock 绕过真实 AI 接口

凡涉及 AI 模型调用的功能，交付前必须确认接口真的能访问。用户没给 API Key 时必须停下来要，禁止硬编码假响应或本地模拟绕过真实调用。Key 到位后先发一次测试请求验证可用性，再继续开发。

单元测试不过，不得交付

核心业务逻辑、API 接口、数据处理函数、边界条件都要覆盖。测试文件统一放 tests/，命名 test_{模块名}.py，Python 项目用 pytest。调试用的临时脚本，用完自行删除。

本节要点

证据先行。加 Log 的 2 分钟，买断的是猜错三轮的返工和被掩盖的根因。修复后用 ⚡ 影响范围：XXX、YYY、ZZZ 的格式声明影响面，交付前过真实接口和单元测试两道线。

Vibe Coding 方法论 · 第 6 节

不接受分期交付

你要一个完整的认证系统，AI 说「先做一个简版的用户名密码登录，后续再加 OAuth」。后续永远不会来。这一节用两个演示，看清「先做简版」的完整生命周期，并练习正确的回应方式。

动机分析

实践中 AI 说「先做简版」往往与复杂度无关，它想快速给你一个能跑的东西来换取正反馈。「先用临时方案」「暂时 Mock」「简单处理一下」背后是同一个模式。打破这个模式后，AI 反而会更认真地分析完整方案。

交互演示一 · 技术债时间线播放器

点击播放，看「先做简版」的登录模块在 90 天里怎么变成永久技术债。上方两个数字会随时间线一起变化。

0
依赖简版接口的模块数
0.5×
补全成本（相对当初直接做完整版）
第 1 天

简版上线

用户名密码登录能跑了，AI 承诺「OAuth 后续再加」，你也觉得挺合理。

此刻补全只要 0.5 倍成本，可惜没人回头
第 30 天

后续没有来

新需求源源不断，没人回头补 OAuth。会话、权限、支付、通知 4 个模块开始直接依赖简版接口。

依赖 +4 · 补全成本升到 3 倍
第 90 天

成为永久技术债

想补全时发现依赖已经长死，9 个模块与简版耦合，重构成本高过重写。简版成了永久版。

依赖 +9 · 补全成本 8 倍，超过重写
交互演示二 · 对话分支模拟

AI 提出了分期方案，你的回应决定了 90 天后的结局。两个分支都可以试。

与 AI 的对话 · 需求：完整的认证系统
分支 A 的结局：简版换来了当天的正反馈，代价是 90 天后一笔高过重写的技术债。「后续再优化」的后续没有来。
分支 B 的结局：AI 给出了完整方案、真实工作量和前置决策清单。选择权回到人手里：要不要拆、怎么拆由你决定。
规则与替代方案

禁止的做法

禁止以任何理由简化实现：「先用临时方案」「后续再优化」「暂时 Mock」「简单处理一下」全部不接受。也禁止 AI 主动规划分期、MVP、阶段一二三。每次实现都必须是完整、正确、没有代码债的方案。

替代的做法

评估一个功能只需回答：完整做下来需要什么、有多复杂。确实太复杂时，明确列出「需要你先做哪些前置决策」，把选择权交还给人。已知有缺陷的方案，直接给正确版本，别先做一个将就的。

适用边界

大型项目里这条规则可能显得激进：一个功能真需要 2000 行代码时，一次写完不现实。此时正确动作依然成立，让 AI 给出完整方案和真实工作量，由人决定是否拆分、怎么拆分。拆分是人的决策，降级是 AI 的自作主张，两者的区别就是这条规则的核心。

本节要点

「后续再优化」的后续永远不会来。把选择权收回来：AI 负责给出完整方案和真实代价，拆不拆、怎么拆由人决定。

VIBE CODING 方法论 · 第 7 节

三份文档与方法论沉淀

做了 30 个功能，三个月后想查「这个功能什么时候加的、当初为什么这样设计、中间改过几次方案」，翻遍 git log 也找不到。解法是让 AI 按严格模板维护三份文档，再加一份自动沉淀的方法论手册。本页两个演示都可以动手操作。

核心分工：FEATURES 回答「这个功能怎么来的」，CHANGELOG 回答「这次改了什么」，RELEASE_NOTES 回答「用户得到了什么」，METHODOLOGY 回答「我们是怎么想的」。四个问题各有归处，决策才能跨越对话存活。

四份文档各管一个维度
docs/FEATURES.md

功能的完整生命周期

功能点的唯一事实来源。状态流转 🟡 规划中 → 🔵 开发中 → 🟢 已完成 / ⚪ 已取消，每个功能带「历史沿革」，记录初始需求、方案变更及原因、最终实现。取消的功能也不删，标 ⚪ 并注明原因。

docs/CHANGELOG.md

每次改动的技术细节

按时间倒序，每条用表格记录问题/需求、根因/方案、改动范围、影响面、状态，类型标签 BUG / FEAT / REFACTOR / PERF / DOCS。写之前必须读系统时间，禁止凭记忆填时间戳，禁止积压补写。

docs/RELEASE_NOTES.md

用户能感知的变化

面向真实用户，语言风格与 CHANGELOG 完全不同。每条描述必须能回答「这对我有什么用」。红线：禁写调试功能、技术细节和用户无感知的改动。

docs/METHODOLOGY.md

产品决策与品味

AI 主动识别对话中的产品思路、决策逻辑和取舍偏好，提炼后直接写入，新对话自动继承。四段结构：产品原则、设计决策记录、用户体验偏好、反模式。

交互练习一 · 文档分诊

项目里每天都会产生各种信息，分诊能力决定文档体系能不能跑起来。下面逐条给出 8 条真实信息，判断每条该写进哪份文档。

第 1 / 8 条 得分：0
交互演示二 · 历史沿革是怎么长出来的

FEATURES 里每个功能都带一条「历史沿革」。它靠状态流转自动生长：每次状态变更、方案调整都追加一条带日期的记录。点击按钮，亲手把一个功能从规划推到上线。

夜间模式
简述：为长时间使用的用户提供暗色界面，降低视觉疲劳
🟡 规划中
历史沿革

记录里的日期读的是你设备的系统时间。规则原文要求：时间必须读取系统当前时间，不能凭记忆填写；方案没变过也要写一条「初始需求」。

CHANGELOG 表格模板

每条改动用固定字段的表格记录，AI 按格填写就行，不需要每次想该写什么。

## YYYY-MM-DD HH:MM

### [类型] 标题        类型：BUG / FEAT / REFACTOR / PERF / DOCS

| 字段       | 内容                                       |
|-----------|--------------------------------------------|
| 问题/需求  | 触发这次改动的原因（用户反馈 / Bug 表现 / 新需求）|
| 根因/方案  | Bug 填根因分析，功能填技术方案概述            |
| 改动范围   | 涉及的文件或模块列表                         |
| 影响面     | 这次改动可能影响哪些已有功能                  |
| 状态       | ✅ 已完成 / ⏳ 进行中 / ⚠️ 需观察             |
RELEASE_NOTES 内容红线
❌ 禁止出现
  • Debug / 调试相关功能
  • 技术实现细节：模块名、文件路径、重构
  • 用户无感知的改动
  • 开发者术语和技术原理解释
✅ 只写这些
  • 用户能感知到的变化，每条能回答「这对我有什么用」
  • 新功能：一句话说明用户能做什么新事情
  • 修复：之前什么问题，现在解决了
  • 每条不超过 3 句话，版本号遵循 SemVer
METHODOLOGY 的结构与写入原则

四段结构

  • 产品原则：反复出现的核心信念和产品理念
  • 设计决策记录：[日期] 决策内容，附理由与上下文
  • 用户体验偏好：对 UI/UX 的品味、倾向、审美标准
  • 反模式：明确拒绝过的方案，附拒绝理由

写入原则

  • 提炼本质，同类合并，新条目标注日期，避免照搬对话原文
  • 不记技术实现细节（那是 CHANGELOG 的事），不记一次性临时决定
  • 触发时机：用户解释了「为什么这样做」、否决了方案并给出理由、表达了明确的 UI/UX 偏好、复盘时总结了经验
  • AI 识别到就直接写入，写完简要告知，无需每次征求许可

为什么放在仓库里：设计决策写在 Notion 或飞书里也没用，AI 读不到外部文档。放在项目仓库内的 Markdown 文件是唯一能让 AI 自动获取上下文的方式。

VIBE CODING 方法论 · 第 8 节

把环境事实写进 Rule

每次新开对话，AI 都不知道该调哪个模型、超时设多少、项目用什么框架。把这些环境事实一次性写死在 Rule 里，相当于给 AI 一份预填好的 .env 说明书，每轮对话自动带入。本页两个演示都可以真实操作。

为什么是 Rule：把配置写在 .env 里让 AI 自己读，它不一定每次都主动读；写在对话里，对话一长就被截断遗忘。Rule 在每轮对话开始前就被加载进上下文，是最稳的注入方式。

交互体验一 · isComposing，用中文输入法亲自试

中文输入法确认候选词时会触发 Enter，只判断 e.key === 'Enter' 的输入框会把半段内容直接发出去。AI 训练数据里 isComposing 覆盖率不高，不写进 Rule 就一定会忘。切换到中文输入法，在下面的输入框里打几个字试试。

真实体验区
isComposing：false（输入法组合中会变为 true）
按键记录会出现在这里。先打一段拼音按回车选词，再直接按一次回车，对比两次的判定结果。英文键盘用户可以直接打字回车，观察 false 的情况。
标准写法
const handleKeyDown = (e: React.KeyboardEvent) => {
  if (e.key === 'Enter' && !e.shiftKey
      && !e.nativeEvent.isComposing) {
    e.preventDefault()
    handleSend()
  }
}
  • isComposing 为 true：输入法正在组合中，回车只确认候选词，不触发发送
  • isComposing 为 false：普通键盘直接输入，回车正常发送
  • 规则原文：禁止只判断 e.key === 'Enter' 而不检查 isComposing
交互练习二 · 这个场景该用什么格式

数据格式三分法：三种格式各管一个领域，互不混用。点击场景，再选一个你认为合适的格式。

❌ JSON 的 escape hell：字符串里再套 JSON
{
  "tool": "send_message",
  "arguments": "{\"channel\": \"dev\",
    \"payload\": \"{\\\"title\\\":
      \\\"发布提醒\\\", \\\"body\\\":
      \\\"v1.4 已上线\\\"}\"}"
}
✅ 同样的内容，XML 版本
<tool_call name="send_message">
  <channel>dev</channel>
  <payload>
    <title>发布提醒</title>
    <body>v1.4 已上线</body>
  </payload>
</tool_call>

JSON 版每层嵌套翻一倍反斜杠，LLM 逐 token 生成时极易配错括号和引号。XML 标签闭合直观，模型出错率更低。

进度：0 / 3 个场景

模型配置：一次写死，轮轮生效
超时

图像生成至少 120-180 秒

图像 API 经常因为默认 30 秒超时失败，AI 还会反复尝试相同的错误配置。HTTP 客户端的超时值写进 Rule，一次解决。

代理回退

网络失败先挂代理重试

网络请求失败时必须尝试代理重试（默认 127.0.0.1:7890），仍失败才向用户报告，禁止跳过代理直接报错。

流式

前端可见响应必须流式

前端可见的所有大模型响应必须用 Streaming 返回，后端内部调用才允许非流式。

技术栈锁定与品味规则

选型是人的决策

  • 后端 FastAPI、前端 React + Tailwind + Vite、数据库 SQLite、向量库 Chroma
  • 一旦定了就不再讨论替代方案，AI 的职责是在确定的栈内把代码写好
  • 端口避开 5000，从 8000-9000 随机分配，多项目同开也不冲突

图标与细节规范

  • 禁止用 emoji 做按钮图标，图标必须用 SVG
  • 看产品调性选图标集：SaaS 用 Lucide，温暖调性用 Tabler Icons
  • 图标直接下载到本地使用，不依赖 CDN

补充说明：只用 GPT 系列的项目可以把工具调用改回 JSON，它的 function calling 原生就是 JSON。「Agent 用 XML」是多模型混用场景的最大公约数选择，Claude 系模型在 XML 格式上表现更稳定。

VIBE CODING 方法论 · 第 9 节

破坏性操作的三道闸

发版时以为只改了 A 功能，实际 diff 里混进了上周调试 B 的临时改动，半成品代码进了生产环境。数据库、配置、部署这些不可逆操作，必须在执行前设闸。下面两个演练都可以动手操作。

核心原则：不可逆操作的安全感来自闸门。备份拦数据损失，回退方案拦无法恢复，diff 审查拦带病发版，三道闸都设在执行之前。

三道闸总览
GATE 1 · 备份

数据库改动先备份

备份放项目根目录 backups/，命名带时间戳。未备份不得执行任何 migrate、drop、alter、delete 操作。成本是一行命令，赌的是整库数据。

GATE 2 · 回退

不可逆操作先说回退方案

回退方案要回答三件事：如何恢复到操作前的状态、需要哪些备份文件、预计恢复耗时。说不出这三件事，说明操作还没想清楚。

GATE 3 · 审查

发版前做 diff 审查

把「我以为我改了什么」和「我实际改了什么」拆开比对。SubAgent 独立分析 diff 与 Release Notes 的偏差，有风险就暂停发版。

交互演练一 · 发版 diff 审查模拟器

你是本次发版的 reviewer。Release Notes 只写了一件事，但实际 diff 有 7 个文件。逐个判断每个文件的改动「符合预期」还是「存在风险」，全部标完后生成审查报告。

RELEASE_NOTES.md · v1.4.0

✨ 新增夜间模式：可以在设置里切换暗色界面，长时间使用不再刺眼。

已标记 0 / 7 个文件
SUBAGENT DIFF REVIEW · v1.3.2 → HEAD
交互演练二 · 这个操作要过哪几道闸

选择一个操作类型，逐项勾选它要通过的闸门，然后尝试执行。漏了哪项，就会看到对应的后果。

先勾闸门，再执行
规则原文要点

备份命令（SQLite 示例）

# 任何涉及数据库结构或数据的改动，执行前必须先备份
cp database.db backups/database_$(date +%Y%m%d_%H%M%S).db

备份文件命名格式：{原文件名}_{YYYYMMDD_HHMMSS}.db，统一放项目根目录 backups/ 下。

发布通道

  • 代码发布、版本发布、服务器部署必须通过 GitHub
  • 服务器通过 git pull 或 CI/CD 流水线拉取代码
  • 紧急热修复可以例外，事后必须补 commit 同步
  • 在用户明确确认之前，打 tag、push、部署全部禁止

凭据管理

  • 所有凭据通过环境变量或 secrets 管理
  • 禁止硬编码在代码或配置文件中
  • Key 一旦进入 git 历史等于永久泄露，只能作废重发

设计意图：Release Notes 描述的是预期改动，实际 commit 里可能混入无关调整甚至误删。正规团队靠 CI/CD 加 PR review 拦这个问题，独立开发者往往跳过 review 直接 push，diff 审查规则等于让 SubAgent 充当 reviewer。

VIBE CODING 方法论 · 第 10 节

长对话锚定与写作规范

对话开头说了用 PostgreSQL，聊到 30 轮 AI 突然建议 SQLite，因为早期约定已经被上下文窗口挤掉了。这一节讲两件事：怎么对抗长对话的认知漂移，以及怎么让 AI 写出的中文摆脱 AI 腔。两个交互演示，动手拖一拖、点一点。

课程目标

理解漂移成因

上下文窗口截断和长文本尾部注意力衰减，让 AI 忘掉早期约定。即使是 200K token 的模型，注意力在长文本尾部的衰减也真实存在。

会设 checkpoint

超过 10 轮后，关键操作前强制复述当前目标和关键约束，用周期性锚点对抗遗忘。

消灭 AI 腔

用可搜索的违禁模式清单和自查流程，替代「请写自然流畅的中文」这类空话。

交互演示一 · 上下文漂移模拟器

下面是一个模拟对话窗口，假设上下文窗口只装得下最近 20 轮。第 1 轮定了「用 PostgreSQL」的硬约束，拖动滑块增加对话轮数，观察这条约定的命运。然后切换到「开启锚定」，看同样 30 轮之后有什么区别。

第 1 轮 · 约定刚刚立下
第 1 轮

灰色划线的消息表示已滑出上下文窗口，AI 看不见它们了。本演示假设窗口容量为最近 20 轮。

锚定规则的三个要点

复述有固定格式

修改代码、修改配置、部署之前，AI 必须先回顾并复述当前目标和关键约束，格式固定，便于扫一眼确认。

📌 当前目标：XXX | 关键约束：YYY

目标以最新一次为准

用户在对话中修改了目标时，复述要以最新一次为准，并明确标注变更，避免新旧目标混在一起。

并行编辑前先重读文件

多个 SubAgent 或多次编辑涉及同一文件时，后续修改必须先重新读取文件当前状态，禁止基于缓存或记忆中的旧内容编辑。这是多 Agent 时代的「乐观锁」。

交互演示二 · AI 腔检测器

下面这段文案由 AI 生成，读起来处处透着一股 AI 腔。点击「开始检测」，按 writing-style.mdc 的自查表逐条扫描违禁模式；再点击每一处红色高亮，查看它违反了哪条规则、应该怎么改。

待检测文案（教学样本，故意写得很「AI」）
两个设计细节

其一，「请用自然流畅的中文」没有用。AI 认为的自然和你认为的自然可能完全不同，必须给出具体的违禁词和违禁句式列表，AI 才能精确执行。交付前逐条搜索违禁模式，发现一处改一处，完成后注明已完成自查，System Prompt 里的违禁句式同样要改。

其二，写作规范独立成文件并设 alwaysApply: false，只在写文案或 Prompt 时手动引用，避免污染编码对话的上下文。

Takeaway

锚定对抗遗忘，清单对抗含糊。长对话里靠周期性复述保住约定，写作上靠可搜索的违禁模式保住风格。两者的共同点是把模糊期望变成可执行动作。

VIBE CODING 方法论 · 第 11 节 · 收官

规则的价值：每条解决一个真实问题

14 个章节走完了。这套规则的来源只有一个：每发现一次 AI 反复犯的错误，就加一条规则。收官这节把全景图摊开，再用一个自查向导帮你把它改造成你自己的。

交互一 · 14 章规则全景图

14 章规则归入五大板块。点击任意板块，展开对应章节明细、一句话说明，以及它在本专题第几节课里讲过。

共同底层：把模糊期望变成可执行的具体动作。「注意质量」执行不了，「删除代码前必须显式声明」才执行得了。
使用方法 · 三步装进项目

STEP 1放入 rules 目录

把 .mdc 文件放进项目的 .cursor/rules/ 目录，Cursor 会自动识别。

STEP 2配置生效方式

frontmatter 里的 alwaysApply 设 true 全局生效，设 false 则需手动 @ 引用，写作规范适合后者。

STEP 3替换环境事实

把模型配置、技术栈、端口规则换成你自己的选型，secrets 文件填占位符并排除出 git。

交互二 · 适配四步自查向导

这套规则并非拿来即用的模板。回答下面 4 个问题，对应「删、换、调、补」四个动作，走完生成一份你的定制建议清单。

适配自查向导 第 1 步 / 4
交互三 · 11 节课回顾

专题一共 11 节课。点击卡片翻开，看每节课的一句话版本。

结课作业 · 发布你的第一版 Rules

60 分钟 · 提交物：你自己的 rules 仓库。从 xs_vibe_rules 出发，按删、换、调、补四个动作产出你的第一版规则文件；在一个真实项目里用满一周，记录哪些规则被触发、哪些从没生效；删掉从没生效的，把新踩的坑写成新规则，然后开源你的版本。

Takeaway

AI 负责快，规则负责稳。规则的价值不在于多，每条都解决一个真实问题。照搬 14 章不如精选 5 章，规则和代码一样，没人维护就会腐烂。

1 / 12