从演示到生产：AI编程助手在真实遗留系统上的四个失灵点

Demo和真实仓库之间隔着什么

演示视频里的代码库通常是新写的、结构清晰的、依赖单一的。而真实仓库通常是：十年的提交历史、三层抽象叠着两套历史包袱、约定俗成的命名规则从未写进文档、以及一个”千万不要动”的核心模块。

AI编程助手在这两者上的表现差异极大，但它不是”变笨了”，而是它依赖的假设不成立了。下面是四个最常见的失灵点，以及对应的处理方式。

失灵点一：上下文检索抓不到”真正该看的那份文件”

模型看到的是被检索进来的片段。遗留系统的典型陷阱是：同一个业务逻辑有三处实现，只有一处真正生效（一处是死代码，一处被特性开关关闭，一处是线上路径）。检索工具按相似度返回，很可能把你导向死代码。

对策：在仓库里显式维护”入口图”。用一份ARCHITECTURE.md或CODEOWNERS式的映射，标注哪些模块是活跃路径、哪些是废弃路径、关键开关在哪里。再把它作为检索的优先来源。这件事对人类新人也同样有价值——一次投入，两份收益。

失灵点二：隐性约定无法从代码推断

真实代码库里有大量”不写在任何地方”的规则：错误必须用某个包装方式抛出、日志必须带trace_id、时间必须用公司时区工具、禁止在某个包下引入新依赖。模型不知道这些，会生成语法正确但风格违规的代码。

对策：把这些约定变成可执行的检查，而不是依赖模型记住。顺序是：lint规则 > 自定义静态检查 > 仓库内的贡献指南 > 提示词里的一段说明。机器能拦住的，不要靠提示词。同时给AI助手一份精简的AGENTS.md/CONTRIBUTING上下文，只写”最容易被违反的10条”。

失灵点三：改完就报错，因为环境不在它手上

AI能写出代码，但看不到数据库状态、缓存里的旧数据、本地缺失的环境变量、以及那个”只有特定顺序才触发”的竞态。它能跑测试，但测试可能根本没覆盖真实路径。

对策：构建可复现的验证闭环。

• 提供容器化的一键环境，让Agent能真正运行代码
• 提供种子数据与最小复现脚本
• 把”改了A会影响到B”的依赖信息显式化（模块图、数据流图）

没有闭环的AI编程，本质上是”高级自动补全”。

失灵点四：没有回归证据的自信

AI特别容易在描述里写”已完成，测试通过”，而实际上它只跑了与改动直接相关的两个测试文件。真实世界的回归风险来自间接依赖。

对策：把”通过”的定义交给流水线而不是模型。要求：受影响模块的单元测试必须全绿、静态检查通过、关键路径的冒烟测试通过。把这条规则写进PR模板，让AI自己按模板填写证据。

一个稳妥的接入顺序

1. 只读阶段：让AI解释代码、生成文档、定位bug成因。零风险，收益快。
2. 小范围写：在低风险目录（脚本、工具、测试）启用生成，建立评审习惯。
3. 补测试优先：让AI先写测试再写实现，用测试作为对生成的约束。
4. 接管重复性改动：依赖升级、API迁移、样板代码批量改造——这类任务规则清晰、验证明确，是AI性价比最高的场景。
5. 核心模块：最后，且必须有人在环。让AI出方案、人做决策。

判断是否”真的提效”的三个信号

• PR的返工率没上升
• 新人上手时间缩短（知识显性化的副产品）
• 线上缺陷的引入来源没有从”人”转移到”AI”

如果前两项没改善，说明还停留在把AI当打字机的阶段；这项投入的回报主要来自知识显性化，而不是生成速度。