编码智能体是否遵守 AGENTS.md：政策措辞怎样影响指令遵守

编码智能体是否遵守 AGENTS.md：政策措辞怎样影响指令遵守

Rikuto Tsuchida、Youmei Fan、Kenichi Matsumoto，奈良先端科学技术大学院大学。Kazumasa Shimari，和歌山大学。Raula Gaikovina Kula，大阪大学。许可证：CC BY 4.0。arXiv:2611.04367，2026 年 11 月 3 日。

编码智能体并不总是遵守智能体上下文文件（Agent Context File，ACF，用自然语言写在仓库里、告诉智能体项目背景和规矩的 Markdown 文件）里的政策。作者往 86 个基准任务的 ACF 里各插入一条政策，写成四种风格，在四组支架与模型组合上测试。条件式（Conditional，先判断“如果发生某事”才执行）被遵守的次数，少于规定式（Prescriptive，直接下令）和解释式（Explanatory，下令并给出理由）。后两种里哪一种更好，随组合而变。

1 引言

近些年，Claude Code、Codex 这类自主编码智能体已经用在开源开发里。它们把自然语言提示拆成任务，在很少人工介入的情况下写代码并执行。开发者主要用 ACF 配置这些智能体的行为。AGENTS.md 就是一种 ACF：用自然语言描述项目背景和指令，放在仓库根目录，或放在用户的个人设置里。一项覆盖 2,853 个开源仓库的研究发现，90.6% 含有 ACF，说明它是开发者配置智能体的主要方式。

智能体却不总是遵守 ACF 里的政策。政策（Policy）是开发者希望智能体遵守的一条指令。已有工作表明，大语言模型（LLM，按提示生成文字的模型）经常在生成时忽略提示里的政策。以 LLM 为底座的智能体也会这样。在仓库上跑智能体的评测里，单条政策的遵守率只有 79.75% 到 85.64%。另一项针对开源贡献规则的评测报告，要求拒绝某类贡献的规则，四个模型的遵守率都是 0%；把规则原文放进提示，也没有改善。ACF 在每次会话开始时加载，其中的政策作用于该会话的每一个任务，所以遵守 ACF 政策，比遵守只出现在单条提示里的政策更要紧。

政策怎么写，可能影响会不会被遵守，但这件事还没被研究过。此前查过的因素——ACF 的长度、政策在文件里的位置、文件结构、有没有互相冲突的政策——都没有改变遵守率。另有工作表明，意思相同、措辞不同的提示，会改变 LLM 写出的代码是否正确、是否有漏洞。因此，政策的写法也可能改变智能体的遵守频率。

写法的效果，在模型和支架之间也可能不一致。不同开发者用不同的支架（harness，包在模型外面、负责给工具和上下文的程序）和模型，却共用同一份 ACF。模型和支架的对齐方式和训练数据可能不同，在一个环境里有效的写法，换一个环境未必有效。

这项研究问两件事：政策写法会不会改变遵守率；这种影响在支架与模型的组合之间是否一致。案例做法是：从已经含有 ACF 的仓库基准任务里取样，把一条目标政策放进每个仓库的 ACF。这条政策可以机械检查。它和开发者真正写在 ACF 里的政策一样，例如“永远不要提交凭据”“结束前一定要跑检查器”“不要改生成文件”，作用于会话中智能体做的每一处改动。四种风格是：规定式、解释式、条件式、禁止式（Prohibitive，用否定句禁止某件事）。每次会话都判断智能体有没有遵守，再按写法计算遵守率。

研究问题：

1. RQ1：政策写法会不会影响智能体的遵守率？
2. RQ2：写法对遵守率的影响，在支架与模型的组合之间是否一致？

贡献有两项。第一，把同一条政策写成不同风格，遵守率会变。第二，这种变化在四组支架与模型组合上并不相同。

2 方法

图 1 是实验流程：从筛选数据集、按四种写法插入政策，到运行智能体、检查遵守情况。

作者使用 CTXbench。它是类似 SWE-bench 的基准，仓库本身带有 ACF，文件是真实项目里开发者写的。138 个任务里，保留任务提交时就含有 ACF 的 86 个，来自 10 个仓库。AGENTS.md 和 CLAUDE.md 同时存在时，用较大的文件，删掉较小的。每种支架读的文件名不同，所以同一份 ACF 按对应支架要读的文件名保存。

目标政策加在每份 ACF 的最后一行，与原文隔一个空行，其余内容不动。因此四种风格在同一任务里的位置和周围文字相同。

四种写法来自 Mohsenimofidi 等人归纳的五种 ACF 政策风格中的四种，去掉描述式（Descriptive），因为它不表达明确政策。规定式是直接下令。解释式是下令并给出理由。条件式带有条件。禁止式禁止某件事。表 1 是四种写法实际插入的英文政策。实验沿用先前研究：要求在新增或修改的每个 Python 函数的 def 行正下方写上注释 # @tracked，以便机械判断是否遵守。

一共评测四组组合，覆盖商业模型和本地运行的开放权重模型。表 2 是支架和模型。在 Claude Code 上比较 claude-opus-5 和 claude-sonnet-5：同一开发方、同一商业支架，模型能力不同。本地模型在 qwen-code 支架上比较 gpt-oss-120b 和面向代码的 Qwen3-Coder-Next：支架固定，模型结构和训练不同。每个组合在全部 86 个任务、四种写法上各重复 3 次。

对智能体新增或修改的 Python 函数，指定注释出现在 def 行正下方才算遵守。遵守率定义为：所有目标函数都遵守的会话所占比例。同一任务的重复彼此相关，所以先在每个任务的三次运行上计算遵守率，再把这个比例当成该任务的一个值。智能体没有新增或修改任何 Python 函数的会话被排除。每种风格下，三次运行里至少还剩一次，该任务才保留。每种风格有 1,032 个会话：规定式去掉 72 个，解释式去掉 75 个，条件式去掉 63 个，禁止式去掉 74 个。表 3 的 n 是在这个条件下剩下的任务数。

RQ1 只在 Claude Code 加 claude-opus-5 上检验四种写法的遵守率是否不同。四种写法用在同一批任务上，所以用弗里德曼检验（Friedman test，把任务当区组，比较多个相关样本的秩检验），任务是区组。若显著，再对所有写法两两做威尔科克森符号秩检验（Wilcoxon signed-rank test，比较配对差值的秩），并用 Holm 方法校正多次比较。每个任务的值是至多三次重复的比例，取值档位少、并列多，所以用 Pratt 方法处理并列。效应量用配对秩双列相关（matched-pairs rank-biserial correlation，看两种写法谁更高、差多大；正值表示前一种更高）。

RQ2 对表 2 的四组组合使用和 RQ1 相同的步骤。然后看每组的配对秩双列相关和写法排序，判断风格之间差异的方向和大小是否跨组合一致。

复现材料在 https://doi.org/10.5281/zenodo.23148524 。

3 结果

表 3 是四种组合上各写法的遵守率，以及弗里德曼检验。表 4 是两两写法的配对秩双列相关。星号表示 Holm 校正后 p < 0.05。正值表示前一种写法的遵守率更高。P 是规定式，E 是解释式，C 是条件式，Pr 是禁止式。

RQ1：Claude Code 加 claude-opus-5 上，写法之间差异显著。显著的两对是规定式对条件式、解释式对条件式，条件式都更低。规定式和解释式没有显著差异。

在 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。

比较四组可以看到：条件式的惩罚是稳定的，最好的写法并不稳定。三个效应显著的组合里，条件式都低于规定式和解释式，秩双列相关从 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 里政策写法如何影响智能体遵守。四种组合里有三种写法差异显著；在这些组合上，智能体对条件式的遵守少于规定式和解释式。规定式和解释式哪一种更有效，则随组合变化，能力较低的模型上，写法之间的差别尤其大。作者建议开发者避免条件式措辞，也不要假定为一个智能体调好的写法能换到另一个智能体上。后续工作会测试更多种类的政策，并研究按给定模型和支架自动选择写法。

致谢

本工作由 JSPS 科研费 JP26K21197 资助。

参考文献

• Galster 等，2026。Configuring Agentic AI Coding Tools: An Exploratory Study。AIware ’26。2,853 个仓库里 90.6% 含有 ACF。
• Chatlatanagulchai 等，2026。Agent READMEs。ACM Transactions on Software Engineering and Methodology，已接收。
• Pyatkin 等，2025。Generalizing Verifiable Instruction Following。NeurIPS。
• Ding 等，2026。OctoBench。ACL。仓库上的单条政策遵守率 79.75%–85.64%。
• Yang、He、Zhou，2026。开源贡献规则遵守。arXiv:2607.26819。拒绝类规则遵守率为 0%。
• McMillan，2026。Instruction Adherence in Coding Agent Configuration Files。arXiv:2605.10039。长度、位置、结构和冲突政策没有改变遵守率。
• Deaconu 等，2026。提示框架对 LLM 代码生成的影响。Empirical Software Engineering。
• Gloaguen 等，2026。Evaluating AGENTS.md。CTXbench。arXiv:2602.11988。
• Jimenez 等，2024。SWE-bench。
• Mohsenimofidi 等，2026。Context Engineering for AI Agents in Open-Source Software。MSR。五种 ACF 政策风格的来源。

出处：Rikuto Tsuchida，Youmei Fan，Kazumasa Shimari，Raula Gaikovina Kula，Kenichi Matsumoto，Do Coding Agents Follow AGENTS.md? The Effect of Policy Wording on Instruction Compliance，2026-11-03，https://arxiv.org/abs/2611.04367，CC BY 4.0。