AGENTS.md 规则怎么写编码智能体才照做：条件句遵守率最低，换个模型最佳写法就变

原文信息：本文译自 arXiv 论文《Do Coding Agents Follow AGENTS.md? The Effect of Policy Wording on Instruction Compliance》，作者 Rikuto Tsuchida、Youmei Fan、Kazumasa Shimari、Raula Gaikovina Kula、Kenichi Matsumoto（日本奈良先端科学技术大学院大学、和歌山大学、大阪大学），2026 年 11 月 3 日提交（arXiv:2611.04367，cs.SE）。原文链接：https://arxiv.org/abs/2611.04367 。原文采用 CC BY 4.0 许可。本文为翻译（全文译出，略去参考文献），文中配图请见原文；译者在文末补充了译者注。

译者导语：越来越多的团队在仓库根目录放一份 AGENTS.md 或 CLAUDE.md，把“提交前跑 lint”“不要改生成文件”这类规矩写给编码智能体看。可写进去不等于它会照做。这篇短论文做了一个很实用的对照实验：同一条规则换四种写法，放进真实项目的 AGENTS.md，看 Claude Code 和 qwen-code 上的四个模型各自遵守了多少。结论有两条值得马上用上：别用“如果……就……”的条件句写规则；在一个智能体上调好的写法，换个模型或工具未必管用。

摘要

编码智能体（coding agent）并不总是遵守智能体上下文文件（Agent Context File，ACF）里写的规则。我们把同一条规则用四种写法分别插入 86 个基准任务的 ACF，在四种“运行框架（harness）+ 模型”组合上测试。条件式写法的遵守率低于指令式和解释式；而这两者谁更好，因组合而异。

1 引言

近年来，Claude Code、Codex 等自主 AI 智能体已开始用于开源开发。它们把自然语言提示拆解为任务，在很少人工干预的情况下编写并执行代码。开发者主要通过智能体上下文文件（ACF）来配置这些智能体的行为。ACF 是用自然语言写的 Markdown 文件，例如 AGENTS.md，描述项目背景和各项要求，放在仓库根目录或用户的个人设置中。一项针对 2,853 个开源仓库的研究发现，其中 90.6% 含有 ACF，说明 ACF 已是开发者配置 AI 智能体的主要方式。

然而，AI 智能体并不总会遵守 ACF 中的规则。我们把开发者希望智能体遵守的一条要求称为一条规则（Policy）。已有研究表明，大语言模型常常无视提示中的规则生成输出。以大语言模型为底座的 AI 智能体也会如此：在仓库上运行 AI 智能体的评测显示，单条规则的遵守率只有 79.75%～85.64%。另一项聚焦开源贡献规范的评测更发现，对于“应当拒绝贡献”的规则，四个模型的遵守率全部为 0%，即便把规则原文直接放进提示也无济于事。由于 ACF 在每次会话开始时加载，其中的规则作用于该会话中的每一个任务，因此 ACF 规则的遵守情况比单次提示中的规则更要紧。

规则的写法可能影响智能体是否遵守，但这一点还没有人研究过。此前考察过的因素——ACF 的长度、规则在文件中的位置、文件结构、是否存在相互冲突的规则——都没有改变遵守率。已有研究表明，含义相同、措辞不同的提示会影响大语言模型生成代码的正确性或安全漏洞情况。因此，规则的写法也可能改变 AI 智能体遵守它的频率。

此外，写法的影响在不同模型和运行框架之间未必一致。不同开发者使用不同的运行框架和模型，却共用同一份 ACF。由于各模型和运行框架的对齐方法、训练数据不同，在一个环境里有效的写法，换个环境可能就不灵了。

本研究考察两个问题：规则写法是否影响遵守率；这种影响在不同“运行框架 + 模型”组合之间是否一致。作为案例研究，我们选取本身已含 ACF 的仓库中的基准任务，在每个仓库的 ACF 里放入一条目标规则。这条规则可以机械判定是否遵守，并且和开发者在真实 ACF 中写的规则一样（例如“绝不提交凭据”“结束前务必运行 lint”“不要编辑生成的文件”），作用于智能体在会话中做出的每一处改动。我们测试了四种写法：指令式（Prescriptive）、解释式（Explanatory）、条件式（Conditional）和禁止式（Prohibitive）。对每个会话，我们判定智能体是否遵守了规则，并计算每种写法的遵守率。

本文回答以下研究问题：

• RQ1：规则的写法是否影响 AI 智能体的遵守率？
• RQ2：写法对遵守率的影响，在不同“运行框架 + 模型”组合之间是否一致？

本研究有两点贡献：第一，证明换一种写法会改变遵守率；第二，证明写法的影响在四种“运行框架 + 模型”组合之间存在差异。

2 方法

（图 1 为实验流程概览：从数据集筛选、按四种写法插入规则，到运行 AI 智能体和判定遵守情况。配图见原文。）

我们使用 CTXbench，这是一个类似 SWE-bench、由含 ACF 的仓库构建的基准，其中的 ACF 都是真实项目里开发者写的。在 138 个任务中，我们保留了在任务对应提交时已含 ACF 的 86 个，它们来自 10 个仓库。当 AGENTS.md 和 CLAUDE.md 同时存在时，我们保留较大的文件、删除较小的。由于每种运行框架读取的文件名不同，我们按对应运行框架所读取的文件名保存每份 ACF。

我们把目标规则追加为每份 ACF 的最后一行，与原有内容之间空一行，文件其余部分不变。因此在同一任务内，四种写法的位置和上下文完全相同。

我们评估四种写法：指令式、解释式、条件式和禁止式。它们选自 Mohsenimofidi 等人归纳的五种 ACF 规则风格，排除了“描述式”，因为它不表达明确的规则。指令式是直接下达的规则，解释式是附带理由的规则，条件式是附带条件的规则，禁止式是禁止某种行为的规则。表 1 列出了四种写法所用的规则。

沿用此前研究的做法，实验所用规则要求：对任何新增或修改的 Python 函数，在 def 行的正下方加上注释 # @tracked，以便机械判定是否遵守。

表 1：四种写法所用的规则（规则原文为英文，保留原文并附译文）

我们共评估四种组合，涵盖商业模型和本地运行的开放权重模型，见表 2。在 Claude Code 上，我们比较 claude-opus-5 和 claude-sonnet-5：同一家开发商、同一个商业运行框架，只改变模型能力。在本地模型方面，我们在 qwen-code 运行框架上比较 gpt-oss-120b 和面向代码的 Qwen3-Coder-Next：固定运行框架，改变模型架构和训练方式。每种组合都在全部 86 个任务、四种写法上重复实验三次。

表 2：运行框架与模型组合

对于智能体新增或修改的 Python 函数，若指定注释出现在 def 行正下方，即视为遵守；我们把遵守率定义为“所有目标函数都遵守”的会话所占比例。由于同一任务的多次重复彼此相关，我们按任务把三次运行的遵守率合并为一个值。智能体没有新增或修改任何 Python 函数的会话被排除；某个任务在每种写法下只要还剩至少一次运行，就予以保留。每种写法有 1,032 个会话，其中指令式剔除 72 个、解释式 75 个、条件式 63 个、禁止式 74 个。表 3 中的 n 列即满足该条件后保留的任务数。

在 RQ1 中，我们检验 Claude Code + claude-opus-5 组合下四种写法的遵守率是否存在差异。由于所有写法作用于同一批任务，我们以任务为区组使用 Friedman 检验；若显著，再对所有写法两两做 Wilcoxon 符号秩检验，并用 Holm 法做多重比较校正。由于每个任务的取值是最多三次重复的比例，只有少数几个取值水平、并列很多，我们采用 Pratt 法处理并列。效应量使用配对秩二列相关系数（matched-pairs rank-biserial correlation）。

在 RQ2 中，我们按与 RQ1 相同的流程检验表 2 中的四种组合，然后比较各组合的配对秩二列相关系数和写法排名，评估写法之间差异的方向和大小是否在各组合间一致。

我们的复现包公开在 Zenodo（DOI：10.5281/zenodo.23148524）。

3 结果

表 3 给出四种组合下各写法的遵守率及 Friedman 检验结果。表 4 给出每对写法之间的配对秩二列相关系数，星号表示经 Holm 校正后显著。

表 3：各写法的遵守率（%）与 Friedman 检验结果（n 为参与分析的任务数）

表 4：写法两两之间的配对秩二列相关系数（正值表示前一种写法遵守率更高；* 表示经 Holm 校正后 p<0.05。P=指令式，E=解释式，C=条件式，Pr=禁止式）

RQ1：在 Claude Code + claude-opus-5 上，不同写法之间存在显著差异。显著的两组是“指令式 vs 条件式”和“解释式 vs 条件式”，两组中都是条件式的遵守率更低；指令式和解释式之间没有显著差异。

RQ1 小结：规则的写法会影响遵守情况，条件式写法比直接下达的指令更少被遵守。例如在 Claude Code + claude-opus-5 上，指令式和解释式的遵守率分别为 78.0% 和 77.2%，条件式只有 64.2%，两组差异都显著（秩二列相关系数分别为 0.65 和 0.56）。相比之下，给直接指令加上理由并没有带来差别：指令式和解释式之间不存在显著差异。

RQ2：除 qwen-code + Qwen3-Coder-Next 外，其余三种组合的写法之间都有显著差异。Qwen3-Coder-Next 在所有写法下的遵守率都低于 1.5%。在三种显著的组合中，解释式和指令式都高于条件式。而在指令式和解释式之间，claude-sonnet-5 上指令式更高，qwen-code 上的 gpt-oss-120b 则是解释式更高。在 claude-sonnet-5 和 qwen-code 上的 gpt-oss-120b 这两种组合中，禁止式显著低于指令式和解释式。

RQ2 小结：比较四种组合可以发现，条件式写法的“吃亏”是一致的，最佳写法却不一致。例如在三种效应显著的组合中，条件式都比指令式和解释式更少被遵守（秩二列相关系数 0.29～0.97）。相比之下，claude-sonnet-5 上指令式最好，gpt-oss-120b 上则是解释式最好（20.4% 对 6.7%）；写法之间的差距也从 claude-opus-5 上的 14 个百分点扩大到 claude-sonnet-5 上的 54 个百分点。这说明为某个智能体挑选的写法，不能想当然地套用到另一个智能体上。

4 讨论

写法会影响遵守情况：在所有写法之间存在差异的组合中，条件式都比指令式和解释式更少被遵守。像“如果你新增或修改了函数”这样的条件式规则，要求智能体先判断自己的行为是否满足条件，因此比直接指令更容易被忽略。

指令式和解释式谁更常被遵守，因组合而异。即便在同一个运行框架 Claude Code 上，claude-opus-5 的遵守率只在 64.2%～78.0% 之间浮动，找不出唯一的最佳写法；claude-sonnet-5 则在 17.3%～71.6% 之间，指令式明显最好。两个模型中能力较弱的那个，遵守率随写法变化更大。

在不同运行框架之间，Claude Code 和 qwen-code 不仅遵守水平不同，指令式和解释式谁更高也不同。由于模型也不一样，我们无法单独剥离运行框架的影响；但每个运行框架把 ACF 嵌入提示的方式不同，同一条规则到达模型时的形态可能也不同。

这些结果对在 ACF 中写规则有两点启示。第一，相比直接规则或附带理由的规则，智能体可能更不容易遵守条件句。第二，直接规则和附带理由的规则哪个更好，取决于环境。当多个模型和运行框架共用同一份 ACF 时，在一个环境里选定的写法，到了另一个环境未必同样被遵守。

只有当智能体基本会遵守规则时，写法才有意义。在 qwen-code 上，两个开放权重模型在我们写的每种写法下遵守率都低于 21%。由于这两个模型只在 qwen-code 上运行，我们无法判断这个上限来自模型、来自运行框架，还是来自两者的组合。

5 效度威胁

以下四点限制了结果的适用范围。第一，每种写法只用了一条文本，写法与它的具体措辞混在一起；四条文本的用词和长度也不同，差距可能来自句子本身而非写法——不过在三种组合中，条件式都低于指令式和解释式。第二，我们只插入了一条规则（标记注释），并且只有当每个目标函数都带标记时才判定会话遵守，因此遵守率只适用于这类规则和这一判定标准。第三，我们排除了没有新增或修改 Python 函数的会话，这会抬高报告的遵守率，并使每个任务只剩一到三次运行。第四，86 个任务只来自 10 个仓库，同一仓库内的任务共用 ACF 和代码库，因此 p 值可能偏乐观。

6 结论

本研究评估了 ACF 中规则的写法如何影响 AI 智能体的遵守情况。在写法造成显著差异的三种组合中，智能体遵守条件式规则的频率都低于指令式和解释式。然而，指令式和解释式哪个更有效因组合而异，能力较弱的模型在不同写法之间差异尤其大。我们建议开发者避免条件式写法，也不要假定为某个智能体调好的写法能迁移到另一个智能体。后续工作将测试更多种类的规则，并研究如何针对给定的模型和运行框架自动选择写法。

（致谢：本研究得到日本学术振兴会 JSPS KAKENHI 项目 JP26K21197 资助。）

译者注

1. 马上可以改的地方：把团队 AGENTS.md / CLAUDE.md 里“如果……就……”的规则改写成直接的指令。例如把“如果改了接口，请同步更新 OpenAPI 文档”改成“每次修改接口，都同步更新 OpenAPI 文档”。论文里条件式在三种组合上都垫底，这是最稳的结论。
2. “加理由”不是万能药：解释式在 gpt-oss-120b 上明显更好，在 claude-sonnet-5 上却明显变差，在 claude-opus-5 上没区别。团队若同时用多种智能体，比较务实的做法是：关键规则写成一句简短的直接指令，理由另起一行放在后面，再在各自用的智能体上抽样验证。
3. 规则写进文件，仍要有机器兜底：即便表现最好的组合，遵守率也不到 80%，两个开放权重模型甚至低于 21%。对“不提交密钥”“必须过 lint”这类硬性要求，应当在代码托管 CodeArts Repo 的提交检查、流水线 CodeArts Pipeline 的门禁和代码检查 CodeArts Check 的规则集里再落一道自动校验，而不是只靠 AGENTS.md 里的一句话。
4. 样本有限，结论要自己复测：实验只用了一条可机械判定的规则、10 个仓库，作者也在效度威胁部分坦言 p 值可能偏乐观。更换模型或升级智能体工具版本后，建议用类似“插入标记注释、统计命中率”的小实验，快速检查团队关键规则是否还被遵守。

相关阅读

• 编码智能体写测试有何不同：11.4 万个 Java PR 显示，它更爱新增测试、少改旧测试：https://bbs.huaweicloud.com/blogs/2f9380ec6d274727b31fc2a63bf9d97f
• 让 AI 编程智能体替你“拆依赖”：Flask 案例研究的五种策略与五条经验：https://bbs.huaweicloud.com/blogs/709270b0c61a40a29d65af75a4a3b480