1. 为什么 Claude Code 写出来的代码总像“外人”团队里用 Claude Code 的人一多问题就冒出来了同一个项目A 同事生成的代码用Slf4jB 同事生成的却用LoggerFactory.getLogger()有人抛BusinessException有人直接throw new RuntimeException()变量命名一会儿驼峰一会儿下划线。代码能跑但 review 的时候满屏都是风格问题改起来比自己写还累。这不是 Claude 能力不行而是它默认按“全网代码的平均值”来写。训练数据里各种风格都有你不告诉它你们团队的规矩它就只能猜。猜对了是运气猜错了是常态。解决思路很直接把团队编码规范写成 Claude Code 每次启动都会读的规则文件也就是CLAUDE.md。它放在项目根目录Claude Code 启动时自动加载相当于给 AI 定了一份“家规”。规则写得越精确生成代码的风格就越接近团队里老手的手笔。这篇面向正在用 Claude Code 做团队协作的开发者交付一套可复制的CLAUDE.md配置骨架、Plan Mode 的验证动作以及规则写太粗导致失效的排查方法。如果你还没装 Claude Code先跑一行命令npm install -g anthropic-ai/claude-code装完在项目目录下执行claude它会自动读取项目结构然后就能用自然语言对话了。接下来重点讲规则怎么定。2. 前置准备TaoToken 接入与 Claude Code 环境Claude Code 要跑起来得先解决模型调用的问题。我这边用的是 TaoToken 的 API 接入官网入口在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。整个流程分三步拿 Key、配环境变量、验证连通。2.1 获取 API Key登录后进入控制台在 API Keys 页面创建一个新 Key。建议按项目或按人分配方便后续排查用量。创建后立刻复制保存页面刷新后就不再完整显示。2.2 配置环境变量Claude Code 通过环境变量读取 API 地址和 Key。在~/.bashrc或~/.zshrc里加上export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key改完执行source ~/.zshrc让配置生效。注意ANTHROPIC_BASE_URL不要带末尾斜杠否则部分版本会拼接出双斜杠导致 404。2.3 验证连通在任意目录跑一次简单对话确认 Key 和地址都对claude -p 回复 ok 两个字母即可返回ok就说明链路通了。如果报 401检查 Key 是否复制完整报连接超时检查ANTHROPIC_BASE_URL是否写成了https://taotoken.net/api/多了斜杠。提示团队协作时建议把 Key 放在共享的密钥管理工具里不要直接提交到 Git 仓库。.env文件记得加进.gitignore。3. 可复制的 CLAUDE.md 配置骨架规则文件的核心原则是“精确到类名和方法签名”。模糊的“注意异常处理”等于没写Claude 会按自己的理解来。下面这份骨架可以直接复制到项目根目录按团队情况改。3.1 基础骨架# CLAUDE.md - 项目规则 ## 技术栈 - Java 17, Spring Boot 3.2.x - MyBatis-Plus 3.5.7, Sa-Token 1.38.x - Hutool 5.8.x, Lombok 1.18.30 ## 代码规范 - 类名 PascalCase, 方法/变量 camelCase, 常量 UPPER_SNAKE - 使用 Slf4j 记录日志, 禁止 LoggerFactory.getLogger() - 业务异常抛 BusinessException(code, message) - Controller 返回 ResponseEntity, 统一用 BaseResponse 包装 - 所有 public 方法必须有 Javadoc - 对象拷贝使用 BeanUtil.copyProperties ## 目录结构 src/main/java/com/example/ ├── controller/ # REST 控制器 ├── service/ # 业务逻辑 (interface impl) ├── mapper/ # MyBatis-Plus Mapper ├── entity/ # 数据库实体 ├── dto/ # 请求/响应对象 └── exception/ # 异常定义 ## 禁止 - 禁止硬编码敏感信息 - 禁止空 catch 块 - 禁止字符串拼接 SQL这份骨架控制在 60 行左右Claude 读取时不会因为太长而忽略后半部分。社区经验是把CLAUDE.md控制在 200 行以内超出就拆到子规则文件。3.2 分层规则管理项目变大后把所有规则塞进一个文件会失控。推荐拆成.claude/rules/目录项目根目录/ ├── CLAUDE.md # 核心规则 ├── .claude/ │ ├── rules/ │ │ ├── java.md # Java 领域规则 │ │ ├── test.md # 测试规范 │ │ └── security.md # 安全规则 │ └── settings.json # 权限、模型、沙箱配置CLAUDE.md里用引用## 代码规范 rules/java.md rules/test.md rules/security.md这样改 Java 规则不用动测试规范团队成员也能按需加载。注意settings.json管的是“能做什么操作”权限、沙箱CLAUDE.md管的是“怎么写代码”两者职责别混。3.3 规则粒度对照模糊写法精确写法效果差异注意异常处理业务异常抛 BusinessException(code, message)前者加 try-catch 打印堆栈后者抛具体异常用日志使用 Slf4j禁止 LoggerFactory.getLogger()前者可能用 System.out后者锁定注解命名规范类名 PascalCase方法 camelCase常量 UPPER_SNAKE前者仍可能混用后者可逐条核对注意安全禁止字符串拼接 SQL用 MyBatis-Plus 条件构造器前者可能忽略后者直接约束写法写规则时优先用正面指令。“业务异常必须抛 BusinessException”比“不要用 RuntimeException”遵守度更高负面禁止有时反而让模型困惑。4. 验证请求与 Plan Mode 实操规则写好了怎么确认它真的生效两个动作一次直接对话验证风格一次 Plan Mode 验证方案。4.1 直接对话验证在项目目录下启动 Claude Code给一个明确的小需求claude然后输入在 UserService 里加一个 getUserById 方法按 CLAUDE.md 的规范写观察生成结果。如果规则生效应该看到Slf4j注解、BusinessException抛出、Javadoc 注释齐全。如果还是出现LoggerFactory.getLogger()说明规则没被读到或写得不够精确。4.2 Plan Mode 验证方案需求不明确或涉及多个文件时先用 Plan Mode。输入/plan后描述需求/plan 给项目加一套基于角色的权限校验涉及 Controller 和 Service 层Claude 会先分析现有代码结构列出几种方案比如注解式拦截 vs 手动校验分析利弊后给出推荐方案和执行步骤。你确认方向没问题再让它动手写代码。我的经验是超过 3 个文件需要修改的任务先用 Plan Mode。不然 Claude 直接上手改改到一半发现方向不对整个上下文就废了只能重开对话。4.3 完整工作流CLAUDE.md 加载规则 │ ▼ /init 读取项目结构 │ ▼ 需求明确 ──是──→ 直接对话Claude 按规则改代码 │ 否 ▼ /plan 规划方案 → 你确认 → 执行 → Review这个闭环跑顺后Claude 生成的代码风格基本和团队老手一致review 时不用再纠结格式问题。5. 本篇常见错排查规则不生效通常不是 Claude 的问题而是配置或写法出了偏差。下面几个坑我踩过。5.1 规则文件没被读取现象生成的代码完全无视CLAUDE.md。排查顺序确认文件在项目根目录不是子目录确认文件名大小写正确CLAUDE.md不是claude.md确认启动claude时的工作目录就是项目根目录。如果用了rules/java.md引用检查路径是否相对于项目根目录。5.2 规则太笼统导致失效现象写了“注意异常处理”Claude 还是抛RuntimeException。原因是“注意”这个词没有可执行边界。改成“业务异常抛 BusinessException(code, message)不允许 RuntimeException”遵守度立刻提升。规则要写到类名和方法签名的粒度。5.3 规则文件过长被截断现象前面的规则生效后面的被忽略。CLAUDE.md超过 200 行后模型可能只关注前半部分。解决办法是拆分到.claude/rules/目录主文件只留核心规则和引用。5.4 强制行为写错位置现象在CLAUDE.md里写“禁止生成 Co-Authored-By”但提交时还是带上了。这类强制行为应该放到.claude/settings.json里配置比如attribution.commit: 从源头关掉。CLAUDE.md管代码风格settings.json管操作约束。5.5 API 报错排查如果对话时报 401检查ANTHROPIC_API_KEY是否完整报 404检查ANTHROPIC_BASE_URL是否多了末尾斜杠报超时检查网络和地址是否写成https://taotoken.net/api。这些配置问题在接入文档里有详细说明遇到报错可以先对照排查。6. 把规范固化进每次输出给 Claude 定规则的核心就一条把团队编码规范写成机器可读的精确指令。写到“用 Slf4j禁止 LoggerFactory.getLogger()”这个粒度Claude 基本不会再出错。规则文件分层管理核心规则控制在 200 行以内领域规则拆到.claude/rules/强制行为交给settings.json。团队协作场景下建议把CLAUDE.md纳入 code review 流程。每次 review 发现新共识就同步更新到规则文件里。时间长了这份文件就是团队编码规范的活文档新成员入职看它也能快速对齐风格。如果你还在选模型接入方式可以先从模型对话页面试一下效果确认链路通了再配到 Claude Code 里。长期做编码和 Agent 任务的团队Coding Plan 的用量和成本更可控。API Key 的创建和管理在控制台的 API Keys 页面接入细节可以对照接入文档操作。规则定好之后Claude Code 写出的代码就像团队自己的人写的一样review 效率会明显不一样。