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

laude 很快给出了一段代码。你扫了一眼，眉头就皱起来了——它用了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 有什么区别？

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引入外部文档，避免重复。