一个来自 AI 编程智能体的 40 个文件的重构任务摆到了你的桌面。你打开 PR，滚动查看差异（diff），每一个代码块（hunk）看起来都没问题。命名重构很一致，导入很整洁，测试在隔离状态下也能编译。你合并了代码。40 分钟后，主分支的 CI 变红了，因为同级包（sibling package）中的两个调用点仍然向一个现在需要四个参数的函数传递三个参数，而原本能捕获这一错误的类型检查器从未包含在智能体的内环（inner loop）中。
这是当今智能体编写的重构中最常见的失败模式，而且它与单个修改的质量几乎无关。每一个文件单独审查时，看起来都像是一个细心的人类写的。Bug 存在于“接缝”处——即来自不同文件的修改必须保持一致的边界。文件级的审查隐藏了接缝级的正确性，而大多数审查工作流都是围绕文件设计的。
大多数 AI 编码演示展示的是智能体从零构建一个 Todo 应用，或者干净地实现一个全新的 API。而你的代码库，却是一个有着十五年历史的单体应用：充满未文档化的隐性契约、三个团队都依赖但没人完全搞清楚的废弃依赖，以及一个从单一类起步、如今已蔓延到四十个文件的服务层。演示与现实之间的差距，不仅仅是规模问题——更是结构性问题。在把代码库的"钥匙"交给智能体之前，理解这一点，能让你避开一类既隐蔽又代价高昂的失败。
AI 编码智能体确实能帮助处理遗留系统，但只在特定任务边界内才有效。超出这些边界，它们不是显眼地失败——而是生成外观可信、语法正确、语义却有误的变更，这些变更能通过代码审查，最终在生产环境中暴露出来。
当 Airbnb 需要将 3,500 个 React 测试文件从 Enzyme 迁移到 React Testing Library 时，他们估计该项目需要 1.5 年的人力。通过使用 LLM 驱动的流水线，他们仅用 6 周就完成了交付。当 Google 研究了一个由 3 名开发人员在 12 个月内执行的 39 次不同代码迁移（595 次代码更改，93,574 次编辑）时，他们发现 74% 的编辑是由 AI 生成的，其中 87% 的编辑在没有人工修改的情况下就被提交了，整体迁移时间缩短了 50%。
这些数字是真实的。但这也是事实：在这些迁移过程中，工程师花费了大约 50% 的时间来验证 AI 的输出——修复上下文窗口故障、清理幻觉生成的导入，以及理顺测试未能捕捉到的业务逻辑错误。效率的提升是真实的，痛点也是真实的。问题不在于 AI 是否属于代码迁移；而在于准确了解它在何处提供帮助，以及在何处创造的清理工作超过了它所节省的时间。
每个工程团队都有这样的故事：AI 编码代理在全新项目中能产出完美代码，但在你的生产代码库中却像没有地图的游客一样跌跌撞撞。代理没有坏。你的代码库是不可读的——不是对人类，而是对机器。
几十年来，"可读性"只意味着一件事：人类开发者能否浏览这个文件并理解其意图？我们通过命名、文件大小、文档和抽象深度等约定来为这个读者做优化。但你代码库增长最快的消费者不再是入职第一周的初级工程师。它是一个 LLM 驱动的代理，每天阅读、推理和修改你的代码数千次。
越来越多的证据表明，代码库结构是 AI 辅助开发速度的最大杠杆——比模型选择更重要，比提示工程更重要，比你使用哪个 IDE 插件更重要。拥有良好结构代码库的团队在使用 AI 助手时报告迭代周期减少了 60-70%。问题不再是是否要为机器可读性优化，而是如何优化。
我是 Tian Pan，一名工程师型创始人，专注于智能体工程——构建自主 AI 系统并扩展工程团队。我撰写关于系统设计、技术领导力和 AI 智能体实战的实用指南。曾在 Uber、Brex 和 IoTeX 担任早期工程师。
