当代码开始写给 Agent 阅读

你让 AI 改一个函数名，它第一件事是在你的仓库里搜。

这个”搜”没有任何高深的地方：把整个仓库的文字过一遍，看哪些行里出现了你要的那串字符。跟你在编辑器里按 Ctrl+F 是同一回事。命令行里叫 grep，几十年前就有了。AI 用的是它的加速版 ripgrep。

它不会去问编译器要一张依赖关系图，也没有语言服务器帮它把符号解析明白。它认的只有字面。

不是某个工具偷懒。Claude Code 团队早期试过把代码转成向量嵌进数据库，后来扔掉了——因为纯文本搜索效果更好。学术界的 SWE-agent 也落在同一个结论上：给模型专门做的关键词搜索工具，没有更花哨的东西。

门牌越清楚，走错的岔路越少。

每一个标识符都是一次搜索查询

Modem 这家公司从 2025 年初创业时就决定全用 AI 写代码。一年下来 36 万行 TypeScript 应用代码加 32 万行测试代码，99.9% 由模型生成。下面的经验和 1680 次对照实验都出自这一年。

他们拿三个功能完全一样的函数做了对比。区别只在名字。

第一个叫 create。在 Modem 约 2900 个 TypeScript 文件的仓库里搜了一遍：1585 个命中。散在几百样不相干的东西里——测试用的假数据、往数据库里插记录、注册后台任务。

第二个叫 createClient。还是一个泛化名称。几百个命中。

第三个叫 createStripeClient。43 个命中。这 43 个全是：定义、调用点、测试。全都在讲同一个客户端。

问题不在搜得快不快。grep 交回来的是匹配的行，不是答案。一行 const client = create(config) 不能告诉 Agent 这是不是你要找的那个客户端，还是那几百个同样叫 create 的东西之一。

要弄清楚，它得打开文件读命中处周围那一段。一个文件几十到上千行，排除一个错误候选就是几百到几千 token。挨个排除十几个，几万 token 已经没了。而你要它干的活还一个字没动。

14 种主流模型测试同一个结论：只改命名，同一个任务最多少烧三分之二的 token。

不是”代码可读性”，是”代码可发现性”

文件路径也是搜索词。Agent 拿到一个任务问”会话中介是怎么工作的”，它会拿 session-broker、sessionBroker、session_broker 三种拼法去扫文件名。一个叫 session-broker/ 的目录，在它读到第一行代码之前就已经是一次命中。

反过来，一个被拆成三层嵌套 barrels 的模块——lib/components/ui/forms/Input/index.ts——它需要额外跳好几步才能确认这个文件确实是那个 Input。

Agent 搜索的路径是：搜索关键词 → 拿到命中列表 → 打开文件看周围上下文 → 不够就扩大范围或换词再搜 → 够了才开始改。这条链上唯一完全握在写代码的人手里的输入，就是你代码里的词和文件上的名字，能不能当好搜索词。

面向 Agent 的代码质量，首先表现为可发现性。不是”读起来像自然语言”，是”搜一次就能定位到对的文件、打开第一眼就能确认没找错”。

类型怎样缩短查找路径

完整类型是一种隐式的链接。一个带类型的函数签名告诉 Agent：这个函数的输入长什么样、输出长什么样、它依赖了哪些类型。它不需要打开函数体就能判断这是不是它要找的。

弱类型正好相反。一个 any 参数强迫 Agent 读完整段实现代码才能知道参数的真实形状。一个不完整的类型定义让它以为找到了但又不敢确定——于是再打开两个相关文件确认。每一步都是额外的上下文消耗。

Modem 从第一天就用严格 TypeScript，不是因为”最佳实践”，是因为弱类型让 AI 多读代码，多读代码多烧钱。

“写给人读”和”写给 Agent 读”是不是两套标准

大部分时候不是。好名字对人也好，对 Agent 也好。一个叫 formatDuration 的函数搜出来是时间格式化工具，人看一眼也能猜到。

但有一件事是人不需要、Agent 需要的：推测成本。 人看到一个模糊的变量名，可以凭猜往下走，错了也不贵。Agent 不能猜——它的”猜”就是打开更多文件、读更多行、烧更多 token。每一个泛化名字都在制造额外的检索成本，而这些成本在长任务里会被放大。

这件事诡异的是：我们一直在给人类同事做代码可读性，却从没考虑过 Agent 是怎么”读”代码的。 不是语义理解，是搜索。你的每个函数名、每个文件名、每个目录结构——都是一次未来搜索的查询词。写它们的时刻，你已经在帮 Agent 决定它打开的第一批文件是什么。

建议不复杂：唯一的名称、可发现的路由、不隐藏真实位置的目录结构。而这些恰好也是人类同事想要的。

Modem 的数据是个观察，不是定律。代理框架在变——Cursor 已经在 grep 上叠加了语义搜索——但所有搜索方式都喂自同一个输入：源码里的字。 名字越清晰，所有方式都受益。这是 AI 编程时代里，最保险的一笔投资。