12 个不带范围的规则文件浪费了 78% 的上下文预算 | Claude Code 配置

.claude/rules/ 目录让你把巨型 CLAUDE.md 拆成主题文件。但光拆只解决了一半问题——可维护性。没有 paths frontmatter，每个规则文件在每次编辑时都加载，把无关规范倒进上下文。真正的威力在于独立文件加范围化加载。

怎么工作

把 markdown 文件放到 .claude/rules/。Claude Code 递归发现它们——不需要 @import、不需要注册、不需要显式引用。

.claude/rules/
├── code-style.md
├── testing.md
├── security.md
└── api/
    └── rest-conventions.md

支持子目录。api/ 里的文件和 rules/ 根目录的文件一样被发现。

每个文件可选地包含带 paths 字段的 YAML frontmatter：

---
paths:
  - "src/frontend/**"
---
React 组件规范放这里。

有 paths 时，文件只在被编辑的文件匹配 glob 时加载。没有 paths 时，文件每次编辑都加载——和放在根 CLAUDE.md 里一样。

反模式：不带范围的规则

一个项目有 12 个规则文件，都没有 paths。每次编辑加载全部 12 个——约 4,500 token。平均只有 2-3 个文件和当前编辑相关（约 1,000 token）。意味着 78% 的规则上下文浪费在开发者当下不需要的规范上。

给每个文件加 paths frontmatter 把平均值从 4,500 降到约 1,000 token。规则还在——只是在相关时才加载。

把文件合并成更少更大的文件没有帮助。四个大文件不带范围仍然每次编辑都加载所有东西。token 总量不变。文件少了只意味着更大、更难维护的块，仍然缺少范围。

正确的组织模式

区分技术专属和跨领域规则：

文件	paths	何时加载
`react.md`	`["src/frontend/**"]`	编辑前端文件时
`python.md`	`["src/backend/**"]`	编辑后端文件时
`terraform.md`	`["infra/*/.tf"]`	编辑 Terraform 文件时
`testing.md`	（无）	每次编辑
`security.md`	（无）	每次编辑
`api-design.md`	（无）	每次编辑

技术规则范围到对应目录。跨领域规则（测试、安全、API 设计）处处适用因为不管什么技术都相关。React 规则在编辑 Terraform 时永远不加载。Terraform 规则在编辑 React 时永远不加载。但安全规则始终存在。

跨目录文件的 Glob 模式

测试文件经常在每个模块目录里：src/auth/auth.test.ts、src/billing/billing.test.ts、lib/utils/utils.test.ts。不能按目录范围因为测试到处都是。

Glob **/*.test.ts 匹配所有测试文件，不管目录深度。一个带这个模式的规则文件替代了否则需要在每个模块目录里各放一个 CLAUDE.md 的做法——每个包含相同的测试规范，每个在规范变化时需要单独更新。

---
paths:
  - "**/*.test.ts"
  - "**/*.spec.ts"
---
测试规范在这里。

这就是 .claude/rules/ 加 paths 比子目录 CLAUDE.md 更灵活的原因。目录级文件按位置范围。Glob 范围的规则按文件模式范围——它们跨越整个项目树。

调试：规则不加载

如果规则文件存在、内容正确但规范没被应用，检查 paths glob。terraform/*.tf 这样的模式漏掉了 terraform/modules/networking.tf 里的文件——你需要 terraform/**/*.tf 带递归通配符。这是最常见的失败模式：文件在那里，内容对，但 glob 没匹配到正在编辑的文件。

规则文件不需要 @import 来被发现。如果文件在 .claude/rules/ 下任何位置，Claude Code 就能找到它。如果没加载，问题在 paths 模式，不是缺少引用。

从巨型 CLAUDE.md 迁移

一个 400 行覆盖 6 个主题的 CLAUDE.md 一步迁移：把每个章节提取到 .claude/rules/ 下自己的文件、在合适的地方加 paths frontmatter、从 CLAUDE.md 删除内容。

保留原始措辞。内容是随时间打磨的——从头重写有丢失细微规范的风险。改进是结构性的（模块化和范围化），不是编辑性的。

不要同时保持 CLAUDE.md 内容和规则文件都活跃。重复配置有矛盾风险和双倍加载同样规则的问题。

不存在的东西

同一目录多个 CLAUDE.md — 每个目录层级只识别一个 CLAUDE.md。
按章节标题范围 — 一个文件内的章节标题不控制哪些部分加载。整个文件要么加载要么不加载。
优先级排序 — 规则文件不比 @import 引用有更高或更低优先级。它们是不同机制，都是项目级。
文件数量限制 — .claude/rules/ 能包含的文件数没有实际限制。

一句话总结： 独立文件实现模块化，paths frontmatter 实现范围化加载——没有两者都做，你要么有一个巨型文件，要么有一堆到处都加载的文件。