用 Claude Code 写 Java 代码，大多数人第一步就做错了。

不是不会用，是根本没配 CLAUDE.md。

没有 CLAUDE.md 的 Claude Code，就像一个第一天入职的新人——聪明，但什么都不知道。它不知道你的项目用 Java 21 还是 Java 17，不知道你的分层规范，不知道哪些写法在你们团队是禁止的。每次生成代码都在猜，猜对了靠运气，猜错了你来改。

配好 CLAUDE.md 之后，感觉像给它塞了一份项目手册。它知道规范，知道边界，知道你们团队的习惯——生成的代码拿来直接能用，不用再花时间对齐风格。

这篇文章，把一份可以直接用的 Java SpringBoot CLAUDE.md 模板完整放出来，每一段说清楚为什么这么写、不写会怎样。

先搞清楚：CLAUDE.md 是什么

CLAUDE.md 是放在项目根目录的一个 Markdown 文件，Claude Code 每次启动都会自动读取它，把里面的内容作为上下文加载进去。

它是项目的记忆系统，让 AI 理解你的项目，并支持自我进化。

简单说，它是你给 Claude Code 写的「项目说明书」，告诉它：

  • 这个项目用什么技术栈

  • 代码要怎么组织

  • 哪些写法是禁止的

  • 遇到问题要怎么处理

一个合理的层次结构是这样的：

CLAUDE.md        ← 每次必加载：核心禁令、架构要点
.claude/
├── skills/      ← 按需加载：详细规范、代码模板
└── agents/      ← 子代理：专项任务专家

完整模板

下面这份模板直接复制，放进项目根目录的 CLAUDE.md，最多改一下包名和版本号就能用。

# CLAUDE.md — Java SpringBoot 项目规范

## 技术栈

- Java: 21（LTS 版本，强制）
- Spring Boot: 3.2.x
- 数据库: MySQL 8.0 或 PostgreSQL 15
- 构建工具: Maven（使用 ./mvnw，不要直接用 mvn）
- 测试框架: JUnit 5 + Testcontainers（集成测试禁止使用 H2）

## 架构规范

### 分层结构

src/main/java/com.company.project/
├── controller/     # REST 端点，只做参数校验和调用 service
├── service/        # 业务逻辑，接口以 I 前缀命名
├── repository/     # 数据访问，继承 JpaRepository
├── model/          # JPA 实体类
├── dto/            # 请求/响应 DTO，不要把 Entity 直接暴露给 API
├── config/         # Spring 配置类
└── exception/      # 自定义异常 + 全局异常处理

### 命名规范

- 包命名：com.company.模块名.层级
- 类命名：大驼峰，Service 接口加 I 前缀（如 IUserService）
- 方法命名：小驼峰，动词开头（如 getUserById、createOrder）
- 常量命名：全大写下划线分隔（如 MAX_RETRY_COUNT）

## 代码规范

### Controller 层

- 使用 @RestController + @RequestMapping
- 统一返回 ResponseEntity<ResponseDTO<T>>
- 参数校验使用 @Valid，不要在 controller 里写 if 判断
- 错误响应使用 ProblemDetail（Spring Boot 3.x 内置，RFC 7807 标准）
- URL 路径使用名词复数：/users 而不是 /getUsers

正确写法：
@PostMapping("/users")
public ResponseEntity<ResponseDTO<UserDTO>> createUser(
    @Valid @RequestBody CreateUserRequest request) {
    return ResponseEntity.ok(ResponseDTO.success(userService.createUser(request)));
}

禁止写法：
@PostMapping("/users")
public UserDTO createUser(@RequestBody CreateUserRequest request) {
    if (request.getName() == null) {
        throw new RuntimeException("name is null");
    }
    return userService.createUser(request);
}

### Service 层

- 使用构造器注入，不要用 @Autowired 字段注入
- 事务注解 @Transactional 只加在 Service 实现类上，不要加在接口上
- 跨服务调用不要嵌套 @Transactional，容易出事务穿透问题

正确写法：
@Service
@RequiredArgsConstructor
public class UserServiceImpl implements IUserService {
    private final UserRepository userRepository;
    private final PasswordEncoder passwordEncoder;
}

禁止写法：
@Service
public class UserServiceImpl implements IUserService {
    @Autowired
    private UserRepository userRepository;
}

### Repository 层（JPA 规范）

- 使用 DTO Projection 替代直接返回 Entity
- 关联查询优先使用 @EntityGraph 或 JPQL JOIN FETCH
- 禁止在循环里调用 repository 方法（N+1 问题）
- 分页查询必须使用 Pageable 参数
- 禁止在 @OneToMany 上使用 FetchType.EAGER

正确写法：
@Query("SELECT new com.company.dto.UserDTO(u.id, u.name, u.email)
        FROM User u WHERE u.id = :id")
Optional<UserDTO> findUserDTOById(@Param("id") Long id);

禁止写法：
Optional<User> findById(Long id); // 然后直接 return 给 API

### 异常处理

- 业务异常继承 BusinessException，包含错误码和错误信息
- 全局异常处理使用 @RestControllerAdvice
- 不允许直接 throw new RuntimeException("xxx")，必须使用自定义异常
- 日志记录使用 SLF4J，不允许使用 System.out.println

正确写法：
throw new BusinessException(ErrorCode.USER_NOT_FOUND, "用户不存在: " + userId);

禁止写法：
throw new RuntimeException("用户不存在");

## 工作流规范

### Plan Mode（重要）

任何非简单任务都必须先进入 Plan Mode，写详细方案后再执行。

触发条件：
- 超过 3 个步骤的任务 → Plan Mode
- 涉及架构决策 → Plan Mode
- 修改核心业务逻辑 → Plan Mode
- 数据库 Schema 变更 → Plan Mode

工作流四阶段：探索（理解需求）→ 计划（写方案）→ 实施（写代码）→ 提交（验证）

### 每次修改后必须执行

./mvnw test
./mvnw checkstyle:check

测试通过才能提交，不允许跳过。

## 明确禁止的模式

- 禁止直接将 Entity 暴露在 API 响应里
- 禁止在 @OneToMany 上使用 FetchType.EAGER
- 禁止在循环里调用数据库方法
- 禁止使用 System.out.println 输出日志
- 禁止 catch 所有异常后 log.error("失败") 就完事，必须区分异常类型
- 禁止直接在 Controller 里写业务逻辑
- 禁止跳过测试提交代码
- 禁止修改已有的数据库迁移文件，只能新增

## API 设计规范

- URL 路径使用名词复数：/users 而不是 /getUsers
- HTTP 方法语义正确：GET 查询，POST 创建，PUT 全量更新，PATCH 部分更新，DELETE 删除
- 版本管理：URL 路径前缀 /api/v1/
- 分页接口返回 Page 对象，包含 totalElements 和 totalPages
- 所有时间字段使用 ISO 8601 格式（LocalDateTime + @JsonFormat）

## Git 提交规范

格式：类型(范围): 描述

类型：
- feat: 新功能
- fix: Bug 修复
- refactor: 重构（不涉及功能变化）
- test: 测试相关
- docs: 文档修改
- chore: 构建/配置相关

示例：feat(user): 添加用户手机号绑定功能

怎么用起来

第一步：放进项目根目录

Windows PowerShell：

cd 你的项目路径
New-Item -ItemType File -Path CLAUDE.md -Force
notepad CLAUDE.md

把上面的模板内容粘贴进去，保存。

第二步：改成你项目的实际情况

最少需要改这几处：

位置

改什么

技术栈

Java 版本、SpringBoot 版本、数据库类型

包命名

 com.company.project

 换成你的实际包名

命名规范

Service 接口是否加 I 前缀根据团队习惯调整

禁止模式

加入你们团队特有的禁止写法

第三步：启动 Claude Code 验证

cd 你的项目路径
claude

Claude Code 启动后，输入：

帮我写一个用户查询接口，根据 ID 查用户信息，返回 UserDTO

第四步：签入 Git 团队共享

git add CLAUDE.md
git commit -m "docs: 添加 Claude Code 项目规范"
git push

整个团队共享这份行为准则，所有人的 AI 按同一套规范工作。

配了前后的代码对比

同样的 prompt： 「帮我写一个用户查询接口，根据 ID 查用户信息」

没有 CLAUDE.md 时：

@GetMapping("/user/{id}")
public User getUser(@PathVariable Long id){
    return userRepository.findById(id)
        .orElseThrow(() -> new RuntimeException("用户不存在"));
}

问题一眼可见：直接返回 Entity，抛了 RuntimeException，URL 用了单数，没有统一响应格式。

配了 CLAUDE.md 之后：

@GetMapping("/users/{id}")
public ResponseEntity<ResponseDTO<UserDTO>> getUserById(@PathVariable Long id) {
    UserDTO user = userService.getUserById(id);
    return ResponseEntity.ok(ResponseDTO.success(user));
}

URL 规范（复数 /users），返回 ResponseDTO，调用 Service 而不是直接查库，异常处理交给全局异常处理器。

逐段解析：为什么这么写

技术栈声明——不写会怎样

不声明技术栈，Claude Code 会自己猜。

它可能用 Java 17 的语法写代码（你的项目是 21），可能用 Spring Boot 2.x 的 API（你的项目是 3.x），可能推荐 H2 做集成测试（你们规定用 Testcontainers）。每处猜错都要你来修。

Plan Mode——最被忽视的规范

CLAUDE.md 的最佳实践里，90% 的时间都应该使用 Plan Mode：先规划后执行，减少返工提高质量。

不强制 Plan Mode，Claude Code 对着需求直接开写，写到一半发现方向不对，要么返工，要么将错就错。

禁止模式——最有用的部分

有效的规则是具体且可测试的。

「禁止在循环里调用数据库方法」比「避免 N+1 问题」有效得多。前者是可执行的规则，后者是模糊的概念。

把你们团队踩过的坑、Code Review 里反复出现的问题，都写进禁止模式。让 AI 替你把关，在生成阶段就拦掉这些问题。

维护建议

写完不是终点，三个触发更新的时机：

  • Code Review 里反复出现同一类问题 → 加进禁止模式

  • 团队引入新的技术选型 → 更新技术栈声明

  • 之前的规范被废弃 → 删掉对应规则

最后一条原则：CLAUDE.md 只放 AI 无法自动执行的规则。

能用 Checkstyle 强制的代码风格，不要写进 CLAUDE.md。能用 FindBugs 检查的问题，不要写进 CLAUDE.md。CLAUDE.md 只写架构模式、业务逻辑约束、工作流指令——这些是工具检查不了、只有人和 AI 才能判断的东西。

参考资料：

piomin/claude-ai-spring-boot：https://github.com/piomin/claude-ai-spring-bootCLAUDE.md 最佳实践：https://www.heyuan110.com/zh/posts/ai/2026-03-05-claude-code-claudemd-best-practices/

# java # 开发语言
Logo
https://edu.csdn.net/learn/39067/627173?utm_source=2019755004

汇聚全球AI编程工具，助力开发者即刻编程。

更多推荐

cover

Codex CLI vs Claude Code 全方位对比：设计哲学与用户体验深度解析

avatar AI编程社区
cover

Claude 4.8 代码生成提示词大全：15个万能模板直接复制使用

avatar AI编程社区
cover

【提示词工程实战指南:同样的大模型,凭什么别人用得比你好?】

avatar AI编程社区