Audit your Agent files

审计你的代理文件 - Addy Osmani - Elevate

审计你的代理文件

关于审计你的编码代理仍需哪些内容的实用指南

Addy Osmani

2026年8月27日

TL;DR：你的编码代理配置具有半衰期。模型持续改进，工具链不断增加新功能，代码库不断变化，而我们为旧版本编写的指令却停留在原地。近期研究发现个性化技能的价值存在不一致性。我现在每隔几周就会运行一次Claude的/doctor功能，单独审查记忆部分，并要求每条指令重新证明其存在的必要性。

我觉得关于技能文件以及如何处理你的CLAUDE.md和AGENTS.md文件，存在很多混淆，特别是在过去几个月阅读Twitter上的开发者讨论后。人们常说，保持技能文件和CLAUDE.md/AGENTS.md文件的更新是一个很大的痛点。很多时候，人们试图通过这些文件来指导代理行为，但即使200行是官方目标，也很难保持文件长度。人们发现很难保持这些文件简洁，它们会增加token成本，而且随着不断添加内容，可能会让代理表现变差。

解码代理循环。每个代理都遵循相同的内核循环：调用模型、运行工具、反馈结果、重复循环。使一个代理达到生产就绪状态的是围绕这个循环添加的内容：状态、记忆以及运行它们的工具链。Oracle的开发团队将其分解为三个层次（最小循环→具备记忆能力的推理引擎→作为系统的工具链），每个层次都有可运行的笔记本，让你可以实际构建而非仅仅阅读。如果你的代理已经超越演示阶段，这值得一读。阅读链接→https://fandf.co/4q1byDX · 由Oracle赞助。#ad

我读到的官方建议是，你应该定期删除CLAUDE.md文件、技能文件和钩子文件，比如每隔几个月，只重建真正重要的部分。但根据我的个人经验，人们对此存在恐惧：嘿，我不确定这样做是否真的会让情况显著恶化。我担心如果这么做，质量会大幅下降，而且我没有简单的方法可以快速恢复或尝试。我可以使用模型的配置方式有很多种，因此这种建议有时看起来很容易尝试，但实际情况可能并非如此。有时这些Markdown文件和实践可能会过时，反而造成更多伤害。但我觉得这些建议中确实有值得借鉴的地方，即模型和工具链确实会变得越来越好。

我是技能的粉丝。批评依然合理。

我个人非常推崇代理技能。我和一些朋友维护了一些获得一定关注的代理技能包。我维护的Agent Skills是一个以SDLC（软件开发生命周期）为重点的包。我的朋友Paul Bakaus维护的Impeccable是一个以设计为重点的包。总体来看，开发者使用技能与编码代理时的反馈普遍积极。它们被视为将通用型代理转变为专业型代理的良好抽象方式，对吧？而且它们与许多不同的编码代理和工具链都能很好地配合。因此人们喜欢它们。

一些批评意见是合理的。当然，不同领域的人都会根据各自的需求撰写这些内容，目前并没有一套成熟的指导方案可供参考。因此，我们只能边实践边摸索，并相互学习。我们会采纳社区的反馈，持续改进这些内容。但技能管理仍然非常重要。有时你会发现某些技能包的描述过于简略，或其工作流程的说明不够明确。因此，我仍然坚信代理技能的价值，我认为它们具有重要意义。但过去几个月里，随着越来越多的人开始使用这些技能，对技能的审核也变得越来越重要。

在任何一天，你都可能同时进行多个不同的并行项目或并行任务。对于其中一些任务，你可能会尝试使用社区提供的新技能，或者尝试自己为这些任务构建技能。可以想象，经过几个月的积累，这些技能会逐渐在本地环境中堆积起来，但你很可能并不会全部使用它们。实际上，你可能只会使用其中一小部分。

当我阅读 Hacker News 上关于公共技能的讨论时，争论非常激烈。有人认为技能确实有价值，也有人认为它们是净负面因素。还有人认为目前缺乏足够的证据来证明其价值，也有人认为这些技能只是增加了噪音。它们涉及高昂的令牌成本，可靠性不足。我当然认为这些反馈中有很多合理的观点。有时确实很难为所有人的工作流程提供足够的证据来证明这些技能是净正面的。但确实有很多人表示这些技能对他们有帮助，也有许多案例表明这些反馈是有效的。例如，有人会说：“请向我展示这些技能实际上对我项目的价值。”

为什么代理配置会退化

每当看到代理引导你走向错误方向时，人们就会不断向 CLAUDE.md 文件和技能中添加新规则。我过去也做过类似的事情。随着时间推移，文件会不断膨胀，遵循规则的严谨性下降，规则越来越多，质量反而可能下降。你几乎会把它当作一个完整的知识库，而不是一个简洁的决策指南。这是一个非常经典的错误。

AGENTS.md 和 CLAUDE.md 文件的膨胀也是另一个重大问题。目前这一点已经得到广泛认可。已有多个研究项目对真实仓库进行了分析，发现了很多常见的配置问题。上下文膨胀、技能泄露、代码规范泄露等问题非常普遍。这些研究项目测试的大多数代理文件都至少存在一个问题。文件长度通常会超过 Anthropic 的 200 行指导建议，有些甚至达到数百甚至上千行，每次会话都会浪费大量令牌。

我也要为这个问题负责。当我回顾过去整理的一些CLAUDE.md文件时（这些文件并非用于分享，而是我自己的配置），发现其中有些文件的行数也超过了200行。在分析自己的文件时，我发现了一些常见的失败模式。例如，示例过长、重复内容（可能出现在README文件、包清单或技能文件中），以及每次代理出错时都添加新规则。这种增长趋势会持续累积。因此我认为，必须以非常专注的方式思考这个问题。我还发现，在CLAUDE.md或AGENTS.md文件中过于具体地描述规则，有时反而无法达到预期效果。

关于数据：一项6月份对100个流行仓库的研究发现，62%的仓库存在与代码检查相关的泄漏问题，42%存在上下文膨胀问题，35%存在技能泄漏问题。在《上下文工程的新规则》中，Anthropic提到，他们在Claude 5生成模型中移除了Claude Code系统提示的80%以上，且在内部编码评估中没有可衡量的性能损失。但需要说明的是，这一结果并非目标，因为评估结果未公开，且仅适用于特定模型和特定测试环境。关键教训是：指令的价值可能会过期，因此应优先归档，如果某些规则必须始终有效，应将其编码到测试、钩子或权限中，而不是以模型可能遗忘的文本形式存在。

我认为最近几个月读到的一些研究非常有价值，其中一些实证研究或许能帮助推动相关讨论。我希望在文章中涵盖这些内容，因为我认为有些人可能还没时间阅读这些论文。

个性化技能是否有助于编码代理？

我一直在思考，Claude Code或Codex逐步学习我偏好的工作方式是否会有帮助。也许我更倾向于小规模修改，希望以特定方式运行测试，或者不希望代理重构无关代码。这篇论文试图将这种交互历史转化为可复用的个人技能。令人惊讶的结果是，个性化并没有带来显著帮助。基于某位开发者历史记录的技能与借用他人技能的效果相当。而基于大量开发者构建的通用技能总体上更有用。

对我们许多人来说，认为拥有一套针对特定工作流程的技能能带来巨大差异是理所当然的。但一些研究实际上表明，这未必总是成立，基于更广泛的工程实践和社区最佳实践的技能，反而可能更有意义并能创造更大价值。抱歉，我还需要补充一点：如果技能中包含针对特定任务的更多示例，确实能带来价值。有时这些更广泛的社区技能正好具备这一点。例如，如果我要解决一个与调度相关的问题，而调度有多种实现方式和一些特殊注意事项，如果我的技能中包含大量具体示例和针对性说明，或许能帮助代理以特定方式处理问题。否则，仅仅说明"我希望调度原语的格式是这样"，这样的细节其实帮助有限。

上下文文件是否有助于编码代理？

我一直在使用类似 AGENTS.md 和 CLAUDE.md 的文件作为编码代理的操作手册。这篇论文探讨了这些文件是否真的能帮助 Claude Code 和 Codex 完成更多任务。在 17 个真实任务的 288 次运行中，它们对正确性没有明显影响。

但上下文文件确实改变了代理的工作方式。在一个仓库中，指南警告说完整的测试套件非常慢。Claude 的响应是运行更针对性的测试，从而减少时间浪费。它并没有在实现功能方面变得更好，但更高效地遵循了仓库的工作流程。我认为这是关键区别。上下文文件可以告诉代理有关昂贵命令、生成的文件、架构边界或项目特定安全规则的信息。它不一定能教会代理如何做出微妙的设计决策；接近失误通常归因于实现判断，更多的仓库文本也不会解决这些问题。

我的结论是保持仓库上下文文件聚焦于模型无法从代码中轻易推断的内容：如何运行正确的检查、哪些操作成本高昂、哪些必须保持原样，以及非常规项目惯例所在的位置。我不会用关于编写干净代码的通用建议填满它们。一项相关研究也指出了同样的方向：摘要回答了 45 个行为问题中的 4 个，而源代码本身回答了 45 个中的 27 个，因为摘要会忽略那些真正重要的细节。让代理直接查看真实代码，而不是代码的描述。

我审计自己设置时的发现

看到 Claude Code 推出了 doctor 命令，我感到非常高兴。这是一个良好的卫生命令，基本上会运行一次检查，涵盖未使用的技能、MCP 服务器和插件相对于上下文成本的使用情况，是否有多指定的 CLAUDE.md 文件、缓慢的钩子、冗余代码或类似问题。当我对自己设置运行 doctor 命令时，我对自己忘记的遗留问题感到震惊。比如，如果有人问我，我根本不会猜到它们还存在。我完全忘记了自己甚至尝试过它们。

我来举一个例子。大约四到五个月前，我曾对人们正在尝试的各种写作技巧感到好奇。当时很多人在实验不同的反低效写作技巧。我尝试了其中很多种，结果非常震惊，因为我完全忘记了自己曾经安装过这么多技巧。我根本不知道这些技巧是否同时被触发，或者是否有优先级之分，或者是否都被忽略了。我完全没有意识到这些技巧居然还一直存在。因此，对这些技巧进行审计非常有用。有些朋友开发了一些设计技巧，我曾经尝试过但已经忘记了。现在，随着社区在某些情况下逐渐聚焦于一些高质量的技巧，我更倾向于使用这些技巧，而不是几个月前尝试过的其他实验性技巧。

我最近看到一条推文，有人提到自己开始审计自己的技巧，数量从250个减少到了25个。我当时就震惊了，怎么会有250个技巧？这太疯狂了。但通过大量尝试社区开发的技巧，这些数量很容易随着时间累积。你当然不希望让自己的代理感到困惑，对吧？因此，你必须定期对代理环境进行代码规范检查和清理。

安装一个有用的技巧和永久保留它完全是两个不同的决定。

审计质量，而不仅仅是数量

我认为另一个关于技巧的重要点是确保它们的质量。Anthropic 自己的 Skill Creator 工具现在包含了评估和基准测试模式，用于检查技巧的质量。社区中也有一些很好的工具可以检查 SKILL.md 的质量。比如，它们是否有良好的描述、清晰的触发条件、明确的步骤和示例？此外，还有一些更注重安全性的审计工具和技巧的最佳实践。

一个值得了解的命名陷阱是：在 Claude Code 中，会话内的 /doctor 是配置审计，而 shell 中的 claude doctor 只会打印安装诊断信息，这就是为什么有些人报告说 doctor “只显示状态检查”。已安装的技巧也不会将其全部内容写入每个提示中：名称和描述会在默认占上下文窗口 1% 的列表预算内加载以供发现，而正文内容则在调用时加载。我还会通过 /memory 单独检查内存，因为自动内存可能在项目文件整洁后仍然保留过时的偏好设置。

按周期审计，然后测试删除

因此，我认为每隔几周甚至每月一次，对你的技巧和设置运行一次 doctor，审计你正在做的事情并思考：“好吧，哪些仍然适用？”如果你有时间，可以进一步测试：假设你删除所有技巧，或者指示代理“不要使用任何本地技巧，只使用原始模型和工具完成任务”，看看是否真的可以不依赖这些技巧完成任务。然后你可以问自己：“好吧，也许我确实可以删除这些技巧，这可能没问题。”

但我觉得有时我们会依赖这些技巧，把所有安装的工具当作拐杖，因为我们觉得删除它们是不安全的，因为我们不信任模型和工具是否真的已经改进。因此，我认为我们还有很多可以尝试和学习的地方。

继续维护良好的实践规范。定期审计质量和安全性，经常运行 doctor 命令，确保本地环境保持精简但又足够具体以满足需求。

再次感谢我们的赞助商 Oracle。请查看他们的《Agent Loop Decoded》文章，这是一篇关于每位代理工程师必须了解的三个层级的非常值得一读的技术文章。