Claude Code Rules 配置详解

关键原则：规则会自动合并，冲突时高优先级规则覆盖低优先级规则

三、高级规则配置技巧

1. 路径特定规则（最实用）

通过 YAML 前置元数据限定规则适用范围，避免规则全局生效导致冲突

--- paths: - "src/frontend/**/*.tsx" # 仅前端 React 组件文件 - "src/frontend/**/*.ts" # 仅前端 TypeScript 文件 --- # React 前端开发规范 1. **必须**使用函数组件+Hook，禁止 Class 组件 2. **必须**使用 TypeScript 类型定义所有 Props 3. **建议**组件拆分粒度：单个组件不超过 200 行代码 

2. 规则内容编写最佳实践

1. 简洁性原则：单个规则文件控制在 100 行以内，避免 AI 处理负担过重
2. 明确性原则：使用'必须/禁止/建议'等强指令词汇，避免模糊表述
3. 分层原则：按功能拆分规则文件（编码风格、安全、测试等），便于维护
4. 可执行性原则：规则需具体可操作，如指定具体库版本、配置参数值

3. 与 settings.json 配合使用

规则可与权限配置结合，实现更严格的安全控制：

// .claude/settings.json
{
  "permissions": {
    "default": "deny",
    "allow": ["read(**)", "edit(**)", "bash(npm run *)", "bash(git *)"],
    "deny": ["bash(rm -rf *)", "bash(sudo *)", "read(.env*)"]
  }
}

四、规则生效与验证

1. 自动加载机制：保存规则文件后，Claude Code 会自动检测并加载，无需重启
2. 验证方法：
   • 在 Claude Code 交互界面输入 /rules 命令，查看当前生效规则
   • 测试 AI 生成代码，检查是否符合规则要求
   • 如规则未生效，检查文件路径和命名是否正确

五、示例：完整规则配置

1. 项目级规则示例（.claude/rules/python-style.md）

--- paths: "**/*.py" # 所有 Python 文件 --- # Python 编码规范 ## 格式要求 1. **必须**使用 4 个空格缩进，禁止使用 Tab 2. **必须**每行不超过 88 个字符（PEP 8 标准） 3. **必须**使用 UTF-8 编码 ## 命名规范 - 变量/函数：snake_case（小写字母 + 下划线） - 类名：CamelCase（首字母大写） - 常量：UPPER_SNAKE_CASE（全大写 + 下划线） ## 导入规范 1. **必须**按标准顺序导入：标准库→第三方库→本地模块 2. **禁止**使用 `from module import *`（除特殊情况） 3. **建议**使用绝对导入，避免相对导入 ## 安全要求 1. **禁止**硬编码密码、密钥等敏感信息 2. **必须**对用户输入进行验证和转义 3. **建议**使用 `typing` 模块添加类型注解 

2. 全局规则示例（~/.claude/CLAUDE.md）

# 全局开发规范 ## 通用安全规则 1. **必须**对所有用户输入进行验证，防止注入攻击 2. **必须**处理所有异常，避免暴露敏感错误信息 3. **禁止**使用已废弃的库函数和 API ## 文档规范 1. **必须**为所有函数、类添加文档字符串 2. **建议**使用 Google 风格或 NumPy 风格文档 3. **必须**为复杂逻辑添加注释说明 ## 测试规范 1. **必须**为核心功能编写单元测试 2. **建议**测试覆盖率不低于 80% 3. **必须**在提交代码前运行所有测试 

六、常见问题解决

1. 规则不生效：
   • 检查文件路径是否正确（.claude/rules/ 目录是否存在）
   • 确认文件扩展名为 .md
   • 检查 YAML 前置元数据语法是否正确
   • 重启 Claude Code 会话（输入 /restart 命令）
2. 规则冲突：
   • 检查是否有重复规则定义
   • 调整规则优先级（项目规则覆盖全局规则）
   • 使用路径限定减少冲突范围
3. AI 忽略规则：
   • 规则是否过于复杂或冗长（建议拆分）
   • 规则表述是否明确（使用'必须/禁止'等词汇）
   • 检查是否有更高优先级规则覆盖当前规则

七、最佳实践总结

1. 模块化管理：按功能拆分规则文件，避免单个文件过大
2. 分层配置：项目规则定义项目特有规范，全局规则定义通用标准
3. 版本控制：将 .claude/ 目录纳入 Git，确保团队成员使用相同规则
4. 定期更新：根据项目发展和技术变化更新规则内容
5. 结合钩子：使用 Claude Code 的 Hooks 功能自动执行规则检查（如 PreToolUse 钩子运行代码格式化）

通过以上配置，你可以让 Claude Code 完全遵循项目的开发标准，生成更符合需求的高质量代码。

2. 进阶篇：Rules 下建子文件夹管理不同语言

Claude Code 完全支持在 rules 文件夹下创建子文件夹（如 common、python、go、java 等）来分类管理不同语言/通用规则，这是非常推荐的最佳实践，能让规则体系更清晰、易维护。

如果 common 和 python 下是以相同文件名管理，则在 python 中文件要加一句:

> This file extends [common/coding-style.md](../common/coding-style.md) with Python specific content. 

一、子文件夹的核心特性

Claude Code 会递归扫描.claude/rules/ 目录下的所有层级，只要是 .md 格式的规则文件，无论放在多少级子文件夹中，都会被自动加载生效。

二、推荐的目录结构

这种分层结构能让团队成员快速定位对应语言/场景的规则，示例如下：

project-root/ └── .claude/ └── rules/ # 根规则目录 ├── common/ # 通用规则（所有语言/场景） │ ├── security.md # 通用安全规范（如敏感数据处理、注入防护） │ ├── doc-style.md # 通用文档注释规范 │ └── git.md # 通用 Git 提交规范 ├── python/ # Python 专属规则 │ ├── coding-style.md # Python 编码风格（PEP8） │ ├── testing.md # Python 测试规范（pytest） │ └── security.md # Python 安全规范（如依赖检查） ├── go/ # Go 专属规则 │ ├── coding-style.md # Go 编码风格（GoFmt） │ └── project-layout.md # Go 项目结构规范 └── java/ # Java 专属规则 ├── coding-style.md # Java 编码风格（阿里巴巴规范） └── spring.md # Spring 框架规范 

三、子文件夹规则配置要点

1. 保持 paths 元数据精准匹配

每个语言的规则文件依然通过 paths 限定适用范围，避免不同语言规则冲突：

# .claude/rules/python/coding-style.md --- paths: - "**/*.py" # 仅匹配所有 Python 文件 - "!**/*_test.py" # 排除测试文件（可选） --- # Python 编码规范 1. **必须**遵循 PEP 8 标准，使用 4 空格缩进 2. **必须**为所有函数添加类型注解（Python 3.9+） 3. **禁止**使用 eval()、exec() 等危险函数 

# .claude/rules/java/coding-style.md --- paths: - "**/*.java" # 仅匹配所有 Java 文件 --- # Java 编码规范 1. **必须**遵循阿里巴巴 Java 开发手册 2. **必须**使用驼峰命名法，类名首字母大写 3. **禁止**使用魔法值（如直接写 100 而非常量） 

2. 通用规则（common）的配置技巧

通用规则无需限定 paths（或限定为 **/*），确保对所有文件生效：

# .claude/rules/common/security.md --- paths: "**/*" # 所有文件均适用 --- # 通用安全规则 1. **禁止**硬编码任何密钥、密码、Token 2. **必须**对用户输入做合法性校验 3. **必须**捕获并优雅处理所有异常，避免暴露堆栈信息 

3. 优先级与冲突处理

• 子文件夹中的规则优先级依然遵循原有逻辑：项目级（.claude/rules/ 下所有文件）> 全局级；路径精准匹配的规则 > 通用规则。
• 若不同子文件夹的规则冲突（如 python/security.md 和 common/security.md 对同一场景有不同要求），路径更精准的规则会覆盖通用规则（比如仅匹配 .py 文件的规则会覆盖 **/* 的通用规则）。

4. 注意事项

• 避免嵌套过深：建议最多嵌套 2 层（如 rules/python/testing/unit.md 是合理的，更深则不易维护）。
• 文件命名清晰：每个 .md 文件命名要直观（如 coding-style.md 而非 rule1.md）。
• 避免规则重复：通用规则只放所有语言共用的内容，语言专属规则仅补充该语言特有的规范。

四、验证子文件夹规则是否生效

配置完成后，可通过以下方式验证：

1. 在 Claude Code 交互界面输入 /rules 命令，会列出所有加载的规则（包括子文件夹中的）；
2. 让 AI 生成对应语言的代码（如'写一个 Python 工具函数'），检查是否遵循 python/ 下的规则；
3. 生成通用代码（如'写一个 README 说明'），检查是否遵循 common/ 下的规则。

总结

1. Claude Code 支持在 rules 下创建子文件夹分类管理规则，会递归加载所有 .md 规则文件；
2. 推荐按'通用（common）+ 语言专属（python/go/java）'分层，配合 paths 元数据精准限定规则适用范围；
3. 子文件夹规则的优先级逻辑不变，路径精准匹配的语言规则会覆盖通用规则，避免冲突。

3. 全局规则 or 项目级规则？

问题：多种语言的 rules 是放在全局规则 ~/.claude/rules/ 下面还是按项目所需语言，仅把需要的语言放在项目 .claude/rules/ 下面？所有语言都放全局规则下面要方便些，但是会不会把不需要的语言的 rules 也加载到上下文消耗更多 token?

这个问题非常关键，核心要解决「便捷性」和「Token 效率」的平衡——结论先给到你：推荐把所有语言的通用规则放在全局 ~/.claude/rules/ 下，项目仅放该项目专属的定制化规则。下面详细解释原因和实操方案：

一、核心问题：Token 消耗的真相

你担心的「加载不需要的语言规则消耗 Token」是合理的，但 Claude Code 有一个关键机制能避免这个问题：

规则是否进入上下文，取决于 paths 元数据的匹配结果，而非文件是否存在于全局/项目目录。

简单来说：

• 即使你在全局规则里放了 java/、go/、python/ 所有文件夹，当你处理一个 .py 文件时，Claude 只会加载 paths 匹配 **.py 的规则（即 python/ 下的规则 + common/ 下全局匹配的规则）；
• java/、go/ 下的规则因为 paths 是 **.java/**.go，不会匹配当前 .py 文件，因此完全不会进入上下文，也不会消耗 Token；
• 只有「没有配置 paths（默认匹配所有文件）」的规则，才会无条件进入上下文，这才是 Token 浪费的根源。

二、两种方案的对比与选择

结论：优先选第一种方案

全局放所有语言的通用规则，是「一劳永逸」的最优解——前期只需花少量时间给每个规则文件配置精准的 paths，后续所有项目都能复用，且完全不浪费 Token。

三、实操配置方案（兼顾便捷+Token 效率）

1. 全局规则（~/.claude/rules/）：存放「通用标准规则」

只放各语言的行业通用规范（无需修改的基础规则），每个文件都严格配置 paths：

~/.claude/rules/ ├── common/ # 所有语言通用规则（paths: **/*） │ ├── security.md # 通用安全规范（如禁止硬编码密钥） │ └── doc-style.md # 通用注释规范 ├── python/ │ ├── pep8.md # paths: **/*.py（PEP8 基础规范） │ └── pytest.md # paths: **/*.py（pytest 通用测试规范） ├── go/ │ ├── gofmt.md # paths: **/*.go（GoFmt 规范） │ └── project.md # paths: **/*.go（Go 标准项目结构） └── java/ ├── alibaba.md # paths: **/*.java（阿里 Java 开发手册） └── spring.md # paths: **/*.java（Spring 通用规范） 

示例：全局 Python 规则文件（~/.claude/rules/python/pep8.md）

--- paths: "**/*.py" # 仅匹配 Python 文件，处理其他文件时不加载 --- # Python PEP8 通用规范 1. **必须**使用 4 空格缩进，禁止 Tab 2. **必须**每行不超过 88 个字符 3. **必须**使用 snake_case 命名变量/函数 

2. 项目规则（.claude/rules/）：仅存放「项目定制规则」

只补充该项目特有的规则（覆盖全局规则中需要调整的部分），无需重复存放通用规则：

# 示例：一个 Python+Go 的项目 project-root/.claude/rules/ ├── python/ │ └── project-custom.md # paths: **/*.py（项目特有的 Python 规则，如指定依赖版本） └── go/ └── project-custom.md # paths: **/*.go（项目特有的 Go 规则，如定制化日志格式） 

示例：项目定制 Python 规则（覆盖全局规则）

--- paths: "**/*.py" --- # 项目专属 Python 规则（覆盖全局 PEP8） 1. **覆盖全局**：每行字符数放宽至 120 个（适配项目长参数场景） 2. **新增要求**：必须使用 pydantic v2.x 做数据校验 3. **新增要求**：所有函数必须添加单元测试（测试覆盖率≥90%） 

3. 关键优化：避免 Token 浪费的小技巧

1. 精准配置 paths：所有语言专属规则必须指定 paths: **/*.xx，绝对不要省略；
2. 拆分规则文件：单个规则文件控制在 200 行以内，Claude 加载更高效；
3. 验证加载结果：输入 /rules 命令，查看当前生效的规则列表，确认只有匹配当前文件的规则被加载。

使用排除规则：对不需要的文件类型做排除，减少匹配范围：

--- paths: - "**/*.py" - "!tests/**/*.py" # 排除测试文件，避免规则冗余 --- 

四、Token 消耗验证方法

你可以通过以下步骤验证规则加载的 Token 消耗：

1. 全局配置好所有语言规则（带精准 paths）；
2. 在项目中打开一个 .py 文件，输入 /rules 命令；
3. 查看输出的规则列表，只会显示 common/ + python/ 下的规则，java//go/ 规则不会出现在列表中；
4. 这说明这些未匹配的规则完全没有进入上下文，不会消耗 Token。

总结

1. 全局放所有语言的通用规则（带精准 paths）是最优选择，既便捷又不浪费 Token；
2. 项目规则仅存放定制化内容，无需重复配置通用规则，减少维护成本；
3. Token 消耗的关键是 paths 元数据的精准匹配，而非规则文件的存放位置。

这种配置方式既能享受「一次配置、多项目复用」的便捷，又能保证 Token 效率，是团队协作和个人开发的最佳实践。