1. 为什么你的 Claude Code 写 Java 总像实习生用 Claude Code 写 Java 代码大多数人第一步就做错了。不是不会用是根本没配 CLAUDE.md。没有这份文件的 Claude Code就像一个第一天入职的新人——聪明但什么都不知道。它不知道你的项目用 Java 21 还是 Java 17不知道你的分层规范不知道哪些写法在你们团队是禁止的。每次生成代码都在猜猜对了靠运气猜错了你来改。CLAUDE.md 是放在项目根目录的一个 Markdown 文件Claude Code 每次启动都会自动读取它把里面的内容作为上下文加载进去。它是项目的记忆系统让 AI 理解你的项目并支持自我进化。简单说它是你给 Claude Code 写的「项目说明书」告诉它这个项目用什么技术栈、代码要怎么组织、哪些写法是禁止的、遇到问题要怎么处理。这篇内容我会把一份可以直接用的 Java SpringBoot CLAUDE.md 模板完整放出来每一段说清楚为什么这么写、不写会怎样。同时给出 settings.json 接入 TaoToken 统一 Key/API 通道的配置片段并演示一次生成后校验分层结构、依赖与编译通过的验证动作。适合正在用 Claude Code 写 SpringBoot 项目、但生成代码总需要大量返工的开发者。一个合理的层次结构是这样的CLAUDE.md 每次必加载放核心禁令和架构要点.claude/skills/ 按需加载放详细规范和代码模板.claude/agents/ 放子代理处理专项任务。下面这份模板直接复制放进项目根目录的 CLAUDE.md最多改一下包名和版本号就能用。2. 前置准备TaoToken 统一 Key 与 Claude Code 接入在写 CLAUDE.md 之前先把 API 通道配好。Claude Code 需要一个稳定的模型调用入口TaoToken 提供统一的 Key 和 API 通道省去你到处切换配置的麻烦。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。你需要先拿到 API Key。登录后进入控制台在 API Keys 页面创建一个新的 Key复制保存好。这个 Key 后面会写进 Claude Code 的 settings.json 里。Claude Code 的配置文件通常放在用户目录下的 .claude/settings.json或者项目根目录的 .claude/settings.json。项目级的配置优先级更高适合团队共享。下面是一个可复制的配置片段把 ANTHROPIC_BASE_URL 指向 TaoToken 的 API 地址ANTHROPIC_AUTH_TOKEN 填你刚创建的 Key{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoToken密钥, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }这里有个细节要注意ANTHROPIC_BASE_URL 不要带末尾斜杠也不要加 UTM 参数保持干净的 API 根地址。ANTHROPIC_MODEL 按你实际订阅的模型名填写如果你不确定用哪个可以先在模型对话页面测试一下再决定。配好之后在终端里进入项目目录运行 claude 命令启动。如果配置生效Claude Code 会正常加载并等待你的输入。如果报认证错误先检查 Key 是否复制完整、有没有多余空格。3. 可复制的 CLAUDE.md 模板与 settings.json 配置下面这份模板直接复制放进项目根目录的 CLAUDE.md。每一段我都标注了为什么这么写。# CLAUDE.md — Java SpringBoot 项目规范 ## 技术栈 - Java: 21LTS 版本强制 - 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 - 统一返回 ResponseEntityResponseDTOT - 参数校验使用 Valid不要在 controller 里写 if 判断 - 错误响应使用 ProblemDetailSpring Boot 3.x 内置RFC 7807 标准 - URL 路径使用名词复数/users 而不是 /getUsers 正确写法 PostMapping(/users) public ResponseEntityResponseDTOUserDTO 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 方法N1 问题 - 分页查询必须使用 Pageable 参数 - 禁止在 OneToMany 上使用 FetchType.EAGER 正确写法 Query(SELECT new com.company.dto.UserDTO(u.id, u.name, u.email) FROM User u WHERE u.id :id) OptionalUserDTO findUserDTOById(Param(id) Long id); 禁止写法 OptionalUser 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): 添加用户手机号绑定功能放进项目根目录后最少需要改这几处技术栈里的 Java 版本、SpringBoot 版本、数据库类型包命名 com.company.project 换成你的实际包名命名规范里 Service 接口是否加 I 前缀根据团队习惯调整禁止模式里加入你们团队特有的禁止写法。4. 验证请求生成后校验分层、依赖与编译配好 CLAUDE.md 和 settings.json 之后启动 Claude Code 验证效果。进入项目目录运行 claude然后输入一个具体需求帮我写一个用户查询接口根据 ID 查用户信息返回 UserDTO配了 CLAUDE.md 之后生成的代码应该是这样的GetMapping(/users/{id}) public ResponseEntityResponseDTOUserDTO getUserById(PathVariable Long id) { UserDTO user userService.getUserById(id); return ResponseEntity.ok(ResponseDTO.success(user)); }URL 规范复数 /users返回 ResponseDTO调用 Service 而不是直接查库异常处理交给全局异常处理器。对比没有 CLAUDE.md 时的输出差异非常明显——没配的时候它可能直接返回 Entity、抛 RuntimeException、URL 用单数、没有统一响应格式。生成之后你需要做三个验证动作。第一检查分层结构确认生成的类是否落在正确的包下controller 里有没有混入业务逻辑service 接口有没有加 I 前缀。第二检查依赖确认有没有引入不该出现的依赖比如集成测试用了 H2 而不是 Testcontainers。第三编译验证./mvnw clean compile ./mvnw test ./mvnw checkstyle:check如果编译通过、测试通过、checkstyle 通过说明这份 CLAUDE.md 的约束生效了。如果编译报错把错误信息贴回给 Claude Code让它根据 CLAUDE.md 的规范修正。实测下来配好模板后第一次生成就能编译通过的概率会高很多返工主要集中在业务逻辑细节上而不是架构和规范层面。5. 本篇常见错排查第一个常见错误是 CLAUDE.md 放错位置。它必须放在项目根目录和 pom.xml 同级。如果你放在 .claude/ 目录下Claude Code 不会自动加载。项目级的 CLAUDE.md 和用户级的 ~/.claude/CLAUDE.md 是两回事团队共享的规范要放项目根目录。第二个错误是 settings.json 里的 ANTHROPIC_BASE_URL 带了末尾斜杠或 UTM 参数。正确的写法是 https://taotoken.net/api 不要加任何多余字符。如果认证失败先检查 Key 有没有复制完整再检查 JSON 格式有没有语法错误比如多余的逗号或缺少引号。第三个错误是规范写得太模糊。「避免 N1 问题」这种表述 AI 很难执行要写成「禁止在循环里调用 repository 方法」。「代码要规范」这种话等于没说要写成具体的、可测试的规则。有效的规则是具体且可测试的把你们团队 Code Review 里反复出现的问题都写进禁止模式。第四个错误是把 Checkstyle 能管的风格问题写进 CLAUDE.md。能用工具强制的代码风格不要写进 CLAUDE.md能用静态检查发现的问题也不要写进 CLAUDE.md。CLAUDE.md 只写架构模式、业务逻辑约束、工作流指令——这些是工具检查不了、只有人和 AI 才能判断的东西。第五个错误是写完就不管了。三个触发更新的时机Code Review 里反复出现同一类问题加进禁止模式团队引入新的技术选型更新技术栈声明之前的规范被废弃删掉对应规则。CLAUDE.md 是活的文档不是一次性任务。如果你在接入过程中遇到认证或通道问题可以去 API Keys 页面重新生成 Key或者查阅接入文档确认配置格式。需要验证模型输出效果时模型对话页面可以快速测试。长期做编码和 Agent 任务的话Coding Plan 更适合高频使用场景。6. 让规范持续生效的接入方式CLAUDE.md 配好只是第一步真正让团队持续受益的是把 API 通道和规范文件都纳入版本管理。settings.json 里的 Key 不要直接提交到 Git用环境变量或者本地覆盖的方式处理。项目级的 .claude/settings.json 可以提交但把敏感字段抽出来。团队协作时CLAUDE.md 跟着项目走所有人的 AI 按同一套规范工作。新成员入职拉下代码就自带项目说明书不用再口头传达规范。Code Review 的压力也会小很多因为很多低级问题在生成阶段就被 CLAUDE.md 拦掉了。如果你还没配好 API 通道可以从 API Keys 页面创建一个 Key然后参考接入文档把 settings.json 配好。需要长期跑编码任务的Coding Plan 的额度模型更适合日常高频调用。规范文件加统一通道这两件事配好之后Claude Code 写出来的 Java 代码才真正具备企业级项目的可用性。
