Claude Code Rules 配置指南：从基础到进阶的最佳实践

规则优先级与作用域

当多个规则同时存在时，系统会自动合并，冲突时高优先级规则覆盖低优先级规则。理解这个层级关系能避免很多意想不到的行为：

进阶：分层管理与子文件夹

为了应对多语言项目，Claude Code 支持在 rules 文件夹下创建子文件夹（如 common, python, go, java 等）。这是非常推荐的实践，能让规则体系更清晰。

推荐的目录结构

这种分层结构能让团队成员快速定位对应语言或场景的规则：

project-root/
└── .claude/
    └── rules/
        ├── common/          # 通用规则（所有语言/场景）
        │   ├── security.md  # 通用安全规范
        │   ├── doc-style.md # 通用文档注释规范
        │   └── git.md       # 通用 Git 提交规范
        ├── python/          # Python 专属规则
        │   ├── coding-style.md
        │   ├── testing.md
        │   └── security.md
        ├── go/              # Go 专属规则
        │   ├── coding-style.md
        │   └── project-layout.md
        └── java/            # Java 专属规则
            ├── coding-style.md
            └── spring.md

配置要点

1. 保持 paths 元数据精准匹配：每个语言的规则文件依然通过 paths 限定适用范围，避免不同语言规则冲突。
2. 通用规则配置技巧：通用规则无需限定 paths（或限定为 **/*），确保对所有文件生效。
3. 优先级与冲突处理：子文件夹中的规则优先级依然遵循原有逻辑。若不同子文件夹的规则冲突，路径更精准的规则会覆盖通用规则。

注意：避免嵌套过深，建议最多嵌套 2 层。文件命名要直观，避免规则重复。

策略：全局还是项目级？

很多开发者纠结于：多种语言的规则是放在全局 ~/.claude/rules/ 下面，还是按项目所需语言仅放在项目 .claude/rules/ 下面？

核心要解决的是「便捷性」和「Token 效率」的平衡。结论是：推荐把所有语言的通用规则放在全局 ~/.claude/rules/ 下，项目仅放该项目专属的定制化规则。

Token 消耗的真相

你担心的「加载不需要的语言规则消耗 Token」是合理的，但 Claude Code 有一个关键机制能避免这个问题：规则是否进入上下文，取决于 paths 元数据的匹配结果，而非文件是否存在于全局/项目目录。

简单来说：

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

实操配置方案

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

只放各语言的行业通用规范，每个文件都严格配置 paths：

~/.claude/rules/
├── common/                # 所有语言通用规则（paths: **/*）
│   ├── security.md        # 通用安全规范
│   └── doc-style.md       # 通用注释规范
├── python/
│   ├── pep8.md            # paths: **/*.py
│   └── pytest.md          # paths: **/*.py
└── java/
    ├── alibaba.md         # paths: **/*.java
    └── spring.md          # paths: **/*.java

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

---
paths: "**/*.py"
---
# Python PEP8 通用规范
1. **必须**使用 4 空格缩进，禁止 Tab
2. **必须**每行不超过 88 个字符
3. **必须**使用 snake_case 命名变量/函数

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

只补充该项目特有的规则，无需重复存放通用规则：

project-root/.claude/rules/
├── python/
│   └── project-custom.md  # 项目特有的 Python 规则
└── go/
    └── project-custom.md  # 项目特有的 Go 规则

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

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

验证与常见问题

验证方法

1. 自动加载机制：保存规则文件后，Claude Code 会自动检测并加载，无需重启。
2. 查看生效规则：在交互界面输入 /rules 命令，查看当前生效规则列表。
3. 实际测试：生成代码检查是否符合规则要求。

常见问题排查

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

最佳实践总结

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

通过以上配置，你可以让 Claude Code 完全遵循项目的开发标准，生成更符合需求的高质量代码。记得善用 paths 元数据来控制上下文大小，这是提升效率的关键。