AI教程之ClaudeCodeEP07:rules详解

什么是rules

rules本质上和CLAUDE.md文件没有任务区别，本质上都是一段被注入上下本的文本。它的优势就是，可读性高，可以按主题拆分成多个文件，而且支持按条件加载。

全局加载(无paths字段)

这种rule和CLAUDE.md一样，开局就会被加载进上下文。唯一好处就是可读性高。

# 通用编码规范（全局生效）

## 代码可读性
- 所有公开的类、方法、常量必须有清晰的注释（Java：Javadoc）。
- 方法长度不得超过 60 行，类长度不得超过 500 行（特殊情况需在 PR 中说明）。
- 避免嵌套超过 3 层（if/for/while 等）。

## 命名约定
- 变量名、方法名使用 `lowerCamelCase`，常量使用 `UPPER_SNAKE_CASE`。
- 布尔变量/方法以 `is`、`has`、`can` 开头（如 `isActive`、`hasPermission`）。
- 集合类型变量使用复数命名（如 `List<Product> products`，而不是 `productList`）。

## 禁止使用的不良模式
- ❌ 禁止使用 `printStackTrace()`（必须用日志框架输出）。
- ❌ 禁止捕获 `Exception` 后什么都不做（至少记录日志）。
- ❌ 禁止在循环中拼接字符串（应使用 `StringBuilder`）。
- ❌ 禁止返回 `null` 来代替空集合（应返回空集合如 `Collections.emptyList()`）。

## 异常处理
- 业务异常使用自定义的 `BusinessException`（继承 `RuntimeException`）。
- 不要吞掉中断异常（`InterruptedException`）而不恢复中断标志。

## 依赖注入
- 优先使用构造器注入（Spring 项目中）。
- 不要在字段注入 (`@Autowired`) 上添加 `final`，那会直接编译报错；正确做法是 `private final XxxService xxxService` + 构造器。

## 日志规范
- 使用 Lombok `@Slf4j` 或显式定义 Logger。
- 日志级别：`info` 记录关键业务节点，`debug` 记录详细参数，`error` 必须包含异常堆栈。
- 禁止在日志中输出敏感信息（密码、token、身份证号等）。

条件加载(有paths字段)

---
paths: "**/controller/**/*.java"
---

# REST API 风格
- 使用复数名词作为路径：`/api/v1/products`，而不是 `/api/v1/product`。
- HTTP 方法映射：
  - GET → 查询（分页使用 `?page=0&size=20`）
  - POST → 创建（响应 201 Created + Location header）
  - PUT → 全量更新
  - PATCH → 部分更新
  - DELETE → 删除
- 路径参数统一用 `@PathVariable`，请求体用 `@Valid` + `@RequestBody`。
- 在 Controller 方法上显式注解 `@ResponseStatus`（如 POST 返回 201）。

条件加载的rule在启动时不加载进上下文，只有在 Claude 将要读取或编辑与 paths 模式匹配的文件时才会加载，不匹配时不加载，任务完成后会从上下文中移除。

这种让 AI 只在需要时获取详细信息的技术被称为渐进式披露 (Progressive Disclosure)

paths 字段怎么配置

paths 字段写在 Markdown 规则文件开头的 YAML frontmatter 中。

什么时候拆解CLAUDE.md 拆到 rules

当 CLAUDE.md 的内容开始影响 AI 的响应质量，或者难以维护时，就应该拆分。具体有以下 4 个明确的信号：

CLAUDE.md 超过 200 行

官方建议 CLAUDE.md 保持在 200 行以内。超过后，AI 的上下文窗口会被大量规则占据，导致：

理解准确率下降（尤其长对话中）
后续指令容易被“遗忘”
响应速度变慢

✅ 此时拆分：把非核心、非全局的规则移到 .claude/rules/ 下，CLAUDE.md 只保留项目最核心的技术栈、架构边界、禁止事项

规则只针对特定文件类型或路径

你的规则出现大量类似这样的描述：

“所有 *Controller.java 必须……”
“在 src/test/ 下的测试类应该……”

这意味着这些规则是有条件生效的，如果继续放在CLAUDE.md里就会浪费上下文,因为AI在处理无关需求仍会加载它们。

✅ 此时拆分：为不同文件类型创建带 paths 的规则文件，例如：

.claude/rules/controller.md → paths: "**/*Controller.java"
.claude/rules/testing.md → paths: "**/*Test.java", "**/test/**"

不同的关注点/主题相互独立

即便都是全局规则（无 paths），如果内容涉及多个不相关的领域（如数据库设计、日志规范、Git 提交格式），放在一个文件里会变得臃肿且难以查找。

✅ 此时拆分：按主题拆分到不同的规则文件（仍可不带 paths），例如：

.claude/rules/database.md → 数据库命名、索引、迁移规范
.claude/rules/logging.md → 日志级别、格式、敏感信息屏蔽
.claude/rules/git-commit.md → Conventional Commits 格式

💡 即使不带 paths，Claude 也会一次性加载所有规则文件，但按主题拆分便于人类维护和审阅。

团队协作出现冲突

当多个人维护同一个 CLAUDE.md 时，Git 合并冲突会频繁发生，尤其是不同职能的开发者（架构、后端、测试）在文件不同区域添加规则

✅ 此时拆分：每个人/每个团队维护自己的规则文件，互不干扰。例如：

架构团队维护 .claude/rules/‌Architecture.md
后端团队维护 .claude/rules/backend.md
测试团队维护 .claude/rules/testing.md

拆解前后对比

拆解前

# 技术栈：SpringBoot 3.2
# 包结构：...
# Controller 规范：所有 Controller 返回 Result...
# Service 规范：必须使用 @Transactional...
# Repository 规范：继承 JpaRepository...
# 测试规范：使用 @SpringBootTest...
# 前端规范：React 组件必须使用函数式...
# 日志规范：使用 @Slf4j...
# ... 200+ 行后

拆解后

# 项目核心
- JDK 17 + SpringBoot 3.2
- 包结构：controller/service/repository/…
- 统一响应：Result<T>
- 禁止字段注入（必须构造器注入）
- 实体类禁止使用 @Data

（其余规范见 .claude/rules/）

.claude/rules/
├── controller.md      (paths: **/*Controller.java)
├── service.md         (paths: **/*Service*.java)
├── repository.md      (paths: **/*Repository.java)
├── testing.md         (paths: src/test/**)
├── frontend.md        (paths: frontend/**)
├── logging.md         (全局，无 paths)
└── git-commit.md      (全局，无 paths)