Claude Code rules 如何加载：全局规则、路径规则与 monorepo

理解 .claude/rules/ 的关键，不只是会创建 Markdown 文件，还要知道不同规则什么时候进入上下文。

如果所有规则都无条件加载，前端、后端、数据库和测试规范会同时挤进上下文；如果路径写错，Claude 又可能根本看不到对应规则。

这一篇集中讲清规则的作用域与加载方式。

第一类：无条件规则

规则文件没有 paths frontmatter 时，会作为无条件规则加载。例如：

# 全局代码要求

- Java 和 TypeScript 方法名使用 camelCase
- 禁止在业务代码中使用标准输出打印日志
- 不得把真实密钥、Token 或密码提交到仓库
- 修改外部可见行为时必须同步更新测试

这类规则适合真正跨目录、跨模块成立的内容，例如：

全局命名约定
安全底线
通用日志原则
提交和验证要求
全仓库统一的文档或测试要求

不要因为一个规则“比较重要”就让它全局加载。重要性和作用范围是两个不同概念。Controller 的职责虽然重要，但它只影响 Controller，仍然应该使用路径规则。

第二类：路径规则

路径规则在 Markdown 文件顶部使用 YAML frontmatter：

---
paths:
  - "src/api/**/*.ts"
---

# API 开发规范

- 所有外部输入必须通过项目 schema 校验
- 使用统一错误响应模型
- 新增端点时同步更新 OpenAPI 描述

当 Claude 读取与这些模式匹配的文件时，规则才会进入上下文。它不是在每次工具调用时都重新执行一次，也不是操作系统级访问控制。

常见 glob 模式包括：

模式	匹配范围
`*/.ts`	任意目录下的 TypeScript 文件
`src/*/`	`src/` 下的所有文件
`*.md`	项目根目录的 Markdown 文件
`src/components/*.tsx`	指定目录下一层的 React 组件
`src/*/.{ts,tsx}`	`src/` 下的 TS 与 TSX 文件

也可以指定多个路径：

---
paths:
  - "src/**/*.{ts,tsx}"
  - "lib/**/*.ts"
  - "tests/**/*.test.ts"
---

为什么路径规则特别重要？

假设一个 monorepo 同时包含 React 前端和 Java 后端：

my-project/
├── frontend/
├── backend/
└── .claude/
    └── rules/
        ├── global.md
        ├── frontend.md
        └── backend.md

如果前端、后端规则全部无条件加载，会带来三个问题：

浪费上下文：改一个按钮时不需要知道数据库事务规则。
分散注意力：常驻规则越多，真正相关的指令越不突出。
产生误用：Claude 可能把某一技术栈的习惯错误带到另一边。

可以这样限定前端规则：

---
paths:
  - "frontend/**/*.{ts,tsx,css}"
---

# 前端规范

- React 组件使用 PascalCase
- 优先复用项目现有设计系统组件
- 状态管理沿用当前模块已有方案
- 修改交互行为时补充对应测试

后端规则则限定为：

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

# 后端规范

- Controller 不承载业务逻辑
- 外部输入必须校验
- 数据库结构改动必须提供 migration
- 禁止在事务中执行非必要远程调用

这样处理前端文件时只加载前端规则，处理后端文件时只加载后端规则。

第三类：用户级规则

项目规则之外，还可以在用户目录配置个人规则：

~/.claude/rules/
├── preferences.md
└── workflows.md

它适合保存跨项目的个人习惯，例如：

完成修改后先说明验证结果。
在不确定需求时先列出假设。
执行破坏性命令前请求确认。
个人偏好的提交说明格式。

但个人规则不应该替团队做架构决策。比如当前项目统一使用某种错误模型，个人不应通过全局规则要求另一套模型。

官方文档说明，用户规则先加载，项目规则后加载，因此项目规则具有更高的上下文优先级。不过不要把这种加载顺序理解为程序中的硬覆盖：相互矛盾的自然语言指令仍然可能导致不稳定结果。

最可靠的做法永远是消除冲突，而不是期待 Claude 每次都正确判断谁“优先”。

Claude Code 会沿目录层级发现 CLAUDE.md。从当前工作目录向上的说明会在启动时加载；当前目录下方子目录里的 CLAUDE.md，通常在 Claude 读取对应目录文件时按需加载。

这对 monorepo 很有用：

monorepo/
├── CLAUDE.md
├── frontend/
│   └── CLAUDE.md
└── backend/
    └── CLAUDE.md

可以这样分工：

根目录 CLAUDE.md：仓库级命令、共享工具链和全局架构。
frontend/CLAUDE.md：前端启动方式、测试环境和目录事实。
backend/CLAUDE.md：后端服务、数据库依赖和本地运行方式。
根目录 .claude/rules/：通过 paths 管理可执行编码规范。

子目录 CLAUDE.md 更适合记录该区域的项目事实；细粒度编码规范仍可以集中放在根目录 rules 中，以便统一治理和查找。

多团队 monorepo 的两种组织方式

方式一：子目录 CLAUDE.md 提供团队上下文

适合各子项目启动方式、技术栈和目录结构差异明显的情况。

优点：

上下文靠近实际代码。
子团队可以独立维护自己的事实说明。
Claude 进入对应目录后更容易得到相关信息。

风险：

多个层级文件可能出现重复和冲突。
从仓库不同位置启动 Claude Code，加载集合可能不同。
规则过于分散后不容易统一审查。

方式二：根目录 rules 配合 paths

适合公司希望集中治理编码规范的情况。

优点：

规范入口统一。
可以按团队、语言和目录精确划分范围。
便于设置统一负责人和评审流程。

实践中通常会组合使用：子目录 CLAUDE.md 记录事实，根目录 rules 管理规范。

跨项目共享规则

如果多个项目使用同一套技术规范，可以通过符号链接共享规则：

ln -s ~/company-standards/java-style.md \
  .claude/rules/java-style.md

Claude Code 官方支持 .claude/rules/ 中的文件或目录符号链接。

但团队采用这种方式时，需要注意可复现性：

链接目标必须在每位开发者机器上存在。
本地绝对路径往往无法直接跨机器工作。
Windows 创建符号链接可能需要管理员权限或开发者模式。
中心规则更新后，正在运行的会话不一定立即获得新上下文。

团队可以根据基础设施选择 Git submodule、subtree、内部包、构建时同步或仓库内复制。关键不是使用哪一种工具，而是确保版本可追踪、环境可复现。

如何确认规则真的加载了？

不要只通过“让 Claude 随便写段代码”来猜测规则是否生效。更直接的方法是：

运行 /context 查看当前会话实际加载的指令来源。
使用 /memory 查看和管理相关说明文件。
检查 glob 是否真的能匹配目标路径。
查看是否从预期目录启动了 Claude Code。
排查用户、项目和子目录规则是否互相矛盾。
需要精确诊断时，使用 InstructionsLoaded Hook 记录加载事件。

如果修改了关键规则，团队应通知成员拉取最新版本，并在必要时重新开启会话。不要假设仓库里的规则文件一变化，所有既有上下文都会即时同步。

小结

规则作用域决定了上下文质量：

无条件规则只放真正全局的内容。
路径规则把专业规范限制在相关文件。
用户规则保存个人偏好，不代替团队决策。
子目录 CLAUDE.md 提供局部项目事实。
monorepo 同时利用子目录说明和根目录路径规则。
共享规则要兼顾版本追踪和跨平台可复现性。

下一篇将讨论 rules 的边界：为什么它不能代替 Hook、lint、测试和 CI，以及怎样组合成真正可靠的质量防线。