Claude Code Rules 配置实战：从基础到多语言管理

高级技巧

路径特定规则

通过 YAML 前置元数据限定适用范围，避免规则全局生效导致冲突。例如针对前端 React 组件：

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

与 settings.json 配合

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

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

验证方法

保存规则后，Claude Code 会自动检测并加载，无需重启。在交互界面输入 /rules 命令即可查看当前生效规则。

2. 进阶篇：子文件夹管理

Claude Code 支持在 rules 文件夹下创建子文件夹（如 common, python, go），这是非常推荐的最佳实践，能让规则体系更清晰。

目录结构示例

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

project-root/
└── .claude/
    └── rules/
        ├── common/          # 通用规则
        │   ├── security.md
        │   └── doc-style.md
        ├── python/          # Python 专属
        │   ├── coding-style.md
        │   └── testing.md
        ├── go/              # Go 专属
        │   ├── coding-style.md
        │   └── project-layout.md
        └── java/            # Java 专属
            ├── coding-style.md
            └── spring.md

继承与扩展

如果 common 和 python 下有相同文件名管理的规则，可以在 Python 文件中声明继承关系：

This file extends common/coding-style.md with Python specific content.

配置要点

1. 保持 paths 精准匹配：每个语言的规则文件依然通过 paths 限定适用范围。
2. 通用规则配置：common 下的规则无需限定 paths（或限定为 **/*），确保对所有文件生效。
3. 优先级逻辑：子文件夹中的规则优先级依然遵循原有逻辑，路径更精准的规则会覆盖通用规则。

注意事项

• 避免嵌套过深：建议最多嵌套 2 层。
• 文件命名清晰：直观命名，如 coding-style.md 而非 rule1.md。
• 避免规则重复：通用规则只放所有语言共用的内容。

3. 全局规则 vs 项目级规则

很多开发者纠结：多种语言的规则是放在全局 ~/.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/           # 所有语言通用规则
│   ├── security.md
│   └── doc-style.md
├── python/           # Python 专属
│   ├── pep8.md
│   └── pytest.md
└── java/             # Java 专属
    ├── alibaba.md
    └── spring.md

示例：全局 Python 规则文件

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

2. 项目规则（.claude/rules/）

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

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

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

常见问题解决

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

最佳实践总结

• 模块化管理：按功能拆分规则文件，避免单个文件过大。
• 版本控制：将 .claude/ 目录纳入 Git，确保团队成员使用相同规则。
• 定期更新：根据项目发展和技术变化更新规则内容。
• 结合钩子：使用 Claude Code 的 Hooks 功能自动执行规则检查。

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