AGENTS.md 写好了、放在根目录了，AI agent 干活却像没读过——指令不遵守、命令用错、边界乱闯。「不生效」是 AGENTS.md 使用中最高频的抱怨，但原因几乎都能查清：文件没被发现、被另一份同名文件静默覆盖、项目未信任、或者内容超出指令链的承载上限。这篇按排查顺序展开：先弄清 agent 按什么路径找说明文件，再逐级检查每一道闸门，最后给一份可以直接照做的排查清单。
发现顺序：全局、根、嵌套、override
agent 寻找 AGENTS.md 的顺序可以概括为一条链：从全局位置（用户主目录）开始，到仓库根目录，再到当前工作目录的嵌套文件，最后叠加 override 变体。这条链有两个关键性质。其一，多层是叠加而非替换：全局说明始终在场，根目录补充，嵌套再补充，指令像洋葱一样层层包住任务。其二，override 变体是终点：同一目录里如果存在 AGENTS.override.md，它会取代同级的 AGENTS.md，而且这个替代是静默的——两个文件并存时，你以为在维护生效的那份，实际被读的是另一份。发现顺序与写法原则的正面讲解见AGENTS.md 写法一篇，这里只管读没读到、读的哪份。
| 层级 | 放在哪 | 与相邻层的关系 |
|---|---|---|
| 全局说明 | 用户主目录 | 始终在场，作为最外层叠加，不被下层替换 |
| 根目录说明 | 仓库根目录 | 在全局之上补充，指令层层包住任务 |
| 嵌套说明 | 当前工作目录 | 就近读取，补充或收窄外层约定 |
| override 变体 | 与同级 AGENTS.md 同目录 | 静默取代同级文件，是发现链的终点 |
排查第一步：先确认读到了
「不生效」的第一种可能最朴素：agent 根本没读到。验证方法是直接问：在会话里让 agent 复述它当前加载到的项目说明要点——读到了，它能把命令与边界原样说出；读不到，它会告诉你没有相关内容。第二步复核文件位置：AGENTS.md 必须放在 agent 实际打开的目录可见的位置，用 --cd 指定别的目录或在子目录里启动时，可读范围跟着启动目录走，从仓库根目录之外启动，根目录那份文件可能根本不在视野里。这与文件可见性的边界同源：工具链只认部分文件，未跟踪文件的盲区见Git 盲区与 .env一篇。
override 的静默覆盖：改了也白改
第二种可能藏在文件名里。临时验证时留下的 AGENTS.override.md，用完忘了删，此后每次会话生效的都是这份 override，你精心维护的 AGENTS.md 成了摆设。这类覆盖不报错、不提示，属于静默行为，只有对着目录逐一核对文件名才能发现。排查动作：列出项目里所有 AGENTS 相关文件（含嵌套目录），确认每个目录里生效的到底是哪一份；发现 override 且已无用，删掉或合并回主文件。多份嵌套文件之间的覆盖同理：靠近工作目录的说明收窄外层，预期与实际不符时按层级逐层比对。
未信任与长度上限：两道隐性闸门
还有两道闸门不显眼但常兜底命中。一是未信任：项目级说明文件的加载与项目信任状态挂钩，新克隆的仓库没走过信任确认，项目层 AGENTS.md 不会被读取——表现与「文件没写好」一模一样，区别只在于信任一遍就好。配置层的信任机制在config.toml 分层一篇讲过，指令文件与配置共享这道门槛。二是大小上限：多层指令叠加成一条指令链，链的总大小有上限，超限后部分层被截断或跳过——大仓库里嵌套说明层层加码，最外层或最内层悄悄丢内容，正是「有时生效有时不生效」的典型来源。给指令瘦身，把背景描述移去文档站，只留命令与规则，既避开上限又提高遵守率。排查下来仍觉得行为反常，退一步补一点 agent 指令遵循的基础概念，见AI 智能体一篇。
照单排查：五步清单
把上面的内容压成一份可执行清单。第一步，会话里让 agent 复述加载到的说明，确认读到没读到。第二步，核对启动目录与文件位置，确认目标文件在可见范围内。第三步，列出所有 AGENTS 相关文件，揪出静默的 override 变体。第四步，确认项目信任状态，未信任的走一遍信任流程。第五步，检查多层叠加后的总大小，瘦身或拆分嵌套。五步走完，绝大多数「不生效」都会归位。平时想省事，可以让 Kimi 把这五步生成一张排障卡片存进项目文档，遇到问题时再让智谱清言按现场情况把清单过一遍，定位卡在哪一步。
AGENTS.md 排查速查
- 发现链：全局、根目录、嵌套、override，层层叠加而非替换
- override 静默取代同级文件，排查先对文件名
- 未信任项目不读项目级说明，先信任再查内容
- 指令链有大小上限，超限截断表现为时好时坏
- 五步：验读取、对位置、查 override、走信任、砍长度
AGENTS.md 排查快问快答
- 怎么快速确认 agent 读的是哪一份？：会话里直接让它报出当前加载说明的来源路径与要点，答案与哪份文件对得上，生效的就是哪份。
- override 文件有正当用途吗？：有。临时实验、本地个人习惯需要覆盖团队约定时用，但要用完即删或加入忽略，长期共存必然埋坑。
- 瘦身后还是偶尔不遵守怎么办？：排除加载问题后，剩下的多是条目写法问题：把形容词换成命令、把长段拆成条目，遵守率通常明显上升。
