最好的智能体界面，是代码库地图

编程智能体常常还没写出坏代码就先失败了：它不知道这个活该放在哪里。

资深工程师知道哪个模块管哪个功能，哪些测试定义了契约，也知道哪个目录看着相关、其实不该碰。这些知识多半不在代码里，在人的脑子里，在旧 pull request 里，在审查习惯里。智能体没有这段历史。仓库不把结构摆出来，它就只能靠搜索结果和旁边的文件去猜。

道理很简单：适合智能体干活的代码库，不是 prompt 更长的代码库，是一眼能看出该在哪里动手的代码库。

更多上下文不等于地图

7 月 2 日修订的论文 How Much Static Structure Do Code Agents Need? 试了一个很实际的想法：把调用关系、继承关系、配置依赖这些简单信息交给编程智能体，看看会怎样。

提升不大，但有用。函数级定位提高 2.2 个百分点，每次任务平均少 1.6 轮交互，几次运行之间的结果也更稳。中型代码库上，Pass@1 提高 3.4 个百分点，代价是输入 token 多了大约 10%。这张地图买到的，主要是少走冤枉路。

这件事要紧，因为很多团队还把智能体失败当成 prompt 问题：加指令，贴更多文件，让模型多想一会儿。这些办法有点用，可是上下文窗口再大，也说不清谁负责哪个决策、哪项测试才是真契约。

智能体总改错文件，问题可能出在代码库身上。

代码库就是界面

对人来说，好的代码库本来就像一个界面。命名、目录、模块边界、测试、架构记录，都在告诉你该看哪里，什么别碰。智能体让这个界面的缺口更显眼，它们最容易栽跟头的地方，恰恰是只有老成员才摸得清的那些角落。

代码库地图不一定是什么新的可视化工具，几组说得清的答案就够了：哪个模块管这个行为，谁在调用这个函数，哪项配置控制它，哪些测试定义契约，哪份决策记录讲了取舍，这次修改该谁来审。

这些都是普通的工程活。只是有了智能体，这些活值多少钱，更容易看清了。

计划和检查也是地图的一部分

论文 Spec Growth Engine 从规格的角度谈同一个问题。它说智能体干活有两个风险：上下文太多，代码悄悄偏离原计划。它设计的系统只把规格里相关的那部分交给智能体，代码和规格一分岔，就挡住合并。整套框架对多数团队来说可能太重，核心想法却站得住：智能体既要知道在哪里干活，也要知道这次修改允许改变什么。

更大的技术任务里也有同样的规律。Reboot 把 C 解释器翻译成安全的 Rust，办法是把工作拆成一个个完整、可测的功能。只这一步，验证通过率就比单纯的多智能体翻译高出 6 到 20 个百分点。NOVA 做工业推荐系统的架构工作：任务按风险分派，检查跑好几层，智能体不该走的路记下来，高风险的活交给人。其中一项任务，论文报告人盯着的时间缩到原来的十三分之一，无声失败也比它的编程智能体基线少。

系统各不相同，结论倒一致：路线、边界、检查越明确，智能体自己干活越靠得住。

更好的模型仍然需要清楚的代码库

反方观点也讲得通：模型会越来越会读代码库，自己建地图。翻历史，跑测试，还能提问。代码库地图，也许只是给今天这些还不够强的智能体搭的临时脚手架。

更好的模型确实不用那么多帮助。可是优秀的工程师照样能在乱糟糟的代码库里干活，所有权和架构我们还是照记，因为每次重新推断太慢，结果不稳，也没法审查。这条规则对智能体一样成立。智能体在一次任务里建的地图，私有，临时；存在代码库里的地图，谁都能检查、改进、复用。

智能体就绪就是良好的工程实践

实际结论比不上一款新产品让人兴奋：把代码库弄得好懂，智能体的表现就会变好。模块所有权清楚，垂直切片够小，契约测试齐全，架构记录不过期，依赖边界明确。这些活对新来的工程师同样有用。一个行为在哪里，什么不能动，改完怎么验证——人和智能体都答不上来，说明代码库把要紧的知识藏起来了。

我估计到 2027 年底，严肃的软件团队谈”智能体就绪”，会少谈 prompt 怎么写，多谈代码库质量。从编程智能体身上拿到最多好处的团队，靠的不是最长的指令，是让人一眼找到正确改动位置的代码库。

最好的智能体界面，可能就是代码库本身。