# 仓库里同时塞 AGENTS.md 和 CLAUDE.md，各家工具认谁

**URL:** <https://www.shiqidu.com/t/topic/1788>\
**Category:** 人工智能\
**Tags:** Claude, AICoding, Codex, Cursor\
**Created:** [2026 年10 月 26 日 03:19 UTC](https://www.shiqidu.com/t/topic/1788 "2026-10-26T03:19:01Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

作者： ![shiqidu\_editor](https://www.shiqidu.com/user_avatar/www.shiqidu.com/shiqidu_editor/32/528_2.png) [@shiqidu\_editor](https://www.shiqidu.com/u/shiqidu_editor)\
发布日期： [2026 年10 月 26 日 03:19 UTC](https://www.shiqidu.com/t/topic/1788/1 "2026-10-26T03:19:01Z")

</div>

在仓库里放一份给 Agent 看的说明，以前各家叫法都不一样。Claude Code 认 `CLAUDE.md`，Codex 认 `AGENTS.md`，Cursor 有 `.cursor/rules`，也开始读根目录的 `AGENTS.md`。在几个工具之间切换，文件名就对不上；都放一份，又不知道会不会冲突。下面按公开文档能对上的写，查不到的会说明。

Claude Code 的主文件还是 `CLAUDE.md`。项目根可以是 `./CLAUDE.md` 或 `./.claude/CLAUDE.md`，个人全局在 `~/.claude/CLAUDE.md`，不想进 git 的个人偏好用 `./CLAUDE.local.md`。组织级还有系统路径上的 managed 文件。加载时从宽到窄依次拼进上下文，后面的不会整份覆盖前面的；从文件系统根往工作目录排，越靠近你启动位置的内容越靠后读到。子目录里的 `CLAUDE.md` 默认不会在启动时全部加载，要等你读写那个目录里的文件时才按需加载。官方也写了：两条互相打架的说明没有确定谁赢，Claude 可能随便按其中一条来，所以别在不同层写相反的规则。

从 v2.1.277 起，Claude Code 也能直接读仓库里的 `AGENTS.md`。默认策略叫 `claude-md-or-agents-md`：工作目录往上只要没有 `CLAUDE.md`、`.claude/CLAUDE.md`、`CLAUDE.local.md`，就读 `AGENTS.md`；一旦这些里有任何一个，默认就只跟 `CLAUDE.md` 那一套，`AGENTS.md` 就不读了。想两份都进上下文，要在 `/config` 里把 Project instructions 改成 `claude-md-and-agents-md`（也可写进用户级 settings 的 `pluginConfigs`）。注意 `~/.claude/CLAUDE.md` 和组织 managed 文件不算在内，不会让 `AGENTS.md` 失效；容易出问题的是项目根上还留着个空的 `CLAUDE.md`，这样公共说明照样读不到。更老的版本、或者某些读不到 `AGENTS.md` 的会话，官方建议在 `CLAUDE.md` 里用 `@AGENTS.md` 导入；非 Windows 也可以 `ln -s AGENTS.md CLAUDE.md`，Windows 上建 symlink 麻烦，文档更推荐 `@` 导入。

Codex 的公开指南写的是开工前先读 `AGENTS.md`。全局在 `~/.codex/AGENTS.md`（有 `AGENTS.override.md` 就优先用 override）；项目从 git 根往当前目录走，每一层最多收一份，顺序是 `AGENTS.override.md` → `AGENTS.md` → 你在 `project_doc_fallback_filenames` 里配的别名。合并是从上到下拼，靠近当前目录的后出现，后面的用来覆盖前面的。默认整份拼起来有约 32 KiB 上限（`project_doc_max_bytes`）。Codex 不认 `CLAUDE.md`，除非你把它加进 fallback 文件名列表。

Cursor 文档把 `AGENTS.md` 写成 `.cursor/rules` 的简单替代：纯 Markdown、没有 frontmatter。根目录和子目录都能放；嵌套的会跟父级合在一起，更具体的优先。需要按 glob、按相关性、手动 `@` 才挂上的，还是用 `.cursor/rules/*.mdc`（带 `alwaysApply` / `description` / `globs`）。`.cursor/rules` 里塞普通 `.md` 会被规则系统忽略，要 plain markdown 就用 `AGENTS.md`。

两种文件同时存在时怎么放，公开文档能查到的大致是这些。只想维护一份给多工具看的公共说明：根目录留 `AGENTS.md`。Codex、Cursor 原生支持；Claude Code 在没有 `CLAUDE.md` 时默认也会读（版本要够新）。已经有 `CLAUDE.md`、又想 Claude 看到同一份 `AGENTS.md`：要么改 Project instructions 为 `claude-md-and-agents-md`，要么在 `CLAUDE.md` 里写一行 `@AGENTS.md`，Claude 专属的规则写在导入下面。两边内容别互相矛盾：Claude 官方明说冲突时不确定听哪条；Codex 是后出现的覆盖前面的；Cursor 嵌套时更具体的优先。同一条规矩在 `AGENTS.md` 写「用 pnpm」、在 `CLAUDE.md` 写「用 npm」，你自己都说不清 Agent 会听哪个。个人沙箱 URL、本地测试数据这类东西：Claude 用 `CLAUDE.local.md` 并 gitignore；Codex 用对应目录的 `AGENTS.override.md`。别把这些塞进团队共享的那份。

常见的坑：仓库根已经有 `AGENTS.md`，有人为了让 Claude 也能看到，又加了个空的 `CLAUDE.md`，结果按默认策略 Claude 只读这个空文件，公共说明全没了。解决办法是删掉多余的 `CLAUDE.md`，或者改成两份都读，或者用 `@` 导入。三家规则冲突时听谁的，公开文档没有统一说法，只能按各家自己的加载规则推断。

官方文档（写稿时核对过）：

- Claude Code Memory（CLAUDE.md / AGENTS.md）：[How Claude remembers your project - Claude Code Docs](https://code.claude.com/docs/en/memory)
- Codex Custom instructions with AGENTS.md：[https://developers.openai.com/codex/guides/agents-md](https://developers.openai.com/codex/guides/agents-md)
- Cursor Rules（含 AGENTS.md）：[https://cursor.com/docs/rules](https://cursor.com/docs/rules)