你把 AGENTS.md 写成咒语大全，Agent 还是会乱改

Wed, 17 Jun 2026 22:52:57 +0800

晚上十一点多，我盯着终端里那段 diff，第一反应不是生气，是有点懵。

我明明只让 Agent 改一个很小的接口判断。结果它顺手动了 service，改了 model，又把测试绕过去了。最后还很认真地补了一段解释：这些改动是为了保持架构一致性。

这句话最气人。

它不是胡来。它看起来甚至很努力。可你知道，这个项目里权限逻辑不能这么碰，数据库字段不能顺手改，测试没跑就说“已验证”更不能接受。

于是你打开 AGENTS.md，开始往里面加规则。

不要乱改。不要跳过测试。不要引入没确认的依赖。不要动工作区外的文件。不要提交。不要重构。不要假装验证。

过几天，它还是会在另一个地方犯同类错误。

更烦的是，它不是每次都乱。小改时挺听话，一到多文件联动、接口变更、数据库字段、安全策略，它又开始像一个拿到权限但没进过项目组的人：先动手，动完再解释。

这时候很多人的第一反应是继续加规则。

AGENTS.md 越写越长，CLAUDE.md 越写越像公司制度，Cursor Rules、OpenSpec、Superpowers、各种 skill 又各写一套。最后真正开工前，Agent 先读半天，人也要猜半天：今天到底该按哪份规则来？

问题不一定是规则太少。

更多时候，是你把不同层级的规则塞进了同一个入口。

AGENTS.md 不该是咒语大全。它更像 Agent 的入职导航。

它最重要的工作，不是把每一条纪律都背给 Agent 听，而是告诉它：这类问题去哪里读、什么事情必须先停下来、哪些文件才是当前项目真正的制度。

AGENTS.md 越长，未必越稳

AGENTS.md 官网对它的定位很朴素：README 是给人看的，AGENTS.md 是给 Coding Agent 看的。构建步骤、测试命令、代码约定、安全注意事项，这些不适合塞进 README 的 Agent 细节，可以放在这里。

这句话容易被误读。

很多人会把它理解成：既然 Agent 会读 AGENTS.md，那所有规则都往里面放。

于是一个文件开始膨胀：项目背景、架构说明、业务概念、测试命令、提交规范、分支策略、重构原则、安全边界、调试流程、代码风格、长期 roadmap，全放进去。

看起来很完整。

但 Agent 真正执行任务时，完整经常不等于清楚。

你让它修一个拼写错误，它读到一堆“重大变更必须先开 proposal”；你让它改认证策略，它又在同一个文件里看到“低风险修改可以直接执行”。规则没有分层，它就只能临场猜：这次到底算 typo，还是架构变更？

不给 Agent 分级，它就会把 typo 和架构重构用同一种速度处理。

这不是模型笨，而是制度没说清。

人类团队不会把新人入职手册、年度规划、数据库迁移审批、单元测试规范、代码评审 checklist 全塞进同一页 Notion。因为每类信息解决的问题不一样。