代码库即提示词：AI 在不同项目成败的关键

开发者圈里流传着一个老笑话：“当我写下这段代码时，只有上帝和我知道它是怎么工作的。现在只有上帝知道了。”

这个笑话之所以好笑，是因为它精准地击中了我们每个人都遇到过的项目——代码能跑，但只有那位主程真正理解它。那些决策、例外和潜规则全在他脑子里。久而久之，开发者本人就成了代码库。

这对开发团队来说早已是老问题。而编码智能体的处境更糟：如果另一位人类开发者都搞不清代码该放在哪里、为何这样设计、改哪里会崩，AI 面对的也是同样的困境。

与其讨论“如何让 AI 更会写代码”，不如换个视角：代码库本身就是给 AI 的提示词。提示词清晰，AI 如鱼得水；提示词混乱，AI 只能靠猜。以下这些习惯，本质上不是 AI 时代的新发明，而是那些一旦引入 AI、缺失代价会急剧放大的既有工程实践。

AI 无法执行一种“氛围”

AI 最擅长的是把已经清晰的工作做好。

如果你一早来到工位只是说“咱们来优化点东西吧”，然后边写边做决定，智能体没有任何稳固的东西可以跟随。它能生成代码，但它无法替你决定产品应该做什么、什么该纳入范围、你真正想要的是哪种权衡。

作者的做法是：在让编码智能体上手之前，先和另一个 AI 讨论任务。把问题定义清楚，质疑方案，考虑边界情况，把工作拆成明确的步骤。然后让它为本地编码智能体准备一份详细的提示词。

AI 可以在不同层级上提供帮助。用一个智能体来思考工作，用另一个来执行。不要指望编码智能体从一句模糊的话里同时完成产品规划、架构设计和全部实现。

模糊的任务不会给智能体自由，只会给它猜测的许可。

让项目变得可预测

一个结构良好的项目不应该让你感到意外。

当你第一次打开一个代码库时，你应该能大致猜到业务逻辑、校验、API 调用、视图和共享工具分别住在哪里。同一类工作在整个项目中应遵循相同的模式。

如果一条校验规则在控制器里，另一条在 helper 里，第三条藏在视图中，那这个结构已经失败了。AI 确实能搜索整个仓库，但这不代表它必须这样做。

可预测性减少了智能体所需的上下文量，也降低了它把正确的代码放到错误位置的概率。

追求的不是巧妙炫技的目录结构，而是无聊但一致的目录结构——后者通常更好用。

尽早隔离领域边界

当不相关的业务领域开始互相渗透时，项目就会变得难以理解。

支付逻辑不该悄悄依赖通知逻辑，用户管理不该知道报表是怎么生成的。每个领域需要有清晰的归属、有限的职责、以及与其他系统通信的显式方式。

这对 AI 来说更为重要。边界越小，智能体需要的上下文越少，在任务之外改错东西的概率也越低。

作者偏爱微服务，因为微服务让这些边界更难被忽视——每个服务拥有自己的逻辑、数据和通信契约。

但目标不是制造更多服务，而是让每一次改动都有一个明确的归属地。

康威定律（Conway's Law）由程序员梅尔文·康威于 1968 年提出：任何组织在设计系统时，其产出的系统结构往往与组织自身的沟通结构高度一致。这意味着，如果一个团队是按职能（前端、后端、数据库）划分的，他们设计的架构也很可能按技术分层；如果团队按业务领域（支付、用户、报表）划分，架构就更可能呈现出清晰的领域边界。这条定律对 AI 协作同样适用：当代码库的边界模糊、职责交叉时，往往反映的是团队沟通本身就没有把领域划清楚。智能体没有组织记忆，只能读代码，因此它拿到的边界信息比人类开发者更少。想让 AI 少犯错，先让团队在组织层面把“谁负责哪块业务”讲明白，代码库里的领域边界才会自然变得清晰。

写下那些隐藏的规则

代码展示了系统做了什么，却很少解释为什么。

总有一些隐藏规则存在：一处奇怪的 workaround、一个绝不能升级的依赖、一个看起来可选但实际必须的字段、一条只有某位开发者记得的业务规则。

AI 不会靠猜安全地发现它们，下一位接手的人类开发者也一样。

作者倾向于把这些规则放在项目附近：简短的架构笔记、清晰的 README 文件，以及针对重要约定的智能体指令。不是没人维护的巨型 wiki，而只是足够阻止同样错误再次发生的上下文。

如果一条规则很重要，它就不该只存在于某个人的脑子里。

在软件工程中，这类从未被正式记录、只靠口口相传的知识被称为部落知识（Tribal Knowledge）。它通常包括：为什么某个依赖被锁定在旧版本、某个字段看似冗余却绝不能删、某段代码为何用了一个奇怪的正则而不是标准解析器。部落知识对小团队短期效率很高，因为老成员一问便知；但它的代价随人员流动和时间推移迅速放大——新人要花数周甚至数月才能重建这些认知，而 AI 智能体根本无法通过“问同事”来获取。更隐蔽的风险是：当拥有这些知识的开发者离职，代码库并不会报错，但错误的修改会悄悄积累。缓解办法是把部落知识“外化”为仓库内的架构决策记录（ADR）、README 注释或智能体指令文件，让关键规则变成可检索、可被 AI 读取的一等公民。

给 AI 一个反馈回路

智能体不该自己拍板说“工作已完成”。

在代码层面，它需要能运行的检查：测试、构建、类型检查、linter 以及清晰的错误信息。这些把任务从“写点看起来对的东西”变成“让这个通过，且不弄坏那个”。

作者还喜欢在实现完成之后引入另一个智能体。一个全新的智能体可以审查 diff、质疑方案、寻找遗漏的边界情况，并将结果与最初的计划进行对比。

实现智能体已经对自己的方案产生了投入感，而审查者起点上的假设更少。

当 AI 能写、能测、能失败、能修复、还能为结果辩护时，它才真正变得有用。

类型检查（Type Checking）与 linting 是反馈回路中最廉价、最快的一层。类型检查在编译或运行前验证变量、参数和返回值的类型是否一致，能在代码尚未执行时就捕获大量接口误用；lint 工具则通过静态分析发现未使用变量、可疑的空值处理、风格违规等模式问题。相比单元测试，它们不需要运行完整业务逻辑，因此反馈周期以秒计，非常适合智能体在每次改动后立即自查。对 AI 而言，这两类工具的意义不仅是“发现错误”，更是提供一种明确、可解析的信号：智能体不需要理解整个系统，只要读取报错信息，就能知道自己的修改是否越界。反馈回路越短、越确定，智能体自我纠错的迭代成本就越低，从而把“写点看起来对的东西”逐步收敛为“让检查全部通过”。

单一职责，单一位置

单一职责原则是 SOLID 里的第一个字母，也是最容易被忽视的原则之一。

一个方法应该做一件清晰的事，一个类应该只有一个清晰的变更理由，一条业务规则应该有一个权威的归属地。

这不是要把所有东西都拆成微小的方法，而是让归属和责任变得一目了然。当同一条规则同时出现在控制器、helper 和后台任务里时，开发者和 AI 都无法知道哪个版本才是对的。

SOLID 是面向对象设计中五个原则的首字母缩写，由罗伯特·C·马丁（Robert C. Martin）推广：单一职责原则（S）、开闭原则（O）、里氏替换原则（L）、接口隔离原则（I）和依赖倒置原则（D）。其中单一职责原则最容易被误解为“一个类只做一件事”，但更准确的表述是“一个模块应该只有一个变更的理由”——也就是说，它的职责边界由谁会要求它变化来界定。当一条业务规则同时存在于控制器、helper 和后台任务中时，任何一次需求变更都会迫使开发者在多处修改，而且很难保证一致性。对 AI 而言，这种重复是灾难性的：智能体无法判断哪一处才是权威版本，很容易只改一处而遗漏其他，导致看似正确、实则分裂的实现。

删除错误的示例

AI 通过跟随已存在的东西来学习你的项目。

当仓库里塞满死代码、被遗弃的抽象、旧模式和临时 workaround——而这些 workaround 又阴差阳错变成了永久方案——问题就来了。智能体并不总能分辨哪个示例是当前的，哪个只是意外存活下来的。

与其留着“以防万一”，不如删掉过时的代码。如果旧路径必须保留，就明确标注并解释原因。

每一个陈旧的实现，都是智能体可能满怀信心地抄错的另一个答案。

一个更干净的代码库不仅减少维护成本，也减少了可供走错的方向。

把这几条串起来看，逻辑是一致的：AI 写代码的上限，往往不取决于模型本身，而取决于你的代码库作为一份“提示词”写得有多好。产品与工程团队若想让编码智能体真正发挥价值，与其追最新的模型，不如先回头修一修那些被忽视多年的工程地基。