设想一下，每天早晨抵达办公室，你都需要耗费整整10分钟，向新加入的同事从头到尾解释项目的技术栈——"我们用的是Spring Boot还是Spring Cloud？Maven该怎么配置？代码分层规范又是什么？"说实话，这听起来确实有些荒谬。其实，只需一份文档就能解决所有问题。

没错，CLAUDE.md就是你写给Claude Code的那份专属使用指南。

Claude Code本身是"无状态"的。每次你启动一个新的会话，它对你项目的了解程度几乎为零。如果没有CLAUDE.md，你必须在每次对话中不厌其烦地重复相同的背景信息——"我们这个项目是什么、技术栈有哪些、代码结构长什么样"……但有了它呢？Claude在正式开始工作之前，就已经把你的技术栈、代码规范、项目结构了解得一清二楚，直接就能进入高效协作模式。

更关键的是，CLAUDE.md的强大之处在于——它是你整个配置体系中"杠杆效应最高的那个环节"。它会被自动加载到每一次对话中，影响Claude的每一个决策。你花时间把这个文件打磨好，就相当于给你的AI搭档做了一次全面、系统、彻底的入职培训。

一、CLAUDE.md 到底是什么

简单来说，CLAUDE.md就是一个采用Markdown格式的文本文件。Claude Code在每次会话启动时，会自动读取它的内容，并将其作为上下文的一部分注入到对话中。你无需手动引用它，甚至不需要在对话里提及它——它就像一个24小时在线、永不掉线的项目说明书。

一句话概括它的定位：

它和其他配置的关系

Claude Code的配置体系并不只有CLAUDE.md这一个层级。理解它们各自的分工，才能把正确的内容放到正确的位置：

graph TDA["CLAUDE.md
每次会话自动加载
项目级上下文"] --> B["Skills (.claude/skills/)
按需加载
领域知识与工作流"]A --> C["Hooks (settings.json)
确定性执行
工具调用时触发脚本"]A --> D["Settings (settings.json)
权限与行为配置
工具许可/拒绝列表"]classDef primary fill:#1A9090,stroke:#1A9090,color:#fffclassDef secondary fill:#2d2d2d,stroke:#1A9090,color:#e0e0e0class A primaryclass B,C,D secondary

关键的区分原则如下：

• 普遍适用的指令 → 放入CLAUDE.md
• 特定场景的知识 → 放入Skills
• 必须执行的动作 → 放入Hooks
• 工具权限控制 → 放入Settings

文件放在哪里

CLAUDE.md并不只有一个固定的存放位置，它支持多个层级，从全局到局部，形成一个完整的体系：

Claude Code会自动合并这些层级的内容。在多模块Maven项目中，这种层级机制尤其实用——你可以在根目录放置通用规范，在各子模块目录存放模块特有的说明。

二、应该写什么：WHAT-WHY-HOW 框架

一份优质的CLAUDE.md，本质上需要回答三个核心问题：项目是什么（WHAT），为什么这么做（WHY），以及如何在项目中开展工作（HOW）。

2.1 WHAT —— 告诉 Claude 项目的技术地图

这部分的作用是让Claude快速掌握项目的技术栈和代码结构。

# 项目概述这是一个基于 Spring Boot 3.2 + Ja va 21 的电商订单管理系统。# 技术栈- 框架: Spring Boot 3.2- 语言: Ja va 21- 构建工具: Ma ven 3.9- 数据库: MySQL 8.0 + MyBatis-Plus- 缓存: Redis (Lettuce)- 消息队列: RocketMQ- 测试: JUnit 5 + Mockito# 项目结构 (标准分层架构)- src/main/ja va/com/acme/order/- controller/ - REST 接口层- service/- 业务逻辑层- service/impl/ - 业务逻辑实现- mapper/ - MyBatis 数据访问层- model/- entity/ - 数据库实体- dto/- 数据传输对象- vo/ - 视图对象- config/ - 配置类- common/ - 公共工具和常量

2.2 WHY —— 解释关键的设计决策

这部分需要阐明那些"不看说明就会踩坑"的设计决策。Claude最需要的往往不是"该怎么做"，而是"为什么这样做"。

# 设计决策- 使用 MyBatis-Plus 而非 JPA/Hibernate原因：团队更熟悉 SQL 优化，MyBatis-Plus 提供灵活的 SQL 控制能力- 所有接口返回统一响应体 Result<T>，不直接返回实体原因：前后端约定统一的数据格式，便于全局异常处理- 分布式 ID 使用雪花算法 (Snowflake)，不使用数据库自增原因：分库分表场景下保证 ID 全局唯一且有序

2.3 HOW —— 告诉 Claude 怎么干活

这部分就是Claude真正"动手"时需要的操作手册。

# 常用命令- 编译打包: `mvn clean package -DskipTests`- 运行全部测试: `mvn test`- 运行单个测试类: `mvn test -Dtest=OrderServiceTest`- 本地启动: `mvn spring-boot:run -Dspring-boot.run.profiles=dev`- 代码格式化: `mvn spotless:apply`- 依赖检查: `mvn dependency:tree`# 代码规范- Controller 层只做参数校验和结果封装，不写业务逻辑- Service 接口和实现分离，接口放 service/ 包，实现放 service/impl/ 包- 所有数据库实体继承 BaseEntity（包含 id, createTime, updateTime）- 方法命名: findXxx / sa veXxx / updateXxx / removeXxx- 提交信息遵循 Conventional Commits 规范# Git 工作流- 分支命名: feature/xxx, fix/xxx, chore/xxx- 提交前必须通过编译和 checkstyle 检查

三、怎么写才好：六条黄金法则

法则一：保持精简，控制在 200 行以内

这是最为关键的一条法则。CLAUDE.md的每一行都会被注入到对话上下文中，占用宝贵的token预算。

相关研究表明，前沿LLM能够可靠遵循的独立指令数量，大约在150到200条之间。Claude Code的系统提示已经包含了约50条指令，留给你CLAUDE.md的"指令预算"其实相当有限。

判断标准是这样的：对每一行内容，你都要问自己——"如果删掉这行，Claude会犯错吗？"如果答案是"不会"，那就果断删除。

法则二：用引用拆分文档，而非塞进一个文件

CLAUDE.md支持通过 @ 语法引用其他文件，实现一种"渐进式披露"的效果：

# 项目指南@README.md@docs/architecture.md@docs/database-design.md@docs/api-conventions.md

Claude会在需要时才主动去读取这些文件，而不是每次对话都加载全部内容。这样一来，你的CLAUDE.md可以保持精简，同时Claude又能在需要时获取到详细信息。

法则三：用工具约束格式，而非用指令

这是一个常见的误区——在CLAUDE.md里堆砌大量的代码风格规则：

# 不推荐- 缩进使用 4 个空格- 左大括号不换行- 类名使用 PascalCase- 常量使用 UPPER_SNAKE_CASE- import 语句按包名排序

但别忘了，Claude不是代码检查工具。这些规则应该交给Checkstyle、Spotless、SonarLint等工具去强制执行，而在CLAUDE.md里只需要写一句：

# 代码风格代码提交前会自动运行 `mvn spotless:apply`，无需手动关注格式问题。

如果你非要确保Claude每次提交前都执行格式化，那就应该用Hooks，而不是用CLAUDE.md的指令。

法则四：对关键规则使用强调语法

当某条规则特别重要时，可以用大写或强调标记来提高Claude的遵循率：

IMPORTANT: 所有数据库操作必须通过 MyBatis-Plus 的 Mapper 接口，禁止在 Service 层拼接 SQL 字符串。IMPORTANT: 不要修改 src/main/ja va/com/acme/order/generated/ 目录下的任何文件，这些是 MyBatis Generator 自动生成的代码。

Anthropic官方建议使用"IMPORTANT"、"YOU MUST"、"NEVER"这类强调词来提高指令遵循度。但不要滥用——如果每条规则都标注为"重要"，那就等于没有重要的规则。

法则五：记录"坑"和"怪癖"

项目中总有一些违反直觉的设计或已知的陷阱，这些才是CLAUDE.md最有价值的内容：

# 注意事项- 权限校验通过自定义注解 @RequirePermission 在 AOP 中统一处理如果要新增需要权限的接口，只需在 Controller 方法上加注解即可- 测试环境使用 H2 内存数据库，配置在 application-test.yml 中运行测试前不需要启动外部数据库- legacy/ 包下的代码正在迁移中，新功能不要引用这个包

法则六：像维护代码一样维护 CLAUDE.md

CLAUDE.md不是写一次就完事的文件。随着项目演进，你要定期审查和更新它：

• 发现Claude反复犯同一个错误 → 加一条规则
• 发现Claude忽略了某条规则 → 检查文件是否太长导致规则"被淹没"
• 项目技术栈变更 → 及时更新

一个很好的实践是：在日常使用中，每当你发现自己在对话中反复解释某件事，就按 # 键把它加入CLAUDE.md。久而久之，这个文件会真正反映出你团队实际的工作方式。

四、一个完整的实战示例

下面是一个真实项目级别的CLAUDE.md参考模板，大约60行，涵盖了最核心的信息：

# 项目概述这是 Acme 公司的内部订单管理系统，基于 Spring Boot 3.2 + Ja va 21。# 技术栈- Spring Boot 3.2, Ja va 21, Ma ven 3.9- 数据库: MySQL 8.0 + MyBatis-Plus 3.5- 缓存: Redis (Spring Data Redis + Lettuce)- 消息: RocketMQ 5.x- 测试: JUnit 5 + Mockito + H2# 常用命令- 编译: `mvn clean compile`- 打包: `mvn clean package -DskipTests`- 全部测试: `mvn test`- 单个测试: `mvn test -Dtest=OrderServiceTest`- 本地运行: `mvn spring-boot:run -Dspring-boot.run.profiles=dev`- 格式化: `mvn spotless:apply`- 依赖树: `mvn dependency:tree`# 项目结构 (com.acme.order)- controller/ - REST 接口，只做参数校验和结果封装- service/- 业务接口定义- service/impl/ - 业务逻辑实现- mapper/ - MyBatis 数据访问层- model/entity/ - 数据库实体 (继承 BaseEntity)- model/dto/- 请求/响应数据传输对象- model/vo/ - 视图对象- config/ - Spring 配置类- common/ - 工具类、常量、统一响应体 Result<T># 代码规范- Controller 不写业务逻辑，Service 接口与实现分离- 所有接口返回 Result<T> 统一响应体- 方法命名: findXxx / sa veXxx / updateXxx / removeXxx- 提交信息遵循 Conventional Commits# 详细文档@docs/architecture.md@docs/database-design.md@docs/deployment.md# Git 工作流- 分支: feature/xxx, fix/xxx, chore/xxx- PR 必须通过 CI 检查后才能合并# 注意事项IMPORTANT: 数据库操作通过 MyBatis-Plus Mapper，禁止拼接 SQL 字符串IMPORTANT: generated/ 包是自动生成的，不要手动修改- legacy/ 包下的代码正在迁移，新功能不要依赖- 环境变量在 application-dev.yml 中说明，敏感配置走 Nacos- 分布式 ID 使用雪花算法，不要用数据库自增 ID

五、从 /init 开始，但不要止步于此

如果你的项目还没有CLAUDE.md，最快的起步方式是在项目目录下运行 /init 命令。Claude会自动分析你的项目结构、读取pom.xml等配置文件，生成一份初始的CLAUDE.md。

但一定要注意：/init 生成的只是一个起点。它能捕捉到明显的模式，但可能会遗漏你团队特有的工作流程和约定。真正有价值的CLAUDE.md，是在日常使用中逐步打磨出来的。

graph LRA["运行 /init
生成初始文件"] --> B["日常使用
发现重复解释的内容"]B --> C["添加到 CLAUDE.md"]C --> D["定期审查
删除过时内容"]D --> BclassDef step fill:#1A9090,stroke:#1A9090,color:#fffclass A,B,C,D step

六、总结

写好CLAUDE.md的核心思路，其实可以归纳为三句话：

1. 写对的内容：用WHAT-WHY-HOW框架覆盖项目的技术地图、设计决策和操作手册
2. 控制好篇幅：200行以内，用 @ 引用拆分详细文档，把格式校验交给工具
3. 持续迭代：像维护代码一样维护它，让它真实反映团队的工作方式

CLAUDE.md本质上是你和AI之间的一份契约——你告诉它项目的规则和边界，它在这个框架内高效地帮你完成工作。花30分钟写好这份"契约"，能为你节省未来无数次重复解释的时间。