Claude Code 规则配置与最佳实践

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

高级规则配置技巧

路径特定规则（最实用）

通过 YAML 前置元数据限定规则适用范围，避免规则全局生效导致冲突。比如前端 React 组件和后端逻辑往往需要不同的规范。

---
paths:
  - "src/frontend/**/*.tsx" # 仅前端 React 组件文件
  - "src/frontend/**/*.ts"  # 仅前端 TypeScript 文件
---

# React 前端开发规范

1. **必须**使用函数组件+Hook，禁止 Class 组件
2. **必须**使用 TypeScript 类型定义所有 Props
3. **建议**组件拆分粒度：单个组件不超过 200 行代码

规则内容编写最佳实践

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

与 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 生成代码，检查是否符合规则要求
   • 如规则未生效，检查文件路径和命名是否正确

示例：完整规则配置

项目级规则示例（.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` 模块添加类型注解

全局规则示例（~/.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 完全遵循项目的开发标准，生成更符合需求的高质量代码。

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

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

如果 common 和 python 下是以相同文件名管理，则在 python 中文件要加一句引用声明：

This file extends 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 框架规范

子文件夹规则配置要点

保持 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 而非常量）

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

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

# .claude/rules/common/security.md
---
paths: "**/*" # 所有文件均适用
---

# 通用安全规则

1. **禁止**硬编码任何密钥、密码、Token
2. **必须**对用户输入做合法性校验
3. **必须**捕获并优雅处理所有异常，避免暴露堆栈信息

优先级与冲突处理

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

注意事项

• 避免嵌套过深：建议最多嵌套 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. 子文件夹规则的优先级逻辑不变，路径精准匹配的语言规则会覆盖通用规则，避免冲突。

全局规则 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 效率，是团队协作和个人开发的最佳实践。