Claude Code 记忆系统实践指南

前言

Claude Code 每次启动都是全新状态------它不记得上次你们讨论了什么架构决策，CLAUDE.md 就是解决这个问题的文件。Claude Code 每次启动时都会自动读取它，让你不必在每个新会话里重新介绍自己的项目。

这篇文章专门拆解这个文件：它的加载机制、该写什么、不该写什么、如何维护，以及 Claude Code 2026 年新增的自动记忆（Auto Memory）系统。

文章结构

复制代码

1. 加载机制 --- 什么时候读、从哪里读、加载顺序
2. 该写什么 --- 三类核心内容
3. 不该写什么 --- 常见的错误和陷阱
4. 文件组织 --- 拆分与导入语法
5. 记忆文件 --- CLAUDE.md 和 MEMORY.md
6. 维护原则 --- 如何让它保持有效
7. 实战练习

快速参考卡

复制代码

文件位置（加载优先级从高到低）
  /etc/claude-code/CLAUDE.md ① 企业专用，不可被覆盖
  ~/.claude/CLAUDE.md ② 全局个人偏好
  ./CLAUDE.md ③ 团队共享，提交到 git
  ./.claude/rules/*.md ③ 同级，自动合并，无需导入
  ./CLAUDE.local.md ④ 个人覆盖，加入.gitignore不提交到git
  ./子目录/CLAUDE.md ⑤ 子目录按需加载，非启动时加载

Auto Memory 位置（Claude 自动维护）
  ~/.claude/projects/<project>/memory/MEMORY.md
  ~/.claude/projects/<project>/memory/*.md

导入语法
  @README.md 导入同级文件
  @docs/api-rules.md 导入子目录文件
  @~/.claude/personal-rules.md 导入全局个人规则

排除特定文件
  # 在 settings.json 中配置（用户级、项目级或本地均可）
  { "claudeMdExcludes": ["./legacy/CLAUDE.md", "./vendor/**"] }
  # Managed Policy 的 CLAUDE.md 不可被排除

生成与编辑
  /init 自动生成项目起始CLAUDE.md文件
  /memory 浏览和编辑记忆文件，开关 Auto Memory

注意事项
  文件名大小写敏感，必须是 CLAUDE.md（CLAUDE 全大写，.md 全小写）
  建议控制在 200 行以内，超过后遵守率明显下降
  系统提示词已占用约 50 条指令配额，CLAUDE.md 竞争剩余的 100 至 150 条

第一节：加载机制

理解 Claude 怎么读这个文件，才能知道怎么写好它。

完整加载顺序

Claude Code 启动时按以下优先级顺序加载，数字越小优先级越高：

复制代码

① /etc/claude-code/CLAUDE.md
   Managed Policy（macOS 对应 /Library/Application Support/ClaudeCode/CLAUDE.md）
   企业 IT 团队统一部署，不可被任何个人或项目覆盖。

② ~/.claude/CLAUDE.md
   User Global，你的全局个人偏好，作用于所有项目。

③ ./CLAUDE.md  +  ./.claude/rules/*.md
   Project Root，提交到 git，团队所有人共享同一份上下文。
   .claude/rules/ 目录内的所有 .md 文件与主文件同优先级，自动合并加载。

④ ./CLAUDE.local.md
   Local Project，个人级别的项目覆盖。
   Claude Code 创建时会自动将它加入 .gitignore，不会被提交。

⑤ ./子目录/CLAUDE.md
   子目录级别，按需加载。
   不在启动时加载，只有当 Claude 实际操作那个子目录下的文件时才读取。

所有层级的内容会合并生效，优先级规则：Personal > Project > Global。若相同指令出现在多个层级，最具体的（Personal/Local）优先。Managed Policy 是唯一例外------它永远优先，任何层级都无法覆盖。

排除特定 CLAUDE.md

如果你不想加载某个路径下的 CLAUDE.md（比如 vendor 目录里第三方库带的配置），可以在 settings.json 里配置：

json 复制代码

{
  "claudeMdExcludes": [
    "./vendor/**",
    "./legacy/CLAUDE.md"
  ]
}

这个配置可以放在用户级、项目级或本地 settings 文件中，数组会跨层级合并。Managed Policy 的 CLAUDE.md 不受此配置影响，无法被排除。

指令配额的限制

前沿模型大约能可靠地遵循 150 到 200 条独立指令。但 Claude Code 的系统提示词本身就已经使用了约 50 条。这意味着你的 CLAUDE.md 实际可用的配额只有 100 到 150 条左右。

写得越多，不一定遵守得越好。内容精简的 CLAUDE.md 往往比堆满规则的版本效果更好。

第二节：该写什么

一个好的 CLAUDE.md 回答三个问题：这是什么项目、为什么这样设计、Claude 应该怎么工作。

WHAT --- 项目是什么

让 Claude 在一秒内理解你的项目：

markdown 复制代码

## 项目概述

这是一个 Python 实时数据采集与分析系统，使用 FastAPI 提供 REST 接口，
Celery + Redis 处理异步任务，ClickHouse 存储时序数据。
主要用户是运维和数据团队。

## 目录结构

src/api/        FastAPI 路由和接口定义
src/workers/    Celery 异步任务
src/models/     数据模型和 schema
src/services/   业务逻辑层
tests/          pytest 测试，镜像 src/ 目录结构

HOW --- Claude 怎么工作

最有价值的部分：Claude 无法从代码中推断出来的工作方式：

markdown 复制代码

## 开发命令

uv run pytest tests/ -x --tb=short        # 运行测试
uv run celery -A src.workers worker -l info  # 启动 worker

# 使用 uv，不要使用 pip 或 pip install
# 依赖管理通过 pyproject.toml，不维护 requirements.txt

## 工作流规则

- 所有 Celery 任务必须实现幂等性
- ClickHouse 查询必须放在 src/services/ 层，不要在路由里写原始 SQL

WHY --- 重要的设计决策和陷阱

这类信息最容易被忽略，但往往最有价值：

markdown 复制代码

## 必须知道的陷阱

- src/api/auth.py 有历史遗留问题，修改前必须告诉我
- ClickHouse 的 ReplacingMergeTree 有最终一致性，不要用它做强一致性校验
- tests/fixtures/ 下的 conftest.py 有共享状态，并发测试时注意隔离

第三节：不该写什么

不要写代码风格规则

markdown 复制代码

# 不推荐
- 使用 4 个空格缩进
- 变量名用 snake_case
- 字符串用双引号

用 Hooks 在每次文件写入后自动运行 formatter，比在 CLAUDE.md 里写 20 条格式规则有效得多。

不要写 Claude 本来就会做的事

markdown 复制代码

# 不推荐（这些 Claude 默认就会做）
- 写代码前先理解需求
- 修改文件前先阅读文件
- 给函数加注释

每一条无效指令都在消耗配额。只写"如果没有这条规则，Claude 就会犯错"的内容。

不要写只在特定任务才相关的内容

markdown 复制代码

# 不推荐（只在部署时才相关的详细步骤）
- 部署时先更新镜像，再触发 rolling update，等待健康检查......

这类内容应该放进自定义 Slash 命令或 Skills 里，按需加载。塞进 CLAUDE.md 只会在每次普通编码会话里浪费上下文。

第四节：文件组织

拆分规则文件

当团队规模变大，一个人维护整个 CLAUDE.md 会产生合并冲突。利用 .claude/rules/ 目录------放进这个目录的所有 Markdown 文件会被自动加载，无需在主文件里显式导入：

复制代码

.claude/
  rules/
    testing.md       # 测试规范，测试团队维护
    security.md      # 安全规范，安全团队维护
    git.md           # Git 工作流，所有人共同维护

不同团队各自维护自己负责的规则文件，互不干扰，也不会在同一个文件上产生冲突。

@ 导入语法

主 CLAUDE.md 可以用 @ 引用其他文件，避免重复维护：

markdown 复制代码

项目概述参见 @README.md。

附加规则：
- 部署流程：@docs/deployment.md
- 个人偏好：@~/.claude/my-overrides.md

全局个人规则

在 ~/.claude/CLAUDE.md 里放你的个人偏好，作用于你参与的所有项目：

markdown 复制代码

## 我的个人偏好

- 请用中文回答
- 如果我的问题有歧义，先问清楚再动手

CLAUDE.local.md 的用途

CLAUDE.local.md 是个人的项目级覆盖文件，自动被 git 忽略。适合放一些只对你自己有意义、不适合提交的内容：

markdown 复制代码

## 我的本地配置

- 本地数据库连接到 localhost:5432（不是 Docker 里的那个）
- 我用 vim，生成的代码不需要 VS Code 的 launch.json

第五节：记忆文件

`CLAUDE.md` 和 `MEMORY.md`

CLAUDE.md是你写的内容（规则和指令），它可以在CLAUDE.md / CLAUDE.local.md / .claude/rules/*.md等处被找到。其会在启动时加载，告诉 Claude 该怎么做。

MEMORY.md是Claude 的记录（会话学到的知识），它可以在~/.claude/projects//memory/中被找到。包含 MEMORY.md（索引文件，每次启动加载）和 *.md（主题文件，按需读取）

它们的核心区别是：

	CLAUDE.md	Auto Memory（MEMORY.md）
谁来写	你	Claude 自动写
内容类型	规则、指令、约束	学到的事实、调试经验、发现的模式
存储位置	项目目录	`~/.claude/projects/`
是否提交 git	是（主文件）	否（机器本地）
启动时加载	全量加载	只加载 MEMORY.md 索引

Auto Memory

Auto Memory 是 Claude Code v2.1.59（2026 年 2 月）加入的功能，默认开启。

工作原理：Claude 在工作过程中，会把它认为值得记住的内容自动写入 ~/.claude/projects/<项目路径>/memory/：

复制代码

~/.claude/projects/-Users-you-myproject/memory/
  MEMORY.md         每次启动加载的索引
  debugging.md      调试经验和已知问题
  patterns.md       发现的代码模式和约定
  build.md          构建和环境细节

MEMORY.md 是索引，每次启动都会加载。其他主题文件只在 Claude 需要时按需读取，不会撑大每次的上下文。

Auto Memory 记录的是事实，不是规则。它会写"项目用 uv 管理依赖，测试命令是 uv run pytest"，而不是"你必须用 uv"。

在会话中执行 /memory 会打开一个交互界面，可以：

查看当前会话加载了哪些 CLAUDE.md 文件
直接编辑 CLAUDE.md（想固化某条规则时最快的方式）
查看和浏览 Auto Memory 的文件
开关 Auto Memory 功能

/memory 不等于 Auto Memory，它是管理所有记忆类文件的统一入口。除了 /memory，也可在你的项目设置中设置 autoMemoryEnabled：

json 复制代码

{
  "autoMemoryEnabled": false
}

总结

你在 CLAUDE.md 里写规则
你用 /memory 在会话中固化临时决策
Claude 在 Auto Memory 里写它发现的事实

第六节：维护原则

判断一行是否该留的标准

对每一行问自己：去掉这行，Claude 会犯错吗？

如果不会，删掉它。每一行无效内容都在稀释真正重要的规则。

出问题时检查文件

如果 Claude 反复忽略某条规则，通常有两个原因：

文件太长，规则被淹没了------精简内容，或把这条规则提到最前面
规则描述不够具体------"格式化代码"这样的指令过于模糊，改成"提交前运行 ruff format ."

定期修剪

建议在每次大的重构或技术栈升级后，把 CLAUDE.md 过一遍，删掉不再适用的内容。这件事 Auto Memory 不会替你做，因为它记录事实，不负责管理你写的规则。

提交到 git

项目根目录的 CLAUDE.md 应该提交到 git。它会随着项目演进积累价值，新成员加入时也能立刻获得完整的上下文。CLAUDE.local.md 则始终不提交。

实战练习

练习 1：用 /init 生成起点，然后精简

bash 复制代码

cd your-project
claude
/init

生成文件后，逐行审查：对每一行问"去掉这行 Claude 会犯错吗？"不会的就删掉。目标是把生成的文件长度减少 30% 以上。

练习 2：找出你项目里真正的陷阱

回想：上个月有没有哪个 Bug 是因为不了解某个历史决策而引入的？有没有某个模块是"碰不得"的？把这些写进 CLAUDE.md 的"必须知道的陷阱"里。

练习 3：查看 Auto Memory 是否在工作

bash 复制代码

# 查看 Auto Memory 目录
ls ~/.claude/projects/

# 进入 Claude Code 会话
claude
/memory

在 /memory 界面确认 Auto Memory 开关状态，查看 Claude 已经积累了哪些关于你项目的笔记。

练习 4：建立全局个人规则

bash 复制代码

cat > ~/.claude/CLAUDE.md << 'EOF'
## 我的个人偏好

- 请用中文回答
- 解释方案时先给结论，再给推理过程
- 如果我的问题有歧义，先问清楚再动手
EOF

重启一个会话，验证 Claude 的行为是否改变。

练习 5：测试你的 CLAUDE.md 是否有效

复制代码

1. 关闭当前会话，重新启动 claude
2. 直接问：你知道这个项目用什么工具管理 Python 依赖吗？
3. 如果 Claude 答错或说不知道，说明相关内容没有写进 CLAUDE.md，或描述不清晰
4. 修改文件，再测试一次

下一篇预告

#04 --- Claude Code 的权限系统：让 AI 在安全边界内工作

Claude Code 可以读文件、写文件、执行命令------但这些操作你都能控制。权限系统、沙盒模式、.claude/settings.json 的配置方式，下一篇全面拆解。

参考文档：Claude Code 官方文档