1. 为什么你的 Claude Code 总是不听话很多人第一次用 Claude Code 写 Java 项目时都会遇到同一个困惑明明在对话里反复强调用构造器注入别硬编码密钥测试覆盖率要够它当时答应得好好的换个会话就全忘了。这不是模型笨而是你没有把要求变成规则。Claude Code 的规则体系Rules就是解决这个问题的。它是一套以 Markdown 文件为载体的规范性约束系统存放在.claude/rules/目录下运行时自动加载并强制遵循。你可以把它理解成给 AI 配的一份团队编码手册——不是每次口头交代而是写进文件、按路径自动生效。规则和技能Skills是两回事别搞混。规则规定应当遵循什么比如 80% 最低测试覆盖率、禁止硬编码密钥技能规定如何具体实施比如 Python 的测试模式、Go 的并发范式。规则是约束技能是操作手册两者互补。这篇文章聚焦落地配置Markdown 规则文件怎么写、Java 项目的路径匹配怎么配、settings.json骨架长什么样、规则到底有没有生效怎么验证。适合正在用 Claude Code 做 Java 项目、想让 AI 稳定遵守团队规范的开发者。下面所有配置都可以直接复制到你的项目里跑。2. 规则目录结构通用层 语言层的两级架构规则体系采用通用层 语言层的两级设计。通用层放跨语言适用的普适原则语言层在通用层基础上扩展框架特定的内容。目录长这样rules/ ├── README.md ├── common/ # 语言无关的通用规则层 │ ├── agents.md │ ├── code-review.md │ ├── coding-style.md │ ├── development-workflow.md │ ├── git-workflow.md │ ├── hooks.md │ ├── patterns.md │ ├── performance.md │ ├── security.md │ └── testing.md ├── zh/ # common 的中文本地化版本 ├── java/ # Java 语言特定规则 ├── golang/ ├── python/ ├── typescript/ └── web/ # 前端领域规则额外含 design-quality.md每个语言目录遵循统一的五文件标准coding-style.md格式化、命名、错误处理、testing.md框架选型、覆盖率、patterns.md设计模式、hooks.mdPostToolUse 钩子、security.md密钥管理、安全实践。分层的关键在于继承和覆盖。语言规则文件开头会显式声明继承关系 本文件在 [common/coding-style.md](../common/coding-style.md) 基础上扩展 Java 特定内容。当通用规则和语言规则冲突时语言规则优先也就是特定覆盖通用。这个行为类似 CSS 特异性或.gitignore优先级。举个例子common/coding-style.md把不可变性设为默认原则但 Go 语言里修改结构体用指针接收者是惯用做法golang/coding-style.md就可以覆盖它。通用规则里可能被覆盖的条款都会用标准注记标出来语言注记此规则可能被语言特定规则覆盖当该模式在该语言中不符合惯用范式时适用。Java 层的扩展内容大致是这样coding-style用 google-java-format、record 不可变类型、sealed class、pattern matching instanceoftesting用 JUnit 5 AssertJ Mockito TestcontainersJaCoCo 目标 80%patterns用 Repository 接口抽象、Service 层编排、构造器注入、record DTO、Builder、sealed 域模型、ApiResponse 统一信封security用System.getenv()管密钥、PreparedStatement 防注入、Bean Validation、bcrypt/Argon2 哈希。3. 前置准备通过 TaoToken 拿到可用的 API Key规则体系要跑起来前提是 Claude Code 能正常调用模型。这里我用 TaoToken 作为接入入口它提供统一的 API 地址配置简单适合快速验证规则是否生效。先到官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号然后进入控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。拿到 Key 之后API 基础地址填https://taotoken.net/api这个地址不加 UTM 参数。如果你只是想先验证模型能不能正常对话可以直接用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 试一句确认 Key 有效再往下配。注意API Key 属于敏感凭证不要写进规则文件或提交到 Git。规则文件里应该写密钥从环境变量读取这类约束而不是把密钥本身放进去。如果你打算长期用 Claude Code 做编码和 Agent 任务可以了解下 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。4. 可复制配置settings.json 骨架与规则文件4.1 settings.json 骨架Claude Code 的配置放在~/.claude/settings.json全局或项目根目录的.claude/settings.json项目级。项目级配置优先级更高适合团队共享。下面是一份可直接用的骨架{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的Key从环境变量注入, ANTHROPIC_MODEL: claude-sonnet-4-20250514 }, permissions: { allow: [ Read, Edit, Bash(mvn *), Bash(./mvnw *), Bash(git status), Bash(git diff *) ], deny: [ Bash(rm -rf *), Read(./.env), Read(./secrets/**) ] }, rules: { directory: .claude/rules, autoLoad: true } }几个关键点env里配 API 地址和模型permissions.allow放允许的操作deny放禁止的比如禁止读取.env和secrets/目录这本身就是一条安全规则rules.directory指向规则目录autoLoad开启自动加载。实际使用时API Key 建议通过环境变量注入而不是明文写在 JSON 里export ANTHROPIC_API_KEYsk-你的Key export ANTHROPIC_BASE_URLhttps://taotoken.net/api4.2 Java 规则文件与路径匹配规则文件的路径匹配靠 YAML frontmatter 里的paths字段。Java 的hooks.md可以这样写--- paths: - **/*.java - **/pom.xml - **/build.gradle --- # Java Hooks 规则 本文件在 [common/hooks.md](../common/hooks.md) 基础上扩展 Java 特定内容。 ## PostToolUse 钩子 - 文件保存后自动执行 google-java-format 格式化 - 执行 checkstyle 风格校验 - 用 mvnw/gradlew 做编译验证paths支持 glob 模式**/*.java匹配任意层级的 Java 文件**/pom.xml和**/build.gradle覆盖 Maven 和 Gradle 两种构建配置。运行时 Claude Code 会根据当前操作涉及的文件路径自动匹配并加载对应规则避免无关规则干扰。4.3 安装规则目录手动安装时通用层和语言层都要复制# 通用规则层所有项目必须安装 cp -r rules/common ~/.claude/rules/common # 按技术栈安装语言规则层 cp -r rules/java ~/.claude/rules/java cp -r rules/python ~/.claude/rules/python重要约束必须以完整目录为单元复制严禁用/*通配符展平。通用层和语言层存在同名文件展平合并会导致语言层覆盖通用层还会破坏语言层文件里../common/的相对路径引用。4.4 扩展新语言规则集要给还没覆盖的语言加规则以 Rust 为例按这个流程走创建rules/rust/目录添加五个标准文件coding-style.md、testing.md、patterns.md、hooks.md、security.md每个文件开头声明继承关系 This file extends [common/coding-style.md](../common/coding-style.md) with Rust-specific content.需要的话再在skills/目录下建配套的 Skill 定义文件。非语言类的领域规则集比如web/只要可复用内容够多也能按同样的分层模式独立出来。5. 验证规则是否生效配完不算完得验证。最直接的办法是让 Claude Code 处理一个 Java 文件看它是否遵守了规则。第一步确认规则被加载。在项目里启动 Claude Code问它当前加载了哪些规则请列出当前会话加载的规则文件及其 paths 匹配范围如果配置正确它应该能报出common/和java/下的文件以及各自的paths字段。第二步做一次路径匹配测试。创建一个测试文件src/main/java/demo/UserService.java故意写一段硬编码密钥public class UserService { private static final String API_KEY sk-hardcoded-12345; public String getKey() { return API_KEY; } }然后让 Claude Code 审查这个文件。如果java/security.md生效它应该指出硬编码密钥违反规则并建议改用System.getenv()。第三步验证 hooks 触发。修改一个.java文件保存观察是否自动执行了格式化或 checkstyle。如果hooks.md的paths配对了PostToolUse 钩子会在文件变更后触发。第四步验证优先级覆盖。在common/coding-style.md里不可变性是默认原则但 Java 的 record 是惯用不可变类型。让 Claude Code 写一个 DTO看它是否优先用 record 而不是普通 class——如果用了 record说明语言层覆盖生效了。实测下来最容易出问题的是路径匹配。如果规则没生效先检查paths的 glob 写对没有再确认规则目录的层级结构没被展平破坏。6. 常见错误排查规则完全不生效先看settings.json里rules.directory路径对不对autoLoad是不是true。项目级配置和全局配置冲突时项目级优先别在两边写了矛盾的规则。路径匹配不上paths里的 glob 是相对项目根目录的。**/*.java能匹配src/main/java/...但如果你写成了/src/*.java就只匹配一层。构建文件记得同时写pom.xml和build.gradle别漏。语言层覆盖了通用层但行为不对检查语言文件开头的继承声明路径../common/xxx.md是否正确。如果安装时用了/*展平相对路径就断了继承关系失效。API 调用报错确认ANTHROPIC_BASE_URL是https://taotoken.net/apiKey 从环境变量注入且没多余空格。如果 Key 无效去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 重新生成一个。hooks 不触发hooks.md的paths要覆盖到实际改动的文件类型。Java 项目里如果只写了**/*.java改pom.xml时就不会触发记得把构建文件也加进去。权限被拒permissions.deny里如果误加了Bash(mvn *)会导致构建命令跑不了。deny 列表只放真正危险的操作比如rm -rf。7. 把规则体系用起来规则体系搭好之后日常开发会省很多口舌。我的习惯是新项目初始化时先把common/和对应语言层复制进去然后根据团队规范微调coding-style.md和testing.md的阈值。Java 项目重点盯security.md的密钥管理和hooks.md的格式化钩子这两个最容易在协作中出问题。如果你还在调模型接入先用模型对话 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 确认 Key 和地址没问题长期做编码和 Agent 任务的话Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 更合适接入细节和参数说明都在接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 里。规则文件写好后记得提交到 Git 让团队共享但 API Key 永远走环境变量别进版本库。