接手过不少用 AI 辅助做出来的项目，初期跑得飞起，后面基本都难逃一个结局：改不动、不敢动、看不懂。这不是工具的问题，是大部分人把 AI 当成了“无限加班但从不写文档的极客程序员”，而不是把它当成一个需要规则约束的协作对象。今天我讲透这个事：为什么你的 AI 编程项目迟早会烂掉，以及你该做的那件事到底是什么。
经常在技术群里看到有人发“AI 一小时给我写了个完整项目”“Cursor 把模块重构完了，测试全过”这类动态。说实话，前两周确实爽，但一个月后再问他们，基本都是沉默。真正用到生产环境的项目，靠的不只是“生成代码”的速度，而是“代码进去之后还能不能长期被维护”的能力，后者恰恰是 AI 编程最容易忽略的部分。
这不是让你不用 AI，而是让你在 AI 进场之前，先给它画好跑道。下面我要讲的这套方法，适合正在进行 AI 辅助开发的个人开发者、小团队技术负责人，以及所有在代码库里大量引入 AI 生成内容的工程师。哪怕你只是用 AI 写脚本和工具函数，这套思路也能让你的项目不变成一团乱麻。
1. 先说病根：AI 编程项目是怎么一步步烂掉的
1.1 AI 没有记忆，每轮对话都像一个新来的实习生
很多人以为 AI 记住了你之前说过的所有话，其实没有。你每次新建对话，它都像一个刚入职、没看过任何文档的新人。你之前说过的“这个项目用 Python 3.11”“数据库连接统一走这个模块”“不要改公共接口的返回结构”，如果不放在当前上下文里，AI 基本是不知道的。
这个特性带来的后果很隐蔽。你在第 5 轮对话里明确要求“分页参数统一命名为 page 和 page_size”，到了第 18 轮对话，AI 很可能写出来currentPage和limit。你问它为什么，它还会振振有词地告诉你这样更规范。它的“规范”来自通用训练数据，不是你项目的规范。
我把这个过程类比成：让一个没看过会议纪要的新同事接手昨天的任务。他能力很强，但他不知道你昨天刚刚否定了某个技术方案，不知道某个函数是为了兼容老数据才写成这样。他按照自己的理解做，结果就是和现有系统产生大量隐性冲突。
AI 编程项目烂掉的第一步，就是“不一致”——命名不一致、接口不一致、风格不一致、对系统边界的理解不一致。这些东西单独看都不致命，但累积到一定程度，整个代码库就变成了多种风格拼接的缝合怪，没有人能靠直觉判断“这个项目里到底什么叫正常”。
1.2 局部最优陷阱：AI 只对“当前这句话”负责
AI 生成代码的底层逻辑，是在当前上下文里预测最合理的下一步。这意味着它会全力满足你最近的那句指令，但不会操心这个改动对全局架构的影响。
举个例子。你在一个订单系统里让 AI “给订单增加一个优惠券抵扣字段”。AI 很听话，直接在订单模型上加了couponAmount，顺带在创建订单的接口里把参数也加上了。这时候一切正常。但等到下一步，你让 AI “重构订单创建逻辑，把支付和订单拆开”，它看到的只是当前这段代码里的耦合关系，根本没意识到当时加couponAmount的时候，前端、报表系统、对账服务都在依赖同一个接口结构。
结果就是：AI 拆得很痛快，但报表系统的解析挂掉了。它不坏，因为它根本不知道报表系统的存在。
这个问题的本质是“局部视野”。你给的信息越少，它看到的范围就越小。如果项目里没有一个完整的、结构化的系统视图让 AI 随时参考，它就像一个趴在树叶上啃食的毛毛虫，永远不知道整棵树长什么样。
很多人这时候会骂“AI 写代码太不靠谱”。但换个角度想，如果你让一个从来没看过建筑图纸的工人去装修，他能做对才是奇迹。AI 很强，但它强在“生成”，弱在“理解存量约束”。理解存量约束这件事，恰恰需要你提供机制，而不是靠 AI 自己领悟。
1.3 烂掉的三部曲：蜜月期、叠加期、失控期
我观察了很多 AI 辅助项目，烂掉的过程基本分三个阶段，你可以对照一下自己项目现在处在哪个阶段。
蜜月期（0 到 2 周）：你让 AI 写功能，它很快交付，跑起来没问题。你会产生一种“这工具太强了”的错觉。这个阶段项目规模小，模块之间调用关系清晰，AI 的局部修改不会引发连锁反应。
叠加期（3 到 6 周）：功能越来越多，项目结构从几个文件变成十几个目录。AI 开始频繁提出“重构建议”，但你不敢让它随便动。这个阶段已经出现“改 A 坏 B”的现象，但一般是小问题，修一修还能过。
失控期（2 个月以后）：你让 AI 加一个简单功能，它疯狂改文件，然后测试挂了，你回滚了几轮，最后决定“还是自己手写吧”。但你自己也发现代码已经复杂到不敢接手。项目进入“只读模式”——没人敢改，但业务需求还在来，每一次改动都像拆炸弹。
核心问题是，这个过程不是突然发生的。每一次“让 AI 按你自己的偏好重写”都是一次技术债积累，每一次“先不管统一规范后面再说”都是一次结构腐化。AI 只是把这些动作放大了十倍——它比人有执行力，但比人更没有记忆和全局观。
所以，要让项目不烂掉，关键不是限制 AI 的能力，而是给它建立一个“稳定的决策基线”，让它的每一次输出都对齐到这套基线上。这就是我说的那件事。
2. 那件事到底是什么：给 AI 编程建立“决策基线”
2.1 一句话说清楚决策基线
决策基线就是一套“AI 在生成代码时必须遵守的规则集合”，包括项目文档、架构约束、接口契约、测试保护和变更流程。
它不是让你写一本几百页的说明手册，而是让你把“这个项目里哪些事是绝对不能妥协的”写清楚，然后用工具和流程强制 AI 在每次改动时对齐。
我常用一个比喻：拍电影的时候，演员可以自己发挥台词，但剧情走向、人物设定、结尾结局是已经定死的。你不能让演员到了片场自己编一个完全不同的故事。AI 写代码也一样，它可以发挥具体实现方式，但架构方向、关键命名、接口边界、数据流方向，这些是“剧本”，不是“台词”。
没有决策基线的 AI 编程，就像没有剧本的即兴演出。单看每一场都不错，但串起来就是灾难。
2.2 决策基线由四个层次构成
这四个层次缺一不可，它们逐层收窄 AI 的自由度，同时逐层降低出错概率。
第一层是项目级约束。包括技术栈锁定、目录结构约定、核心依赖版本、代码风格指南。这一层解决“AI 不知道项目是什么”的问题。一个写清楚了项目目标的文档，比你在对话里反复强调一百遍“按现有风格来”有效得多。
第二层是模块级契约。包括接口定义、数据模型、错误码规范、关键模块的职责边界。这一层解决“AI 不知道系统怎么连起来”的问题。你告诉它下单服务走 HTTP 调用库存服务，它就不会自作主张把库存查询直接怼进数据库。
第三层是验证级安全网。包括单元测试、集成测试、静态检查、构建脚本。这一层解决“AI 改错了没人发现”的问题。没有测试的 AI 重构，本质上就是高空走钢丝；有测试之后，AI 至少能在提交前发现自己的问题。
第四层是变更级流程。包括每次改动先写计划、生成变更说明、由人审查后再合并。这一层解决“AI 悄悄改坏了什么”的问题。AI 可以高效产出，但“产出的东西是否被接受”必须由人来把关。
这四个层次拆开看都不复杂，但把它们拼成一个体系，效果远大于几次精心设计的提示词。因为提示词只在当次对话里有效，而决策基线是整个项目生命周期里持续运转的机制。
2.3 为什么“文档 + 测试”比“口口相传”更可靠
人之间的沟通靠语言，但代码项目里的“语言”会随着时间和人员流动失真。你今天口头告诉 AI “不要直接用真实文件路径，统一走配置中心”，它记住了；但明天你开了新对话，它就忘了。你不可能每次写代码前都把所有约定口述一遍，而且口述多了总有遗漏。
文档的作用，是给 AI 一份“任何时候都能查阅”的项目宪法。它每次动工前读一遍，就知道这个项目的边界在哪。测试的作用，是给 AI 一支“驳回错误修改”的裁判棒。无论 AI 对代码做了什么，只要测试不通过，修改就不能算完成。
这两样东西有一个共同特点：它们是客观的、可复现的、不依赖任何一方的短期记忆。你把约束写下来，AI 才能“看见”；你把验证自动化，AI 才能“感知”。没有这两样，你和 AI 之间的配合纯靠缘分，这不叫工程。
我经常说，AI 编程的核心不是“怎么把活干完”，而是“怎么让每一次生成的代码都站在上一次的肩膀上”。这个“站着”的支点，就是你的文档和测试。
3. 实操落地：给 AI 编程项目装上“方向盘”
3.1 第一步：花一小时写好项目基线文档
别把这件事想得太复杂。基线文档不需要几十页，我建议控制在 200 行以内，核心是把 AI 最容易跑偏的东西写清楚。
一份典型的结构是下面这样的：
# 项目名：内部订单管理系统 ## 核心目标 - 管理订单全生命周期：创建、支付、发货、售后 - 供内部运营同学使用，日均处理订单 10 万单 ## 技术栈（锁定，不可随意更换） - 后端：Python 3.11 + FastAPI + PostgreSQL 15 - 前端：React 18 + TypeScript 5 + Ant Design - 部署：Docker + Docker Compose，目标环境为 Linux ## 目录结构 - app/api/ # 接口层，只负责参数校验和响应组装 - app/service/ # 业务逻辑层，核心规则放这里 - app/models/ # 数据模型，使用 SQLAlchemy - app/common/ # 公共方法：分页、鉴权、日志 ## 不可妥协的规则 1. 所有分页参数统一命名为 page 和 page_size，禁止使用 currentPage 等变体 2. 数据库连接统一走 app/common/db.py 中的 get_db()，禁止在业务代码里直接创建连接 3. 对外接口的返回结构统一为 {"code": 0, "message": "ok", "data": ...} 4. 涉及订单状态的变更，必须走 app/service/order_state.py 里的状态机函数 5. 禁止在 for 循环里执行数据库查询（N+1 问题） ## 核心数据流 下单请求 → 订单服务创建订单 → 支付回调 → 状态机更新 → 通知发货系统这 20 来行内容，基本锁死了 AI 在写这个项目时最容易犯的错。它每开始一个新任务前，你先让它读一遍文档，它会明显表现得“更懂这个项目”。
写得好不好，有一个简单自测方法：如果这份文档递给一个不认识项目的人，他三天后能在这个代码库里做出符合团队风格的改动，那就是合格的。对于 AI 也一样，它读了文档后生成的代码是否和现有风格一致，是最好的评价指标。
3.2 第二步：搭好“三道闸门”
有了基线文档，还需要工具强制执行，不然 AI 可能读了文档还是闯祸。我给项目配置三道闸门，每一道都负责拦截一类错误。
第一道闸门是 lint + 类型检查。AI 生成的代码很多是“能跑但不规范”的，类型标注缺失、未使用的变量、不一致的命名风格。lint 规则是客观的、跑的，不需要人去判断，AI 只要提交就得过这一关。我给 Python 项目配 ruff，给 TypeScript 项目配 ESLint，规则集用团队已有的配置，不搞特例。
第二道闸门是单元测试。核心业务逻辑必须写测试，状态机、金额计算、数据权限这些高风险区域尤其要覆盖。测试的目的不是保证代码没有 bug，而是保证 AI 在重构时“改坏了自己能发现”。我见过太多项目不敢重构，就是因为没有测试兜底，而有了测试，AI 的胆子可以大十倍，但这种大胆是可控的。
第三道闸门是构建验证。主分支必须时刻保持可构建、可运行状态。这个听起来像是废话，但很多 AI 辅助项目恰恰死在“能编译的代码”和“能跑的系统”之间的地带。缺少某个环境变量、依赖没有锁版本、迁移脚本没跑全，这些都是 AI 容易忽略的细节。用一条 CI 命令把“构建 + 测试 + 启动冒烟”串起来，就能拦截大部分问题。
三道闸门不是要一次性搭出完整的 CI/CD，你可以先在本地用 pre-commit 钩子跑，或者用一个简单的 Makefile 打包执行。关键让“验证”成为每次改动的必经之路，而不用靠人去盯着。
3.3 第三步：每次对话前刷新“上下文包”
即使有了文档，AI 在长对话后依然会漂移。所以我强烈建议你设定一个“上下文包”模板，每次开启新任务之前，先把内容粘贴给 AI。
我的模板大概是这样的：
# 任务上下文 ## 项目背景 [一句话说明项目是做什么的] ## 项目基线文档 [粘贴 PROJECT.md 内容，或者让 AI 先读取该文件] ## 当前任务 我要做的是：[一句话说清楚功能需求] ## 相关现状 目前的代码逻辑在：[文件路径 + 关键函数] 已有的测试在：[文件路径] 最近一次改动是：[简要描述，帮助 AI 对齐变更位置] ## 硬性约束 - 不允许修改的文件：xxx.py - 不允许破坏的接口：对外 API 返回结构 - 必须通过的测试：pytest app/tests/xxx这个刷新动作大概花你两分钟，但它能把 AI 的出错的概率降一半以上。本质上，你不是在教 AI，你是在给它导航。导航地图越新，路线越准。
实测下来有个很明显的感受：大一坨需求一次性丢给 AI，它写出来的东西方向很容易跑偏；但拆成一个个小任务，每次附上上下文包，它产出的代码就“很懂规矩”。这也是我提倡的 AI 协作方式：你当架构师和产品经理，AI 当执行者，而不是把整个项目一次性丢给它自由发挥。
3.4 第四步：强制 AI 提交“变更说明”
AI 改代码最烦的一点是，它有时候会悄悄改一些你没让它动的东西。可能是为了“顺手优化”，也可能是它以为这样更好。但任何未经说明的改动，在项目里都是潜在的雷。
我的做法是，所有 AI 完成的改动，必须附带一份简短的变更说明：
## 变更说明 ### 变更目标 单价计算逻辑增加优惠券分摊 ### 修改文件 - app/service/price.py（修改） - app/tests/test_price.py（新增） - app/api/order.py（修改） ### 关键行为变化 - 优惠券金额按比例分摊到每个商品 - 分摊时保留两位小数，尾差记在最后一个商品上 - 未使用优惠券时，行为与原先完全一致 ### 自测结果 - pytest app/tests/test_price.py 全部通过 - 构建验证通过这个变更说明的价值，不在于它多正式，而在于它强制 AI 梳理了自己到底做了什么。很多时候 AI 在生成过程中做了好几个隐含决策，一旦被要求写说明，它自己也会发现某些改动其实没必要。而且，你在 review 代码时，看着变更说明逐项核对，能很轻松找出“不是本次任务的改动”。
这套流程跑起来之后，AI 就从一个“盲目写代码的工具”变成了“一个带工作日志的执行者”。你可能会觉得这有点多余，但项目一旦进入三个月以上的维护期，这些记录就是你理解项目的唯一线索。
4. 常见问题与排查技巧实录
4.1 AI 老是把它觉得“更好”的方案强加进来
你让 AI 修个 bug，它顺手把整个模块的写法改成了它认为的“最佳实践”。表面上代码变简洁了，但和项目其他地方完全不搭，还可能引入新的行为变化。
这个问题几乎所有人都会遇到。原因很简单：AI 的“好方案”来自通用场景的经验，不是你这个项目的上下文。它不知道你当时为什么选择了一个看起来不那么优雅的方案——也许是为了兼容某个历史数据，也许是团队规范如此。
解法分两步。第一步，在基线文档里加一条“禁止未经明确要求改变代码风格和结构，哪怕你认为新方案更好”。第二步，在 review 时特别标记那些“顺手优化”的改动，一旦发现，直接让 AI 回退。明确告诉它“这个项目里，稳定性优先于优雅性”，它会老实很多。
4.2 测试全绿，但上线后还是出问题
这个坑比较隐蔽。测试通过不等于行为正确，因为测试是你写的，如果测试本身没有覆盖到真实场景，AI 就算写错代码，测试也照样过。
我遇到过一次典型的例子：让 AI 增加“订单金额满 100 减 10”的活动逻辑。AI 写的测试只是验证“满 100 确实减了 10”，但没验证“不满 100 时金额不变”，更没验证“刚好 100 的边界”。结果代码里if amount >= 100写成了if amount > 100，测试全绿，上线后用户打爆了客服电话。
解法是“先补测试，再补功能”。每次让 AI 做需求之前，先让它把需求拆成可验证的行为列表，然后根据列表补测试用例，最后再实现功能。测试的价值不是给代码一个“通过”的标签，而是给项目一张“行为契约”。这张契约必须覆盖正常情况和边界情况，而不只是那条最顺畅的主路径。
4.3 AI 把多层架构压平了，代码全写在一个文件里
很多 AI 生成的代码有个共同的毛病：一个函数里塞了参数校验、业务判断、数据库查询、日志输出。它觉得这样“方便”，但从架构角度，这完全破坏了模块的职责边界。
我把它叫“抽象层坍塌”。你原本有 API 层、Service 层、Model 层，AI 没这个概念的话，它会把所有逻辑均匀地摊在一个函数里。代码是能跑，但下一次你让 AI 改其中一个环节，它会牵连到另几个不相关的部分。
解法是在基线文档里强制定义目录和文件职责，并在代码审查时严格执行“跨层调用”检查。比如 API 层不允许直接操作数据库，Service 层不允许直接处理 HTTP 参数。一旦发现 AI 写了跨层代码，直接打回重写，而不是花时间修补。守住这个底线，项目结构才能长期清晰。
4.4 团队协作时，AI 改的代码和别人冲突严重
如果你的项目是多人协作，AI 生成的内容直接往主分支推，基本都会引发冲突。这不是 AI 的错，是流程问题。
我给团队定了一条规矩：AI 的改动必须提交到独立分支，由人类成员的代码审查通过后再合并。AI 相当于一个“远程开发者”，它提交 PR，人来 review 和 merge。这样既能享受 AI 的效率，又保证了人对代码库的掌控权。
审查时最需要注意的是“行为变化”：测试数据、依赖版本、环境配置是否有变动。这种变动在代码 diff 里特别容易被忽略，但风险极高。我习惯在 merge 前跑一次完整的构建和集成测试，确认无误再合入，省得后面出问题没人接锅。
5. 关于 AI 编程项目，我最后想说的几句大实话
用了这么久的 AI 辅助开发，我最大的感受是：AI 让写代码的成本趋近于零，但这反而放大了系统设计的价值。
以前写代码慢，你会在动手前多想几遍，把错误消灭在脑子里；现在 AI 写代码快，你的“想”被压缩了，但“系统怎么组织、规则怎么定、验证怎么建”这些事，反而成了决定性的环节。
一个没有决策基线的项目，就像一辆没有方向盘的车。AI 是马力强劲的发动机，你踩下油门它会冲出去，但到了弯道它只会笔直开。而你所需要的那件事——建立决策基线——本质上就是给这辆车装上方向盘和刹车。
我强烈建议你从今天开始，无论项目多小，先花一小时写好基线文档，配好一道闸门，哪怕只是一个本地测试命令就够了。再花两分钟把上下文包模板存成文档，每次新任务都粘贴。坚持一个月，你会发现 AI 犯错的比例大幅下降，而且项目不会随着功能变多而失控。
给别人讲的时候我常说，控制不了 AI 的人，用 AI 造轮子；控制得了 AI 的人，用 AI 建系统。区别不在于你会不会写提示词，而在于你有没有为 AI 划好边界。别等项目烂掉之后再来后悔，现在就把这件事做了。
