让你的Claude Code从“能用”到“能打”：CLAUDE.md 配置实战

1. 为什么你的 Claude Code 在 Spring Boot 项目里总是“差口气”Claude Code 是 Anthropic 推出的终端级 AI 编程助手它能直接读取你项目里的文件、执行命令、修改代码和普通聊天窗口最大的区别是它能看到你的pom.xml、application.yml、整个包结构。但很多人把它当“高级版代码补全”用每次对话都从零描述技术栈结果就是生成的代码风格飘忽、异常处理随意、金额字段用 double、返回格式跟项目对不上。我试过在一个 Spring Boot 3.2 JDK 17 MyBatis-Plus 的项目里让 Claude Code 连续生成五个 Service 方法前三个用Data后两个又改成Getter/Setter分页一会儿用 PageHelper 一会儿用 IPage。问题不在模型能力而在于我没有给它一份稳定的“项目规矩”。这篇文章聚焦 Java/Spring Boot 场景围绕CLAUDE.md骨架和settings.json关键项给出可复制的项目级配置与验证动作。适合已经用过 Claude Code、但觉得输出不够“工程化”的后端开发者。读完之后你可以把 AI 提示词从随手问答升级为稳定可复用的工程能力让每次生成的代码都能直接进 Code Review。2. 前置准备TaoToken 接入与 Claude Code 环境确认在配置CLAUDE.md之前先确保你的 Claude Code 能正常调用模型。国内开发者常用的方式是通过 TaoToken 这类兼容 Anthropic API 协议的服务来接入省去网络层面的折腾。你需要准备两样东西一个可用的 API Key以及 Claude Code 的安装。API Key 在 TaoToken 控制台的 API Keys 页面创建地址是https://taotoken.net/api-keys。创建后复制那串以sk-开头的密钥后面配置环境变量会用到。Claude Code 的安装按官方文档走即可安装完成后通过环境变量指定 API 地址和密钥。这里的关键是ANTHROPIC_BASE_URL指向 TaoToken 的 API 端点https://taotoken.net/apiANTHROPIC_API_KEY填你刚创建的 Key。配置完成后在终端执行claude能进入交互界面说明环境通了。注意API 地址不要带多余的路径后缀Claude Code 会自动拼接/v1/messages等端点。如果你在settings.json里同时配了 base URL 和环境变量以环境变量为准避免冲突。环境确认之后进入你的 Spring Boot 项目根目录执行claude启动。此时 Claude Code 会扫描当前目录但它还不知道你的项目规范——这正是CLAUDE.md要解决的问题。3. 可复制配置CLAUDE.md 骨架与 settings.json 关键项3.1 CLAUDE.md 的加载机制与放置位置Claude Code 在每次会话启动时会自动读取项目根目录下的CLAUDE.md。如果你在子目录里工作它还会向上查找最近的CLAUDE.md。这意味着你可以把通用规范放在项目根目录把模块特有的约定放在子模块目录。一个实用的做法是根目录CLAUDE.md写技术栈、编码规范、包结构约定如果项目有多个微服务模块在每个模块目录下再放一个CLAUDE.md补充该模块的业务规则。Claude Code 会合并读取越靠近当前工作目录的优先级越高。3.2 一份可直接落地的 CLAUDE.md 骨架下面这份骨架针对 Spring Boot 项目你可以直接复制到项目根目录按实际情况微调。# 项目概述 这是一个基于 Spring Boot 的企业级管理系统用于设备监控与工单管理。 ## 技术栈 - JDK 17 - Spring Boot 3.2.x - MyBatis-Plus 3.5.x - MySQL 8.0 - Redis 7.x - Maven 构建 ## 编码规范 - 统一返回格式ResultT包含 code、message、data 三个字段 - 异常处理全局异常处理器RestControllerAdvice业务异常用 BusinessException - 金额字段一律使用 BigDecimal禁止 double/float - 日期字段使用 LocalDateTime禁止 Date - Service 方法涉及写操作必须加 Transactional - 使用 Lombok但禁止 Data用 Getter/Setter - 分页统一使用 MyBatis-Plus 的 IPage ## 包结构约定 - controller —— 接口层只做参数校验和调用 Service - service —— 业务逻辑层 - mapper —— 数据访问层继承 BaseMapper - entity —— 数据库实体 - dto —— 数据传输对象 - vo —— 视图对象 - config —— 配置类 - exception —— 自定义异常 - util —— 工具类 ## 命名规范 - 数据库表名t_ 前缀 下划线如 t_order_detail - Java 类名大驼峰OrderDetail - 方法名小驼峰getOrderList - 常量全大写下划线MAX_RETRY_COUNT ## 其他约定 - 接口路径统一 /api/ 前缀 - 所有接口必须有 Swagger 注解Tag、Operation - 禁止在 Controller 中写业务逻辑 - SQL 优先写在 Mapper XML简单 CRUD 用 MyBatis-Plus 内置方法这份骨架的核心价值在于它把“团队口头约定”变成了“AI 可读的硬约束”。你不需要每次对话都提醒“用 BigDecimal”Claude Code 读到CLAUDE.md后会自动遵循。3.3 settings.json 里值得关注的几个配置项Claude Code 的settings.json通常位于~/.claude/settings.json或项目级.claude/settings.json。对于 Spring Boot 项目以下几个配置项值得调整。第一是permissions控制 Claude Code 能执行哪些命令。建议把mvn、git、java加入允许列表这样它可以直接跑编译和测试而不是只生成代码让你手动验证。{ permissions: { allow: [ Bash(mvn *), Bash(git status), Bash(git diff *), Bash(java -version) ] } }第二是env用来固定 API 地址和密钥避免每次终端会话都要重新 export。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的密钥 } }第三是includeCoAuthoredBy如果你不希望提交记录里出现 AI 署名可以设为false。这个看团队规范没有绝对对错。提示项目级.claude/settings.json可以提交到 Git让团队共享权限配置个人密钥放在用户级~/.claude/settings.json不要提交。4. 验证请求用三个动作确认配置生效配置写好了不代表生效你需要用具体动作验证 Claude Code 是否真的读到了CLAUDE.md和settings.json。4.1 验证 CLAUDE.md 是否被加载在项目根目录启动claude然后输入请告诉我这个项目的技术栈和编码规范不要读任何文件直接根据你已有的上下文回答。如果 Claude Code 能准确说出 JDK 17、Spring Boot 3.2、Result 返回格式、BigDecimal 金额规范说明CLAUDE.md已经被加载。如果它说“我不知道你的项目”那就要检查文件是否放在根目录、文件名大小写是否正确。4.2 验证代码生成是否符合规范输入一个具体的生成请求请为 Device 实体生成一个分页查询接口包含 Controller、Service、Mapper、VO。 Device 字段id、deviceName、deviceCode、siteId、status、createTime。观察输出Controller 是否有Tag和Operation返回类型是否是ResultIPageDeviceVOService 是否用了IPage而不是 PageHelper实体是否用了Getter/Setter而不是Data。如果这些都对上了说明规范约束生效。4.3 验证 settings.json 的权限配置让 Claude Code 执行一个编译命令请运行 mvn compile 检查当前代码是否能编译通过。如果它直接执行并返回结果说明permissions.allow里的Bash(mvn *)生效了。如果它提示“需要权限确认”说明配置没被读取检查settings.json的路径和 JSON 格式。5. 本篇常见错排查5.1 CLAUDE.md 写了但 AI 不遵守最常见的原因是文件位置不对。Claude Code 只读取项目根目录和当前工作目录向上查找的CLAUDE.md。如果你在src/main/java下启动claude而CLAUDE.md在项目根目录它仍然能读到因为会向上查找。但如果你在项目外的目录启动就读不到。另一个原因是规范写得太模糊。比如“使用合理的异常处理”这种描述AI 无法执行。要写成“业务异常用 BusinessException全局异常处理器用 RestControllerAdvice”。可执行的规范必须是具体的、可判断的。5.2 settings.json 的 JSON 格式错误JSON 不支持注释也不支持尾逗号。很多人从博客复制配置时带了//注释导致解析失败。Claude Code 启动时如果settings.json解析失败会静默忽略不会报错。建议用jq . ~/.claude/settings.json检查格式。5.3 API 地址配置冲突如果你同时在环境变量和settings.json里配了ANTHROPIC_BASE_URL以环境变量为准。有时候你在终端 export 了一个旧的地址又在settings.json里写了新的结果一直走旧地址。排查方法是执行echo $ANTHROPIC_BASE_URL确认当前生效的值。5.4 生成的代码编译不过这通常是因为CLAUDE.md里没有提供通用类的签名。比如你要求返回ResultT但 AI 不知道Result的包路径和构造方法。解决办法是在CLAUDE.md里补充关键通用类的代码片段或者把Result.java的内容直接贴给 Claude Code 一次让它理解你的项目结构。5.5 分页查询生成了 PageHelper 而不是 IPage这是典型的“规范没写清楚”问题。MyBatis-Plus 和 PageHelper 是两套分页方案如果你只写“支持分页”AI 可能选它更熟悉的 PageHelper。在CLAUDE.md里明确写“分页统一使用 MyBatis-Plus 的 IPage禁止 PageHelper”就能避免。6. 把配置变成习惯长期编码与 Agent 场景的延伸CLAUDE.md和settings.json配好之后Claude Code 在单次会话里的表现会稳定很多。但如果你要长期用它做编码、重构、写测试甚至跑 Agent 任务单靠项目级配置还不够。一个自然的延伸是 Coding Plan 这类长期编码方案它把模型调用、额度管理、项目配置整合在一起适合需要持续用 Claude Code 做开发的场景。你可以通过https://taotoken.net/coding-plan了解具体的接入方式。另外如果你想让 Claude Code 在 Agent 模式下自动执行更多操作比如自动跑测试、自动提交 Git需要在settings.json的permissions里逐步放开权限。建议从最小权限开始确认行为符合预期后再逐步扩大。最后提醒一点CLAUDE.md不是一次写完就一劳永逸的。每次 Code Review 发现 AI 生成的代码有共性问题就补充一条规范进去。用上一个月你的CLAUDE.md会变成团队最有价值的工程文档之一——因为它既是给 AI 看的也是给新人看的。