K3.3.3 Task 3.3

文件类型还是文件位置——决定了用哪种机制

目录 CLAUDE.md 按位置范围。Glob 模式规则按文件类型范围。两者都不是绝对优越。正确选择取决于一个问题：规范是由文件在哪里决定的，还是由文件是什么类型决定的？

决策框架

范围机制示例
按类型分散的文件Glob 模式规则测试文件在 20+ 目录中
按位置集中的文件目录 CLAUDE.md后端代码在 src/backend/
所有文件根 CLAUDE.md通用编码标准

按类型分散： 测试文件（*.test.ts）在每个模块目录中存在。CSS 模块（*.module.css）分布在 src/ 各处。配置文件（*.yaml、*.json）出现在 config/、src/config/、deploy/、.github/workflows/。一个 glob 模式规则（paths: ["**/*.test.ts"]）用一个文件覆盖全部。

按位置集中： 一个自包含的后端在 src/backend/，有自己的模型、路由和中间件。所有后端文件在这里，别处没有后端专属文件。src/backend/ 中的目录 CLAUDE.md 更简单——不需要 glob 语法。

为什么目录 CLAUDE.md 对分散文件不管用

CSS 规范文件放在 src/styles/CLAUDE.md，编辑 src/styles/ 中的文件时加载。编辑 src/components/Button.module.css 或 src/pages/Home.module.css 时不加载。规范是关于文件类型的，但机制按目录范围。

修复：规则文件中用 paths: ["**/*.module.css"]。一个文件覆盖项目中每个 CSS 模块，不管目录。

新目录让问题更严重。一个有 src/api/v1/CLAUDE.md 和 src/api/v2/CLAUDE.md 的项目有 v1 和 v2 的规范。开发者创建 src/api/v3/ 时，没有规范加载。CLAUDE.md 必须手动创建——30% 的时候被忘记。

paths: ["src/api/**/*"] 的 glob 规则在 v3 出现那一刻就自动覆盖。不需要手动设置，不会忘记。

规模化的重复问题

一个有测试规范重复在 8 个目录 CLAUDE.md 文件中的项目跟踪了一个季度的维护成本：

  • 测试规范改了 4 次
  • 每次改动需要更新 8 个文件（每次 45 分钟）
  • 4 次改动中 3 次至少漏掉一个目录
  • 不一致的测试生成在发现前持续 2-5 天

季度成本：3 小时更新 + 3 次不一致事件。

迁移到单个 .claude/rules/testing.md 加 paths: ["**/*.test.*"] 后三个问题全部消除。一个文件更新。一个事实来源。零漏掉的目录。

18 个月间，一个项目从 3 个目录 3 个 CLAUDE.md 文件增长到 25 个目录 25 个文件。审计发现：60% 内容重复、15% 过时文件、30% 新目录完全缺少 CLAUDE.md。结构性修复——共享规范用 glob 规则、只有真正目录专属的内容用目录 CLAUDE.md——把 25 个文件减到约 10 个，消除重复并自动覆盖未来目录。

叠加加载：所有东西堆叠

Claude Code 配置是叠加的。编辑 src/backend/auth.test.ts 时：

  1. 根 CLAUDE.md 加载——通用标准适用于所有文件
  2. src/backend/CLAUDE.md 加载——后端规范适用于 src/backend/ 中的文件
  3. .claude/rules/testing.md 加载——测试规范匹配 *.test.*

三个同时加载。没有优先级系统。没有”最具体的赢”。没有覆盖或取消。每个适用的配置加入上下文。

这种叠加行为是分层架构的基础：通用标准始终存在，领域专属规范叠加其上，跨领域模式在文件匹配时加入。

什么时候目录 CLAUDE.md 是正确选择

Glob 模式规则不是严格优越的。对于没有分散文件的有界目录，目录 CLAUDE.md 更简单：

  • 不用写 glob 语法
  • 不用维护 YAML frontmatter
  • 规范和它管辖的代码在一起
  • 当范围确实匹配单个目录树时同样有效

测试：这些规范需要应用到这个目录以外的文件吗？如果不需要，目录 CLAUDE.md 就行。如果需要——如果这种类型的文件存在于项目其他地方——用 glob 模式规则。

企业模式：三层

大型 monorepo 有集中的团队区域和分散的跨领域类型：

第 1 层：根 CLAUDE.md — 通用标准（安全基础、代码质量）。小，始终加载。

第 2 层：目录 CLAUDE.md — 团队专属规范。每个团队一个，在他们集中的区域内。团队之间不重复。

第 3 层：.claude/rules/ 加 paths — 跨领域类型。测试规范（**/*.test.*）、配置规范（**/*.config.*）、迁移规范（**/migrations/**/*）。每个关注点一个文件，通过 glob 覆盖所有目录。

这把 45 个目录 CLAUDE.md 的蔓延减少到约 15-20 个范围良好的文件，消除重复，并在项目增长时自动覆盖新目录。

一句话总结： Glob 模式规则按文件类型跨整棵树范围；目录 CLAUDE.md 按位置范围——在各自范围匹配的地方使用，结合使用实现分层覆盖。