Agent 配置最危险的不是写错，是你以为它生效了：从 Claude Code 的 AGENTS.md 说起

我最近发现，我电脑上的一份 Agent 全局配置，整整失效了一周。

更麻烦的是，它没有报错：Claude Code 还是正常工作，我写进配置里的规则也没有消失，文件就在原来的位置，只是 Claude Code 根本没有读它

事情的起点，是 Claude Code 新增了对 AGENTS.md 的支持。

我同时使用 Claude Code 和 Codex，所以一直让两边共用一份全局规则：~/.claude/AGENTS.md 是实际文件，~/.codex/AGENTS.md 软链过去，而 Claude Code 通过 ~/.claude/CLAUDE.md 里的 @AGENTS.md 把它引入。

看到 Claude Code 宣布原生支持 AGENTS.md 后，我以为中间这层已经没有必要了。

于是我让 Claude 把 ~/.claude/CLAUDE.md 删掉。

它照做了。

还在 AGENTS.md 开头留下了一行注释，解释为什么现在不需要这个文件了。

这一步没有任何报错，也没有任何警告。

直到一周后，我整理另一个项目的配置，才发现 Claude Code 启动时根本没有加载那份全局规则。

我真正踩到的坑，不是 AGENTS.md 放错了地方。

而是我把**「配置文件存在」误认为了「配置已经生效」**。

同一个文件名，两套规则

先说我为什么会这样理解。

9 月 19 日，Claude Code 团队的 Thariq 发推：

We’re adding support for AGENTS.md to Claude Code.

Starting today in version 2.1.277, if there is no CLAUDE.md in a folder, Claude will check for and use AGENTS.md.

~/.claude 也是一个 folder，里面没有 CLAUDE.md，那 Claude 应该会读 AGENTS.md。这个推理看起来没问题，因为 AGENTS.md 这个名字本身就给人一种「它是标准」的印象：同一个文件，各家 agent 都认，放在哪里含义都一样。

在 Codex 里确实如此，~/.codex/AGENTS.md 就是全局配置。但在 Claude Code 里，「全局」根本不是同一个概念：

Claude Code 的 memory 文档把 AGENTS.md 定位成项目说明，读取范围是工作目录及其上级目录：

By default, Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it.

用户级只有 ~/.claude/CLAUDE.md 一个位置，整篇文档没有出现过 ~/.claude/AGENTS.md。

实现上也一样。Thariq 在推文下补充说，这个功能是一个基于 Claude Code mods 的内置 mod，源码在 anthropics/claude-code/mods/agents-md。README 第 94 行写着它做的事：

walks $.fs.ancestors for the AGENTS.md files above the working directory and answers them as project instruction files

我的工作目录是 ~/Documents/myblog/techblog，往上依次是 ~/Documents/myblog、~/Documents、~、/，这条路径不经过 ~/.claude。/config 里对应的设置项也叫 Project instructions，四个选项管的都是项目说明：

AGENTS.md 标准本身也没规定全局文件放在哪。

而且，这种静默失效不一定需要你理解错什么。按文档的判定规则，下面两种情况同样会让项目的 AGENTS.md 悄悄停止加载：

• 家目录 ~ 在目录链上，一个 ~/CLAUDE.md 会让家目录下所有仓库都「有 CLAUDE.md」，AGENTS.md 回退一起失效
• 一个只靠 AGENTS.md 的项目，你为了存私人配置加一个 CLAUDE.local.md，它也算 CLAUDE.md，Claude 从此不再读 AGENTS.md

两种情况都不会有任何提示。

Agent 会把错误固化下来

回头看那次改动，最值得警惕的不是删了一个文件，而是 Claude 留下的那行注释：

<!-- 单一数据源：Claude Code 原生支持无 CLAUDE.md 时回退读 AGENTS.md，故不再用 ~/.claude/CLAUDE.md 做 @AGENTS.md 引入 -->

当时用的还是 Opus 5。它照着我的理解改完了配置，没有指出这个理解有问题，还把理由写得清清楚楚。

以前手动改错配置，链条是这样的：

理解错 → 改错 → 过几天发现

现在多了一环：

人产生错误理解
      ↓
Agent 执行
      ↓
Agent 写注释解释这个错误
      ↓
以后的人 / Agent 看到注释
      ↓
继续相信这个错误

错误的源头在我，但 Agent 把它从一个念头变成了系统里的一段「文档」。一周后如果我没有去查加载列表，而是先读到这行注释，我大概率会相信它。下一个读到它的 agent 也一样。

真正危险的不是 AI 把配置改错，而是它能把一个错误解释得非常像正确答案。

你检查的是文件，还是上下文

检查 Agent 配置，有一个很容易犯的错误：你检查的是文件，而不是上下文。

文件存在，只能证明文件存在。CLAUDE.md 写得正确，也只能证明文本写得正确。真正需要验证的是：这一轮 Claude 启动时，到底把什么加载了进去？

我用的是这样一个探针：起一个全新会话，禁掉读文件的工具，让它只凭启动时加载的内容回答：

claude -p "不要读取任何文件，不要调用工具。只根据你启动时上下文里已加载的指令回答：有没有关于 GitHub 双账号或本地 Postgres 端口的规则？有就原样引用一句，没有就回答『没有』。" --disallowedTools "Read,Bash,Grep,Glob"

两种配置各跑一次：

版本是 Claude Code 2.1.283，满足 2.1.277 的要求。只有 AGENTS.md 时，它确实读不到。

禁用工具是关键。不禁的话，Claude 可能自己去读那个文件，然后告诉你「有」，你测到的就又变成了文件，而不是上下文。

我现在怎么验证 Agent 配置

修复本身很简单，把那一行引入加回来：

# ~/.claude/CLAUDE.md
@AGENTS.md

文档里「Remove an earlier AGENTS.md workaround」一节确实教人删掉旧的 @AGENTS.md 引入，但针对的是项目里的 CLAUDE.md。用户级从来没有原生支持，这一行引入是目前唯一的办法。

之后每次改指令配置，我会做三件事：

1. 用 /context 看 Memory files 列表，确认实际加载了哪些文件。/memory 列出的是所有可能的位置，包括还不存在的文件，不能拿来确认加载
2. 从目标文件里挑一条别处没有的规则，用上面的探针问一遍
3. 共用的文件，每个 Agent 分别验证。Codex 读到了，不代表 Claude Code 也读到了

另外，自动记忆是 Claude 自己维护的项目笔记，不是你写给它的硬规则；需要每次生效的东西，仍然应该放在指令文件里。

文中的加载行为基于 Claude Code 2.1.283 和 2026 年 9 月的官方文档，后续版本可能变化。

写进去，不等于生效了

AGENTS.md 确实让不同 coding agent 之间共享指令变得简单了一些，但它解决的只是「文件叫什么」的问题，没有解决「这个文件在哪里生效」的问题。

而这件事可能比文件名本身重要得多。

同一个 AGENTS.md，在 Codex 里可以是全局规则，在 Claude Code 里却只是项目目录链上的说明文件；同样在 Claude Code 里，~/.claude/AGENTS.md 不在任何加载路径上，~/AGENTS.md 却在每个家目录项目的目录链上。

更麻烦的是，这些规则失效时通常不会报错。

所以我现在看 Agent 配置，会刻意把两个问题分开：

文件写对了吗？

和

Agent 真的读到了吗？

前者检查文件，后者检查上下文。

这次我只是少了几条工作习惯，所以一周没发现问题。如果那份全局规则里写的是安全限制、部署流程，甚至禁止某个危险操作，结果可能完全不同。

AI 让修改配置变得越来越便宜，也让「理解错了以后马上改过去」变得越来越容易。

所以现在给 Agent 加一条规则，我会先问一句：

这条规则到底应该影响哪个 Agent、哪个项目，以及哪个目录？

写进去只是第一步。

确认它真的生效，才算配置完成。

、

关于

关注我获取更多资讯

📢 公众号

💬 个人号