一个文件让 Claude Code 理解你的项目：CLAUDE.md 从入门到精通

很多人装完 Claude Code 就直接用了。然后发现 AI 生成的代码风格跟项目完全不搭------你项目里用构造器注入，它偏写 @Autowired；你时间字段用 LocalDateTime，它总写 Date；你禁止 BeanUtils.copyProperties，它每次都给你搞上去。

每次都要在 Prompt 里重复说"别用 @Autowired""用 LocalDateTime"，说多了就烦了。

其实根本不需要。你项目根目录有个 CLAUDE.md，Claude Code 每次启动对话都会先读它。把这个文件写好，上面这些问题全部自动消失。

CLAUDE.md 到底干什么的

你可以把它理解成"新同事入职手册"------只不过这个同事是 AI。

每次你跟 Claude Code 开始对话，它做的第一件事就是读 CLAUDE.md。里面写了什么技术栈、什么编码规范、什么目录结构，它就会按这些来生成代码。里面写了禁止什么，它就会避开。

没有 CLAUDE.md 的 Claude Code，能力很强但对你项目一无所知。有 CLAUDE.md，它生成的代码风格跟你手写的基本一致。

我从实际使用中感受到的区别：有 CLAUDE.md 比没有，代码生成的一次通过率大概高了一倍。因为你不用每次纠正它了。

最快的方式：让 AI 自己生成

在项目目录下执行：

bash 复制代码

/init

Claude Code 会自动扫描你的项目，生成一个初始的 CLAUDE.md。内容包括它能识别出来的技术栈、目录结构、构建命令。

但这个自动生成的只是"骨架"------它知道你的 pom.xml 里有什么依赖，但你团队的编码规范它猜不出来。所以 /init 只是第一步，后面需要你手动补充规范部分。

一个可以直接抄的模板

下面是一个 Java Spring Boot 项目的完整 CLAUDE.md。你把里面的包名、技术栈、具体规范换成自己项目的就行：

csharp 复制代码

# Admin Service（后台管理系统）

## 技术栈
- Java 17 + Spring Boot 3.2.x
- MyBatis-Plus 3.5.x + MySQL 8.0
- Redis 7.x（Lettuce 客户端）
- Nacos 2.3.x（配置中心 + 注册中心）
- Maven 3.9.x
- 工具库：Lombok、Hutool、MapStruct

## 目录结构
src/main/java/com/company/admin/
├── controller/     # REST 接口层
├── service/        # 业务接口
├── service/impl/   # 业务实现
├── mapper/         # MyBatis Mapper
├── entity/         # 数据库实体
├── dto/            # 数据传输对象
├── config/         # Spring 配置
├── common/         # 公共工具、异常定义
│   ├── Result.java        # 统一返回
│   ├── PageResult.java    # 分页返回
│   ├── BusinessException.java
│   └── ErrorCode.java     # 错误码枚举
└── AdminApplication.java

## 编码规范

### 命名
- 类名大驼峰（UserController），方法名小驼峰（getUserById）
- 数据库字段下划线（create_time），Java 字段小驼峰（createTime）
- DTO 以功能结尾：SaveDTO、UpdateDTO、QueryDTO、VO

### 依赖注入
- 禁止 @Autowired 字段注入
- 使用构造器注入，配合 Lombok @RequiredArgsConstructor

### 异常处理
- 业务异常统一抛 BusinessException，传 ErrorCode 枚举
- Controller 层不要 try-catch，由 @ControllerAdvice 统一处理
- catch 块必须记日志（log.error），并传入异常对象
- 禁止吞异常

### 日志规范
- 使用 Lombok @Slf4j
- 格式：log.info("[操作名] 参数1={}, 参数2={}", value1, value2)
- 关键操作必须包含业务标识（订单号、用户 ID）
- 密码、手机号、身份证禁止打印或必须脱敏

### 安全规范
- 用户输入必须校验（@Valid + 自定义校验器）
- SQL 用 #{} 参数化，禁止 ${} 拼接（ORDER BY 除外且要有白名单）
- 密码用 BCrypt 加密存储

## 其他约定
- 时间字段用 LocalDateTime，不要用 Date
- BigDecimal 用 BigDecimal.valueOf()，不要用 new BigDecimal()
- 集合为空返回 Collections.emptyList()，不要返回 null
- 不要用 BeanUtils.copyProperties，用 MapStruct

## 常用命令
mvn spring-boot:run -Dspring-boot.run.profiles=dev  # 启动开发环境
mvn test -pl admin-service                            # 运行测试
mvn clean install -DskipTests                         # 编译打包

如果你做的是前端项目，对应的 CLAUDE.md 就写 React/Vue 版本、组件规范、Hooks 规则、CSS 方案。Python 项目就写 Python 版本、类型注解要求、async/await 规范、日志库选择。思路是一样的。

怎么写最有效

一条规则一句话。别写长段落，AI 抓重点的时候效率会下降。每条规则简单直接：

diff 复制代码

- 禁止 @Autowired 字段注入
- 时间字段用 LocalDateTime，不要用 Date
- 异常不能吞，必须 log.error 并传入异常对象

这种格式最好。AI 一眼就能看到明确的约束。

写你最常纠正的东西。不要试图一次写出一个"完美的 CLAUDE.md"。看看你最近几次对话，最常纠正 Claude 的是什么，把这些先写进去。其他的慢慢补。

别写太多。超过 500 行的话，对话开始时可能会被截断。只保留最核心的规则，次要的看情况再说。

最重要的使用习惯

Claude 犯错之后立刻更新 CLAUDE.md。

这条太重要了所以单独说。每次 Claude Code 生成的代码不符合你预期，别说"算了下次注意"------直接在对话里说：

markdown 复制代码

> 把这条规则记到 CLAUDE.md 里

Claude 会自动更新文件。这个习惯养成了，它犯的错会越来越少。

我现在的 CLAUDE.md 里大部分规则都不是一次写完的，是用了几周逐渐积累出来的------每次它犯一个错我就加一条，慢慢地它就基本不犯错了。

放在 Git 里

CLAUDE.md 应该随代码一起提交，整个团队共享。新同事入职流程变成：

拉代码 → 装 Claude Code → 直接能用（AI 自动遵循团队规范）

省去老同事口头的"注意啊我们这里是这样写的"。这大概是最省力的团队规范推广方式了。

举个例子

假设你的 CLAUDE.md 写了"禁止 @Autowired 字段注入，用构造器注入"。

没有 CLAUDE.md 的时候，你让 AI 生成一个 Service 实现类，它大概率写：

java 复制代码

@Service
public class UserServiceImpl implements UserService {
    @Autowired
    private UserMapper userMapper;    // 你每次都要改
}

有 CLAUDE.md 之后，同样 Prompt，它生成：

less 复制代码

@Service
@RequiredArgsConstructor
public class UserServiceImpl implements UserService {
    private final UserMapper userMapper;    // 自动符合规范
}

就是这种差别。少改一行代码看起来不多，一天积累几十次要改的地方就很烦了。

总结

在项目根目录执行 /init，得到骨架
把你团队的编码规范加进去，一条规则一句话
每次 AI 犯错就说"记到 CLAUDE.md 里"
放在 Git 里团队共享
控制在 500 行以内

花一小时写一个好 CLAUDE.md，之后每次对话都受益------这大概是你学 Claude Code 投入产出比最高的一件事。

下一篇讲 Claude Code 的 10 个必学斜杠命令。这些命令用熟了，你用 Claude Code 的效率至少再提一倍。