首份“配置异味”清单揭示大问题

首份“配置异味”清单揭示了一些普遍存在的问题，像上下文臃肿、技能泄露和指令冲突等，这些问题会降低编码代理的可靠性，还会增加成本。

AI 编码代理在软件开发中变得至关重要，不过指导它们的配置文件，如 Agents.md 或 Claude.md，可能存在“异味”。这意味着这些文件可能有结构缺陷、冗余内容或适得其反的工作流程，导致上下文臃肿、浪费令牌，还降低了编码代理的可靠性。巴西米纳斯吉拉斯联邦大学计算机科学系的研究人员提出了所谓的编码代理配置文件“首份异味清单”。其中最突出的“异味”包括：代码检查和技能泄露、上下文臃肿以及指令冲突。研究人员称：“我们的研究结果表明，这些‘异味’在实际应用中普遍存在。”所以，它们“可能直接影响编码代理对项目规范的解读、指令的优先级排序以及开发任务的执行”。

配置文件“异味”导致模型行为异常

像 Claude Code、Codex、Cursor 和 Gemini 这样的代理正越来越多地承担软件工程任务，如代码生成与审查、测试创建、错误修复、软件迁移和文档编写等。本质上，它们是大语言模型（LLM）和控制框架的组合；模型是“大脑”，控制框架提供执行操作的循环，并允许代理调用完成任务所需的工具，这些工具可能包括网络搜索引擎、问题跟踪平台和测试运行器等。

代理的行为由 Agents.md 和 Claude.md 等配置文件指导，这些文件提供有关项目工作流程、测试要求和特定领域知识的指令，有助于在不同任务和会话之间保持一致性。通常，这些配置文件在会话开始时作为提示的一部分加载，并在整个任务过程中持续使用。

但研究人员发现，这些配置文件存在大量“异味”；在 100 个包含 Agent.md 或 Claude.md 文件的热门开源仓库中，有 91 个至少存在一种“异味”。其中六种最严重的“异味”包括：代码检查泄露（出现在 62%的文件中）、上下文臃肿（42%）、技能泄露（35%）、指令冲突（28%）、初始僵化（24%）和盲目引用（16%）。

“异味”带来的资源浪费

代码检查泄露：当配置文件中的指令不必要地包含代码格式化工具或代码检查器（用于过滤错误、安全漏洞、不一致性和编程错误，例如重复通用风格指南建议、格式化规则、行长度、命名约定或导入顺序）已经强制执行的规则时，就会发生代码检查泄露。研究人员指出，这种重复会增加模型的上下文大小并浪费令牌，“可能使模型无法专注于更重要的项目特定问题，如架构约束、领域规则或安全策略”。

上下文臃肿：指配置文件过大，包含过多不必要或低优先级的规则、示例或细节。这会增加令牌使用量，最终提高成本，并使模型难以专注于高优先级指令。

技能泄露：将很少使用或特定任务的指令不必要地包含在配置文件中，而不是放在单独的专用技能或任务文件中。研究人员指出，即使模型执行任务不需要这些专业知识，它们也会在每次会话中被调用，从而使上下文窗口变大、成本增加且难以维护。他们还写道：“此外，这些规则可能会与项目实际关键规则争夺注意力。”

指令冲突：正如其名，文件规则相互矛盾，导致歧义；模型基本上会“困惑”，只能随意选择。这可能导致结果不一致和不稳定。

初始僵化：当文件生成后不再进行审查或编辑时，就会出现初始僵化，因此文件中包含过时或无关的规则，因为它们没有反映代码库的变化。研究人员解释说：“随着时间的推移，配置往往会积累噪声，增加上下文消耗，并降低代理的整体效率。”

盲目引用：指向文件或文档但不解释其用途。因此，代理可能会直接忽略它们，如果这些文件对任务至关重要，就会导致问题；或者加载不必要的材料以获取上下文，浪费令牌和空间；又或者无法对重要信息进行优先级排序。

此外，研究人员发现“异味”通常会在同一文件中同时出现，并引发其他“异味”；例如，技能泄露和指令冲突会使上下文臃肿的可能性增加 83%，因为它们会添加临时或无关的信息。

消除“异味”的方法

虽然这些“异味”在实际应用中“普遍存在”，但有办法消除它们。

为减少代码检查泄露，应从提示中删除格式设置和导入顺序等风格约束，让编程工具来处理这些问题，研究人员指出，在风格规则上花费预算是一种浪费。

为减少上下文臃肿，Claude.md 和 Agents.md 文件应保持简洁，并提供特定于项目的指导。例如，Anthropic 建议每个 Claude.md 文件的行数不超过 200 行。

为限制技能泄露，开发人员应在配置文件中提供有关项目构建、测试运行、代码规范和其他重要上下文的具体指令。研究人员建议，特定任务的指令应保存在具有描述性名称的单独 Markdown 文件中。

为避免指令冲突，构建者应定期审查配置文件，删除相互矛盾或过时的指令。同样，研究人员解释说，减少初始僵化需要持续更新文件。当代理连续两次犯同样的错误、代码审查揭示代理本应已知的细节，或者开发人员发现自己在提示中重复之前会话中已解决的更正和澄清时，这一点尤为重要。

为减少盲目引用，开发人员应告知代理何时以及为何读取文件，并在引用时简要解释文档的作用、包含的信息以及使用场景。例如，文本可以引用外部依赖项，包含其 GitHub 仓库的链接，并简要说明其用途。研究人员解释说：“这样，代理无需直接加载或检查外部仓库就能理解依赖项的作用。”

最终，他们得出结论，配置文件是代理式软件开发中的“关键工件”，当它们出现“异味”时，就会产生问题。因此，“其质量值得付出努力和关注”。那在实际开发中，要如何更好地落实这些消除‘异味’的方法呢？这值得大家思考。