25 Claude Code 自定义规则：让你的 AI Agent 懂你的代码库

风难追

345人浏览 · 2026-08-02 09:15:00

风难追 · 2026-08-02 09:15:00 发布

摘要：本文详细介绍了 CLAUDE.md 文件的作用和使用方法，这是一个放置在项目根目录的 Markdown 配置文件，能够让 Claude Code AI 编程助手在生成代码时自动遵循项目的编码规范、技术栈和架构约定。文章通过对比安装规则前后的代码生成效果，展示了 CLAUDE.md 如何显著提升代码一致性；提供了针对微服务、前端 React、Python 数据项目等不同场景的规则编写示例；分享了实际项目中的部署经验和踩坑教训；并从团队协作角度探讨了 CLAUDE.md 作为规范对齐器和新人入门文档的价值。最后，文章还给出了规则写错时的修复方法和最佳实践建议。

封面：配图

你有没有遇到过这种情况：跟 Claude Code 说"帮我写一个 Service 层的 CRUD"，它生成的代码确实能跑，但风格跟你的项目格格不入——命名用下划线而不是驼峰、异常类型不对、日志框架不是你用的那个、注释风格完全不一致。

你当然可以在每次对话的时候告诉它一遍"用 Lombok、不要写 getter/setter、日志用 Slf4j、日期用 LocalDateTime"。但每次都讲一遍，你不烦 AI 也烦。

有没有办法让 Claude Code 一次学会你项目的规矩？

有。CLAUDE.md。

这个文件放在你项目根目录，Claude Code 每次进入项目时自动读取。你在这个文件里写清楚项目的规则——编码规范、技术栈、架构约定、命名风格、禁止事项。Claude Code 看到这个文件后，生成代码时会严格遵循你的规则。

相当于给 AI Agent 装了一个"项目记忆卡"。装上了，它就懂了。

CLAUDE.md 到底是什么？

CLAUDE.md 是一个纯 Markdown 文件，放在项目根目录，Claude Code 会话启动时自动加载到上下文中。它不是隐藏文件，不写 . 开头，就叫 CLAUDE.md。

它的工作原理很简单：每次你开一个新的 Claude Code 对话，它都会读到这个文件的内容，并按照文件里的指令调整自己的行为。

类比一下：就像你给新入职的程序员发了一份《团队编码规范手册》，他先读一遍，然后开始写代码。CLAUDE.md 就是这个"手册"的 AI 版本——内容更结构化，AI 的理解更精确。

这里有一个很多人不知道的细节——CLAUDE.md 不只影响代码生成。它还影响 Claude Code 的行为模式。你在文件里写"这个项目使用微服务架构，服务间通过消息队列通信"，Claude Code 在分析你的代码或生成新的代码时，就会带着这个认知去工作。比如它看到你在一个 Service 里直接调用另一个模块的 Repository，会说"微服务架构中不建议跨服务直接访问数据层"。

你给它越多上下文，它的行为就越贴你的实际情况。

CLAUDE.md 还支持全局规则——你把通用规则放在用户主目录的 ~/.claude/CLAUDE.md 里，所有项目都共用。比如"所有代码必须使用中文注释""生成代码时必须有完整的错误处理""变量名禁止使用拼音"这类跨项目规则，写一次就行。项目根目录的 CLAUDE.md 会跟全局规则合并，项目级规则优先级更高。

这个分层设计挺合理的。全局规则管你个人习惯，项目规则管团队和业务约定。

写第一份 CLAUDE.md

我自己项目的 CLAUDE.md 长这样：

# 项目概览
这是一个 SaaS 订单管理系统，基于 Spring Boot 3.2 + Java 17。
前后端分离，前端用 React + TypeScript，后端是纯粹的 REST API。
数据库用 MySQL 8.0，ORM 用 JPA + Hibernate，缓存用 Redis。
编码规范
Java 命名：驼峰命名法，类名首字母大写，方法名和变量名首字母小写
所有 DTO 用 record 类型，不要用 class
Controller 层返回统一响应体 ApiResult&lt;T&gt;，不要直接返回实体
异常统一用 BusinessException(ErrorCode, message) 抛出，全局异常处理
禁止在 Controller 里写业务逻辑，一律委托给 Service 层
日志用 Lombok 的 @Slf4j，不要直接写 LoggerFactory.getLogger
日期时间一律用 java.time.LocalDateTime，不用 Date 或 Calendar
数据库时间字段用 datetime(3)，对应 Java 的 LocalDateTime
所有公开方法必须写 JavaDoc
测试用 JUnit 5 + Mockito，不用 TestNG
架构约定
包结构：controller → service → repository → entity → dto
Service 层接口和实现分离：OrderService 接口 + OrderServiceImpl 实现
Repository 只做数据存取，不做业务判断
跨 Service 的调用通过事件驱动，不用直接注入
Redis 缓存只缓存读多写少的数据，非核心数据不做缓存
禁止事项
不要使用 Hibernate 的 n+1 查询
不要写原生 SQL 字符串拼接（用 QueryDSL 或 @Query）
不要使用 ThreadLocal 存储上下文（用请求范围的 Bean）
不要在 Entity 里放 @Transient 字段做业务逻辑
不要用 @Autowired 注入字段，用构造方法注入

这份文件写了一百多行，花了我 20 分钟。装上去之后，效果立竿见影。

CLAUDE.md 规则文件的内容结构展示：项目概览、编码规范、架构约定、禁止事项四个核心区块

装了规则前后的对比

安装 CLAUDE.md 前后，让 Claude Code 执行同一个任务——"写一个用户积分查询接口"。

没装规则时生成的代码：

@RestController
@RequestMapping("/users")
public class UserController {
    @Autowired
    private UserService userService;
@GetMapping("/points")
public ResponseEntity&lt;List&lt;PointEntity&gt;&gt; getPoints(@RequestParam Long userId) {
    List&lt;PointEntity&gt; points = userService.findUserPoints(userId);
    return ResponseEntity.ok(points);
}
}

这里踩了多少坑？@Autowired 字段注入——禁止事项里明确写了不要。ResponseEntity 裸返回——规则说了要用 ApiResult<T>。PointEntity 直接暴露给前端——典型的 DTO 混淆实体的问题。

装了规则后生成的代码：

@Slf4j
@RestController
@RequestMapping("/users")
public class UserController {
private final UserService userService;

public UserController(UserService userService) {
    this.userService = userService;
}

@GetMapping("/points")
public ApiResult&lt;UserPointsResponse&gt; getPoints(@RequestParam Long userId) {
    log.info("查询用户积分: userId={}", userId);
    UserPointsResponse response = userService.getUserPoints(userId);
    return ApiResult.success(response);
}
}

构造方法注入、Slf4j 日志、统一响应体——全部精准命中规则。更关键的是，生成的 Service 层代码也遵守了"接口+实现分离"的约定，创建了 UserPointsService 接口和 UserPointsServiceImpl 实现类，甚至还自动生成了 UserPointsResponse DTO record。

这种规则一次配置、永久受益。你的项目写得越规范，Claude Code 生成代码的准确率越高。极端情况下，一份好规则能让 Claude Code 的代码通过率从 40% 飙升到 85%。

CLAUDE.md 规则配置前后代码生成效果对比：左侧无规则时命名混乱、框架不匹配、违规使用 @Autowired；右侧有规则后完全符合项目规范

针对不同场景写不同规则

CLAUDE.md 不只是一个"编码规范"文档。你可以让它适应不同的场景需求。

场景一：微服务项目

# 微服务架构规则
每个服务独立数据库，禁止跨服务直接查询表
服务间通信通过 Feign 客户端 + 熔断（Sentinel）
所有接口都要有幂等性设计（幂等键字段）
配置统一用 Nacos，不要写死在 application.yml

场景二：前端 React 项目

# React 前端规则
组件用 TypeScript + Function Component + Hooks
状态管理用 Zustand，不用 Redux
API 请求统一用 react-query，不用 fetch/axios 裸调
CSS 用 Tailwind CSS，不用 CSS Modules
所有组件文件用 index.tsx 导出

场景三：Python 数据项目

# 数据处理项目规则
Python 3.12+，类型标注必须完整
数据处理用 polars，不用 pandas
所有函数写 docstring（Google 风格）
测试用 pytest + hypothesis，不用 unittest
配置用 pydantic-settings，不用 os.environ

不同类型项目的 CLAUDE.md 侧重点完全不同。微服务关注通信和容错，前端关注组件和状态管理，数据项目关注类型和性能。

CLAUDE.md 在真实项目里的表现

我把我写好的 CLAUDE.md 部署到三个不同的项目里，看看实际效果：

项目 A：CRM 系统（Spring Boot + Vue）

这个项目最头疼的问题是 Controller 层和 Service 层的职责混乱。新来的开发经常在 Controller 里写 SQL 查询，或者用 Map 当 DTO 返回前端。装了规则后，Claude Code 每次生成 Controller 代码都会自动用 ApiResult<T> 包装响应、用 @Valid 注解校验参数、把业务逻辑委托给 Service 层。CI 上报的"Controller 层出现业务逻辑"的 lint 规则违规直接降到 0。

项目 B：电商平台（Spring Cloud 微服务）

团队要求每个接口都要有幂等性设计，但经常有人忘记。CLAUDE.md 里写了一条"所有写操作的接口必须实现幂等性"。装了之后，Claude Code 生成的每个 POST、PUT、PATCH 接口都会自动加上@Idempotent 注解或幂等键校验逻辑。Code Review 的时候再也不用一条一条强调"这个接口加幂等了吗"。

项目 C：内部运营工具（Python + FastAPI）

团队用了不到一周的 Python，大部分人之前是写 Java 的。这帮人写出来的 Python 代码都是"Java 风格"的——到处是类、setter/getter、冗长的工厂模式。CLAUDE.md 里写了"Pythonic 风格优先，用函数式编程代替类封装，用 dataclass 代替 DTO，用类型注解代替文档注释"。一个月后回头看，新人写出来的代码几乎看不出是 Java 转过来的。

几个踩坑后的经验

我写 CLAUDE.md 踩了几个坑，分享出来让你少走弯路。

规则要写得具体，不要模糊。

"代码规范要统一"——这种话 AI 听不懂。"所有 DTO 用 record 类型，不要用 class"——这种它就懂了。CLAUDE.md 的每一行都应该是一条可以被机器验证的指令。

但不要写满一千行。

CLAUDE.md 的内容会占用对话上下文。内容太多有两种后果：一是消耗 token，对话变贵；二是 AI 会"迷失"在大量的规则里，反而不知道该优先遵循哪条。我建议控制在 20-30 条左右，只放最重要的。

把"禁止事项"单独列一个章节。

AI 对否定词的敏感性不一样。"不要用 @Autowired"比"尽量用构造方法注入"有效得多。告诉 AI "不要做什么"比"应该做什么"更容易出精确的代码——因为它会做一个显式的检查后再生成。

版本控制 CLAUDE.md。

CLAUDE.md 本身也是项目文件，提交到 git。项目演进时规则也会变——比如数据库从 MySQL 迁移到 PostgreSQL、日志从 Logback 换到 Log4j2。CLAUDE.md 不更新，Claude Code 会一直按旧规则写代码。我每次项目技术栈变更，第一件事就是同步更新 CLAUDE.md。