AI代理总写烂代码？不是提示词的问题，是仓库少了这3样东西

你看到同事删掉了整个聊天记录。他打开一个全新的 AI 编程助手会话，切到同一分支，只给一条任务：“在结账 API 里加一个字段。”没有贴架构文档，没有交代包管理器是 pnpm，没有说迁移脚本是自动生成的。十分钟后，代理读遍仓库文件，自动跑通了测试，交出了一个符合项目分层的小改动。

这不是模型厉害。是仓库在被重新设计之后，已经开始承载“如何工作”这件事。

面对同一份代码，一群工程师和一名 AI 编码代理会读出截然不同的东西。人靠的是入职那周的口头传授、半成文的设置脚本，以及一句“认证这块你去问 Priya”。代理没有 Priya 可问。它只能模式匹配目录树里有什么、能用 grep 搜到什么。如果你写在项目里的不是“这里如何运行”的结构化指令，而是一堆需要人类补全的空白，代理就会在路由处理器里写业务逻辑，因为它三文件夹外找到一个相似的文件。你怪提示词，其实该怪仓库。

这不是一个工具的争论。2026 年初，Hélio Medeiros、Fabisevich、Marmelab、Sourcegraph、Vstorm 等多个团队和个人几乎同时得出一致结论：代理的生产力是一个架构问题。工具重要，但结构更重要，反馈环路更更重。

仓库不再是代码的容器，而是开发者的接口——也是代理的接口。InfoWorld 一篇《为代理编码》的文章甚至提出，上下文已经是基础设施：测试命令、边界规则、“别碰”的路径，都成了当工人是代理时工作运行的一部分。

所以，这篇东西是一份实用提炼。不崇拜工具。只讲你该往仓库里加什么，才能让 Copilot、Claude Code、Cursor、Codex 或者下个月你换的什么新东西，不需要你每开一次会话就重新解释整个项目。

提示词为什么渐渐失灵

人的上下文继承很便宜，一句“和上次一样”就能传递大量预设。代理没有“上次”。每次新会话，它面对的就是文件树和一纸空白的理解。你当然可以手写长篇提示，把团队约定重新敲一遍，但那恰恰是反模式：你在用人类对接的方式去补偿仓库本身的信息缺失。Medeiros 把仓库比作接口，就是这个意思。软件工程的接口会把调用规则写清楚，好的仓库也该把开发规则写清楚。如果没有，代理就只能猜。

从认知上解释，代理不是在“理解”项目，而是在搜索和模式匹配。它看到的每一个文件命名习惯、每一个脚本里的标志位，都会成为它决策的概率权重。如果锁文件有多种格式、安装命令隐藏在某个 Makefile 的注释里、单元测试需要某个持续集成流水线里才有的特殊标志——这些对于人类是可以问出来的信息，对于代理就是信号断点。一旦断点太多，它就会沿着最相似的路径滑下去，而那条路径往往不是你想要的。

所以不是提示词写得不够细。是那份细，本不该由提示词负责。提示词应该描述“要做什么”，不负责解释“这里怎么运作”。把运作知识从人类脑中和聊天记录里转移出来，固化到仓库里，是让代理生产力翻倍的关键一步。

反方观点：这个锅，模型不该背吗？

有人会说，这些问题不过是模型还不够强。如果未来模型的上下文窗口能吞下整个代码仓，推理能力能自动推导出所有隐性约定，那何必花时间整理仓库？让模型适应人，而不是人适应模型，才是工具发展的正道。何况，团队已经习惯了口头文化，突然要求把一切写进结构化文件，会抬高协作门槛，变成文档负担。

这个看法低估了两件事。第一，高上下文窗口并不能解决“信息不存在”的问题。如果测试用的某个标志只存在于某位同事的终端历史里，从来没有被提交到仓库里的任何文件，模型上下文再大也看不到它。

第二，推理能力再强，也无法可靠地区分“某段看起来像业务逻辑的代码放在路由处理器里”究竟是团队有意为之，还是一个需要纠正的错误。仓库里缺失的规范，就是缺失的规范。模型不会替你凭空发明出来。

而且，把运作规则写成代理规范文件这类东西，并不是在为代理写文档。它恰好是为人类自己写文档——你写的就是一个优秀高工入职第一天需要知道的东西。代理只是逼你面对这个事实，因为它们从不参加入职培训。

一张试纸：十分钟判断你仓库的代理就绪度

在你责怪提示词之前，先用一个简单实验检验自己仓库的现状。

第一步，删除所有聊天历史。不要让上一次会话的上下文残留进来。第二步，在同一个分支上打开一个全新的代理会话。第三步，只给一个真实的任务，比如“给结账 API 加一个字段”或者“修复 X 模块里失败的那个测试”。不要贴架构说明，不要补充“我们用 pnpm”“迁移脚本是自动生成的”这类注脚。

如果代理仅靠已提交的文件完不成任务，那说明你仍然在替代理背负它本该从仓库中获取的知识。十分钟的测试，会精确告诉你下一步该往仓库里补什么。