审计你的 Agent 文件

TL;DR：你的编码代理配置有“半衰期”。模型在进步，运行框架在增加能力，代码库在变化，而我们为旧版本写下的指令却会被留在原地。近期研究发现，个性化技能的价值并不稳定。我现在每隔几周就运行一次 Claude 的 /doctor，单独检查 memory，并要求每条指令重新证明自己值得保留。

我感觉过去几个月里，尤其是在我阅读 Twitter 上的开发者讨论时，大家对 skill 文件，以及该如何处理 CLAUDE.md 和 AGENTS.md 文件，存在很多困惑。人们常说，嘿，让这些技能文件和 CLAUDE.md/AGENTS.md 文件保持最新，是个很大的痛点。很多时候，大家想用它们来引导自己的代理，但又很难把它们控制在 200 行以内，尽管这算是官方目标。人们发现很难让它们保持精简。它们会抬高 token 成本。随着你不断往里加东西，它们甚至可能让代理变得更差。

代理循环，已经被解码。每个代理的核心循环都一样：调用模型，运行一个工具，把结果再喂回去，重复。真正让它能投入生产的，是你围绕它补上的东西：状态、记忆，以及运行这一切的 harness。Oracle 的开发团队把这件事拆成了三个层次（最小循环 -> 感知记忆的推理引擎 -> 作为系统的 harness），每一层都有可运行的 notebook，方便你真正动手构建，而不只是阅读。若你正把代理从演示阶段往前推进，这篇值得一读。阅读 -> https://fandf.co/4q1byDX · 由 Oracle 赞助。#广告

我读到的官方建议是，你应该定期删除自己的 CLAUDE.md、skills 和 hooks，比如每隔几个月重建一次，只保留真正重要的内容。但我自己的体验是，很多人会担心：我也不知道这么做会不会真的把事情搞得更糟。我担心一旦删掉，质量会明显下降。而且我没有一种简单的方法能快速恢复，或者先试试看。模型可以搭配的配置太多了。所以这类建议听起来像是很容易尝试，可实际并不总是如此。有时这些 markdown 文件和实践会变得过时，弊大于利。但我确实认为，这条建议背后有一点是对的：模型和 harness 的确在变得更强。

我很喜欢 skills，批评也确实有道理。

我个人非常喜欢 Agent Skills。我和几位朋友维护着一些 Agent Skill 包，也确实有了一点传播。我维护 Agent Skills，这是一个面向 SDLC 的包。我的朋友 Paul Bakaus 维护 Impeccable，这是一个面向设计的包。开发者在把 skills 用到编码代理时，整体情绪也一直相当正面。它们被视为一种很好的抽象方式，可以把通才变成专才，对吧？而且它们和很多不同的编码代理及 harness 都能很好地协作。所以大家喜欢它们。

其中一部分批评是合理的。当然，写这些技能的人很多，而且面对的领域差别很大。实际上并没有一套成熟的操作手册说明该怎么做。所以我们都在摸索。我们会吸收彼此的经验，也会持续接受社区反馈并不断迭代。但 skill 的卫生状况依然非常重要。你有时会看到一些 skill 包描述很薄，或者它们的工作流写得比较含糊。所以我仍然认为，agent skills 是我看好的东西，我也认为它们有很大价值。但随着过去几个月里大家更深入地使用它们，审计 skills 也变得越来越重要。

你在任何一天里都可能同时推进很多个并行项目或并行任务。对于其中一些，你也许会尝试新的社区 skills，或者自己整理一些技能包。可以想象，几个月下来，这些本地技能会越积越多，而你大概率不会全部用到。实际上你用到的可能只是其中一小部分。

我读 Hacker News 上关于公共 skills 的讨论串时，争论很明显：有人觉得 skills 有价值；有人说它们净是负面；也有人认为，关于它们价值的证据还不够充分。还有人觉得它们只是增加噪音。token 成本很高。它们不可靠。我当然认为这里面有很多有效反馈。有时要拿出足够的证据，向每个人的工作流证明这些东西确实是净正收益，是挺难的。但也确实有很多人说他们觉得这些东西有帮助，而且也存在不少反馈合理的情形。比如，嘿，证明给我看它确实足够有用，值得我在自己的项目里考虑。

为什么代理配置会腐化

人们会在每次看到代理把自己引向错误方向时，就往 CLAUDE.md 和 skills 里继续加规则。我自己这些年也确实这么做过。然后文件越长越大，遵循度下降，你再加更多规则，结果质量反而可能更差。最后你几乎是在把它当成一个完整知识库，而不是一份简短的决策指南。这是个非常典型的错误。

AGENTS.md 和 CLAUDE.md 过度膨胀也是另一个大问题。我觉得现在这已经算是广泛共识了。针对真实仓库已经做过不少研究，发现有很多相当常见的配置异味。上下文膨胀很常见，skill 泄漏、lint 泄漏也很常见。而这些研究里尝试过的大多数 agent 文件，至少都有一个问题。文件通常都会超过 Anthropic 建议的 200 行。有些甚至长到几百上千行，每次会话都在浪费 token。

我自己也要为此负责。当我回头看自己过去整理的一些 CLAUDE.md 文件时，不是给别人看的，只是我自己的配置，我也已经超过 200 行了。我发现自己文件里也有一些常见失效模式。比如例子过长。重复内容，可能已经存在于 README、package 清单或 skill 文件里。每次代理报错就加一条规则。这类增长会不断叠加。所以我觉得，这件事必须以非常、非常聚焦的方式来思考。我也看到，在 CLAUDE.md 或 AGENTS.md 里过度具体，有时并不一定真的能带来你想要的结果。

具体数字方面：一项 6 月的研究 对 100 个热门仓库的调查发现，62% 存在 lint 相关泄漏，42% 存在上下文膨胀，35% 存在 skill 泄漏。而在 The new rules of context engineering 里，Anthropic 说他们为 Claude 5 系列模型移除了 Claude Code 系统提示词中 80% 以上的内容，而内部编码评测没有可测量的损失。这个结果不是目标；这些评测不是公开的，而且只覆盖特定 harness 中的特定模型。这里的教训是，指令的价值会过期，所以应当先归档；如果某条规则必须始终成立，就把它编码到测试、hook 或权限里，而不是把它留成模型可能会忘掉的散文。

我觉得过去几个月里我读到了一些很好的研究，一些不错的实证研究，或许能帮助这场讨论。我也想确保自己把其中一些内容写进文章里，因为我觉得有些人也没时间去读这些论文。

个性化 skills 会帮助编码代理吗？

我一直在想，Claude Code 或 Codex 是否能逐渐学会我喜欢怎样工作。也许我偏好小改动，希望测试以某种方式运行，或者不希望代理重构无关代码。这篇论文 试图把这类交互历史转化为可复用的个人技能。令人意外的结果是，个性化并没有带来太大帮助。基于某位开发者历史生成的 skill，表现和从别人那里借来的 skill 差不多。相反，基于很多开发者构建的通用 skill，整体更有用。

对我们很多人来说，我们会觉得，为自己的特定工作流准备一堆 skills，确实能带来巨大差异。但一些研究实际上说，这未必如此；基于更广泛的软件工程经验、更多社区最佳实践的 skills，反而可能更合理，也确实能带来更多价值。还有，我也应该补充一点，skills 如果包含更多针对特定任务的示例，确实可能更有价值。有时那些更宽泛的社区 skills 也会包含这些内容。比如我想处理一个和调度有关的问题，而调度有很多不同的处理方式，也有很多细节陷阱。如果我的 skills，不管是哪一种，里面有很多非常具体的例子和细节，也许它们就能以某种方式更好地引导代理。否则，光是写一些像“我希望我的调度原语格式长这样”的细节，其实并没有多大帮助。

当同一种偏好在多个相似任务中反复出现时，个性化看起来更有前景，不过这些实验使用的是基于 LLM 的开发者模拟器，所以应当把它看作有前景，而不是定论。我的结论是，先从一个强的通用 skill 开始，再逐步加入个人规则。我不会因为自己只提过一次，就把某个偏好提升为永久的代理记忆。

我再说一次 skills。当我和公司交流、也和企业聊过之后，他们会把它看作高价值。他们认为单个工程师的 skills 很有用，但当你为团队或组织准备一组 skills 时，他们觉得这会带来叠加效应，这其实挺酷的。所以你可以把工程文化、合规规则、品牌、内部工具的怪癖、你希望如何在不同人和不同编码代理之间保持一致、你希望如何看待评审流程和权限配置，以及这类事情，都捕捉进去。

上下文文件能帮助编码代理吗？

我一直把 AGENTS.md 和 CLAUDE.md 这类文件当作编码代理的操作手册。这篇论文 研究这些文件是否真的能帮助 Claude Code 和 Codex 完成更多任务。在 17 个真实任务上进行了 288 次运行后，它们对正确性没有带来明显差异。

不过，上下文文件确实改变了代理的工作方式。在某个仓库里，指南提醒完整测试套件非常慢。Claude 于是改跑更有针对性的测试，节省了时间。它并没有因此更擅长实现功能，但它更高效地遵循了仓库的工作流。我认为这才是有用的区别。上下文文件可以告诉代理哪些命令代价高、哪些文件是生成的、架构边界在哪里、项目里有哪些特定安全规则。它未必能教会代理如何做出微妙的设计决策；那些差一点就对的地方，通常都归结为实现层面的判断，而不是再多写一点仓库说明就能解决的问题。

我的结论是，把仓库上下文文件聚焦在模型无法轻易从代码中推断出来的东西上：如何跑对检查、哪些操作成本高、哪些内容必须保持不变、以及那些不寻常的项目约定放在哪里。我不会往里面塞关于“写出干净代码”的通用建议。一项相关研究 也指向同样的方向：散文式摘要只能回答 45 个关于代码的行为问题中的 4 个，而源码本身能回答 45 个中的 27 个，因为摘要会抹平那些真正重要的小细节。让代理直接看真实代码，而不是看对代码的描述。

我审计自己的配置后发现了什么

我很高兴看到 Claude 在 Claude Code 里推出了 doctor 命令。这是一个很好的卫生检查命令，基本上会做一次检查，覆盖未使用的 skills、MCP servers 和 plugins，相对于它们占用的上下文成本，还会检查你是否有过度指定的 CLAUDE.md 文件、缓慢的 hooks、杂物之类的问题。当我在自己的配置上运行 doctor 时，我对那些还挂在那里的东西感到非常震惊，而我早就完全忘了它们的存在。要是你问我，我根本不会猜到它们还在。我甚至完全忘了自己曾经试验过它们。

我举个例子。大概四五个月前，我对不同的写作 skills 很感兴趣，想看看别人都在用什么。很多人都在试验各种 anti-slop skills。所以我也试了一大堆。然后我震惊了，因为我完全忘了自己装过多少个。我根本不知道。比如，这些东西会不会一起触发？还是其中一个会优先生效？它们是不是都被忽略了？我完全没有意识到这些东西竟然还在那儿。所以审计这些东西非常有用。有些朋友写的设计 skills，我也试过，但后来都忘了。现在，正如我们看到的，社区在某些情况下已经收敛到一些高质量的 skills，我更愿意依赖这些，而不是几个月前试过的那些实验性方案。

我记得前阵子看到一条推文，有人说，嗯，我开始审计自己的 skills 之后，从 250 个降到了 25 个。我当时就想，怎么会攒到 250 个 skills？这也太夸张了。但你一旦试了很多社区 skills，这些东西确实会随着时间不断累积。你不想把你的代理搞糊涂，对吧？所以你得定期给你的代理环境做 lint 和清理。

安装一个有用的 skill 和把它永远保留下来，是两回事。

审计质量，不只是数量

我觉得 skills 还有一个重要点，就是要确保它们质量够高。Anthropic 自己的 Skill Creator 现在就包含 evals 和 benchmark 模式，用来检查质量。社区里也有不错的工具可以审查 SKILL.md 的质量。比如，它们的描述是否清晰，触发条件是否明确，步骤和示例是否足够清楚？也有更多偏安全方向的审计工具和 skills 最佳实践。

有一个值得知道的命名陷阱：在 Claude Code 里，会话中的 /doctor 是配置审计，而 shell 里的 claude doctor 只会打印安装诊断，所以有些人会觉得 doctor “只显示状态检查”。而且，已安装的 skill 并不会把整篇内容都灌进每个提示词里：名字和描述会为了发现而加载，受一个 listing budget 限制，默认占上下文窗口的 1%，主体内容则会在调用时加载。我也会单独用 /memory 检查 memory，因为自动 memory 即使在项目文件已经整理干净后，也可能仍然保留过时的偏好。

定期审计，再测试移除

所以我个人觉得，最有价值的做法是，也许每隔几周，甚至每个月，跑一次 doctor，检查你的 skills 和整个配置，审视一下你在做什么，然后问问自己：哪些东西现在仍然成立？如果你有时间，还可以真正去试：如果你删除这些 skills，或者明确告诉代理，不要使用任何本地 skills，只用原始模型和 harness 完成这个任务，会怎么样？看看在不使用这些 skills 的情况下，是不是真的也没问题。然后你就可以问自己：其实，我也许真的可以删掉这些 skills。也许完全没问题。

但我觉得，有时我们会把 skills 和所有这些已安装的东西当成拐杖，因为我们觉得移除它们不安全，因为我们并不相信模型和 harness 真的已经变得更好了。所以我认为，我们还有很多可以尝试和学习的地方。

继续保持这些东西的卫生。审计质量，审计安全性。定期运行 doctor 命令，并且尽量确保你的本地配置保持尽可能精简，同时又足够具体，满足需要。

再次感谢我们的赞助商 Oracle。也请看看他们的 Agent Loop Decoded 文章，这是一篇相当扎实的阅读材料，讲清了每个 agent 工程师都必须了解的三个层次。