VibeCoding长期项目防跑偏完整教程：规则文件、任务拆解与验收防线

在 Vibe Coding 的起步阶段，一段对话写一个小脚本、一个下午做完一个小工具，几乎不会遇到流程问题。当项目从一次性脚本成长为维护数月的真实系统，事故率会陡然上升：AI 每次新会话都像第一次进门的实习生，大需求整份扔进去消化不良，改 A 坏 B 的功能降级防不胜防。本教程把长期项目中最高频的三类事故与对应的三套解法放在一起讲：用项目规则文件让 AI 记住项目约定，用 spec 驱动把大需求拆成 AI 一次能消化的任务，用验收防线守住每一次改动不伤及既有功能。读完后你将得到一套可直接落地的长期项目防跑偏工作流。

前置教程

如想快速开始学习本教程，你可能需要先完成以下前置教程：

• VibeCoding 从 MD 开始，本教程的前作：前作讲解用 Markdown 写需求与提示词的基础范式，本教程把该范式延伸到长期项目的完整工作流。
• 一个好的需求文档应该是什么样的？，第 3 章任务拆解的输入就是需求文档，先掌握它的结构标准。
• 你的第一次AI编程的目标应用是MVP还是现有庞杂系统的改造，立项选型发生在拆解与执行之前，两条路线在本教程的防跑偏框架下都适用。
• Context上下文及相关概念详解，理解上下文窗口的机制与限制，是第 2 章项目规则文件的理论基础。
• DeepSeek Harness 安装与使用教程，DeepSeek Harness 是本教程实战示例使用的 AI 编码工具。

1. 单次对话式 VibeCoding 的三类事故

1.1 事故随项目规模出现

Vibe Coding 的事故有明显的规模阈值。项目只有一个文件、一次会话能从头写到尾时，AI 全程看得见所有代码，出错最多是单个功能写歪，改一遍就好。当项目出现以下任一特征，事故形态就会升级：

下面三类事故覆盖了长期项目中的绝大多数翻车场景，每一类都有对应的系统性解法。

1.2 事故一：AI 不了解你的项目

最典型的表现：每次开新会话，你都要重新解释一遍项目用什么技术栈、代码放在哪个目录、配置怎么写。解释得全，AI 干得对；哪次偷懒少说了一句，AI 就按自己的默认习惯来。

一个常见场景：项目约定所有配置写进 config.py 直接赋值，你某次只说了"加一个发送邮件的功能"，没有提配置约定，AI 顺手就写出了读取环境变量的代码。功能能跑，但项目的配置方式被破坏了，后续维护的人要同时应付两种配置风格。

这类事故的根因在 Context上下文及相关概念详解 中讲得很清楚：模型没有跨会话记忆，上下文窗口里没有的信息等于不存在。你脑子里的项目约定，AI 一概不知，除非把它变成上下文窗口里的文字。对应解法是第 2 章的项目规则文件。

1.3 事故二：大需求一口吞不下

第二个典型表现：把一份完整需求文档直接扔给 AI，要求它一次性实现。结果通常是三种之一：

• AI 只实现了需求的一部分，自认为已经完成；
• 每个部分都实现了一点，全都浅尝辄止，拼不成能用的功能；
• 做到中途上下文窗口耗尽，AI 开始遗忘开头的约定，后半段自由发挥。

这类事故的根因是任务粒度与对话容量不匹配。一次对话的注意力有限，需求越大，摊到每个子任务的注意力越少。对应解法是第 3 章的 spec 驱动：把需求文档拆成 AI 一次能消化的任务清单，逐个喂、逐个验收。

1.4 事故三：改 A 坏 B 的功能降级

第三类事故最隐蔽：你让 AI 给文章列表页加一个搜索框，AI 为了实现搜索重写了数据加载逻辑，搜索框工作正常，分页功能悄悄坏了。你验收时只盯着新功能看，两周后有人告诉你翻页翻不动了，此时已经记不清是哪次改动引入的问题。

功能降级有三个特征，让它成为长期项目的头号敌人：

• 静默：降级不报错，页面照常打开，只是某个行为不对；
• 延迟暴露：出问题的时刻与引入改动的时刻可能相隔数天；
• 难以归因：中间隔了几十次提交，无法凭记忆定位引入点。

这类事故的根因有两个：AI 以完成眼前任务为唯一目标，默认没有保护既有行为的约束；人验收时天然只看增量，旧功能处于验收盲区。对应解法是第 4 章的验收防线。

1.5 三类事故对应三套解法

三套解法各自独立成章，组合起来才构成完整的防线：

三套解法的生效顺序有讲究：规则文件立项时写一次，长期生效；任务清单每个需求拆一次，覆盖整个开发期；验收防线贯穿每次改动。三者叠加后，AI 在长期项目里的每次会话都有约定可依、每个任务体量可控、每轮改动可验证可回退。

2. 项目规则文件：让 AI 记住项目约定

2.1 从口头解释到文件沉淀

对付事故一最直觉的做法是每次会话开头口头解释项目，这个做法有两个致命缺陷：解释内容靠记忆，漏说多少全凭运气；解释无法复用，每个新会话、每个新参与的 AI 工具都要重来一遍。

规则文件方案的思路是把项目信息固化为文件：把项目结构、编码规范、禁做事项写成一份规则文件放在项目根目录，AI 编码工具在每个新会话读取这份文件，效果等同于每个新会话开场都有一份标准化的项目说明。文件进版本库，团队里每个人、每个工具读到的都是同一份约定。

2.2 规则文件的种类与加载方式

项目级规则文件在不同工具中有不同的文件名约定：

规则文件由谁加载，取决于工具的支持程度。Codex 等遵循 AGENTS.md 约定的工具在会话启动时自动读取项目根目录的规则文件并注入上下文；本教程使用的 DeepSeek Harness 没有自动加载机制，做法是把 AGENTS.md 放在项目根目录作为唯一约定来源，每次新会话开场先指令它读取该文件，效果等同：

实际使用中建议只维护一份主规则文件（推荐跨工具通用的 AGENTS.md），使用自有规则文件的工具从主文件摘引内容，避免两份文件各自演化、内容漂移。

一份实用的规则文件由三个部分组成：项目结构说明、编码规范、禁做事项。下面依次展开。

2.3 项目结构说明：让 AI 知道东西放在哪

项目结构说明回答 AI 的第一个问题：这个东西应该放在哪、去哪找。写法要点是目录加一句话职责，只写 AI 干活需要知道的信息：

## 项目结构

| 路径 | 职责 |
|------|------|
| src/api/ | 全部 HTTP 接口，按资源命名文件（users.py、articles.py） |
| src/models/ | 数据库模型定义，一个表一个文件 |
| src/services/ | 业务逻辑层，接口层禁止直接写 SQL |
| config.py | 全部配置项，直接赋值，不使用环境变量 |
| tests/ | 测试文件，与被测模块同名加 test_ 前缀 |
| scripts/ | 一次性运维脚本，不参与服务运行 |

两个常见误区要避开。第一个误区是把完整目录树照抄进来，几十个目录每个都写，AI 反而抓不住重点，只写有约定含义的目录。第二个误区是只写目录不写入口，关键入口文件（如 main.py 是服务启动入口、cli.py 是命令行入口）值得单独点明。

2.4 编码规范：把约定写成可判定的条款

编码规范部分最考验写作功力。空话条款与可判定条款的区别，直接决定规则文件有没有用：

判定方法很简单：读完一条规范，问自己"换个 AI 来，能不能仅凭这句话判断一段代码违不违反它"。能判断的留下，不能判断的改写到能判断为止。

除了编码风格，示例代码约定也值得写进这一部分：示例项目放哪、依赖用什么方式安装、代码块里允不允许出现装饰性分隔注释等。这些约定在纯人工团队里靠口口相传，在 AI 协作里必须落在纸面上。

2.5 禁做事项：负面清单比正面要求更管用

规则文件里价值最高的部分是禁做事项。原因在于 AI 的默认倾向是多做：你让它加功能，它顺手重构；你让它修一处报错，它顺手升级依赖、调整目录。正面规范管住风格，负面清单管住动作。

一份经过实战检验的负面清单通常包含以下条目：

## 禁做事项

- 禁止删除或绕过任何既有功能，即使它看起来冗余；发现疑似废弃代码，在对话中提出，由人确认后处理
- 禁止修改任务范围之外的文件，改动前先列出计划触碰的文件清单
- 禁止升级任何依赖的版本，禁止新增第三方依赖
- 禁止修改数据库表结构与既有字段，新增字段需在任务对话中确认
- 禁止修改配置文件中的既有配置项
- 禁止引入新的代码风格、新的状态管理方式、新的目录约定

负面清单是活的文档：每次 AI 闯了新类型的祸，把对应的禁令补进来。这份清单会随项目成长越来越贴合项目的实际风险点。

2.6 实例拆解：一份真实规则文件的关键段落

下面摘录一份正在真实仓库中使用的 AGENTS.md 的四个关键段落，逐一拆解每段回答了 AI 的什么问题。这个仓库维护着上百篇教程文档与配套示例代码，由 AI 编码工具长期参与维护，规则文件就是它和人之间的协作契约。

第一段，仓库定位：

**仓库类型**：AI/ML 中文教程课件集合（Markdown + Python 示例代码），非软件项目

一句话告诉 AI 这里管什么：AI 不会把教程仓库误当成软件项目去做构建部署，也不会把示例代码当成生产代码去优化性能。

第二段，结构总览：

| 目录 | 主题 | 关键内容 |
|------|------|---------|
| 3.开发与运行环境/ | 开发环境搭建 | Git、VS Code、Node.js/npm、WSL2 |
| 5.RAG检索增强生成/ | RAG 与检索增强 | Embedding/Rerank/向量数据库 |

用表格给出全景地图，AI 接到"在 RAG 目录下新增一篇教程"的任务时，能准确定位到正确位置，并参照同目录既有教程的风格。

第三段，成文规范：

- **语言：** 所有教程均使用简体中文（zh-CN）编写。
- **表情符号：** 全文不使用任何 emoji 表情符号。
- **图表：** 结构/流程图一律使用 Mermaid 代码块，方向优先使用横向布局。

这几条直接约束产物的形态。没有这段，AI 写出的教程会混入英文表述、emoji 装饰和 ASCII 字符画，每一篇都要人工清洗。

第四段，示例代码约定：

- **数据库配置：** 统一使用 ai_ml_tutorial 数据库名，root/root 用户密码。
- **代码注释：** 简洁注释，不使用装饰性分隔线。
- **依赖管理：** requirements.txt 锁定版本。

示例代码的一致性完全靠这几条维持：上百个示例项目用同一个数据库名、同一种注释风格、同一种依赖管理方式，读者在任何一篇教程里看到的都是同一套习惯。

对照来看，这四段分别回答了 AI 的四个问题：这里是什么地方、东西放在哪里、产出的东西长什么样、代码按什么规矩写。你的规则文件无论什么规模，都可以按这四个问题自查有没有遗漏。

2.7 规则文件的维护与进化

规则文件本身也是项目资产，需要维护：

• 进版本库：规则文件与代码一起提交、一起审查，改了规范要有记录；
• 随代码演化：新增了 services/ 层，结构说明同步补上；废弃了某个脚本目录，对应条目删除；
• 事故回流：第 4 章会讲到，每次功能降级复盘后，把教训写成禁令补进负面清单，同一个坑不踩第二次；
• 定期做减法：过期的条款比没有条款更糟，AI 会认真执行每一条规则，包括已经不适用的那条。每个迭代周期通读一遍规则文件，删掉失效内容。

3. spec 驱动：从需求文档到任务清单

3.1 整份需求文档不能直接扔给 AI

一个好的需求文档应该是什么样的？ 讲清楚了需求文档的标准：背景、目标、功能点、边界、验收标准。这份文档是产品语言的产物，它的粒度是"一个完整功能"。

一次 AI 对话适合消化的粒度是"一步明确的实现"，二者的差距就是事故二的来源。拿到需求文档后直接整份扔给 AI，等于要求它同时完成数据设计、接口实现、界面开发、异常处理、边界情况，还要全程遵守项目约定——任何一项注意力分配不足，产出质量就塌方。

spec 驱动的做法是在需求文档与 AI 对话之间插入一个任务拆解环节：人（或人与 AI 一起）把需求文档拆成任务清单，每个任务是一次对话能完成的粒度，然后逐任务喂给 AI、逐任务验收。

3.2 任务拆解四原则

原则一：单任务单会话。 一个任务应当在一次对话内完成，改动的文件控制在五个以内。判断标准：如果你预感这个任务做起来 AI 要"顺便"改很多地方，说明它太大了，继续拆。

原则二：按依赖排序。 下游任务消费上游任务的产出。典型排序：

原则三：完成态明确。 每个任务写清"做到什么程度算完成"，且这个标准客观可验证。写"实现收藏接口"没有完成态，写"POST /favorites 返回 201 且响应体含收藏记录 id"才有。

原则四：以代码衔接，不以记忆衔接。 任务之间通过已提交的代码传递状态，每个新会话从代码现状出发接着干活。上一个任务讨论中产生的想法、没有落地的方案，一律视为不存在。这条原则保证任何一个任务都可以在全新会话中独立执行。

3.3 任务清单模板与实战拆解

任务清单本身也是一个 Markdown 文件，随项目进版本库。模板如下：

# {功能名}任务清单

来源需求：{需求文档文件名或链接}
状态标记：[ ] 未开始 / [x] 已完成并提交

## T{序号} {层名}：{一句话目标}
- 目标：{具体做什么}
- 涉及文件：{预计改动的文件清单}
- 验收标准：{可执行的验证命令与预期结果}
- 回归清单：{本次改动不得破坏的既有行为}
- 依赖：{前置任务编号，无则写"无"}

用一个实战例子演示拆解。需求：给一个已上线的 FastAPI 文章管理后端新增文章收藏功能，读者可以收藏文章、查看自己的收藏列表、在文章详情中看到收藏数。按四原则拆成五个任务：

# 文章收藏功能任务清单

来源需求：文章收藏功能需求文档
状态标记：[ ] 未开始 / [x] 已完成并提交

## T1 数据层：收藏表与模型
- 目标：新建 favorites 表，字段含 id、user_id、article_id、created_at，
  user_id 与 article_id 组合唯一；在模型层补充对应模型类
- 涉及文件：models.py、数据库迁移脚本
- 验收标准：迁移脚本执行成功，favorites 表存在且字段与约束齐全
- 依赖：无

## T2 接口层：收藏、取消收藏、我的收藏
- 目标：新增 POST /favorites、DELETE /favorites/{article_id}、
  GET /favorites 三个接口
- 涉及文件：routes/favorites.py（新建）
- 验收标准：见 3.4 节验收命令，三条命令全部返回预期结果
- 依赖：T1

## T3 业务规则：重复收藏与不存在的文章
- 目标：重复收藏返回 409；收藏不存在的文章返回 404
- 涉及文件：routes/favorites.py
- 验收标准：两条异常场景命令返回预期状态码
- 依赖：T2

## T4 统计：文章收藏计数
- 目标：GET /articles/{id} 响应中新增 favorite_count 字段
- 涉及文件：routes/articles.py
- 验收标准：收藏一次后计数为 1，取消后计数归零
- 回归清单：文章列表与详情的既有字段全部保持不变
- 依赖：T2

## T5 回归验证
- 目标：既有文章接口全部复核一遍
- 验收标准：T1 至 T4 之外的全部既有接口响应与开发前一致
- 依赖：T4

注意 T4 与 T5 的回归清单字段：这是第 4 章防功能降级的伏笔，拆任务时就把"不许坏什么"写清楚。

3.4 把验收标准写成可执行的命令

验收标准的质量决定验收防线的上限。对比三种写法：

可执行写法的标志是：命令加预期输出。人在验收时把命令跑一遍，逐条比对预期，AI 在自验收时跑同样一组命令。T2 的验收标准可以落地为：

# 收藏文章，预期返回 201 与收藏记录
curl -s -X POST http://127.0.0.1:8887/favorites \
  -H "Content-Type: application/json" \
  -d '{"user_id": 1, "article_id": 42}'

# 查询我的收藏，预期返回含 article_id 42 的列表
curl -s "http://127.0.0.1:8887/favorites?user_id=1"

# 取消收藏，预期返回 204
curl -s -X DELETE http://127.0.0.1:8887/favorites/42 -o /dev/null -w "%{http_code}"

写不出验收命令的功能，通常是粒度太粗或者边界没有想清，此时应回炉重拆任务。验收命令写得出来的功能，实现与验收就有了同一把尺子。

3.5 喂任务的节奏

任务清单就绪后，执行阶段的节奏建议如下：

• 一次只喂一个任务。把 T2 的完整内容贴给 AI（开场已让它读取规则文件），明确"完成本任务并自验收，通过后停下等我复核"；
• 新会话开场先加载约定。以 DeepSeek Harness 为例，开场第一句指令 AI 读取项目根目录的 AGENTS.md，随后让它复述从规则文件和任务描述中理解到的关键约定，十秒钟确认，避免十分钟的返工；
• 验收通过立即提交，同时把任务清单中对应条目标记为 [x]，一并提交。提交规范可参考 Angular Commit 规范完全指南：从基础到自动化；
• 拆解不合理就回炉。执行中发现某个任务跨层、某个验收标准写不出来，回到清单重新拆，硬着头皮喂下去只会以翻车收场。

4. 验收驱动与防功能降级：三道防线

4.1 事故还原：一个分页是怎么悄悄坏掉的

先完整还原一次真实形态的功能降级，后面三道防线围绕它展开：

这次事故同时踩中了三个缺口：没有回归清单（不知道要保护什么）、没有小步提交（无法干净回退）、没有改动范围核对（重写无人察觉）。三道防线对应补上。

4.2 第一道防线：验收标准先行，回归清单随行

第一道防线在任务开始前布置。每个任务除验收标准外，必须携带回归清单——本次改动不得破坏的既有行为，来源是改动所触及模块的既有功能：

## T2 接口层：收藏、取消收藏、我的收藏
- 验收标准：三条 curl 命令返回预期结果
- 回归清单：
  - 文章列表接口 GET /articles 全部参数行为不变
  - 文章详情接口 GET /articles/{id} 响应结构不变
  - 服务的启动命令与日志输出格式不变

对关键业务逻辑（计费、权限、数据一致性），进一步采用测试先行：要求 AI 先写测试用例再写实现，测试用例本身就成为回归清单的可执行形态。测试先行在 AI 协作里还有一个额外收益：AI 可以反复运行测试自我校验，人在验收时以测试全绿作为通过条件之一。

4.3 第二道防线：小步提交，随时可退

第二道防线管住版本历史。核心纪律只有一条：每个任务验收通过后立即提交，绝不在未提交的状态上叠加第二个任务。

# 任务 T2 验收通过后立即提交
git add .
git commit -m "feat: 新增文章收藏相关接口"

# 会话中发现 AI 改坏了，丢弃全部未提交改动，回到上个提交
git checkout -- .

# 已提交后发现该次任务引入问题，生成一条反向提交撤销它
git revert <该次任务的提交哈希>

这条纪律的价值在第 4.1 节的事故里看得最清楚：如果每层任务独立提交，第 14 天定位问题时，git log 里每个提交对应一个任务，用 git bisect 或逐个回退测试，几分钟就能锁定引入点；如果多个任务混在一个提交里，回退一个提交等于丢掉几天的工作。

提交粒度与任务粒度对齐，回滚粒度才能与事故粒度对齐。

4.4 第三道防线：改前改后对比验证

第三道防线在改动发生的前后各设一个动作。

改前留底：对本次任务涉及的关键接口，先保存一份改动前的响应；对涉及的关键页面截图。成本一分钟，换来的是第 14 天排查时有一份确定的基线：

# 改动前保存既有接口的响应基线
curl -s "http://127.0.0.1:8887/articles?page=2" > baseline_articles_page2.json

改后核对：验收时分两步走。第一步核对改动范围，让 AI 列出它实际修改的文件清单，与任务声明的涉及文件比对：

# 人工核对实际改动是否超出任务范围
git status
git diff --stat

第 4.1 节的事故里，AI 重写了 routes/articles.py 中的加载函数，而任务声明的涉及文件只有 routes/favorites.py。git diff --stat 一眼就能暴露这个越界。第二步跑回归清单，把清单里每个行为复核一遍，改前基线与改后实测逐项比对。

4.5 三道防线的分工

三道防线分别布置在改动的不同时点：

防线之间有依赖关系：没有回归清单，范围核对就缺少判定依据；没有小步提交，基线比对发现问题时无法干净回退。三道防线配套使用。

4.6 降级发生后的补救四步

防线全部失守、降级已经发生时，按四步补救：

1. 定位：用 git log 与 git bisect 找到引入降级的提交。第 4.3 节的小步提交纪律在这里兑现价值；
2. 锁定：把暴露降级的现象写成一个可重复运行的测试用例或验收命令，降级从"用户口头描述"变成"一条能稳定复现的断言"；
3. 修复：带着这条断言开新会话让 AI 修复，修复完成的判定标准是断言通过且全部既有测试不红。禁止在没有复现手段的情况下让 AI"凭感觉修"；
4. 复盘：回答两个问题，为什么防线没拦住（缺清单、缺提交、缺核对，补哪个），以及 AI 为什么会那样改（把对应的禁令写进规则文件的负面清单，回流到第 2 章）。

5. 三件套协同：完整工作循环

5.1 一个长期项目的完整循环

把三套解法放进时间线，一个长期项目的完整工作循环如下：

循环中每个环节的产出物：

规则文件立项时写一次、每次事故后增量维护；外层的大循环（需求到拆解）每个功能走一遍；内层的小循环（领任务到提交）每个任务走一遍。三个节奏嵌套运转。

5.2 三张检查清单

立项时：

每个任务开始前：

每次提交前：

5.3 什么时候可以简化

三件套有执行成本，按项目形态取舍：

判断的分水岭是这个项目的代码还要活多久：活不过一周的项目，靠对话内的短期记忆足够；要活几个月的项目，必须靠文件沉淀的长期记忆。

6. 总结

6.1 核心内容回顾

• 长期项目中的三类事故：AI 不了解项目、大需求吞不下、改 A 坏 B 的功能降级，分别对应项目规则文件、spec 驱动、验收防线三套解法；
• 项目规则文件放在项目根目录（AGENTS.md、CLAUDE.md 等均属此类），内容由项目结构说明、可判定的编码规范、禁做事项负面清单三部分组成，规范要写成 AI 能执行判定的条款，负面清单随事故持续补充；
• spec 驱动的核心是拆解四原则：单任务单会话、按依赖排序、完成态明确、以代码衔接不以记忆衔接，任务清单里每个任务自带可执行验收标准与回归清单；
• 验收防线的三道关卡：改动前布置验收标准与回归清单，改动中坚持小步提交，改动后核对范围与基线比对；降级发生后按定位、锁定、修复、复盘四步补救，复盘结论回流到规则文件；
• 三件套按项目形态取舍，取舍标准是代码要活多久。

6.2 常见问题与解答

问：同时使用多种编码助手时，规则文件怎么维护？

答：只维护一份主文件（推荐跨工具通用的 AGENTS.md）作为项目唯一约定来源。支持自动读取的工具直接生效；使用自有规则文件的工具，其内容从主文件摘引；两者都不支持的工具，每次会话开场指令它读取主文件。多处指向同一份来源，内容漂移就无从发生。

问：规则文件会不会越写越长，把上下文窗口占满？

答：会，所以要定期做减法。规则文件的长度建议控制在一屏到三屏，过期条款及时删除，工具支持分层加载时（如子目录规则文件只在涉及时生效）把局部约定下沉到对应子目录。占满上下文窗口的规则文件，AI 会开始忽略其中一部分，效果反而变差。

问：任务清单放在哪里合适？

答：放在项目根目录（如 tasks/文章收藏.md）随代码进版本库是最简单的方式，好处是任务清单、代码、规则文件在同一个仓库里，新会话一切可寻址。团队已使用 issue 系统的，用 issue 承载任务清单同样符合 spec 驱动的原则，关键是每个任务可独立引用、可标记状态。

问：AI 反复犯同类错误，是不是该换模型？

答：先查规则文件再考虑换模型。同一个错误出现第二次，把禁令写进负面清单；出现第三次，检查那条禁令是否可判定——"不要乱改"挡不住 AI，"禁止修改 routes 目录外的任何文件"才挡得住。规则文件迭代三轮后仍失控，再评估工具与模型本身。