在仓库里放一份给 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
- Codex Custom instructions with AGENTS.md：https://developers.openai.com/codex/guides/agents-md
- Cursor Rules（含 AGENTS.md）：https://cursor.com/docs/rules