分层 CLAUDE.md 与记忆继承关系

CLAUDE.md 不是单一文件，而是一套由广到窄分层加载、拼接注入上下文的记忆体系。理解各层位置、加载时机与优先级，才能把团队规范、个人偏好与临时约定放到正确位置，既保证生效又不互相覆盖。

一、四层记忆与加载顺序（由广到具体）

层级	典型位置	作用	是否共享
托管策略 Managed	macOS：/Library/Application Support/ClaudeCode/CLAUDE.md；Linux/WSL：/etc/claude-code/CLAUDE.md；Windows：C:Program FilesClaudeCodeCLAUDE.md	组织统一编码标准、安全与合规要求，由 IT/运维下发，优先级最高	组织全体成员
个人 User	~/.claude/CLAUDE.md	本人跨项目的偏好，如个人风格、常用工具习惯	仅本人、全项目生效
项目 Project	./CLAUDE.md 或 ./.claude/CLAUDE.md	团队共享：架构、构建方式、目录约定、常用工作流，随仓库提交	团队成员经版本库共享
本地 Local	./CLAUDE.local.md	当前项目的个人偏好，如本机测试数据、沙箱地址，应加入 .gitignore	仅本人、当前项目

启动时加载工作目录及其所有上级目录中的上述文件；文件之间是拼接合并，而不是后者覆盖前者。内容按文件系统根到工作目录的顺序出现，同一目录内 CLAUDE.local.md 追加在 CLAUDE.md 之后，因此更靠近工作目录、更晚出现的内容更具体。

二、子目录文件按需加载

• 工作目录之下子目录中的 CLAUDE.md 不在启动时一次性载入；当代理读取、写入或编辑该子目录下文件（包括用 cat、head 查看单个文件这类读取动作）时，才会按需加载对应记忆。
• 大型仓库可把规则拆到子目录，减少启动上下文占用；也可用 .claude/rules/ 下按文件类型或路径作用域拆分的规则文件，只在匹配到相关文件时生效。
• 多仓库大型项目可用 claudeMdExcludes 跳过上级目录中与当前任务无关的 CLAUDE.md，避免无关指令进入上下文。

三、自动记忆（auto memory）

• 项目独立的记忆目录位于 ~/.claude/projects/<project>/memory/：其中 MEMORY.md 是索引，每个主题一个独立文件；代理在会话中按需读写这些记忆。
• 自动记忆只保存在本机，不跨机器同步；同一 Git 仓库的 worktree 与子目录共享同一记忆目录。可通过设置项 autoMemoryDirectory 指定自定义路径。
• 当你让代理"记住某约定"（例如固定包管理器、本地测试前置条件）时，这类偏好通常进入自动记忆；若希望成为项目级持久规则，应明确写入项目 CLAUDE.md。

四、AGENTS.md 兼容与查看/编辑命令

命令	用途
/memory	列出各层记忆文件位置、切换自动记忆开关、在编辑器中打开或新建对应文件
/context	查看本次启动实际加载了哪些 Memory files，用于排查"规则为何没生效"
/compact	压缩会话；压缩后项目根 CLAUDE.md 会从磁盘重读并重新注入，子目录规则按需再次加载
/doctor	对冗长、且内容可由代码本身推导出来的 CLAUDE.md 给出裁剪建议

若仓库只有 AGENTS.md 而无 CLAUDE 族文件，代理会读取它；一旦存在 CLAUDE.md/CLAUDE.local.md，则默认只读 CLAUDE 体系。可在 /config 的 Project instructions 中切换读取策略（仅 CLAUDE、两者并读、仅 CLAUDE 或仅托管策略等）。CLAUDE.md 还可用 @路径/文件 语法引入外部片段。