问题场景

很多开发者装完 Claude Code 后直接开始用，然后发现 AI 生成的代码风格跟项目不一致——用 @Autowired 代替构造器注入、时间字段用 Date 而不是 LocalDateTime、使用 BeanUtils.copyProperties 而项目规范要求 MapStruct。

每次都要在 Prompt 里重复纠正这些问题，效率很低。

根本原因：项目缺少一个 CLAUDE.md 文件。

什么是 CLAUDE.md

CLAUDE.md 是放在项目根目录下的项目说明文件，Claude Code 每次启动对话时自动读取。它定义了：

• 项目的技术栈和版本
• 目录结构和分层约定
• 编码规范和禁止项
• 常用的构建和测试命令

有 CLAUDE.md 的 Claude Code，其代码生成符合项目规范的概率远高于没有的情况。

快速生成

在项目目录下执行：

/init

Claude Code 会自动扫描项目（pom.xml、目录结构等），生成一个包含技术栈、依赖、目录结构的基础 CLAUDE.md。

但自动生成的内容仅限于它可以识别的技术信息，无法覆盖团队的编码习惯。需要手动补充规范部分。

完整模板（Java Spring Boot）

# 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）
- Controller 以 Controller 结尾
- Service 接口以 Service 结尾，实现类以 ServiceImpl 结尾
- Mapper 接口以 Mapper 结尾
- DTO 以功能结尾（SaveDTO、UpdateDTO、QueryDTO、VO）

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

### 异常处理
- 业务异常统一抛 BusinessException（传入 ErrorCode 枚举）
- Controller 层不要 try-catch
- 统一由 @ControllerAdvice GlobalExceptionHandler 处理
- 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                         # 编译打包

维护原则

一条规则一句话

AI 在解析 CLAUDE.md 时更倾向于识别明确的短约束，而非长段落描述。每条规范一行为最佳。

好的格式：

• 禁止 @Autowired 字段注入
• 时间字段用 LocalDateTime，不要用 Date

先写最常纠正的内容

查看最近对话中纠正 AI 频率最高的问题，优先写入。

控制在 500 行以内

CLAUDE.md 过长可能被截断，只保留最核心的规范。

渐进式完善

每次 Claude Code 生成的代码不符合预期时，在对话中说"把这条规则记到 CLAUDE.md 里"，AI 会自动更新文件。持续使用后，AI 的低级错误将越来越少。

团队协作

将 CLAUDE.md 纳入 Git 版本管理，团队成员共享同一份规范。新成员配置好 Claude Code 后，AI 自动遵循团队规范，减少培训沟通成本。

示例对比

无 CLAUDE.md 时的输出：

@Service
public class UserServiceImpl implements UserService {
    @Autowired
    private UserMapper userMapper;    // 使用字段注入
}

有 CLAUDE.md 后的输出：

@Service
@RequiredArgsConstructor
public class UserServiceImpl implements UserService {
    private final UserMapper userMapper;    // 构造器注入
}

总结

1. CLI 执行 /init 生成基础版本
2. 补充团队编码规范，一条规则一句话
3. AI 犯错过时直接更新
4. 纳入 Git 团队共享
5. 文件控制在 500 行以内

写一份好的 CLAUDE.md 是所有 Claude Code 配置中投入产出比最高的工作。

---

下一篇：Claude Code 10 个必学斜杠命令详解。