EN
全部 Agent 工程

规范文件

大仓库按目录分指令

大仓库里按目录拆 AGENTS.md 与 CLAUDE.md：给示例目录树，逐工具对照加载范围、嵌套优先级和冲突规则。按官方文档核对，未实测。

大仓库里不同目录的约定常常不一样，如前端用一套命令，后端用另一套。本文先给一个我们自拟的目录树，再分 Claude Code、通用 AGENTS.md（agents.md 官网）和 Cursor 三列，写清每个文件什么时候被读、嵌套时谁优先、冲突时听谁的。官方没写的格子一律填「官方未写明」。

核验日期
· 未实测
适用于
  • Claude Code Claude Code 的加载与嵌套规则[2]
  • 兼容 AGENTS.md 的工具 agents.md 官网说的通用规则（不代表 Codex 的实际行为，Codex 待确认）[1]
  • Cursor Cursor 对根目录和子目录 AGENTS.md 的规则[3]
涉及工具

文件位置

路径适用范围读取方式
./AGENTS.md仓库根目录Claude Code：工作目录及上级没有 CLAUDE.md 时会话开始读取；Cursor：项目根目录；agents.md：根目录[1][2][3]
./CLAUDE.md项目根目录（或 ./.claude/CLAUDE.md）Claude Code：启动时读取工作目录及其上级的 CLAUDE.md；子目录里的按需加载[2]
frontend/AGENTS.md子目录（路径写法取自 Cursor 页面样例）agents.md：读取目录树中最近的文件；Cursor：处理该目录及其子目录的文件时自动应用[1][3]

什么时候用

  • 一个仓库里有多个子项目，希望每个目录各有一份指令。[1][3]
  • 你用 Claude Code，想知道子目录里的 AGENTS.md、CLAUDE.md 分别在什么时候被读到。[2]
  • 团队同时有人用 Claude Code 和 Cursor，想先弄清两边对嵌套文件的处理差在哪。[1][2][3]

什么时候不用

  • 仓库很小、只有一个根目录文件就够用，不需要拆分。[1]
  • 想了解 Codex 的加载细节：本文不写，原因见「Codex 暂不写」一节。[1]
  • 需要强制执行的规则：Claude Code 官方说这些文件是上下文而不是强制配置。[2]

示例目录树

下面的目录树是我们为说明而设计的示例，不是官方样例。根目录只放 AGENTS.md，apps/web 只放 AGENTS.md，services/api 同时放 AGENTS.md 和 CLAUDE.md，用来演示三种不同情形。[1][2][3]

版本口径：agents.md 官网和 Cursor 规则页都没有标注文档版本或格式版本，本文对这两处的说法以 2026-10-28 核验日期读到的页面为准；Claude Code 页面写明直接读取 AGENTS.md 需要 v2.1.277 或更高版本，这是功能最低版本，不是文档版本。[1][2][3]

示例：自拟的大仓库目录树（非官方样例）
monorepo/
├── AGENTS.md
├── apps/
│   └── web/
│       └── AGENTS.md
└── services/
    └── api/
        ├── AGENTS.md
        └── CLAUDE.md

[1][2][3]

后面的表格都按这棵树来读。Claude Code 的列假设你在 monorepo/ 下启动，且 monorepo/ 及其上级目录没有任何 CLAUDE.md。[2]

加载边界逐个标出

示例树中每个文件在三类工具里的加载边界（按官方原文整理）
文件Claude Code通用 AGENTS.md（agents.md 官网）Cursor
monorepo/AGENTS.md默认只在工作目录及上级都没有 CLAUDE.md 时读取；满足条件时，会话开始就读工作目录及其上级的每个 AGENTS.md。放在仓库根目录。支持放在项目根目录。
apps/web/AGENTS.md满足上述条件且该子目录没有自己的 CLAUDE.md 时，Claude 用 Read 打开该目录下的文件时才读。若你直接在 apps/web 下启动，则会话开始就读。官网写：agent 读目录树里最近的文件。处理该目录及其子目录的文件时自动应用，并与上级目录的 AGENTS.md 合并。
services/api/AGENTS.md官方写的读取条件是「该子目录没有任何 CLAUDE.md」，而 services/api 有 CLAUDE.md，所以按原文条件默认不读；用「Project instructions」设置改成同时读两者后，子目录的细节官方未写明。同上：离被编辑文件最近的 AGENTS.md 生效。与 apps/web 相同，按目录范围自动应用；官方页面没有提到同目录放 CLAUDE.md 的情形，官方未写明。
services/api/CLAUDE.md不在会话开始读；Claude 读、写或改该子目录里的其他文件时按需加载一次。官方未写明（官网没有提到 CLAUDE.md）。官方未写明（官方页面没有提到 CLAUDE.md）。

[1][2][3]

补充：Claude Code 读取 AGENTS.md 需要 v2.1.277 或更高版本；如果 CLAUDE.md 里用 @AGENTS.md 引入，则两者都会生效。[2]

嵌套优先级与冲突时听谁的

嵌套优先级与冲突规则对照
问题Claude Code通用 AGENTS.md（agents.md 官网）Cursor
嵌套文件谁优先不是覆盖：所有找到的文件拼接进上下文，从文件系统根到工作目录排序，离启动目录越近的越靠后读。最近的 AGENTS.md 优先。嵌套文件与上级目录的文件合并，更具体的指令优先。
两条指令冲突官方写：两条指令互相矛盾时，Claude 可能任选其一，建议定期清理冲突内容。离被编辑文件最近的 AGENTS.md 胜出。更具体的指令优先；另有规则来源的顺序：Team Rules、Project Rules、User Rules，冲突时靠前的优先。
聊天里用户的明确指令官方未写明；原文只说这些文件是上下文，不是强制配置。官网写：用户在聊天里的明确提示覆盖一切。官方未写明。
排除不相关的文件claudeMdExcludes 设置可按路径或 glob 跳过指定的 CLAUDE.md；官方还写明读取 AGENTS.md 时 claudeMdExcludes 的模式同样生效。官方未写明。官方未写明。

[1][2][3]

Codex 暂不写

agents.md 官网把 OpenAI Codex 列为共同推动 AGENTS.md 的参与方，但本站的来源规则下，Codex 的 AGENTS.md 官方说明页目前读不到可用的最终地址，所以 Codex 的加载细节待确认，本文不写。上表「通用 AGENTS.md」一列只代表 agents.md 官网的说法，不等于 Codex 的实际行为。[1]

拆分时注意什么

  • 子目录里只放该目录特有的内容，通用约定留在根目录文件里。agents.md 官网的做法是在每个包里再放一个 AGENTS.md。
  • 同时服务 Claude Code 和其他工具时，注意 Claude Code 默认在有 CLAUDE.md 时不读 AGENTS.md；需要共用时，在 CLAUDE.md 里用 @AGENTS.md 引入。
  • 不要在不同层级写互相矛盾的指令：Claude Code 不保证选哪一条。
  • 别的团队的 CLAUDE.md 被带进来时，用 claudeMdExcludes 在本机排除。

[1][2][3]

来源

以下均为官方页面，核验日期见各条；链接指向核验时的版本。

  1. agents.md · AGENTS.md
  2. Anthropic · How Claude remembers your project
  3. Cursor · Rules | Cursor Docs

发现错误？告诉我们 →

Claude Code

Anthropic 的编程 Agent，可围绕代码库读取上下文、修改文件、运行命令并协助开发任务。

Cursor

面向代码仓库的编程 Agent，可帮助理解项目、规划功能、修改代码和审查变更。