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.2Java 21MyBatis-Plus批量操作用batchQuery异常用BusinessException日志用 Lombok 的Slf4j禁止e.printStackTrace()禁止System.out……Claude 说好的我使用以上规范完成功能。但你知道下一次启动它什么都不会记得。问题出在哪里Claude Code 每次启动都是一个全新的会话它看不到你上个会话里敲过的约定也读不懂你的pom.xml、application.yml和代码里的Service注解。它就像一个每天第一次来上班的新人你必须从零开始教它我们的项目叫 xxx用的是 Java 21Spring 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”“返回值用ResultT包装”“字段命名禁用下划线”。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 - 不要自动 pushcommit 后等我确认 ## 回答偏好 - 直接给解决方案减少铺垫 - 代码修改时说明为什么改不只是改成什么 - 有多种方案时列出优劣对比让我选择进阶二Auto MemoryClaude Code自己的笔记Claude Code 存在一个功能叫Auto Memory自动记忆的功能。它跟 CLAUDE.md 互补CLAUDE.md你写给 Claude 的指令你必须遵守这些规范Auto MemoryClaude 自己记的笔记我发现这个项目有个坑……存储位置~/.claude/projects/项目名/memory/你可以通过/memory命令直接编辑MEMORY.md文件也可以通过交互式命令让Claude Code记住某些事情记住这个项目的测试数据库连接串是 jdbc:mysql://test-db:3306/order那 CLAUDE.md 和 MEMORY.md 有什么区别CLAUDE.mdMEMORY.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 到底听了哪些话”的好方法。进阶四维护策略最小集起步只写技术栈、项目特有工具、最常踩的坑。痛点驱动别预想完美。定期审计每月检查过时/无用/冗余规则。用/init对比生成草稿。当索引不当百科放指向详细文档的引用如docs/api.md具体规范拆到.claude/rules/。防止膨胀三招超过 200 行就拆分到rules/用paths限定规则生效范围零散偏好交给 Auto Memory/memoryinclude复用用path/to/file引入外部文档避免重复。