一、为什么你的 Claude Code 总在"失忆"

你有没有遇到过这种情况——

用 Claude Code 干活，第一天它表现惊艳：项目结构门儿清、代码风格完全匹配、改起 bug 来又快又准。

第二天再开新会话，它好像什么都不记得了：同样的项目规范要重新讲一遍，之前确认过的技术选型又问你一遍，甚至把你昨天刚废弃的方案又拿出来推荐。

这不是你的错觉，也不是 Claude Code 变笨了——每次新会话，AI 都是"失忆"状态。它不会自动记住你昨天聊了什么、项目有什么约定、你偏好什么风格。

但好消息是：Claude Code 提供了两个机制来解决这个问题——CLAUDE.md（项目记忆）和 memory（全局记忆）。用好了这两个，AI 就能真正"记住"你的项目，从"每次重新认识"变成"老熟人"。

这篇文章就是讲清楚：这两个机制是什么、怎么配、什么时候用哪个。

二、CLAUDE.md：项目的"入职手册"

CLAUDE.md 是 Claude Code 的项目级记忆文件。放在项目根目录（或 CLAUDE/ 目录），每次 Claude Code 在这个项目里启动会话时，都会自动读取它。

它的作用就像公司的入职手册：新员工（AI）第一天上班，先读手册，了解公司规矩、代码规范、项目背景——不用你重新教一遍。

基本用法：创建 CLAUDE.md

在项目根目录创建文件：

touch CLAUDE.md

然后写入项目的关键信息。一个比较完整的示例：

# 项目：订单中台

## 技术栈
- 后端：Spring Boot 3.2 + MyBatis-Plus + MySQL 8
- 前端：Vue 3 + TypeScript + Vite
- 中间件：Redis 7 + RocketMQ

## 代码规范
- 所有 SQL 必须走预编译，禁止字符串拼接
- 金额字段用 BigDecimal，禁止 double
- 日志用 slf4j，禁止 System.out
- Controller 只做参数校验，业务逻辑下沉 Service

## 目录结构
- controller/：HTTP 入口
- service/：业务逻辑（接口 + impl 分离）
- mapper/：MyBatis 接口 + XML
- model/：数据库实体
- dto/：接口出入参

## 注意事项
- 订单号生成走 OrderNumberGenerator，禁止自行拼接
- 库存扣减必须用原子 UPDATE，禁止先查后改
- 支付回调必须做幂等（状态机 PENDING→PAID）

写完之后，你在这个项目里开新会话，Claude Code 会自动读这个文件。你可以直接问它："我们项目的订单号是怎么生成的？"它会基于 CLAUDE.md 里的内容回答你。

什么时候该更新 CLAUDE.md

- 新项目搭好骨架时 → 把技术栈、目录结构写进去

- 定下重要规范时 → 比如"禁止 X""必须 Y"这类约定

- 换人交接时 → 把关键背景写清楚，新会话的 AI 直接继承

- 技术栈变更时 → 比如从 MyBatis 换成 JPA，记得更新

有个小技巧：让 Claude Code 自己帮你写 CLAUDE.md。项目稳定后，跑一句：

claude "分析这个项目，生成一份 CLAUDE.md，包含技术栈、目录结构、代码规范、注意事项"

它会自动读项目代码，生成一份符合你项目的记忆文件。你检查一遍、补上它不知道的业务约定，就完事了。比自己从零写快得多。

三、memory 规则：全局的"长期记忆"

CLAUDE.md 是项目级的，换一个项目它就不知道了。而 memory 是 Claude Code 的全局记忆——对所有项目生效，适合放通用的个人偏好和长期规则。

配置方式

在用户目录下编辑配置文件（默认 ~/.claude/settings.json），加一段：

{
  "memory": true,
  "rules": [
    "代码注释用中文，不用英文",
    "变量命名用驼峰，不用下划线",
    "生成的代码必须带单元测试",
    "优先使用标准库，少引第三方依赖",
    "回答要简洁，先给结论再给细节"
  ]
}

配置好之后，不管你在哪个项目里用 Claude Code，它都会遵循这些全局规则。

CLAUDE.md vs memory：怎么选

这是最容易混的地方，一句话说清：

| | CLAUDE.md | memory |

|---|----------|--------|

| 作用范围 | 单个项目 | 所有项目 |

| 适合内容 | 项目技术栈、目录、规范 | 个人偏好、通用编码习惯 |

| 更新频率 | 项目变化时 | 很少变 |

| 优先级 | 高（项目特定） | 基础（通用） |

举个具体的例子：你的公司规范是"所有 SQL 必须预编译"——这是项目/团队级的，写 CLAUDE.md；而"注释用中文"是你个人习惯，放 memory。两者可以同时生效，互不冲突。

四、进阶玩法：把 CLAUDE.md 拆成模块

项目大了之后，一个 CLAUDE.md 会越来越长，AI 每次都要读全文，浪费上下文。

Claude Code 支持把记忆文件放到 CLAUDE/ 目录下拆分管理，格式和 CLAUDE.md 一样。目录结构可以这样组织：

CLAUDE/
├── CLAUDE.md          # 主文件：技术栈、目录结构
├── backend.md         # 后端规范：数据库、接口、事务
├── frontend.md        # 前端规范：组件、样式、状态管理
├── testing.md         # 测试规范：单测、集成测试要求
└── deployment.md      # 部署规范：环境、流水线、回滚

Claude Code 会按需加载这些文件——你让它改后端代码时，它会重点参考 backend.md；改前端时，重点参考 frontend.md。不用每次全量读一遍，上下文更省，响应也更快。

用目录组织大型项目

对于超大型项目（多模块、多团队），可以在子目录里放各自的 CLAUDE.md：

order-service/
├── CLAUDE.md          # 订单服务专属规范
├── src/
└── ...
payment-service/
├── CLAUDE.md          # 支付服务专属规范
└── ...

Claude Code 处理某个目录下的代码时，会优先读取该目录的 CLAUDE.md。这样每个模块的 AI 上下文都"各归各的"，不会串味。

五、实战：让 CLAUDE.md 帮我省掉 80% 的重复解释

光讲理论没意思，说一个我真实的项目经历。

我维护一个老项目，代码风格跟主流不太一样：Controller 层有自己的一套基类、异常处理用的是公司内部框架、数据库访问全是自定义的封装。以前每次开新会话用 Claude Code，光解释这些背景就要花十几分钟，而且解释完了它还是偶尔会写出不符合规范的代码。

后来我花了一个下午，把项目背景整理成 CLAUDE.md：

- 技术栈和版本号

- 三层架构的具体写法（附代码示例）

- 异常处理的统一方式

- 数据库访问的封装类用法

- 五个最容易写错的地方

从那以后，新会话的 Claude Code 直接就是"老员工"状态——不用解释背景，生成的代码风格跟项目高度一致，review 时几乎不用改格式问题。

这个下午花的两个小时，之后每周帮我省下至少半天。

而且还有个隐藏收益：这份 CLAUDE.md 成了团队的新人入职文档。新同事来了，看一遍 CLAUDE.md，对项目的了解比看三天代码还快。

六、常见坑：写了 CLAUDE.md 但不生效

坑 1：改了文件，但当前会话不生效

CLAUDE.md 是在会话启动时加载的。你改了它，当前正在进行的会话不会自动重读。解决：重启会话（退出重进，或开新会话）。

坑 2：文件放错位置

CLAUDE.md 必须在项目根目录（或者你启动 claude 命令的目录）。放错位置它找不到，自然不生效。确认一下：ls CLAUDE.md 能列出文件，就对了。

坑 3：写得太啰嗦

CLAUDE.md 不是越详细越好。写 500 行的规则文件，AI 读起来也费劲，而且重要信息会被淹没。核心原则：只写"AI 不可能自己知道"的信息——项目背景、团队约定、特殊规范。通用编程常识不用写。

坑 4：和代码冲突

如果 CLAUDE.md 里写的规范和实际代码不一致（比如写了"禁止字符串拼接 SQL"，但代码里全是拼接），AI 会困惑。保持记忆文件与代码现状同步，或者明确标注"历史代码存在违规，新代码必须遵守规范"。

七、总结

Claude Code 的"记忆"机制就两板斧：

1. CLAUDE.md：项目级记忆，写清楚技术栈、目录、规范、注意事项——新会话秒变老员工

2. memory 规则：全局记忆，放个人偏好和通用习惯——所有项目都生效

用好了这两个，你的 Claude Code 从"每次都要重新认识的陌生人"变成"熟悉你所有项目的老同事"。省下的不只是解释时间，还有沟通成本——AI 更懂你，产出的代码更贴合你的预期，review 返工也少。

最后再强调一次：CLAUDE.md 值得你花两小时认真写。它不只是给 AI 看的，也是给团队新人和未来的自己看的。一份好的 CLAUDE.md，是项目知识沉淀的起点。

---

*下一篇：Claude Code Subagent 并行——一条命令拆 10 个任务同时干，效率直接拉满。*