Claude Code 记忆与 CLAUDE.md 的加载规则

这篇适合谁，读完能做到什么

如果你发现 Claude Code 在新会话里忘了项目约定，或者不确定某条指令到底有没有被加载，这篇适合你。读完你能分清两套记忆机制，知道 CLAUDE.md 应该放在哪一层，明白它何时被读入上下文，并能用 /context all 核对加载情况。^[1]

两套记忆：CLAUDE.md 和 auto memory

Claude Code 的每个会话都从一个全新的上下文窗口开始。要让知识跨会话保留，有两种机制。一种是 CLAUDE.md 文件，由你来写；另一种是 auto memory，由 Claude 根据你的纠正和偏好自己写。^[1]

两者在每次对话开始时都会被加载。但要记住，Claude 把它们当作上下文，而不是强制执行的配置。如果某个动作无论如何都必须被阻止，应该用 PreToolUse hook，而不是写进记忆文件。^[1]

二者的分工大致是：CLAUDE.md 用来约束 Claude 的行为，写编码规范、工作流和项目结构；auto memory 记录的是学到的经验和模式，比如你的偏好、你做过的纠正，以及代码里看不出来的项目背景。auto memory 中 MEMORY.md 的前 200 行或前 25KB 会在每次对话开始时加载，以先到者为准。^[1]

一个值得注意的细节是：CLAUDE.md 的内容是作为用户消息在系统提示之后交给 Claude 的，并不属于系统提示本身。Claude 会尝试遵循它，但不保证严格执行，指令越含糊或越互相矛盾，越不可靠。^[1]

CLAUDE.md 应该放在哪一层

CLAUDE.md 可以放在好几个位置，作用范围各不相同。^[1]

• 托管策略（managed policy）：macOS 上是 /Library/Application Support/ClaudeCode/CLAUDE.md，Linux 和 WSL 上是 /etc/claude-code/CLAUDE.md，Windows 上是 C:\Program Files\ClaudeCode\CLAUDE.md。它面向组织里的所有用户，由 IT 或 DevOps 统一管理，适合公司编码规范、安全策略和合规要求。^[1]
• 用户级：~/.claude/CLAUDE.md，对你的所有项目生效，只有你自己用。适合个人的代码风格偏好和工具快捷方式。^[1]
• 项目级：./CLAUDE.md 或 ./.claude/CLAUDE.md，通过版本控制与团队共享。适合项目架构、编码规范和常用工作流。^[1]
• 本地级：./CLAUDE.local.md，只属于你自己、只对当前项目生效。它应该加入 .gitignore，适合你的沙箱地址、常用测试数据之类的个人偏好。^[1]

启动时加载哪些文件

Claude Code 启动时，会从当前工作目录开始，向上一直到文件系统根目录，加载沿途的 CLAUDE.md 和 CLAUDE.local.md。假设你在 foo/bar/ 下启动，那么 foo/bar/CLAUDE.md、foo/CLAUDE.md 以及它们旁边的 CLAUDE.local.md 都会被读入。^[1]

这些文件不是互相覆盖的，而是全部拼接进上下文。顺序是从根目录往下，离启动目录越近的越靠后，所以更靠近你工作位置的指令会最后被读到。在同一个目录里，CLAUDE.local.md 排在 CLAUDE.md 之后。^[1]

子目录里的 CLAUDE.md 不会在启动时加载。只有当 Claude 读取、写入或编辑了那个子目录里的其他文件时，它才会被加载。^[1]

CLAUDE.md 里的块级 HTML 注释（例如 <!-- 维护者备注 -->）会在注入上下文之前被去掉，所以可以用来给人类维护者留言，又不占用上下文。代码块里的注释则会保留。^[1]

用 --add-dir 加入的目录怎么办

--add-dir 可以让 Claude 访问主工作目录之外的其他目录。但默认情况下，这些目录里的 CLAUDE.md 不会被加载。如果需要加载，在启动时设置环境变量即可：^[1]

``bash CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 claude --add-dir ../shared-config ``^[1]

这个写法只对本次启动生效。^[1]

怎样写一份有效的 CLAUDE.md

控制长度很重要：单个 CLAUDE.md 最好不超过 200 行。文件越长，占用的上下文越多，遵循程度也越低。只对代码库某一部分有用的指令，可以移到路径作用域的规则里，只在 Claude 处理匹配文件时才加载。^[1]

指令要写得具体、可以验证。比如「用两个空格缩进」比「把代码格式化好」有用，「API 处理函数放在 src/api/handlers/」比「保持文件整洁」有用。^[1]

如果 CLAUDE.md 太长，可以用 @路径 导入其他文件。导入路径可以是相对路径，相对的是包含这条导入的文件而不是工作目录；导入可以嵌套，但最多四层。导入语法会跳过 Markdown 的代码片段和代码块，所以如果只想提到某个文件而不导入它，把它放进反引号里即可。^[1]

.claude/rules/ 怎么用

当项目变大时，可以把指令拆成多个文件，放进 .claude/rules/ 目录。这个目录下所有的 .md 文件都会被递归发现，所以可以再按 frontend/、backend/ 之类的子目录组织。每个文件最好只讲一个主题，文件名要有描述性，比如 testing.md 或 api-design.md。^[1]

没有设置 paths 字段的规则，启动时就会加载，优先级和 .claude/CLAUDE.md 相同。规则文件的 frontmatter 里，Claude Code 只读取 paths 字段，其他字段会被忽略，也不会报错。^[1]

auto memory 怎么存、怎么关

auto memory 在本地会话中默认开启。在 /memory 里切换开关，会把 autoMemoryEnabled 保存到 ~/.claude/settings.json。^[1]

它的存放位置是 ~/.claude/projects/<project>/memory/。项目路径由 git 仓库推导，所以同一仓库的所有 worktree 和子目录共用一个记忆目录。^[1]

Claude 会把记忆分成四类：user 记录你的角色、专长和工作偏好；feedback 记录你给出的纠正和确认过的做法；project 记录进行中的工作、截止日期和代码与 git 历史里看不出来的决定；reference 记录项目之外的信息位置，比如问题跟踪器或看板。^[1]

有一类内容 Claude 不会记：能从代码库推导出来的东西，以及 CLAUDE.md 里已经写过的东西。^[1]

需要注意，auto memory 的主文件 MEMORY.md 受 200 行和 25KB 的限制，超出的部分启动时不会加载。细节应该放进单独的主题文件，比如 user_role.md，这些文件启动时不加载，Claude 需要时再用文件工具去读。^[1]

排查「指令没生效」

先在会话里运行 /context all，查看 Memory files 列表，确认该加载的 CLAUDE.md 是否都在。如果某个文件不在列表里，Claude 就看不到它。子目录里的 CLAUDE.md 不会出现在这个列表里，因为它是按需加载的。^[1]

/memory 命令可以列出 CLAUDE.md、CLAUDE.local.md 以及其他记忆文件的位置，也能切换 auto memory 的开关。想把内容写进 CLAUDE.md，可以让 Claude 添加，也可以自己用 /memory 打开编辑。^[1]

如果某条指令必须在特定时刻执行，比如每次提交前或每次改文件后，应该改写成 hook。hook 作为 shell 命令在固定的生命周期事件触发，不论 Claude 怎么判断都会执行。^[1]

下一步

关于 CLAUDE.md 的完整加载顺序、AGENTS.md 的用法，以及组织级部署的细节，可以阅读 Claude Code 官方文档中的记忆页面。^[1]