📰 来源: 博客园
这是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 Code 的"项目交接文档"。
打个比方：新同事入职，你会给他一份入职文档——项目目标、技术栈、代码结构、日常命令、编码规范，全写清楚。
CLAUDE.md 就是这份文档。 只不过这位“同事”是 Claude Code，能力出众但经常失忆。所以每次任务前，都需要它先把文档读一遍。
把它放在项目根目录，Claude Code 每次启动会话时都会自动读取。技术栈、规范、命令、约定，一次性写进去——从此再也不用每次对话都从头教一遍。
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，写少了相当于没写。
“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 默认不知道，但一旦告诉它，它就会乖乖用。
“编译：mvn clean compile”“运行测试：mvn test”“本地启动：mvn spring-boot:run”。Claude 可以在执行任务时主动运行这些命令，提前知道它们能省很多解释时间。
比如“订单状态流转不要
🔗 原文链接: 点击阅读原文
文章评论