1. 为什么你的 Claude Code 写 Java 总像第一天入职用 Claude Code 写 Java SpringBoot 项目很多人第一反应是「这玩意儿真聪明」第二反应是「它怎么又乱来」。我试过在没配任何规则文件的情况下让它写一个用户查询接口结果它唰唰唰生成了一段代码Controller 直接返回 EntityURL 写成/user/{id}异常处理就一句throw new RuntimeException(用户不存在)。你反问它「咱项目不是规定返回 DTO 吗」它态度很好地道歉然后下一次继续犯同样的错。问题不在模型智商在于它不知道你们项目的规矩。Claude Code 每次启动时会自动读取项目根目录下的CLAUDE.md这个文件相当于给 AI 看的员工手册用 Java 21 还是 17、分层怎么分、哪些写法是红线全写在里面。没有它Claude Code 就是一个智商很高但第一天入职的实习生聪明是真聪明但你们团队的忌讳、Code Review 里会被骂什么它一概不知每次写代码都在盲猜。这篇就围绕「Skill/MCP规则文件」这个视角把CLAUDE.md当成 Claude Code 每次启动自动加载的规则文件来讲。同时把通道配通启动 Claude Code 前先去 TaoToken 拿到 Key再把 Base URL 填对让 Claude Code 读着CLAUDE.md按你的 Java 规范干活而不是乱抛RuntimeException。适合正在用 Claude Code 写 SpringBoot、被生成代码反复返工折磨的 Java 开发者。2. 先把 TaoToken 通道配好再谈规则文件CLAUDE.md解决的是「AI 懂不懂规矩」通道解决的是「AI 能不能稳定跑起来」。两件事分开做别混在一起排查。TaoToken 在这里只提供 Key 和模型通道让 Claude Code 能正常发起请求它不替代你的编辑器也不碰你的代码库。先去官网注册并创建 Keyhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content注册完进控制台创建 API Key入口在这里https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_campaignrewriteKey 的创建和管理页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite拿到 Key 之后Claude Code 的 Base URL 填这个https://taotoken.net/api这里有两个坑必须说清楚。第一Base URL 不要加/v1填https://taotoken.net/api就行多写一段路径会导致请求 404。第二不要把带 UTM 参数的官网地址填进 Base URL官网地址是给人看的Base URL 是给程序请求用的两者别搞混。如果你后面要长期跑编码任务或者接 Agent可以了解下 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite配通道和写CLAUDE.md是两条并行线通道保证请求能通规则文件保证生成内容对路。下面先讲规则文件怎么写再回头验证请求。3. CLAUDE.md 完整模板从技术栈到禁止模式CLAUDE.md的作用层次可以这样理解CLAUDE.md每次必加载写核心禁令和架构大方向.claude/skills/按需加载放具体场景的细化规范.claude/agents/是子代理处理专项任务。你不需要一上来就搞得很复杂一份好的CLAUDE.md足够让 Claude Code 从野生码农变成懂规矩的队友。把下面内容复制到项目根目录的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): 添加用户手机号绑定功能模板里几个段落值得单独说。技术栈那段看着像废话但不写的话 AI 真的会乱来我见过 Claude Code 默认推荐 Java 17 的语法或者顺手给你用 H2 跑集成测试如果团队规定用 Testcontainers 模拟真实数据库这就踩雷了。把版本钉死等于告诉它在这个项目里别玩花的。架构规范那段很多团队的分层只存在于老员工脑子里新人靠猜。写进CLAUDE.md后AI 生成的代码自然对号入座Controller 里不会冒出业务逻辑Service 接口会按IUserService这种风格命名。禁止模式那段是整份文件里最该认真写的。有效的规则是具体且可测试的「禁止在循环里调用数据库方法」比「避免 N1 问题」管用一百倍前者 Claude Code 能直接执行后者它还得自己理解什么叫「避免」。4. 验证请求从 RuntimeException 到规范 DTO规则文件写好后启动 Claude Code丢个需求验证一下。比如你说「帮我写一个根据 ID 查用户的接口返回 UserDTO。」没配CLAUDE.md之前它可能给你这个GetMapping(/user/{id}) public User getUser(PathVariable Long id) { return userRepository.findById(id) .orElseThrow(() - new RuntimeException(用户不存在)); }配了之后它给的是这个GetMapping(/users/{id}) public ResponseEntityResponseDTOUserDTO getUserById(PathVariable Long id) { UserDTO user userService.getUserById(id); return ResponseEntity.ok(ResponseDTO.success(user)); }差距一眼可见URL 从/user/{id}变成名词复数的/users/{id}返回从裸 Entity 变成统一的ResponseEntityResponseDTOUserDTO分层对了异常也不乱抛了。这就是CLAUDE.md作为规则文件被每次启动自动读取的价值。通道侧也顺手验证一下。确认 Base URL 填的是https://taotoken.net/apiKey 已配置然后让 Claude Code 跑一个简单请求。如果模型能正常返回内容说明通道通了如果返回 401多半是 Key 没填对如果返回 404检查 Base URL 是不是多写了/v1。想单独验证模型是否可用可以走模型对话页面https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite接入相关的文档在这里遇到配置问题可以对照https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite验证完没问题记得git add CLAUDE.md提交推上去整个团队共享所有人的 AI 按同一套规矩干活。5. 本篇常见错排查Base URL 填错导致 404。最常见的是把https://taotoken.net/api写成带/v1的版本或者把带 UTM 参数的官网地址直接粘进 Base URL。记住Base URL 只填https://taotoken.net/api官网地址是给人看的。Key 无效导致 401。检查 Key 是否复制完整有没有多余空格。如果 Key 是在别的项目里用的确认它还有效。重新创建 Key 的入口在https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite。CLAUDE.md 没生效。确认文件在项目根目录文件名大小写正确CLAUDE.md不是claude.md。Claude Code 每次启动自动读改完文件后重启一下会话再验证。AI 还是返回 Entity。检查CLAUDE.md里「禁止直接将 Entity 暴露在 API 响应里」这条是否写清楚以及有没有给出正确写法的示例。规则越具体执行越到位。集成测试还是用 H2。技术栈那段要明确写「集成测试禁止使用 H2」并指定 Testcontainers。不写的话AI 会按它自己的默认习惯来。异常还是 RuntimeException。在禁止模式里明确列出「不允许直接 throw new RuntimeException」并给出BusinessException的正确写法示例。光说「用自定义异常」不够要给可复制的代码。Plan Mode 不触发。检查触发条件是否写清楚比如「超过 3 个步骤的任务」「涉及架构决策」。条件越具体AI 越容易判断什么时候该先出方案。6. 把规则文件当成长期契约来维护CLAUDE.md不是写一次就完事的。三个时机记得更新Code Review 里反复出现同一类问题比如最近三次都有人把 Entity 直接返回给前端那就加一条禁令团队引入新技术上了 Kafka 就把消息消费规范写进去之前的规范被废弃比如决定不用I前缀命名 Service 接口了赶紧删掉别让 AI 继续生成过时代码。有一条原则很重要CLAUDE.md只放 AI 无法自动执行的规则。能用 Checkstyle 强制的代码风格别写进去能用 SpotBugs 检查的问题别写进去。它应该只写架构模式、业务逻辑约束、工作流指令这些是工具检查不了、只有人和 AI 才能判断的东西。写多了文件臃肿AI 加载起来也迷糊写少了该拦的问题拦不住。通道这边长期跑编码任务或者接 Agent 的话Coding Plan 可以了解下https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_campaignrewrite说到底用 Claude Code 写企业级 Java 项目拼的不是谁 prompt 写得花而是谁的项目规范能被 AI 准确理解并执行。一份好的CLAUDE.md就是你和 AI 之间的契约它让 Claude Code 从一个聪明的陌生人变成懂你们团队规矩的老搭档。今晚就在项目根目录建一个明天写代码的时候你会回来谢我的。