Agent 读哪个上下文文件：AGENTS.md、CLAUDE.md，以及模型自己写的记忆

先给结论，赶时间的看这三条就够：

1、项目规范写进 AGENTS.md。它是 Linux Foundation 旗下 Agentic AI Foundation 托管的开放格式，六万多个仓库在用，Codex、Cursor、Copilot、Gemini CLI、Aider、Windsurf、Zed 一票工具都原生读它。

2、Claude Code 是唯一需要单独伺候的。官方文档写得很直白：Claude Code 读 CLAUDE.md，不读 AGENTS.md。解决办法是在 CLAUDE.md 里写一行 @AGENTS.md 把它导入进来，或者干脆做个软链接。

3、模型自己的记忆是另一套东西，不在仓库里，在你本机的家目录下。Claude Code 存 ~/.claude/projects/<项目>/memory/，Codex 存 ~/.codex/memories/。它们不进 git、不跨机器同步，换台电脑就是一张白纸。

下面展开。

一、先把两类东西分开

绝大多数关于「AI 记忆」的困惑，都来自把两件事混成了一件：

	你写的规范	模型自己的记忆
谁写	你（和团队）	模型自己决定
典型文件	`AGENTS.md`、`CLAUDE.md`、`.cursor/rules/*.mdc`	`MEMORY.md`、`~/.codex/memories/`
内容	构建命令、代码规范、架构约定、「永远别做 X」	「上次调这个 bug 发现是环境变量的问题」「他讨厌我自动跑测试」
进不进版本控制	进，团队共享	不进，本机私有
什么时候加载	每次会话开头全量塞进上下文	索引文件每次会话加载，细节文件按需读
你能不能改	你写的，当然能	能，就是纯 markdown，随便编辑删除

Claude Code 官方文档把这两者并列称作「两套互补的记忆系统」。理解了这条分界线，后面全都好办。

二、规范文件：各家到底读哪个

这是当前（2026 年 7 月）的实际情况：

工具	读的文件	备注
OpenAI Codex	`AGENTS.md`	全局 `~/.codex/AGENTS.md` + 仓库内逐级
Cursor	`.cursor/rules/*.mdc`、`AGENTS.md`	`.cursor/rules` 里的纯 `.md` 会被忽略，必须是 `.mdc`
GitHub Copilot	`.github/copilot-instructions.md`、`.github/instructions/*.instructions.md`、`AGENTS.md`/`CLAUDE.md`/`GEMINI.md`	它三种名字都认
Gemini CLI	`GEMINI.md`（默认）	可以在 `settings.json` 里把 `context.fileName` 改成 `AGENTS.md`
Claude Code	只有 `CLAUDE.md`	见下一节
Aider / Devin / Amp / Jules / Zed / Windsurf / Amazon Q 等	`AGENTS.md`	20+ 个工具支持

AGENTS.md 本身没有任何格式要求：纯 markdown，没有必填字段，不需要 YAML frontmatter，标题怎么起都行——agent 就是把文本读进去而已。它跟 README.md 的分工是：README 给人看（项目是什么、怎么快速上手），AGENTS.md 给 agent 看（怎么构建、怎么跑测试、命名约定、哪些坑不能踩），把那些「写进 README 就是噪音」的细节放进去。

三、Claude Code 为什么是个例外，以及怎么办

网上大量 2026 年的「AGENTS.md 完全指南」都把 Claude Code 列进支持列表里，这是错的。Anthropic 官方文档原话是「Claude Code reads CLAUDE.md, not AGENTS.md」，并且给了两种官方桥接方案：

方案一，import（推荐）。 在 CLAUDE.md 里写：

markdown

@AGENTS.md

## Claude Code

在 `src/billing/` 下改动时使用 plan mode。

@路径 是 Claude Code 的导入语法，被导入的文件在启动时展开进上下文，之后再追加下面的 Claude 专属内容。相对路径是相对于「写这行的那个文件」而不是工作目录，最多递归四层。

一个容易踩的细节：import 解析会跳过代码块和行内代码。想在文档里提一句 @README 而不真的导入它，用反引号包起来就行。

方案二，软链接。

bash

ln -s AGENTS.md CLAUDE.md

本站就是这么干的——仓库根目录下一个真实的 AGENTS.md，一个指向它的 CLAUDE.md 符号链接，单一事实来源。

但在 Windows 上创建软链接需要管理员权限或开发者模式，官方直接建议 Windows 用户改用 @AGENTS.md 导入。我这台 Windows 是在 Git Bash 里建的链接（ls -la 能看到正常的 CLAUDE.md -> AGENTS.md），能用，但要事先打开开发者模式，不算零成本。

顺带一提，/init 命令会顺手读 Cursor 的 .cursor/rules/、.cursorrules 和 Copilot 的 .github/copilot-instructions.md，把相关内容揉进生成的 CLAUDE.md。设了 CLAUDE_CODE_NEW_INIT=1 之后，它还会额外读 AGENTS.md、.devin/rules/、.windsurf/rules/、.clinerules。也就是说 Claude Code 在生成环节认识 AGENTS.md，只是运行时不加载它。

四、层级：全局、项目、就近

所有工具的思路是一致的三层——全局偏好、项目约定、子目录特化——差别只在细节。

通用规则是「离改动的文件越近，优先级越高」。 AGENTS.md 规范原文：最接近被编辑文件的那个 AGENTS.md 胜出。而用户在对话里直接下的指令，优先级高于所有文件。

Codex 的做法最容易讲清楚：先在 ~/.codex/ 找 AGENTS.override.md，没有再找 AGENTS.md，只取第一个非空的；然后从 git 根目录往下走到当前目录，每层最多取一个文件；最后把它们从根往下用空行拼接起来——越靠后的越接近你的工作目录，于是自然覆盖前面的。合并后的总大小默认上限 32 KiB（project_doc_max_bytes），超了就得拆到子目录里去。

Claude Code 的加载顺序是：

1、托管策略（/etc/claude-code/CLAUDE.md，Windows 是 C:\Program Files\ClaudeCode\CLAUDE.md）——组织下发，个人设置无法排除。

2、用户级 ~/.claude/CLAUDE.md。

3、项目级 ./CLAUDE.md 或 ./.claude/CLAUDE.md。

4、本地私有 ./CLAUDE.local.md（记得 gitignore）。

工作目录以上的各级 CLAUDE.md 在启动时全量加载，从文件系统根往下排，越近的越晚被读到；同一目录内 CLAUDE.local.md 排在 CLAUDE.md 后面。工作目录以下的子目录 CLAUDE.md 不在启动时加载，而是等 Claude 真的去读那个目录里的文件时才带进来。

几条实用的边角料：

场景	办法
monorepo 里别人组的 CLAUDE.md 老被捎带进来	设置里加 `claudeMdExcludes`，按 glob 排除（托管策略那份排不掉）
想在 CLAUDE.md 里留给人看的注释，又不想烧 token	用块级 HTML 注释 `<!-- ... -->`，注入前会被剥掉
`/compact` 之后感觉指令丢了	项目根的 CLAUDE.md 会被重新读盘注入，子目录里的不会，得等下次读到那个目录
不确定到底加载了哪些	会话里跑 `/context`，看 Memory files 那一栏

五、别把所有东西都堆进一个文件

规范文件是每次会话开头全量进上下文的，它跟你的对话抢 token。官方建议单个 CLAUDE.md 控制在 200 行以内，越长越烧上下文，而且模型的遵守率反而下降。

注意：拆成 @import 并不省上下文，被导入的文件照样在启动时全量加载，那只是组织形式上的整洁。真正能省的是按路径条件加载：

.claude/rules/*.md 支持 YAML frontmatter 里写 paths：

markdown

---
paths:
  - "src/api/**/*.ts"
---

# API 开发规范
- 所有端点必须做输入校验
- 用统一的错误响应格式

没写 paths 的规则无条件加载，写了的只在 Claude 读到匹配文件时才触发。Cursor 的 .mdc frontmatter 是同一个思路，四种模式：alwaysApply: true 总是加载、给了 description 就交给 agent 自己判断要不要用、给了 glob 就在匹配文件进上下文时自动附加、什么都不给就只能 @ 手动提及。Copilot 那边对应的是 .github/instructions/ 下的 *.instructions.md，按文件路径匹配。

还有一条经常被忽略的事实：CLAUDE.md 是作为 system prompt 之后的一条 user message 送进去的，不是 system prompt 的一部分。所以它是「上下文」不是「配置」，模型会读会尽量遵守，但没有强制力。真要硬拦住某个动作，得用 PreToolUse hook——hook 是在固定生命周期节点执行的 shell 命令，跟模型怎么想没关系。

六、模型自己的记忆存在哪

这才是问题的后半段。上面那些都是你写的；模型自己攒的东西存在完全不同的地方，而且都在家目录，不在仓库里。

工具	位置	生成方式	范围
Claude Code	`~/.claude/projects/<项目>/memory/`	会话中随时读写	按 git 仓库划分，同仓库所有 worktree 共用
Codex	`~/.codex/memories/`（受 `CODEX_HOME` 控制）	会话结束后后台异步整合，不是即时的	本机，不跨机器同步
Cursor	Memories	自动从对话里提取	每项目每用户，队友继承不到
Gemini CLI	仓库 `GEMINI.md` / 项目私有记忆目录 / 全局 `~/.gemini/GEMINI.md`	agent 用文件写入工具自己往里加	三档，按内容性质分流
Claude.ai（网页版）	云端账号	聊天时实时读写更新	每个 Project 一个独立记忆空间，与非项目对话隔离

Claude Code 的 auto memory

这套机制值得细看，因为它的设计取舍挺典型。目录长这样：

~/.claude/projects/<项目>/memory/
├── MEMORY.md          # 索引，每次会话都加载
├── debugging.md       # 详细笔记，按需读
├── api-conventions.md
└── ...

关键在于只有 MEMORY.md 的前 200 行或前 25KB（谁先到算谁）会在会话开头加载，超出的部分直接丢掉。主题文件启动时完全不加载，模型需要时才用普通的读文件工具去拿。

这就是「即时检索」（just-in-time retrieval）的思路：索引常驻，细节按需。代价是 MEMORY.md 必须保持极简——一条一行，细节挪进主题文件。Claude Code 自己会盯着这个限制，写完之后量一下文件，接近上限就提醒模型精简，超了就直接报错让它重写索引。

开关在 /memory 里，或者设置 autoMemoryEnabled: false、环境变量 CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。存储位置可以用 autoMemoryDirectory 改。所有文件都是纯 markdown，/memory 能直接打开编辑，想删就删。

写这篇文章的这台机器上，那个目录里躺着十九个文件，从「Astro + shadcn 集成的坑」到「测试交给用户，别自动跑 dev server」都有——后者显然是我某次骂过它之后它自己记下来的。

Codex 的 memories

2026 年 4 月随 Codex CLI 一起发的预览功能，模型分两层：AGENTS.md 是手写的静态指令层，memories 是生成层。它从「合格的」历史会话里提炼上下文，跳过还在进行中的会话，做敏感信息脱敏，然后在后台异步整合成文件写进 ~/.codex/memories/，下次开新线程时注入。

开关在 Settings > Personalization，或者 config.toml 里写 memories = true，还能用 memories.use_memories 和 memories.generate_memories 分别控制「用」和「生成」。会话里 /memories 命令可以看当前这段对话是不是在用记忆、会不会贡献记忆。