本文是 Agent Skills 系列教程第 1 篇。这一篇不写任何 skill 文件,只回答一个前置问题:为什么你的 Agent 明明有 AGENTS.md、有精心调过的 prompt,却还是稳定地产出烂代码。答案不在 prompt 里,在 codebase 的结构里。
如果你用过 Claude Code 或 Cursor 这类编码 Agent,大概率经历过这种挫败:你花了一个下午写了份 AGENTS.md,把项目背景、目录约定、测试命令、部署步骤全部交代清楚;又对着 prompt 反复打磨,告诉它“不要过度设计““复用现有工具函数”“改完跑一下测试”。然后你丢给它一个任务,它返回的代码要么放错了层,要么重新发明了一个已经存在的轮子,要么改了 200 行你完全没打算让它动的东西。
你自然会怀疑是不是 prompt 写得还不够细。于是你继续加约束,越加越长,Agent 却越来越“听话而不靠谱“——它执行你的字面指令,却仍然不理解这个项目到底长什么样。
问题就出在这里:决定 Agent 产出质量的首要因素,从来不是 prompt,而是 codebase 本身的结构。 一个结构混乱、没有可感知组织方式的代码库,无论你喂多好的 prompt,Agent 都会在里面制造出同样混乱的代码;而一个结构清晰、能被快速理解与验证的代码库,Agent 才能稳定地做对事情。这是整个系列的地基——后面所有 skill 的写法、所有“深模块““灰盒模块“的改造,都建立在这个判断之上。
Agent 是「没有记忆的新人」
要理解 Agent 为什么这么依赖 codebase 结构,先要接受一个反直觉的前提:Agent 每次开工都是一个失忆的新人。 原文把这种状态描述为 “new starters with no memory”——这是 Matt Pocock 在 aihero.dev/skills 里的说法。它就像一个刚入职、对公司历史一无所知的新员工,而且比新员工更极端。
它极端在哪?三个特征叠加在一起:
第一,每次会话都是从零开始。 人类工程师会积累——上周刚改过这个模块,知道它的边界在哪、哪些地方是坑、哪位同事负责;下一次开工时这些记忆直接拿来用。Agent 没有这份积累。每一段新会话,它面对的都是一个“全新“的项目,上一次会话里它辛苦建立起来的理解全部清零。
第二,它被“克隆“之后立刻就要干活。 想象一个新员工刚拿到电脑、刚 clone 完仓库,连代码都还没看完一遍,就被要求立刻提交一个改动。这不是夸张,这就是 Agent 的真实处境——它没有 onboarding 期,没有“先花两天熟悉代码“的缓冲,从第一秒开始它就在产出。
第三,它只能通过文件系统感知项目。 这是最关键的一点。Agent 没有在团队里待过,没有参加过需求评审,没有和同事聊过架构演进的历史。它对项目的全部认知来源只有一个:磁盘上的那些文件。它读不到你脑子里、团队 wiki 里、或者过去一次重构决策里的上下文——除非这些东西被写进了文件系统,被写成了它读得到的形式。
这里有个很扎心的对比。当一个人类工程师打开一个中等规模的项目,他脑子里会自动浮现出一张“心智地图“:这是缩略图编辑器、那是视频编辑器、这部分是 auth 鉴权、那几个是 CRUD 表单。他能凭这张地图迅速定位“改这个 bug 应该去哪个文件“。而 Agent 打开同一个项目时,看到的不是这些有意义的模块分组,而是一堆互相 import 的模块——它不知道哪个是入口、哪个是工具、哪个是核心业务逻辑、哪些文件之间在概念上属于同一块。
这就是全部的差异来源:人类脑中的心智地图,Agent 天生没有。而 codebase 结构的意义,就在于决定这张地图能不能被 Agent 从文件系统里重建出来。
三大失败模式
当一个 codebase 无法让“没有记忆的新人“重建心智地图时,Agent 会以一种稳定的、可预测的方式失败。这些失败可以归纳成三种模式:弱反馈闭环、导航困难、认知过载。
弱反馈闭环:改完不知道对不对
Agent 修改代码之后,最需要的是一件事:快速验证它改的东西有没有达到预期。 但这个闭环在大量项目里是断裂的——测试跑不起来、构建依赖一堆本地环境变量、没有一条“改完就能跑“的反馈路径。
后果是,Agent 只能“盲改“。它不知道自己的改动是往对的方向走了还是引入了回归,于是它倾向于两类行为:要么反复试错、不断抛出和收回改动,制造大量噪音;要么干脆保守到不敢动、只做最表面的修改,敷衍了事。无论哪种,产出的都不是可靠的代码。
导航困难:找不到文件,不知道测什么
“没有记忆的新人“要做的第一件事是找到该改哪个文件、该看哪个函数、该跑哪条测试。但在一个组织混乱的代码库里,这本身就是个高难度动作:目录命名和业务不对齐、一个功能散落在十几个文件里、测试在哪里都说不清。
对人类工程师,这是“熟悉了就好“的摩擦;对 Agent,这是致命的。因为它没有任何历史经验来帮它“猜“,它只能靠文件系统里暴露出来的结构去推。结构不提供线索,它就找错地方,找错地方就会在错误的地方打补丁。
认知过载:人被迫替 AI 缝合
第三种失败最容易被忽略,因为它不在 Agent 身上发生,而在人身上发生。当一个 Agent 的输出和现有系统之间的连接不清晰时——它写的代码要插进哪个模块、调用哪个已有接口、遵循哪套约定——这些连接不会自动接上。于是人就不得不手动补上 AI 输出与现有系统之间的这段缝合。
这个缝合成本是隐性的:表面上 Agent 写了代码,实际上你得一行行 review 它有没有放对层、有没有重复造轮子、有没有绕过既有的抽象。当你花在“替它理解项目“上的时间超过了自己写的时间,Agent 就不再是生产力工具,而是一个需要你伺候的对象。认知过载的根,不在 Agent 的能力,而在 codebase 没有把“连接点“显式地暴露出来。
「心智地图」:所有问题的根
如果把三种失败模式往底层再挖一层,会找到同一个根:文件系统本身不提供分组。 文件系统给你的是目录和文件,但它不告诉你“这五个文件加在一起是一个缩略图编辑器““那两个目录合起来是 auth 模块”。这些分组只存在于人类的脑子里。
对一个有记忆、有历史的人,这不是问题——地图在他脑子里,他扫一眼文件就能把文件“挂“回地图上。但对一个“没有记忆的新人“,文件系统给什么,它就只能看到什么。文件系统给的是一堆平铺的、互相 import 的模块,它就只看到一堆平铺的、互相 import 的模块。人类脑中的模块关系,它感知不到。
这就是为什么前面说“心智地图“是根问题:弱反馈闭环之所以致命,是因为 Agent 连“改完后该对着哪个预期去验证“都建立不起来;导航困难之所以致命,是因为 Agent 没有任何地图可以参照来定位文件;认知过载之所以发生在人身上,是因为人必须把自己的心智地图“翻译“给 Agent,而 Agent 却接不住。
所以,如果 codebase 的结构不能在文件系统这一层就显式地表达出“分组“和“关系“,那么无论 prompt 写得多好,Agent 都只能在黑暗中摸索。结构先于 prompt——这是本系列要反复回到的一句话。
codebase 的质量,就是输出的质量
到这里,可以推出那句最扎心、也最重要的话。原文这样讲:
“If you have a garbage code base, the AI will produce garbage within that code base.”
如果你有一个垃圾代码库,AI 就会在这个代码库里产出垃圾。这话的潜台词是:AI 不会自己变出结构来。 它是“从结构里学结构“的——给它一个混乱的代码库,它学到的范式就是混乱,产出的自然也是混乱;给它一个结构清晰的代码库,它才可能产出结构清晰的代码。你喂进去的上下文质量,直接设定了它输出的天花板。
那应该把 AI 当成什么来看待?原文给的答案是:把它当成**“有怪癖的人”**——原文的表述是 “humans with weird constraints, no memory, cloned and go right to work”:他们像人一样能读代码、能推理,但带着一堆奇怪的限制——没有记忆、被克隆出来后立刻就要开工。这个定位很关键:它既不是“全知全能的神“,也不是“只会拼凑的傻瓜“,而是一个有真实能力、但受限于“失忆 + 零上下文“的人。
一旦接受这个定位,一个推论就浮出来了:既然大家都用着差不多的模型,那么“过程“——也就是你引导 Agent 干活的那套路径——就成了真正的差异化因素。 模型能力是现成的、人人都能调,真正能拉开差距的,是你让 Agent 面对一个怎样的代码库、遵循一条怎样的路径去干活。
而正因为 Agent 没有记忆,你无法指望它“自己记得怎么做“。你只能给它一条每次都要严格遵循的路径,让它每一次开工都走上同一条可靠的路,而不是每次重新摸索。这条“每次严格遵循的路径“,就是 skill 的由来——skill 不是用来炫技的 prompt 技巧,而是把“正确的过程“固化下来,去弥补 Agent“没有记忆“这个先天缺陷。
出路:深模块与灰盒模块
那具体该怎么做,才能让一个 codebase 对“没有记忆的新人“友好?这是接下来几篇的核心内容,这里只先抛出两个方向。
第一个方向是深模块。这个概念来自 Ousterhout 的《A Philosophy of Software Design》——好的模块应该有“深“的接口:对外暴露得少(接口窄),内部做的事情多(实现深),把复杂度藏起来而不是摊给调用方。对 Agent 来说,深模块意味着它只需要理解一个很窄的接口,就能正确使用一块强大的能力,而不必搞清楚内部的所有细节。这直接降低了它对“心智地图“的重建成本。
第二个方向是灰盒模块。深模块解决“怎么用对“,灰盒模块解决“谁负责什么“——人负责设计并守住模块的公共接口,AI 负责接口背后的内部实现,测试负责锁住模块的行为;只要测试还绿,就无需翻开内部。这两个概念都指向同一个目标:让模块关系和分组,能从文件系统里被重建出来。
这两个方向,第 2 篇 · 深模块与灰盒模块会展开讲。这一篇你只需要记住它们的指向:codebase 的改造不是为了“让人类看得更舒服“,而是为了让那个“没有记忆的新人“——你的 Agent——能在第一次看到这个项目时,就建立起接近人类的心智地图。
小结
这一篇想让你带走的只有一句话:先让代码库「AI 友好」,skill 才有地基。 在你纠结 AGENTS.md 怎么写、prompt 怎么调之前,先退一步问自己:如果我是一个失忆的新人,第一次打开这个项目,我能看懂它吗?如果答案是否定的,那 Agent 也看不懂,而它产出烂代码,不是它的错,是结构错了。地基打不牢,后面所有的 skill 都是空中楼阁。