Claude Code 基础配置篇-三层配置体系详解

基础配置篇 —— Rules、Memory、Custom Instructions 三层配置体系详解系列导读 Claude Code 最让新手头疼的问题是每次写的代码风格都不一样、“总要重新解释项目架构”。本篇将彻底解决这个问题。通过建立三层配置体系你可以让 Claude 变成一个入职后就熟悉团队规范的老员工。一、为什么要配置一个真实的故事假设你让一个新人开发一个用户注册接口。如果不给他任何规范他可能用字段注入Autowired而不是构造器注入返回MapString, Object而不是统一的ResultT用e.printStackTrace()而不是日志框架表名不统一有的叫user有的叫t_userClaude Code 也是一样——它的默认知识是通用最佳实践不是你团队的实践。配置的作用就是把我们团队怎么干编码成 Claude 的肌肉记忆。二、三层配置体系总览Claude Code 的配置体系非常清晰分为三个层次配置层回答的问题存放位置类比Rules规则“代码该怎么写”.claude/rules/*.md团队的《开发手册》Memory记忆“项目是什么情况”CLAUDE.md、.claude/memory/项目的《备忘录》Custom Instructions自定义指令“我是谁我喜欢什么”~/.claude/CLAUDE.md你的《个人画像》生效优先级从高到低后加载的覆盖先加载的Managed Policy组织管理员配置 Project Rules项目规则 .claude/rules/ Project Memory项目记忆 ./CLAUDE.md Directory Memory目录记忆 子目录/CLAUDE.md User Memory用户记忆 ~/.claude/CLAUDE.md Auto Memory自动记忆 ~/.claude/projects/.../memory/这个优先级设计非常合理越具体的配置优先级越高。子目录的配置可以覆盖项目级的配置项目级的配置可以覆盖用户级的配置。三、Rules让 Claude 按你的规矩写代码3.1 什么是 RulesRules 是 Anthropic 在 2025 年推出的新一代配置方式。相比于把一堆规范塞到一个巨大的CLAUDE.md里Rules 允许你把规则拆分成多个小文件放在.claude/rules/目录下并且可以按文件路径匹配只在操作特定文件时加载。为什么拆分更好精准加载写 Java 代码时只加载 Java 规范写前端代码时只加载前端规范减少上下文噪音维护方便每个规则文件聚焦一个主题更新时不容易出错团队协作不同成员可以负责维护不同的规则文件3.2 Rules 目录结构my-project/ ├── .claude/ │ ├── rules/ │ │ ├── java-style.md # Java 编码规范全局 │ │ ├── spring-boot-api.md # Spring Boot API 规范 │ │ ├── testing.md # 测试规范 │ │ ├── security.md # 安全规范 │ │ └── frontend.md # 前端规范仅对前端目录生效 │ └── settings.json # 可选额外配置 ├── src/ └── pom.xml3.3 Rules 文件格式一个标准的 Rule 文件包含两部分YAML Frontmatter元数据Markdown 内容规则正文。--- title: Java 编码规范 description: 团队 Java 开发的基础编码规范 trigger: 操作 .java 文件时自动加载 --- # Java 编码规范 ## 基础风格 - 使用 Lombok 的 Data、Builder、RequiredArgsConstructor - 禁止使用 public 字段所有字段必须是 private - 类名大驼峰UserService方法名小驼峰findByIdFrontmatter 字段说明字段作用示例title规则的简短标题Java 编码规范description规则的详细描述团队 Java 开发的基础编码规范trigger触发条件说明操作 .java 文件时自动加载glob路径匹配模式可选src/frontend/**/*.tsx3.4 路径匹配让规则只对特定文件生效这是 Rules 最强大的功能之一。你可以指定某个规则只对特定目录或文件类型生效--- title: 前端 React 规范 glob: src/frontend/**/*.{tsx,ts} --- # React 规范 - 使用函数组件 Hooks - 状态管理用 ZustandGlob 语法速查模式含义*.java所有 Java 文件src/**/*.javasrc 及其子目录下的所有 Java 文件src/main/**/*.javasrc/main 及其子目录下的 Java 文件*.{java,xml}所有 Java 和 XML 文件src/test/**src/test 及其子目录下的所有文件3.5 完整 Rules 示例.claude/rules/java-style.md—— Java 基础规范--- title: Java 编码规范 description: 团队 Java 开发的基础编码规范 trigger: 操作 .java 文件时自动加载 --- # Java 编码规范 ## 基础风格 - 使用 Lombok 的 Data、Builder、RequiredArgsConstructor 减少样板代码 - 禁止使用 public 字段所有字段必须是 private - 类名使用大驼峰UserService方法名使用小驼峰findById - 常量使用全大写下划线分隔MAX_RETRY_COUNT - 一行代码不超过 120 个字符 ## 异常处理 - 禁止在 Controller 层捕获通用 Exception必须细化到具体异常 - 使用自定义 BusinessException 承载业务错误码 - 所有 API 返回统一包装为 ResultT 对象 - 异常日志必须打印堆栈log.error(操作失败, e)不能只打印 e.getMessage() ## 依赖注入 - 优先使用构造器注入结合 RequiredArgsConstructor - 禁止使用 Autowired 字段注入 ## 日志规范 - 使用 SLF4J Logback禁止 System.out.println - 入口方法必须打印入参日志敏感字段脱敏 - 耗时操作必须打印执行时间 ## 空值处理 - 方法入参使用 Valid 或 NotNull 校验 - 返回集合时禁止返回 null使用 Collections.emptyList() - Optional 仅用于返回值不用于字段和方法参数.claude/rules/api-design.md—— API 设计规范--- title: REST API 设计规范 description: Spring Boot 项目的接口设计规范 trigger: 操作 Controller 或 DTO 文件时自动加载 --- # REST API 设计规范 ## 路径规范 - 使用 RestController RequestMapping 定义基础路径 /api/v1 - 路径命名使用复数名词小写中划线/api/v1/user-profiles - HTTP 方法语义 - GET查询资源 - POST创建资源 - PUT全量更新 - PATCH部分更新 - DELETE删除资源 ## 请求响应 - 请求 DTO 使用 javax.validation 注解进行参数校验 - 分页查询统一返回 PageResultT - 参数pageNum从 1 开始默认 1、pageSize默认 10最大 100 - 禁止在 DTO 中直接使用数据库实体类 ## 状态码 - 200成功 - 201创建成功 - 400请求参数错误 - 401未认证 - 403无权限 - 404资源不存在 - 409资源冲突如重复创建 - 500服务器内部错误 ## 响应格式 json { code: 200, message: success, data: { ... } }错误响应{code:400,message:用户名不能为空,data:null}**.claude/rules/testing.md** —— 测试规范 markdown --- title: 测试规范 description: 单元测试和集成测试编写规范 trigger: 操作 Test 文件时自动加载 --- # 测试规范 ## 技术栈 - JUnit 5Jupiter - Mockito MockitoExtension - AssertJ流式断言 ## 命名规范 - 测试类名被测试类名 Test如 UserServiceTest - 测试方法名使用 DisplayName 描述行为 - 方法体用下划线分隔shouldThrowExceptionWhenUserNotFound ## 测试结构AAA 模式 java Test DisplayName(当用户不存在时应抛出异常) void shouldThrowExceptionWhenUserNotFound() { // Arrange准备 when(userMapper.findById(1L)).thenReturn(null); // Act执行 assertThatThrownBy(() - userService.findById(1L)) // Assert断言 .isInstanceOf(BusinessException.class) .hasMessageContaining(用户不存在); }覆盖率要求分支覆盖率不低于 70%核心业务逻辑必须覆盖正常和异常路径工具类要求 100% 覆盖禁止事项禁止在单元测试中连接真实数据库使用Mock禁止测试之间相互依赖禁止使用Thread.sleep--- ## 四、Memory让 Claude 记住你的项目 如果说 Rules 是通用的行为准则Memory 就是这个项目的具体情况。 ### 4.1 Memory 的两层体系 | 类型 | 谁写的 | 存在哪里 | 用途 | |------|--------|---------|------| | **CLAUDE.md** | 你开发者 | 项目根目录、子目录、~/.claude/ | 项目背景、架构、技术栈、团队规范 | | **Auto Memory** | Claude 自己 | ~/.claude/projects/project/memory/ | 从对话中学习的偏好、踩过的坑、调试技巧 | ### 4.2 CLAUDE.md 的层级设计 CLAUDE.md 可以放在多个位置形成层级覆盖~/.claude/CLAUDE.md ← 用户级你个人的偏好所有项目通用./CLAUDE.md ← 项目级当前项目的核心记忆./src/main/java/CLAUDE.md ← 目录级Java 代码的特殊规范**优先级**目录级 项目级 用户级 这意味着你可以在项目根目录放一个通用的 CLAUDE.md然后在 src/main/java/ 下放一个专门针对 Java 代码的补充记忆。 ### 4.3 项目级 CLAUDE.md 示例 一个优秀的项目级 CLAUDE.md 应该包含以下内容 markdown # 电商订单服务 ## 项目概述 - **名称**电商订单服务Order Service - **技术栈**Spring Boot 3.2 MyBatis-Plus MySQL 8.0 Redis 7 RabbitMQ - **JDK 版本**17 - **构建工具**Maven - **包名根路径**com.ecommerce.order ## 架构设计 - 分层架构Controller → Service → Mapper → Entity - 统一响应包装类com.ecommerce.order.common.ResultT - 统一分页结果com.ecommerce.order.common.PageResultT - 统一异常处理com.ecommerce.order.common.GlobalExceptionHandler - 自定义异常com.ecommerce.order.common.BusinessException - 所有 Service 接口必须继承 IServiceT实现类继承 ServiceImpl - 所有 Mapper 接口必须继承 BaseMapperT ## 数据库约定 - 主键使用 BIGINT 自增字段名 id - 逻辑删除字段统一为 deleted0未删除1已删除 - 时间字段create_time插入自动填充、update_time插入和更新自动填充 - 表名使用 t_ 前缀如 t_order、t_order_item - 字段命名使用小写下划线如 user_id、total_amount ## 核心实体 - **Order**订单主表 t_order - 字段id, order_no, user_id, total_amount, status, pay_time, deleted, create_time, update_time - **OrderItem**订单明细表 t_order_item - 字段id, order_id, product_id, quantity, unit_price, total_price - **OrderStatus** 枚举0待支付1已支付2已发货3已完成4已取消 ## 业务规则 - 订单号使用雪花算法生成18位数字字符串 - 库存扣减通过 RabbitMQ 异步处理保证最终一致性 - 支付回调需要做幂等处理基于 order_no 支付渠道 - 订单超时未支付自动取消延迟队列30分钟 ## 常用命令 - 启动项目mvn spring-boot:run - 运行测试mvn test - 代码格式化mvn spotless:apply - 打包构建mvn package -DskipTests - 启动 Redisredis-server - 启动 RabbitMQdocker run -d --name rabbitmq -p 5672:5672 -p 15672:15672 rabbitmq:3-management ## 注意事项 - 不要在 Service 层直接操作 HttpServletRequest - 金额计算使用 BigDecimal禁止使用 double/float - 所有对外接口必须记录操作日志4.4 用户级 CLAUDE.md 示例用户级的~/.claude/CLAUDE.md应该聚焦在你的个人偏好上# 我的个人偏好 ## 关于我 - 我是 Java 后端开发工程师10 年经验 - 偏好 Spring 生态熟悉微服务架构 - 英文水平一般技术术语保留英文解释用中文 ## 沟通风格 - 解释技术概念时先给结论再给原因 - 喜欢类比和示意图不喜欢长篇大论 - 代码示例要完整可运行禁止只给伪代码 ## 代码偏好 - 优先使用 Lombok除非团队明确禁止 - 喜欢用 Builder 模式创建复杂对象 - 变量命名要自解释禁止单字母变量循环 i/j 除外 - 所有公共方法必须有 Javadoc ## 工具偏好 - 数据库优先使用 MyBatis-Plus其次 JPA - 缓存优先使用 Caffeine本地其次 Redis分布式 - 单元测试使用 JUnit 5 Mockito - 日志使用 SLF4J Logback ## 排雷记忆 - 我踩过 MySQL ONLY_FULL_GROUP_BY 的坑写 GROUP BY 时要提醒 - 不喜欢在 Service 层直接抛 RuntimeException必须包装成 BusinessException - 曾经因为没处理 RabbitMQ 消息幂等导致重复扣库存4.5 Auto Memory自动记忆这是 Claude Code 最省心的功能。当你跟它说“记住这个项目的分页从第1页开始不是第0页。”Claude 会自动把这条写入~/.claude/projects/project-hash/memory/MEMORY.md下次你再在这个项目里开新 Session这条记忆会自动加载。查看自动记忆# 运行 /memory 命令Claude 会列出所有加载的记忆/memory禁用自动记忆临时CLAUDE_CODE_DISABLE_AUTO_MEMORY1claude清理自动记忆# 手动删除项目记忆目录rm-rf~/.claude/projects/project-hash/memory/五、Custom Instructions让 Claude 更懂你Custom Instructions 和 Rules/Memory 的区别很关键配置告诉 Claude 什么示例Rules“代码该怎么写”客观规范“使用构造器注入”Memory“项目是什么情况”客观事实“这个项目用 Spring Boot 3.2”Custom Instructions“我是谁、我要什么”主观偏好“我喜欢先给结论再给原因”Custom Instructions 通常放在用户级的~/.claude/CLAUDE.md中这样你在任何项目里都能享受到一致的交互体验。5.1 快速写入指令在对话中你可以随时让 Claude 记住新偏好User: 记住以后写 API 的时候分页参数默认 pageSize 不能超过 100。 Claude: 好的我把这条规则保存到项目记忆中。下次写分页接口时会自动加上这个限制。更快捷的方式是用#符号# 记住所有 Controller 方法必须在方法第一行打印入参日志Claude 会询问你要保存到哪个层级项目级还是用户级确认后自动写入对应的CLAUDE.md。六、实战为一个 Spring Boot 项目建立完整配置光看不练学不会。让我们为一个真实的 Spring Boot 项目建立完整的配置体系。Step 1创建项目目录结构mkdirorder-servicecdorder-servicemkdir-p.claude/rulesStep 2编写 Rules创建.claude/rules/java-style.md内容见上文示例。创建.claude/rules/api-design.md内容见上文示例。创建.claude/rules/testing.md内容见上文示例。Step 3编写项目级 Memory创建CLAUDE.md内容见上文示例。Step 4验证配置claude进入后输入/memoryClaude 会输出类似以下内容当前加载的配置 Rules: - .claude/rules/java-style.md (trigger: *.java) - .claude/rules/api-design.md (trigger: *Controller.java, *DTO.java) - .claude/rules/testing.md (trigger: *Test.java) Memory: - ./CLAUDE.md (项目级) - ~/.claude/CLAUDE.md (用户级) Auto Memory: - ~/.claude/projects/xxx/memory/MEMORY.md (3 条)确认关键文件已加载后就可以开始开发了。Step 5测试配置是否生效给 Claude 一个测试指令请创建一个 UserController实现用户的分页查询接口。观察生成的代码是否✅ 使用了RestController和RequestMapping(/api/v1)✅ 分页参数是pageNum和pageSize✅ 返回了ResultPageResultUserVO✅ 使用了构造器注入✅ 有 Javadoc 注释如果都符合说明你的配置体系已经生效七、配置的黄金法则7.1 什么时候用什么场景使用配置存放位置团队 Java 编码规范如必须用 LombokRules.claude/rules/java-style.md项目技术栈和数据库约定Memory (CLAUDE.md)./CLAUDE.md个人喜欢用 Builder 模式Custom Instructions~/.claude/CLAUDE.md上次踩过的坑下次别再犯Auto Memory自动写入~/.claude/projects/.../memory/特定模块的特殊规范Directory Memory子目录/CLAUDE.md7.2 最佳实践清单CLAUDE.md 保持精简官方建议不超过 200 行。太长了 Claude 会记不住拆分规则到.claude/rules/更好。Rules 要具体可操作❌ 差“写干净的代码”✅ 好“使用RequiredArgsConstructor替代Autowired”定期清理 Auto Memory运行/memory可以查看所有加载的内容把临时性的、过时的笔记删掉。用# new rule into memory快速追加对话中直接输入这个命令Claude 会提示你保存到哪个层级。测试配置是否生效开新会话后先输入/memory确认关键文件已加载再开始写代码。版本控制规则文件.claude/rules/和CLAUDE.md应该提交到 Git让团队共享。但~/.claude/下的个人配置不要提交。八、本篇小结通过本篇你应该已经✅ 理解了 Rules、Memory、Custom Instructions 三层配置的定位和区别✅ 掌握了 Rules 的拆分策略和路径匹配glob语法✅ 学会了编写项目级 CLAUDE.md 和用户级 CLAUDE.md✅ 了解了 Auto Memory 的自动记录机制✅ 为一个真实项目建立了完整的配置体系✅ 掌握了 6 条配置黄金法则