AI 编程已经很强了，但很多团队发现一个诡异的现象：
刚引入 AI 编程时，交付速度确实快了。
但三个月后，项目越来越难维护，改一个 bug 要排查一下午。
你忍不住骂一句：这他妈的谁写的烂代码？
旁边的同事默默告诉你：这是你三个月前让 AI 写的。
不是我泼冷水，是所有 AI 编程工具都有一个致命缺陷：
它搜不到真相，只能靠猜。
具体表现为 4 个通病，看看你中了几个：
1. 上下文召回不可靠
现实中的崩溃现场：
- PRD 写的是
每天限额 10 次 - 接口文档写的
是单次上限 10 - 代码实现是
limit: 10 - 测试用例写的是
支持 10/20/50 三档
四个地方四个说法，AI 看了也懵。
关键规则散落在：飞书文档、PRD、会议纪要、口口相传。AI 搜代码，只能搜到冰山一角。
2. 边界意识差
你让 AI 修一个 bug，它很开心地 顺便：
- 改了目录结构
- 把接口语义也
优化了 - 把测试规则改成
更好测的版本
它觉得自己在做好事，你觉得它在越级执法。
3. 规则、契约、实现三者漂移
没有唯一真理时，系统里会出现三份互相背离的真相：
| 业务规则 | 文档写的 | 实际跑的 |
|---|---|---|
| 每天限额 10 次 | 单次上限 10 | limit: 10 |
AI 加速了这个漂移——因为它能同时写三样，而且每样都写得像真的。
4. 正确性无法证明
没有明确验收口径时，你对 AI 输出的评估方式只剩一种：
看起来合理。
工程里最贵的成本，就藏在看起来三个字里。
根因：不是检索不够强，而是缺乏「真相」
很多人遇到上下文问题的第一反应是：上 RAG、上向量库、上更强模型。
这些解决的是搜的工具，不是被搜的对象。
如果你的系统里：
- 真相散落在仓库外
- 同一个概念多套说法
- 文档不版本化、不评审、不追踪
那再强的检索，也只能把碎片捞得更快一点。
我的解法：文档即代码
1. System Manifest：给项目一张地图
{
"modules": ["backend", "frontend", "docs"],
"contracts": "./openapi/",
"generated": "./src/api/"
}
好处：AI 不再先搜再说，而是先定位再深入。
2. L1-L4 分层：把真相分类型管理
| 层级 | 职责 |
|---|---|
| L1 | 系统边界与上下文（去哪儿找） |
| L2 | 模型与不变式（怎么理解） |
| L3 | 业务规则（什么算对） |
| L4 | 接口契约（前后端怎么对齐） |
3. L3 唯一真理：把「正确性」做成可验证
场景: 每日限额检查
假设 用户当天已调用 9 次
当 用户发起第 10 次请求
那么 返回 "每日限额已达上限"
AI 的工作从写看起来对的代码，变成把规则跑通。
4. 结构化移交单：把协作从聊天升级为指令
每次变更必须输出：
- 改动意图
- 影响范围（哪些模块/接口）
- 具体变化（字段级）
结尾
AI 能帮你写 10 倍代码，也能帮你制造 10 倍看起来合理的隐患。
你需要的不是更强的补全，而是更强的顶层设计：
- 真相可寻址（Manifest）
- 变更可追踪（版本化）
- 正确性可验证（L3 规则）
- 协作可执行（移交单）
简单项目可以靠感觉，复杂系统永远靠规约。
你在 AI 编程中踩过什么坑？评论区聊聊 👇
