Claude Code通关手册（三）：CLAUDE.md深度实战

这是Claude Code通关手册的第三篇，在上一篇中，我们搞定了权限设置，让Claude Code安全可控地访问你的文件。今天，我们将更进一步------用CLAUDE.md赋予它长期记忆，彻底告别每次对话都要重复交代技术栈的烦恼。

我来描述一个场景，你看有没有中过招------

周一早上，你打开终端，启动 Claude Code，想赶紧收尾上周遗留的功能，你输入：为 OrderService 增加一个批量查询订单的方法，根据订单 ID 列表批量返回订单详情。

Claude 很快给出了一段代码。你扫了一眼，眉头就皱起来了------它用了 ArrayList 的 for 循环 + 单条 SQL，一条一条查。而你们项目里明明已经封装好了 batchQuery()。

你打字纠正：用 batchQuery()，不要手写循环查数据库。

Claude 回复：好的，我改用 batchQuery()。 然后重新生成代码------这次又忘了你们约定的异常处理规范：不要吞掉异常，也不要直接 e.printStackTrace()，而是要用 log.error 并抛出业务异常。

你补充：异常用 BusinessException 包装，日志用 @Slf4j 的 log，别用 System.out。

来回四五个回合，十分钟过去了。代码终于勉强能跑了。你长舒一口气，总算完成了。

周二，你打开一个新的终端窗口，启动 Claude Code，输入几乎相同的需求：给 UserService 加一个批量查询用户的方法。

Claude 再次给出了那个"标准答案"------手写 for 循环 + 单条 SQL，没有批量工具，没有异常包装，没有日志规范。

你深吸一口气，又开始敲：用 batchQuery，异常用 BusinessException，日志用 log......

周三，你开始怀疑自己是不是陷入了一个时间循环。明明昨天才教过它，今天又忘了。

周四，你甚至还没等 Claude 把代码生成完，就直接打断它：使用Spring Boot 3.2，Java 21，MyBatis-Plus，批量操作用 batchQuery，异常用 BusinessException，日志用 Lombok 的 @Slf4j，禁止 e.printStackTrace()，禁止 System.out......

Claude 说：好的，我使用以上规范完成功能。

但你知道，下一次启动，它什么都不会记得。

问题出在哪里？Claude Code 每次启动都是一个全新的会话，它看不到你上个会话里敲过的约定，也读不懂你的 pom.xml、application.yml 和代码里的 @Service 注解。它就像一个每天第一次来上班的新人，你必须从零开始教它：我们的项目叫 xxx，用的是 Java 21，Spring Boot 版本是......

直到有一天，你发现了 CLAUDE.md。

你只需在项目根目录创建一个 CLAUDE.md 文件，把那些每周重复了无数遍的话写进去，从此，Claude 每次启动都会自动读取这个文件。它打开你的项目，就像翻开一本写满习惯的笔记本------框架版本、工具类、异常处理、日志规范，全在里面。

今天这篇文章，我彻底将它讲透。

一句话讲明白：CLAUDE.md是什么？

CLAUDE.md 是写给 Claude Code 的"项目交接文档"。

打个比方：新同事入职，你会给他一份入职文档------项目目标、技术栈、代码结构、日常命令、编码规范，全写清楚。

CLAUDE.md 就是这份文档。 只不过这位"同事"是 Claude Code，能力出众但经常失忆。所以每次任务前，都需要它先把文档读一遍。

把它放在项目根目录，Claude Code 每次启动会话时都会自动读取。技术栈、规范、命令、约定，一次性写进去------从此再也不用每次对话都从头教一遍。

CLAUDE.md 放在哪里，区别很大。

Anthropic 设计了四层配置，从个人习惯到项目规范，层层递进：

1. 用户根目录：~/.claude/CLAUDE.md

存放你的个人偏好------比如用中文回复，代码注释用英文，commit 信息遵循 Conventional Commits。所有项目都会继承这些设定，相当于 Claude 对你的基本认知。

2. 项目根目录：/your-project/CLAUDE.md

存放当前项目的技术栈、编码规范、常用命令。比如Java 21 + Spring Boot 3.2，日志使用 lombok，异常用 BusinessException。Claude 在这个项目里干活时会自动遵守。

3. 项目根目录：/your-project/CLAUDE.local.md
项目级的个人偏好，不提交 Git （记得加 .gitignore）。比如你在某个项目里有自己的调试习惯、本地特殊配置。Claude 会把它和 CLAUDE.md 合并，且优先级更高------适合放"只有你需要、不想影响同事"的内容。

4. 子目录：/your-project/src/legacy/CLAUDE.md

用于局部例外，渐进式披露，需要时才加载。比如老模块不想按新规范重构，就在这个文件夹里放一份补充指令，告诉 Claude "这里只修 bug，不要动结构"。

加载顺序 ：用户级 → 项目级（CLAUDE.md）→ 项目级本地（CLAUDE.local.md）→ 子目录级。后面的覆盖前面的冲突项。

你只需要花十分钟把这几层写清楚，之后 Claude 无论在你哪个项目的哪个角落干活，都不会再问那些让你血压升高的问题。

该写什么？不该写什么？

CLAUDE.md 不是项目说明书，是给 AI 的"行动准则"，写多了浪费token，写少了相当于没写。

该写什么 ✅

1. 技术栈和版本号

"Java 21、Spring Boot 3.2、MyBatis-Plus 3.1.0"就够了，不用把 Spring 文档抄一遍。Claude 知道这些框架怎么用，它只需要知道"你要我用哪个版本"。

2. 编码规范的"关键差异点"

不用把Java风格指南或阿里巴巴 Java 手册抄进去------Claude 已经背过了。你只需要写那些和通用规范不一样的地方 ：比如"禁止 e.printStackTrace()，统一抛 BusinessException"，"返回值用 Result<T> 包装"，"字段命名禁用下划线"。

3. 封装好的工具类和常用方法

"批量查询用 JDBCTemplate.batchQuery()、缓存用 CacheService.getOrLoad()、日志用 @Slf4j 的 log"。

这些是你们项目独有的东西，Claude 默认不知道，但一旦告诉它，它就会乖乖用。

4. 常用命令

"编译：mvn clean compile""运行测试：mvn test""本地启动：mvn spring-boot:run"。Claude 可以在执行任务时主动运行这些命令，提前知道它们能省很多解释时间。

5. 项目特有的坑

比如"订单状态流转不要直接改状态字段，要调用 OrderService.transferStatus()，用户 ID 从 UserContextHolder 获取，不要从参数传"。

这些历史的教训写进去，Claude 会帮你避坑。

不该写什么？❌

1. 通用知识

"Spring Boot 怎么配置数据源，Java 的 Optional 怎么用"

这些 Claude 比你熟。写进去就是浪费 token，还会让真正重要的指令被淹没。

2. 频繁变动的内容

比如"当前迭代的需求文档，临时测试环境的 IP 地址"。

这些东西今天写了明天就得改，而 CLAUDE.md 不是给你天天改的。变动的信息应该放在每次对话里直接告诉 Claude。

3. 冲突的指令

"用 BatchUtils 做批量查询" 和 "优先使用 MyBatis-Plus 的 selectBatchIds" 不要同时出现。Claude 会困惑，然后随机选一个------你又要回来改。

4. 语气模糊的要求

"代码尽量写得优雅一点""性能要足够好"

这种话对 AI 没用。换成具体的："批量操作超过 1000 条要分页处理，单个方法行数不超过 80 行"。

核心思路：想象你给一个高级工程师写一份项目的交接文档，他什么都会，只是还不了解这个项目的情况，你只需要写特殊情况，不需要教他基础知识。

经验法则：控制在 100-200 行以内。 研究表明，AI模型能够稳定遵循约150-200条指令。一旦超出这一范围，指令的遵循率便会显著下降。因此，与其撰写一篇面面俱到的万字长文，不如创作一份精炼而每条都颇具分量的指南。

完整实操，为项目编写CLAUDE.md

分析项目，生成初稿

进入项目目录下启动Claude Code并输入

分析这个项目的完整结构，帮我生成一份 CLAUDE.md 初稿，  
包括项目概述、技术栈、目录结构、编码规范和常用命令

或者有个更简单的操作，Claude Code 内置了一个命令：

/init

这个命令会扫描你的项目，并生成一份CLAUDE.md初稿。

手动补充，形成终稿

Claude Code生成的CLAUDE.md仅作为初稿参考，项目中特定的编码规范、技术约束、团队约定以及已发现的技术难点，都需要我们手动补充并持续完善。

效果测试

完成 CLAUDE.md 文件编写后，请开启一个全新的会话 进行测试。现在请输入以下内容：为 OrderService 添加一个根据订单ID查询订单详情的方法，并实现缓存功能。

此时你无需额外说明，Claude Code 将自动识别项目使用 MyBatis-Plus 框架，并采用 Redis 进行缓存处理。

这就是 CLAUDE.md 的魔力------一次编写，每次会话自动生效。

进阶一：全局配置，个人偏好

除了项目级别的CALUDE.md外，你还应该有一份全局的~/.claude/CLAUDE.md,他定义你在所有项目中通用的偏好。

下面是一个全局的CLAUDE.md，可以参考使用

## 语言和沟通  
- 用中文回答问题和写注释  
- 代码中的变量名、函数名、commit message 用中文
- 解释技术概念时优先用类比和例子  
  
## 代码风格  
- 缩进：2 个空格  
- 引号：单引号（字符串）  
- 命名导入优先于默认导入  
  
## Git 习惯  
- commit message 格式：type(scope): description  
- 不要自动 push，commit 后等我确认  
  
## 回答偏好  
- 直接给解决方案，减少铺垫  
- 代码修改时说明"为什么"改，不只是"改成什么"  
- 有多种方案时列出优劣对比，让我选择

进阶二：Auto Memory，Claude Code自己的笔记

Claude Code 存在一个功能叫 Auto Memory（自动记忆） 的功能。它跟 CLAUDE.md 互补：

• CLAUDE.md：你写给 Claude 的指令（"你必须遵守这些规范"）

• Auto Memory：Claude 自己记的笔记（"我发现这个项目有个坑......"）

存储位置：~/.claude/projects/<项目名>/memory/

你可以通过/memory命令直接编辑MEMORY.md文件，也可以通过交互式命令让Claude Code记住某些事情

记住这个项目的测试数据库连接串是 `jdbc:mysql://test-db:3306/order`

那 CLAUDE.md 和 MEMORY.md 有什么区别？

CLAUDE.md	MEMORY.md
技术栈、编码规范、常用命令	零散偏好、调试经验、日常发现
手动编辑	自动捕捉
团队共享	个人专属

Auto Memory 不会让 Claude 一夜之间变成项目专家，但它解决了一个很细碎但很烦人的痛点------重复解释。你用得越久，它记住的越多，你每次启动需要交代的就越少。

进阶三：.claude/rules/模块化规则

聊完了 CLAUDE.md 和 Auto Memory，今天来聊聊 Claude Code 记忆体系里最灵活、最适合团队协作 的一环------.claude/rules/ 模块化规则。

如果你在团队里用过 CLAUDE.md，可能已经碰到过这个问题：文件越来越长，越来越难维护。 技术规范、测试约定、安全要求、API 设计准则......全都挤在一个文件里，改一行要找半天，还经常误伤其他内容

简单说，就是把 CLAUDE.md 拆成多个小文件，按主题分开管理。

你只需要在项目根目录下创建 .claude/rules/文件夹，然后把规则文件放进去。Claude 会自动读取里面所有的 .md 文件。

目录结构：

your-project/
├── .claude/
│   ├── CLAUDE.md          # 总纲（可选）
│   └── rules/
│       ├── code-style.md    # 代码风格规范
|	    ├── database.md      # 数据库操作规范
|	    ├── exception.md     # 异常处理与日志
|	    ├── transaction.md   # 事务管理规范
|	    ├── legacy.md        # 老模块特别规则（限定路径）
│       ├── testing.md       # 测试规范
│       ├── security.md      # 安全要求
│       ├── api-design.md    # API 设计准则
│       └── git-workflow.md  # Git 工作流规范

每个文件就是一个独立关注点 。需要改代码风格？直接改 code-style.md，不影响其他规则。团队协作时，不同成员可以分别维护自己擅长的规则文件，互不冲突。

内容说明

你只需要把它们放进 .claude/rules/，Claude Code 启动时会自动加载。如果需要只对特定文件生效 ，就在文件顶部加上 paths: 的 YAML frontmatter。

注意 ：paths 支持 glob 模式，也支持 ! 排除。例如：

---
paths:
  - "src/main/java/**/*.java"
  - "!src/main/java/**/legacy/**/*.java"
---

# Java 代码风格规范
1. **类命名**：大驼峰，Service/Controller/DAO 后缀明确
2. **方法长度**：单个方法不超过 50 行，超过必须拆分
3. **依赖注入**：使用构造器注入，禁止 `@Autowired` 字段注入
4. **注释**：所有 public 方法必须有 JavaDoc，描述参数、返回值和异常
5. **IDE 格式化**：使用 Google Java Format 插件，提交前格式化

这个意思是对所有 Java 文件生效，但排除 legacy 包下的文件。

加载顺序

没有 paths 限定的规则文件，会在 Claude Code 启动时无条件加载进系统提示词。

凡是声明了 paths 字段的规则文件，都属于按需加载。 当且仅当 Claude 读取或处理匹配该路径的文件时，相关规则才会被动态加载进上下文。

这是平衡上下文使用、精准控制规则生效范围的关键机制。

团队协作怎么办？

.claude/rules/ 文件夹可以提交到 Git ，整个团队共用。每个人 git pull 后，Claude Code 自动获得最新规则。

如果你有自己的本地偏好（比如测试时连本地数据库），可以创建 .claude/rules.local/（不提交 Git），作用和 .claude/rules/ 一样，但只在你本地生效。

用 /rules 命令查看当前加载的规则

在 Claude Code 会话中，输入 /rules，它会列出当前所有生效的规则文件及其路径限定。这是一个快速检查"Claude 到底听了哪些话"的好方法。

进阶四：维护策略

1. 最小集起步：只写技术栈、项目特有工具、最常踩的坑。痛点驱动，别预想完美。
2. 定期审计 ：每月检查过时/无用/冗余规则。用 /init 对比生成草稿。
3. 当索引，不当百科 ：放指向详细文档的引用（如 @docs/api.md），具体规范拆到 .claude/rules/。
4. 防止膨胀三招 ：
   • 超过 200 行就拆分到 rules/
   • 用 paths 限定规则生效范围
   • 零散偏好交给 Auto Memory（/memory）
5. include 复用 ：用 @path/to/file 引入外部文档，避免重复。
6. 改后必测：每条新规则用一个真实任务验证 Claude 是否理解正确。

核心思想：CLAUDE.md 是长出来的，不是写出来的------自然演进，定期修剪。