Claude Code 记忆系统完全指南：CLAUDE.md、自动记忆和规则配置实战
每次打开 Claude Code，它都像失忆了一样——上次说好的代码风格、项目架构、甚至你纠正过的错误，全忘了。这不是 bug，是设计。Claude Code 的每个会话都是全新的上下文窗口，不会自动记住上次聊了什么。
但它其实有记忆能力，而且不止一种。搞明白这套记忆系统之后，我的 Claude Code 使用效率至少翻了一倍——不用每次重新解释项目结构，不用反复纠正同一个错误，甚至它能自己记住踩过的坑。
这篇文章聊聊 Claude Code 的三种记忆机制，以及我实际使用中摸索出来的一些经验。
两种核心记忆：CLAUDE.md 和自动记忆
Claude Code 有两套互补的记忆系统，每次会话启动时都会加载：
- CLAUDE.md 文件：你手写的指令，告诉 Claude 这个项目怎么搞
- 自动记忆（Auto Memory）：Claude 自己写的笔记，记录它学到的东西
一个是你主动喂给它的，一个是它自己积累的。用好了这两个，Claude Code 就从"每次都是新来的实习生"变成了"熟悉项目的老手"。
CLAUDE.md：你给 Claude 的项目说明书
CLAUDE.md 就是一个 Markdown 文件，Claude 每次会话启动时都会读它。你可以把它理解成给新同事写的 onboarding 文档——只不过这个"同事"每次都失忆，所以你得每次都给它看。
什么时候该往 CLAUDE.md 里加东西
不是什么都往里塞。官方建议的判断标准很简单：
- Claude 犯了同一个错误第二次
- Code review 发现了 Claude 应该知道的东西
- 你上次在聊天里输入了同样的纠正
- 新同事来也需要知道这些信息
说白了，就是那些"你不想每次都重复说"的东西。
CLAUDE.md 放哪里
这是个容易搞混的地方。CLAUDE.md 可以放在好几个位置，每个位置的范围不同：
用户级别：~/.claude/CLAUDE.md
放你个人的偏好，所有项目通用。比如"我习惯用 pnpm 不用 npm"、"代码缩进用 2 个空格"。
项目级别：./CLAUDE.md 或 ./.claude/CLAUDE.md
团队共享的项目规范。提交到 git，所有人都能用。比如"构建命令是 pnpm build"、"测试用 vitest"。
本地级别：./CLAUDE.local.md
你个人对这个项目的偏好，不提交到 git。比如"本地数据库密码是 xxx"、"我喜欢先跑单测再提交"。记得加到 .gitignore。
目录级别：子目录下的 CLAUDE.md
只在 Claude 读取该子目录下的文件时才加载。适合大型项目里不同模块的特殊规则。
加载顺序是从文件系统的根目录往下，越靠近当前工作目录的越后加载，所以项目级别的指令会覆盖用户级别的。
写好 CLAUDE.md 的关键
我踩过最大的坑就是把 CLAUDE.md 写成了长篇大论。结果 Claude 根本不怎么遵守——内容太多，它反而抓不住重点。
几个实战经验：
控制在 200 行以内。CLAUDE.md 会占用上下文窗口，太长了反而影响效果。如果内容确实多，拆到 .claude/rules/ 里用路径匹配按需加载。
写具体，别写废话。"使用 2 空格缩进"比"格式化代码"有用得多。"API handler 放在 src/api/handlers/"比"保持文件组织"有用得多。越具体，Claude 越遵守。
别互相矛盾。如果两个规则冲突了，Claude 会随机选一个。定期检查一下 CLAUDE.md 和 rules 目录，删掉过时的或冲突的指令。
用 Markdown 结构化。标题、列表、分组，Claude 扫描结构的方式跟人一样——有组织的比一坨文字好使。
一个实际的 CLAUDE.md 示例
| 1 | |
| 2 | |
| 3 | |
| 4 | |
| 5 | |
| 6 | |
| 7 | |
| 8 | |
| 9 | |
| 10 | |
| 11 | |
| 12 | |
| 13 | |
| 14 | |
| 15 | |
| 16 | |
| 17 | |
| 18 | |
| 19 | |
| 20 | |
| 21 | |
| 22 | |
| 23 | |
| 24 | |
| 25 | |
| 26 | |
短小精悍，每次会话都加载，Claude 看了就知道项目怎么搞。
导入其他文件
CLAUDE.md 支持 @path/to/file 语法导入其他文件。比如：
| 1 | |
| 2 | |
| 3 | |
| 4 | |
导入的文件会在启动时一起加载到上下文里。注意，导入不会减少 token 消耗——文件内容还是会全部进入上下文窗口。好处是组织更清晰，不用在一个文件里塞所有东西。
AGENTS.md 兼容
如果你的项目已经在用 AGENTS.md（给其他 AI 编程工具用的），可以直接在 CLAUDE.md 里导入它：
| 1 | |
| 2 | |
| 3 | |
| 4 | |
或者简单粗暴做个符号链接：ln -s AGENTS.md CLAUDE.md。
.claude/rules/：按路径加载的规则
项目大了之后，一个 CLAUDE.md 里塞不下所有规则，而且很多规则只对特定文件有效。.claude/rules/ 解决了这个问题。
基本用法
在项目下创建 .claude/rules/ 目录，每个文件覆盖一个主题：
| 1 | |
| 2 | |
| 3 | |
| 4 | |
| 5 | |
| 6 | |
| 7 | |
没有 paths 字段的规则在启动时全部加载，跟 .claude/CLAUDE.md 一样。
路径匹配规则
这是 rules 最牛的地方——可以只在 Claude 处理特定文件时才加载对应规则。用 YAML frontmatter 的 paths 字段：
| 1 | |
| 2 | |
| 3 | |
| 4 | |
| 5 | |
| 6 | |
| 7 | |
| 8 | |
| 9 | |
这个规则只在 Claude 读取 src/api/ 下的 TypeScript 文件时才生效。不在那个目录工作的时候，这些规则不占上下文。
支持 glob 模式：
**/*.ts— 所有 TypeScript 文件src/**/*— src 下所有文件*.md— 根目录的 Markdown 文件src/components/*.tsx— 特定目录的 React 组件src/**/*.{ts,tsx}— 多种扩展名
这对大型项目太有用了。前端规则只在前端文件生效，后端规则只在后端文件生效，互不干扰。
用户级 rules
~/.claude/rules/ 下的规则对你所有项目生效。适合放个人偏好：
| 1 | |
| 2 | |
| 3 | |
用户级规则先加载，项目级规则后加载，所以项目级优先级更高。
管理员部署
公司 IT 可以在 macOS 的 /Library/Application Support/ClaudeCode/CLAUDE.md 或 Linux 的 /etc/claude-code/CLAUDE.md 放一个全局 CLAUDE.md，所有用户都会加载，而且不能被排除。适合放公司编码规范、安全策略、合规要求。
自动记忆：Claude 自己学的东西
这是我觉得最酷的功能。自动记忆让 Claude 在工作过程中自己做笔记——构建命令、调试经验、架构设计、代码风格偏好、工作流习惯。它不是每个会话都记，而是判断"这个信息以后有没有用"来决定要不要存。
存在哪里
每个项目有自己的记忆目录：~/.claude/projects/<project>/memory/。<project> 路径是从 git 仓库推导的，所以同一个仓库的所有 worktree 和子目录共享同一个记忆。
目录结构长这样：
| 1 | |
| 2 | |
| 3 | |
| 4 | |
| 5 | |
MEMORY.md 是索引，前 200 行（或 25KB，取小值）会在每次会话启动时加载。超过的部分不加载。topic 文件（如 debugging.md）不会在启动时加载，Claude 需要的时候才会去读。
实际效果
用了一段时间之后，我发现 Claude 自动记住了一些东西：
- "这个项目用 pnpm，不是 npm"
- "测试用 vitest，不是 jest"
- "数据库连接字符串在 .env.local 里"
- "上次那个 SSR hydration 错误是因为组件在服务端渲染时访问了 window"
每次新会话它都会带上这些记忆，不用我再提醒。尤其是那些踩过的坑，它记住了就不会再犯。
管理自动记忆
在 Claude Code 里输入 /memory 可以查看所有加载的 CLAUDE.md、CLAUDE.local.md、rules 文件，以及自动记忆。可以开关自动记忆，也可以直接打开记忆文件夹编辑。
自动记忆是纯 Markdown 文件，随时可以手动编辑或删除。觉得 Claude 记错了什么，直接改就行。
想手动让 Claude 记住什么，直接在聊天里说："记住这个项目用 pnpm"。Claude 会存到自动记忆里。如果想存到 CLAUDE.md 里，说"把这个加到 CLAUDE.md"。
关闭自动记忆
不太建议关，但如果确实需要：
| 1 | |
| 2 | |
| 3 | |
或者环境变量：CLAUDE_CODE_DISABLE_AUTO_MEMORY=1。
/compact 之后记忆还在吗
这是个好问题。/compact 会压缩当前会话的上下文，但项目根目录的 CLAUDE.md 会在压缩后重新从磁盘读取注入。子目录下的 CLAUDE.md 不会自动重新加载——要等到 Claude 下次读取那个子目录的文件时才会加载。
所以关键的指令放在项目根目录的 CLAUDE.md 里，别放在子目录。否则 compact 之后可能就"忘了"。
自动记忆不受 compact 影响——它存在磁盘上，每次会话启动都从磁盘读取。
实战建议：怎么组织记忆系统
摸索了一段时间，我总结了一套组织方式：
CLAUDE.md 放什么：
- 项目架构和目录结构
- 构建、测试、部署命令
- 团队编码规范
- 重要的"总是要做的事"
CLAUDE.local.md 放什么：
- 本地开发环境配置
- 个人偏好（不影响团队）
- 测试用的数据库/服务地址
.claude/rules/ 放什么：
- 按模块分的规则（前端、后端、数据库）
- 路径特定的规则（API 验证、组件规范）
- 敏感目录的特殊要求（billing、auth）
自动记忆：
- 让 Claude 自己积累
- 定期检查，删掉过时的
- 踩过的坑让它自己记，比你手写更准
常见问题
Claude 不遵守 CLAUDE.md 怎么办
先用 /memory 确认文件确实被加载了。如果加载了但不遵守，把指令写得更具体。如果某个规则必须严格执行（比如"提交前必须跑 lint"），用 Hook 而不是 CLAUDE.md——Hook 是强制执行的，CLAUDE.md 只是建议。
CLAUDE.md 太长了
超过 200 行效果就开始下降。拆到 .claude/rules/ 里用路径匹配，只在需要的时候加载。或者把详细说明移到 @import 的单独文件里（不过这不会减少 token 消耗，只是组织更清晰）。
自动记忆记了不该记的东西
直接去 ~/.claude/projects/<project>/memory/ 删掉或编辑。都是纯文本，没有加密或特殊格式。
monorepo 里被其他团队的 CLAUDE.md 干扰
用 claudeMdExcludes 排除不相关的文件：
| 1 | |
| 2 | |
| 3 | |
| 4 | |
| 5 | |
| 6 | |
放在 .claude/settings.local.json 里，只影响你本地。
想让指令在系统 prompt 层级生效
CLAUDE.md 是作为 user message 注入的，不是系统 prompt。如果需要系统 prompt 级别的指令，用 --append-system-prompt 参数。不过这个每次启动都要传，适合脚本和自动化场景。
写在后面
Claude Code 的记忆系统看起来简单——就是几个 Markdown 文件——但用好了差距很大。关键是找到一个平衡：给够上下文让 Claude 理解项目，但别塞太多东西把它淹没。
我现在的习惯是：CLAUDE.md 保持在 50 行左右，核心规则和构建命令。模块特定的规则拆到 rules 目录。自动记忆开着，偶尔检查一下 Claude 记了什么。这样每次开 Claude Code，它已经知道 80% 的上下文，我只需要说要做什么就行。
后面打算折腾一下 Hooks 系统——那个是真正的强制执行机制，不靠 Claude "自觉"。到时候再写一篇。
有啥问题评论区聊。