3.3　应用路径专属规则，按条件加载约定

这一条考什么

考你能否用 .claude/rules/ 下带 paths 前置信息的规则文件实现“按文件路径条件加载”的约定：只有编辑匹配的文件时才加载，从而减少无关上下文和 token 消耗。核心判断是：当约定适用于散落在代码库各处的同类文件（如所有测试文件）时，用 glob 模式的路径规则比在各子目录放 CLAUDE.md 更合适。

核心概念

paths 前置信息

.claude/rules/ 中的 Markdown 文件可以在 YAML 前置信息里写 paths 字段，值为一个或多个 glob 模式：

---
paths:
  - "terraform/**/*"
---

# Terraform 约定
- 所有资源必须带 owner 和 cost-center 标签
- 禁止在模块内硬编码 region，统一用变量
- 修改 state 相关配置前先说明影响范围

没有 paths 的规则文件在会话开始时无条件加载（相当于项目 CLAUDE.md 的一部分）；带 paths 的规则只在 Claude 读取或编辑匹配这些模式的文件时才被加入上下文。

为什么能节省上下文

一个大型仓库可能有前端、后端、基础设施、数据管道等十几套约定。如果全部写在根 CLAUDE.md 里，Claude 在改一个 React 组件时也要背着 Terraform 和 SQL 迁移的规则：

• 浪费 token，挤压真正有用的上下文；
• 无关指令可能干扰判断，甚至被误用到不相关的文件上。

路径规则让“该出现的时候才出现”。改 terraform/ 下的文件时加载 Terraform 规则，改测试时加载测试规则，互不打扰。

glob 模式按文件类型生效

glob 的威力在于不依赖目录位置：

---
paths:
  - "**/*.test.tsx"
  - "**/*.test.ts"
---

# 测试约定
- 使用 Testing Library，按用户可见行为断言，避免测试实现细节
- 网络请求统一用 msw mock，不要直接 mock fetch
- 每个 describe 只覆盖一个组件或函数

---
paths:
  - "db/migrations/**/*.sql"
---

# 迁移约定
- 每个迁移必须可回滚，提供 down 脚本
- 大表加索引使用 CONCURRENTLY

**/*.test.tsx 会匹配 src/components/Button.test.tsx、packages/admin/src/pages/Users.test.tsx 等任何位置的测试文件。

路径规则 vs 子目录 CLAUDE.md

子目录 CLAUDE.md 是按目录组织的：packages/payments/CLAUDE.md 适合“这个包特有的知识”。但如果约定针对的是一类文件，而这类文件分散在几十个目录中：

• 用子目录 CLAUDE.md，你得在每个含测试的目录里放一份相同的内容，重复且难以同步；新建目录还容易漏掉。
• 用一条 paths: ["**/*.test.tsx"] 的规则，一处定义，处处生效。

判断口诀：按目录归属的知识 → 子目录 CLAUDE.md；按文件类型横跨多目录的约定 → 路径规则。

指导性 vs 强制性

路径规则仍然只是“加载到上下文的指导”，不是强制机制。如果需求是“绝对禁止编辑 db/migrations/ 下的文件”，应该用 settings 中的 permissions.deny（如 Edit(./db/migrations/**)）或 PreToolUse hook 拦截；路径规则适合承载“改这些文件时应遵循的写法”。

正确做法与反模式

• 正确：为 Terraform、测试、迁移等分别建 .claude/rules/*.md，用 paths 限定适用范围。反模式：所有约定都堆进根 CLAUDE.md，每次会话全量加载。
• 正确：用 **/*.test.tsx 这类 glob 按文件类型生效。反模式：在每个包含测试的目录里复制一份 CLAUDE.md。
• 正确：约定横跨多目录时选路径规则；某个包独有的背景知识用子目录 CLAUDE.md。反模式：反过来用子目录 CLAUDE.md 管理全仓库的测试规范。
• 正确：硬性禁止用权限或 hooks。反模式：指望路径规则“阻止”编辑。

常见陷阱

• “在每个测试目录放 CLAUDE.md”：能工作，但维护成本高、容易遗漏，题目强调“文件散布在代码库各处”时就是干扰项。
• “把所有规则放根 CLAUDE.md，用标题分节”：组织上清楚了，但仍是全量加载，没有解决 token 与无关上下文问题。
• 把路径规则当作强制措施：题干出现“绝不能”“必须保证”时，路径规则只是部分答案，硬约束要靠 permissions.deny 或 hooks。
• 把 Skill 当作路径触发机制：Skill 依赖描述匹配或手动调用，并不是“编辑某类文件就必然加载”；按文件类型自动加载的是路径规则。
• glob 写得太窄：例如只写 src/*.test.tsx，漏掉嵌套目录。应使用 **/。

实操练习

目标：建立两条路径规则，验证它们只在编辑匹配文件时生效。

1. 在仓库中准备 terraform/main.tf、src/components/Button.tsx 和 src/components/Button.test.tsx，以及 packages/admin/Users.test.tsx。
2. 创建下方两条规则文件。
3. 启动 Claude Code，先让它修改 Button.tsx，运行 /memory 或观察回答，确认测试规则和 Terraform 规则未被加载。
4. 再让它为 packages/admin/Users.test.tsx 补一个测试，确认它遵循 msw 和 Testing Library 约定。
5. 让它给 terraform/main.tf 加一个 S3 bucket，确认自动加上 owner 和 cost-center 标签。

mkdir -p .claude/rules
cat > .claude/rules/testing.md <<'EOF'
---
paths:
  - "**/*.test.tsx"
  - "**/*.test.ts"
---
# 测试约定
- 用 Testing Library 按用户可见行为断言
- 网络请求一律用 msw mock
EOF

cat > .claude/rules/terraform.md <<'EOF'
---
paths:
  - "terraform/**/*"
---
# Terraform 约定
- 所有资源必须带 owner 与 cost-center 标签
EOF

claude -p "给 terraform/main.tf 增加一个 S3 bucket 资源" --allowedTools "Read,Edit,Write"
git diff terraform/main.tf

检查结果：生成的 bucket 带有两个标签；修改 React 组件的会话中没有出现 Terraform 相关的提示或行为。

自测清单

• .claude/rules/ 文件中的 paths 字段写在哪里？取值格式是什么？
• 带 paths 与不带 paths 的规则文件，加载时机有什么不同？
• 路径规则为什么能减少 token 消耗和无关干扰？
• 测试文件散布在 30 个目录里，为什么路径规则优于子目录 CLAUDE.md？
• 什么场景应该仍然使用子目录 CLAUDE.md？
• 需求是“禁止编辑迁移目录”，路径规则够不够？还需要什么？