给Agent写了说明，它为什么还是会猜？

核验日期：2026年8月24日

事实来源：一项公开消融研究让 Claude Code 与 Codex 在真实合并任务上分别读取完整上下文文件、检索式上下文和不加上下文，再比较补丁是否通过金标准测试。研究没有观察到上下文文件显著提高正确率。另一项开源扫描同时提醒：有 AGENTS.md 的仓库，入口说明未必更完整。本文不把有限样本写成“AGENTS.md 无效”。

规则写了三页，Agent进项目以后，第一步还是猜命令。

它猜怎么安装，猜测试跑哪一组，猜哪个目录能改，最后再猜“做到什么程度算完成”。

华子社长先说判断：Agent真正缺的不是更多规则，而是可执行上下文。

规则告诉它别犯什么错。可执行上下文则告诉它从哪里进、先做什么、怎样知道自己做对了。

一、这项研究真正反常识的地方

公开研究选了三个真实 Python 仓库里的已合并任务，让 Claude Code 和 Codex 分别在三种条件下工作：读取完整上下文文件、读取拆分后按需检索的上下文、完全不额外注入上下文。

研究者用金标准测试判断补丁是否正确。结果是：在这组任务与实验设置里，加入 AGENTS.md 或 CLAUDE.md，没有带来可测量的正确率提升。

这句话很容易被写成“AGENTS.md 没用”，但那是错的。

研究样本有限，任务集中在三个 Python 项目，评价的是补丁能否通过测试。它没有覆盖所有模型、所有仓库、所有工作类型，也没有证明说明文件永远无效。

更值得追问的是：为什么一份人看起来很完整的说明，对 Agent 不一定形成有效行动？

二、说明文件最容易犯的四种错

第一种错，只有方向，没有入口。

“保持代码简洁”“遵循现有风格”“修改后运行测试”都没错，但 Agent 仍然不知道先读哪个文件、测试命令是什么、最小验证集在哪里。

第二种错，只有入口，没有动作顺序。

文档把安装、构建、测试命令都列了出来，却没有告诉 Agent 当前任务先跑哪一个。信息齐全，不等于决策成本低。

第三种错，动作能运行，结果不能验收。

测试通过不一定代表任务完成。界面可能错位，生成文件可能为空，配置可能没有真正生效。没有验收标准，Agent容易把“命令退出码为零”误判成“交付完成”。

第四种错，规则会漂移。

仓库改了目录，命令换了，发布流程升级了，说明文件还停在旧版本。过时规则比没有规则更危险，因为它看起来可信。

三、把AGENTS.md改成“可执行上下文四层”

我把今天的绝活压缩成四层：方向、入口、动作、验收。

1. 方向：这次允许做什么

只写稳定边界：任务目标、禁止触碰的区域、权限限制、风险动作需要谁确认。方向应该短，能让 Agent 在冲突时做判断。

2. 入口：从哪里开始读

明确项目地图：主模块在哪里、配置在哪里、测试在哪里、真实数据在哪里。不要只描述目录名，要说明每个入口负责什么。

3. 动作：可以直接运行什么

给出经过验证的安装、检查、测试和预览命令，并写清适用范围。一个命令最好对应一个目的，不让 Agent 自己拼接危险参数。

4. 验收：什么证据算完成

验收必须可观察。比如“生成5张图片，尺寸分别为900×383与1080×720，均可解码且哈希不同”，就比“图片看起来正常”更可靠。

四、一个真实场景：让Agent改发布系统

假设你让 Agent 修一个多平台内容发布系统。

普通说明可能写：“遵守平台规则，不要直接发布，修改后运行测试。”

这句话没有错，却不够用。Agent仍然要猜：平台配置在哪，草稿和发布按钮如何区分，哪条测试覆盖图片上传，怎样确认草稿重开后仍存在。

改成四层以后：

• 方向：只保存草稿；严禁点击发表、发布或定时发布；
• 入口：平台注册表在配置目录，草稿路由在发布脚本，结果证据在发布包；
• 动作：先运行内容合规检查，再运行统一 dry-run，只有门禁通过才能进入浏览器；
• 验收：图片实际可见、封面正确、草稿重开仍存在，三项都要有证据。

同一个模型，规则没有变多多少，但猜测空间被压缩了。

这就是可执行上下文的价值：不是替 Agent 想完所有事，而是把最容易猜错的接口写死。

五、还有一个隐藏问题：文件不是自动更新的

AGENTS.md 是快照，仓库是流动的。

如果说明里写着旧命令、旧目录、旧权限，它会把 Agent 稳定地带向错误。真正成熟的做法，是让关键规则能被检查：

• 命令在自动测试里真实运行；
• 路径在脚本里验证存在；
• 重要限制由门禁阻断，而不是只靠一句提醒；
• 每次流程变化，同步更新说明与测试。

也就是说，最重要的规则不要只写在文档里，还要变成机器能执行的约束。

六、今天就做一次十五分钟改造

现在打开你最常让 Agent 工作的项目，只做四件事。

1. 删掉一条无法验证、已经过时或与其他文档冲突的规则。

2. 补一个真实入口，写清“先读哪里”和“为什么读它”。

3. 补一条你亲自运行过的最小测试命令。

4. 补三个完成证据，至少覆盖结果、边界与失败状态。

然后用同一个任务做两次：一次使用旧说明，一次使用四层版本。

比较四个数字：第一次有效动作前用了多久、Agent猜了几次、返工几次、最后是否拿出了可验证证据。

最后

AGENTS.md 不是魔法提示词。它更像项目的登机口指示牌。

指示牌写得再漂亮，如果没告诉人从哪个口进、下一步往哪走、到达后如何确认，大家还是会在大厅里猜。

今天不要再给 Agent 加十条抽象原则。先把一条真实工作写成方向、入口、动作、验收。

规则负责守边界，可执行上下文负责把活做完。