你的代码库要为 AI 编程重写一遍

摘要代码库一直是为人写的。Agent 进来后多了一类读者它不脑补只看得见上下文里那一角。本文聊怎么把边界、契约和隐性知识重写进代码本身让仓库自己长成 Agent 能干活的样子。你让 Agent 改个小需求给报表模块加一个导出字段。它在仓库里转了十分钟最后把逻辑写进了一个几乎同名的方法——那个方法属于隔壁模块。你看着 diff 哭笑不得模型明明不笨怎么净往坑里跳先别急着怪模型。换你自己进一个陌生仓库第一件事也是找哪个文件管哪块。你能找对是因为你会脑补看到calculate_total你猜得出它跟价格和税有关看到目录叫billing你知道付款逻辑八成在这。这套脑补能力Agent 没有。问题在于你的代码库人写的有的没有注释有的注释和跟实际对不上。Agent 读代码跟你不是一回事过去三十年软件工程的所有默认设置都围着人脑转。文件夹按人的习惯分注释写给接手的同事看抽象层是为了让人脑一次少记几个概念。ShShell 那篇讲 Repository Intelligence 的文章把这个局面说得很准传统仓库里的命名、目录、注释服务的都是「一次只能装下几个概念的人脑」甚至还有那种省行数但藏意图的聪明代码——人看着都要愣一下Agent 更看不懂。Agent 是怎么读的它不脑补只看得见被塞进上下文的那一小角。一个百万行的单体仓库对它是大片大片看不见的黑它能看见正在改的文件看不见五个目录之外那个会被这次改动连累的遗留模块。ShShell 给了一个数Agent 把九成精力花在「找业务逻辑在哪」只剩一成花在真正干活上。你可能会说上下文窗口不是越做越大了吗。确实在变大但塞进去不等于用得上。NVIDIA 的 RULER 基准测过一个扎心的数模型的有效上下文往往只有标称窗口的 50% 到 65%。窗口再大注意力也摊不平。那怎么办这就是今年越来越多团队在做的事把代码库按 Agent 的读法重写一遍。补文档、写规则文件为什么都不是答案直觉一给 Agent 补文档。方向对但它有个致命弱点——会漂移。今年一份工程手册里的 ADR 分析把这层窗户纸捅破了写在函数旁边的 docstring 跟代码打架import 的时候就会暴露可一份独立维护的文档跟代码打架能静默通过所有 CI 检查没人发现。文档是复印件代码才是原件复印件迟早过期。直觉二写规则文件。AGENTS.md 这类约定确实火开源仓库里已经铺了六万多个。可它的天花板摆在那Anthropic 自己的建议是 CLAUDE.md 别超 200 行再长遵循率明显掉Codex 默认读 AGENTS.md 到 32KiB 就停。更扎心的是网站侧的 llms.txt——Ahrefs 实测约三万八千个发布了这份文件的域名里97% 的文件从来没有被任何 AI 爬虫抓取过。你精心写的说明书读者根本没翻开。这两个直觉都错在哪错在把「让 AI 看懂」当成加一层说明的事。说明是路标路还是那条烂路——路本身不改路标插得再多Agent 该迷路还迷路。正解是把力气花在代码自己身上让边界、契约、隐性知识长进代码的结构里仓库自己会说话。第一刀把边界画在明面上先看一个最常见的坑。同一个业务对象auth 服务里叫User账单服务里叫AccountCRM 里叫Client。人没问题知道是一个东西Agent 会在某个下午把它们当成三个东西给你幻觉出一个跨系统同步的 bug。命名统一不是洁癖是在给 Agent 铺语义地图。目录也一样。Short and Clear 那篇文章给了个好对照src/services/user_service.py是给人看的分层习惯src/billing/calculate_invoice_use_case.py是让 Agent 一眼定位的喊名法——目录名直接喊出业务。它管这叫 Screaming Architecture让仓库结构自己喊出「这个系统是干嘛的」。边界画清楚还有个额外好处。六边形架构里业务核心只暴露端口数据库、外部服务都是可替换的适配器。你让 Agent 给订单处理加一个 MongoDB 的适配器它照着端口接口生成就行核心业务规则碰都不用碰——边界就是护栏。这里有个反直觉的地方值得单独说。AI 友好的代码是拆得更碎吗恰恰相反。人为了让人脑省力习惯把一个概念拆成工厂、策略、适配器五层每层一个文件。对模型来说这是跳转税每跳一次就多烧一份上下文。一个概念完整、边界清楚的高内聚文件比硬拆五层更容易被读懂。真正该留的规矩就一条有真实的多实现时再做抽象别为想象中的未来预留。第二刀让编译器和测试替你管教它改代码这件事上编译器是 Agent 最好的师傅。强类型底下Agent 生成的调用缺了参数、类型对不上编译器把行号列号精确报出来它自己读报错、自己改全程不用回来烦你。类型系统把模型的搜索空间框住了——它不再凭语感猜只能在契约里动。这就是为什么 strict 模式下的 TypeScript、Go、Rust 项目里Agent 的产出明显更稳。没有类型可依赖的动态语言怎么办用契约注释补。今年有团队把一条规矩写成了架构决策每个源文件开头用该语言原生的文档格式回答四个问题——这个文件做什么、明确不做什么、公开接口是哪些、不显然的设计决策为什么这么定。Agent 动手前先读契约就能少踩「把有意为之的设计当 bug 修掉」这种坑。测试的价值也换了位置。test_should_reject_order_when_credit_limit_exceeded这个测试名本身就是一行行为规格比任何注释都精确地告诉 Agent「超额订单该被拒绝」。ShShell 那句话说得狠没有测试的代码库对 AI 是隐形的。顺带一个趋势数据New Relic 的 2026 报告里78% 的团队已经习惯在 prompt 里要求把日志和埋点直接写进 AI 生成的代码——可观测性不再是人写完再补的工序成了生成时的一部分。第三刀把隐性知识搬进代码你的项目里一定有这种知识这个模块容易出事动它之前先跑全量回归这个字段看着能删其实下游有个报表在偷着用这条链路当年重构踩过坑别按教科书的方式改。这些全在老员工的脑子里代码里一个字都没有。对人类团队这叫传帮带。对 Agent这是真空——它每次进项目都是全新人没有茶水间没有老同事只有文件里写没写。你不把知识搬出来它就只能靠猜猜错就是开头那个改错模块的故事。但搬有搬的规矩。记忆文件不是越多越好它只该装代码表达不了的东西历史决策、跨系统协议、踩坑记录。能从类型和结构推出来的就别重复写——写多了文件膨胀膨胀了遵循率掉又回到 200 行红线那个问题。隐性知识显性化是好事把显性知识再抄一遍是给上下文交税。老仓库别推倒改到哪补到哪看到这你大概想问几十万行的老项目难道要停下来重写半年不用这事可以渐进。有现成的迁移策略可以抄新建的文件立即按新规矩来存量文件改到哪个补哪个。三个月下来最常被改的那批文件就都合规了——而那批文件恰恰是 Agent 最常碰的投入产出比最高。施工队都是现成的就是 Agent 自己。命名统一、类型补全、函数拆分这类活人做起来枯燥AI 做起来又快又稳。有开发者拿它重构一个三年老项目的核心模块代码行数少了四成单测覆盖率从 30% 拉到 85%。但有一条纪律别破让它先列清单、你确认、再批量改。一句「自动全改」下去它漏掉的隐含状态依赖会让你修到怀疑人生。哪些仓库值得花这个力气判断标准很简单Agent 触碰的频率。天天让 AI 改的模块值得第一个改造一年没人动的角落放着就好。重写是给高频读者修的路不是给荒地铺的铁轨。小结你的代码库多了类不脑补的读者它九成精力花在找路上——这不是模型的 bug是仓库的债。补文档和写规则文件都是路标真正的路是把边界、契约、隐性知识长进代码结构命名统一、目录喊业务、类型框搜索空间、测试当规格、知识只搬代码装不下的。老仓库不用推倒改到哪补到哪让 Agent 修它自己要走的路——但批量改动前先让它列清单你点头。参考资料Making Your Codebase Legible to AI: Repository IntelligenceShShellAgent 90% 精力用于定位、命名不一致引发幻觉、无测试即隐形。AI-Driven System Architecture 2026The Vibelog类型契约作为 Agent 自纠错回路、四大支柱。AI Native 架构有限上下文、确定性边界与质量闸门51CTO高内聚优于硬拆五层、有真实多实现再抽象、隐性知识显性化分层。ADR-26045: AI-Native Development — Code as Primary DocumentationSoviar Systems文档漂移机制、契约注释四问、渐进迁移策略、NVIDIA RULER 有效上下文 50–65%。Agent instruction file (AGENTS.md, llms.txt)Data PandaAGENTS.md 六万仓库、CLAUDE.md 200 行建议、Codex 32KiB 截断。What Is AGENTS.md?llms-txt.ioGitHub 分析 2500 仓库可执行命令胜过含糊散文。The agent-interface trackeragentinterface.appAhrefs 实测约 3.8 万域名发布的 llms.txt 中 97% 从未被 AI 抓取。Future-Proofing Your CodeShort and ClearScreaming Architecture、六边形端口适配器、测试即规格。AI 时代的代码重构该怎么做CocoLoop三年老项目重构实测行数 -40%、覆盖率 30%→85%、先列清单再批量改。AI-Generated Code Grades Higher in Review, Yet Triggers Rise in Production IncidentsDEVOPSdigest引 New Relic 2026 报告78% 团队要求把遥测埋点写进生成的代码。作者唐悦玮 | 从后端出发用 AI 拓展到全栈的工程师。