AGENTS.md 文件用于告诉编程 Agent 如何在代码仓库中工作。每次会话都会把它 载入上下文，这意味着你添加的每一行，都会在每项任务中产生 Token 成本，也会 与用户真正的请求争夺 Agent 的注意力。

仅这一点，就足以解释下面的大多数建议。

只写无法通过查看仓库发现的内容

如果 Agent 能通过查看仓库得知某件事，就不要把它写进文件。目录结构、使用的 框架、测试文件的命名方式——这些都能直接从仓库里看出来，无需重复说明。

真正无法直接发现的是意图和约束：

  • 运行测试的命令，尤其是在命令并不直观时
  • 代码尚未处处遵循的约定
  • 看起来像缺陷、其实是有意为之的行为
  • 禁止编辑的目录，以及禁止编辑的原因

保持简短，让人能够完整读完

文件超过大约一百行后，就会开始变成没人阅读的文档。埋在第 180 行的指令很难 可靠地改变 Agent 的行为，因为它还要与文件里的其余内容争夺注意力。

如果你的文件已经变得很长，更有用的问题不是“怎样才能让 Agent 遵守这些 指令？”，而是“这些内容中，哪些真正改变过结果？”

明确写出具体命令

含糊的指导只会产生含糊的行为。比较下面两种写法：

Run the tests before committing.

以及：

Run `pnpm test -- --run` before committing. It takes about 40 seconds.
Do not run `pnpm test` without `--run`; it starts watch mode and hangs.

第二种写法能避免一个具体且反复发生的问题。第一种写法只是在表达态度。

解释原因，而不只是写规则

带有原因的规则能够应对陌生情况；单纯的禁令则做不到。“不要编辑 src/generated/”会让人第一次觉得直接修改更方便时选择破例。“不要编辑 src/generated/——它会被 pnpm codegen 覆盖，你的修改会消失”则不会。

在文件不再起作用时重新审视它

把这个文件看作会随时间逐渐失效的内容。当 Agent 反复做出你不想要的行为时， 这反映的是文件本身的问题，而不只是模型的问题。要么缺少了某条指令，要么已有 指令正被三百行已经不再重要的内容淹没。