什么能让智能体配置保持真实：25 个工具与 6 篇论文的观察

来自约 25 个编码智能体工具、已公开的配置方案以及六篇近期论文的笔记。智能体只会遵循摆在眼前的东西，跳过需要自己去获取的内容，而且几乎没有什么会去检查某条规则是否仍然成立。
tags: ai, devtools, opensource, productivity
canonical_url: https://emeraldleaf.dev/writing/what-keeps-an-agent-setup-true/

最初发布于 emeraldleaf.dev。

任何认真使用编码智能体的人最终都会形成一套配置：一个 CLAUDE.md 或 AGENTS.md、一些规则、几项技能、一两个钩子、若干 MCP 服务器。如今已有工具可以把这套配置同步到多台机器、在不同智能体之间转换，并与团队共享。我想知道那些做得很好的人，他们的配置里实际保留了什么、如何让配置保持最新，以及证据对此都说了些什么。

于是我查看了约 25 个工具和已公开的配置方案，并阅读了六篇近期论文。有四点格外突出。

1. 智能体只会遵循摆在眼前的东西，跳过需要自己去获取的内容

Vercel 做了我所找到的最干净的测试。在他们的智能体评测中，他们用两种方式给智能体提供同一份文档：一种是作为 AGENTS.md 中的索引，始终处于上下文中；另一种是作为技能，由智能体在判断相关时自行加载。AGENTS.md 通过了 100% 的用例。技能通过了 53%，而且在 56% 的用例中，智能体根本没有加载该技能。明确告诉它要使用技能后，得分提升到了 79%。

Scott Spence 从另一面测量了同样的效应。单独使用时，Claude Code 在他的测试提示中有 50% 到 55% 的情况下激活了正确的技能。加上一个 UserPromptSubmit 钩子，让它在开始前评估每一项技能后，激活率达到了 100%，22 个提示全部命中。

对任何配置的启示：凡是智能体必须自己决定去查找的内容，大约有一半的时候会被跳过。如果某件事很重要，就在智能体开始前把它摆在它面前，或者让运行框架来做这个决定。

2. 常驻上下文带来的成本大于收益，除非它是正确的那一类

这并不意味着要把所有东西都塞进 AGENTS.md。Gloaguen 及其同事在 SWE-bench 任务以及那些已经有此类文件的代码库的真实 issue 上测试了仓库上下文文件。这些文件“通常不会提高任务成功率”，无论是由模型还是开发者撰写，同时还会使推理成本增加 20% 以上。智能体确实遵循了这些文件中的指令。没有起到作用的是仓库概览，也就是大多数入门模板生成的那种“这里是代码库的布局方式”的章节。

其他结果也指向同一方向。IFScale 一次性给模型最多 500 条指令；在这种密度下，最好的前沿模型遵循了其中 68%，并且更倾向于靠前的那些。Anthropic 自己对 CLAUDE.md 的建议很直白：对每一行都问一句“删掉这个会不会让 Claude 犯错？”如果不会，就删掉。

关于文件大小本身的证据则莫衷一是。Damon McMillan 运行了 1,650 次 Claude Code 会话，改变文件大小、指令位置、冲突指令和结构，结果没有发现其中任何一项有可检测的影响。真正有影响的是时间：智能体在一次会话中每多写一个函数，它遵循某条指令的几率就下降约 5.6%。指令会随着会话的进行而逐渐失效，无论它们位于何处。

综合来看：把常驻上下文限制在具体、可操作的指令上，并预期它们会在长时间会话中逐渐失效。

3. 什么都记录的记忆基本没什么用。经过核验的记忆才有用

最新的证据来自 VibeMemBench，它在真实仓库任务上测试了编码智能体的记忆系统。注入经过实际运行验证的过往经验，将任务解决率提升了 1.1 到 4.5 个百分点。自动记忆系统——即那种捕获所发生之事并加以回放的方式——在 12 组配对中有 11 组未能击败无记忆基线。

GitHub 的 Copilot Memory 是最有力的反例，它展示了自动捕获为何能奏效。其智能体会自行保存关于仓库的事实，但每条事实都带有指向支撑它的代码的引用。在使用一条事实之前，Copilot“会将这些引用与当前分支进行核对，以确认信息仍然准确。只有经过验证的事实才会被使用。”28 天未被使用的事实会被删除。GitHub 报告称，带记忆的拉取请求合并率为 90%，而不带记忆的为 83%：这是厂商的数据，但也是来自真实世界的数据。

所以分界线不在于人工捕获还是自动捕获，而在于在智能体依赖某条记忆之前，它是否已对照代码进行过核查。

Zhang 及其同事提出的 ACE 补充了一点：记忆应如何随时间变化。整体重写上下文会导致“上下文崩塌，即迭代重写会随时间侵蚀细节”；小而结构化、增量式的更新则能保留细节。他们的方法将智能体基准提升了 10.6%。

4. 配置会漂移，而几乎无人察觉

每一种配置都会过时，而最谨慎的人会主动说明这一点。Aristidis Vasilopoulos 在一个 66 万行的 C# 代码库上运行着一份 660 行的章程、19 份智能体规范和 34 份文档，并报告称“规范过时是首要的失败模式”。当某个子系统发生变化而其规范没有跟上时，“AI 会基于过时的信息生成代码。”他的解决办法是一个会话启动钩子，它将最近的提交与子系统到文件的映射进行比对，并在代码已更改但其规范未更新时发出警告。

其他人则靠手工完成。Sentry 的智能体技能附带一份 SOURCES.md，将每项主张映射到支撑它的文件和函数，并标注捕获日期和最后更新日期。Every 的 compound-engineering 插件——我所找到的最接近学习循环的东西——记录会话中的解决方案笔记，并提供一个刷新命令，用于保留、更新、合并、替换或删除这些笔记。它的规则是我在任何地方都愿意采纳的：“仅凭时间久远并不等于过时。”

可移植性工具解决的是另一种漂移。rulesync、微软的 APM 及类似工具从单一来源生成每个智能体的配置，并且当生成的文件不再与之匹配时可以让 CI 失败（rulesync generate --check 以 1 退出）。这能捕获过时的副本，但它不会追问规则本身是否仍然符合代码的实际情况。

我会从中汲取什么

让常驻指令保持简短、具体、可操作。删掉概述以及智能体可以从代码中读到的任何内容。
不要依赖智能体去获取重要信息。把它放在智能体面前，或者让钩子来完成这件事。
要预料到指令在长会话中会逐渐淡化，并在关键时刻重述相关指令。
只保留你能核查的记忆。一条背后没有证据的笔记，就是智能体会信以为真的猜测。
当证据表明规则有误时就将其淘汰，而不是因为它年头久了。
既要留意规则所声称内容的漂移，也要留意副本之间的漂移。当规则所描述的代码发生变化时，应该有人重新审视一番。

我自己的循环适合放在哪里

最后一点正是我一直在与 okl 一起努力填补的空白，这是我一直在构建的一个开源工具。每条经验都可以通过你选择的检查来验证，当它所管理的代码发生变化时，CI 就会变红，直到有人再次运行检查。在我自己的评估中，在每个任务之前先简报经验教训，将重复出现的已知 bug 从 43% 降低到 8%，这是在我编写的一小部分任务样本上得出的结果。

这项研究也让我看到了 okl 的不足之处。Claude Code 之外的智能体必须主动调用它的经验教训，而 Vercel 的结果表明它们往往不会这么做。它是在 CI 中标记过时的经验教训，而不是在使用它们的那一刻。而且它可以在受管理的文件即将被编辑时再次进行简报，因为指令在一次会话中会逐渐淡化。这些都是下一步的工作。

我是如何做到的

我使用 AI 研究助手来调查各种工具、已发布的配置和论文，然后回到源头重新阅读了这里引用的每一项主张。一份研究摘要错误陈述了一篇论文的发现；本文使用的是该论文自己的摘要。这一领域的工具和数字每周都在变化；本文所有内容截至 2026 年 10 月 1 日。

来源

论文

Fan 等，VibeMemBench：在真实仓库编码任务上评估编码智能体的记忆系统（2026）
Gloaguen 等，评估 AGENTS.md：仓库级上下文文件对编码智能体有帮助吗？（2026）
McMillan，编码智能体配置文件中的指令遵循：四项文件结构变量的析因研究（2026）
Jaroslawicz 等，LLM 一次能遵循多少条指令？（2025）
Zhang 等，智能体上下文工程：为自我改进的语言模型演化上下文（2025）
Vasilopoulos，编码化上下文：复杂代码库中 AI 智能体的基础设施（2026）

测量与文档

Vercel，在我们的智能体评估中 AGENTS.md 优于 skills
Scott Spence，用沙盒评估测量 Claude Code skill 激活
GitHub，为 GitHub Copilot 构建智能体记忆系统以及Copilot Memory 文档
Anthropic，Claude Code 最佳实践

配置与工具