如何构建 AI 智能体喜欢的代码库

AI 不是拥有超能力的开发者，而是一个没有记忆的新员工。每次启动智能体，都像《记忆碎片》的主角走进代码库，说：“好了，我到了，现在要做什么？”

相比提示词或 AGENTS.md 文件，代码库本身对 AI 输出的影响要大得多。如果设计有误，会在三个方面付出代价。

反馈循环薄弱。 AI 无法足够快地获得反馈，因此不知道自己的修改是否真正达到了预期。

难以导航。 AI 很难理解结构、找到文件，并判断该如何测试。

认知耗竭。 最终只能自己勉强维系 AI 与代码库之间的协作，并手动修补一切。

AI 实际看到的内容

假设这是你的代码库：

每个方块都是导出某项功能的模块，例如函数、变量或组件。内部只有模糊分组：缩略图编辑器、视频编辑器、身份验证、CRUD 表单。

你理解这张心智地图，但 AI 不理解。它看到的是：

一堆彼此都能相互导入的零散模块，没有分组，也没有关系。文件系统同样没有提供帮助，一切混杂在一起。

你每天都在让 20 多个新员工查看代码库并修改代码。因此代码库必须对它们友好且易于导航。

解决方案：深模块

代码库的文件系统和设计，需要与你脑中的内部地图一致。我找到的最佳方式是使用 深模块.

深模块来自《A Philosophy of Software Design》。核心思想很简单：用一个简单接口控制大量实现。

不要使用大量小模块：

最终得到的是大块功能，以及简单、可控的接口。所有导出都必须通过该接口。

灰盒模块

深模块会在代码库中形成天然接缝。你精心控制和设计接口，内部实现则交给 AI。

编写测试来锁定模块行为，这样就不必查看内部。当然，如果想施加品味、影响结果或改进性能，也可以查看；但只要测试通过，就不必操心。

这就是 灰盒模块。你负责接口，AI 负责实现，测试则确保实现可靠。

提升可导航性

为每个模块分配独立文件夹和清晰的公共接口。AI 可以在文件系统中看到所有服务、读取其类型并理解用途，而无需深入实现。

我们让代码库能够渐进式披露复杂度。 接口位于最上层，说明模块的作用；只有需要时才深入内部。

减少认知耗竭

无需在脑中维持数百个相互关联的模块，只要记住七八个功能块。AI 管理每个块的内部内容，你只需关注接口设计及其组合方式。

这与 氛围编程仍然相距甚远。你需要在边界处运用品味，决定哪些内容属于哪个模块。不过心智地图已经简单得多。

优秀实践依然是优秀实践

这并不新鲜，优秀代码库二十年来一直这样设计。对人类有效的方式，对 AI 同样有效。

总结

你的代码库很可能还没有准备好迎接 AI。它没有深模块，只有一张由相互连接的浅模块组成的网：

这种结构难以导航、难以测试，也难以记在脑中。

解决方案是拥有清晰接口和强测试的深模块。从 PRD 到实现 issue，都要考虑模块边界。测试和反馈循环不可或缺，它们能让 AI 新员工知道修改是否有效。

有些语言更容易实现这种结构。在 TypeScript 中，强制这些边界并不容易；我越来越常使用 Effect，因为它能简化代码库模块化。