Claude Code 的规则配置机制，涵盖基础文件位置、Markdown 格式规范及优先级策略。内容包含通过子文件夹分类管理多语言规则（Python、Java、Go 等）的最佳实践，以及全局规则与项目级规则的权衡分析。重点阐述了利用 paths 元数据控制规则生效范围以优化 Token 消耗的方法，并提供验证命令与常见问题排查方案，帮助开发者建立高效、可维护的 AI 代码生成规范体系。
Claude Code 的 Rules 是用于定义代码规范、安全限制、工作流规则的核心配置机制，能让 AI 遵循项目特定的开发标准。以下是详细配置方法：
CLAUDE.md 或用户主目录的 ~/.claude/CLAUDE.md全局规则（跨项目复用）：用户主目录下的 文件夹
.claude/rules/~/.claude/rules/
项目级规则（优先级最高）：项目根目录下的 .claude/rules/ 文件夹，所有 .md 文件会自动加载
project-root/ └── .claude/ └── rules/ ├── coding-style.md # 编码风格规则 ├── security.md # 安全规范规则 └── testing.md # 测试标准规则
规则文件使用 Markdown 格式，核心结构包含：
--- # 可选 YAML 前置元数据（用于路径限定） paths: - "src/api/**/*.ts" # 仅对匹配路径生效 - "!src/api/**/*.test.ts" # 排除测试文件 name: API 开发规范 description: 项目 API 层的编码与安全标准 --- # API 开发规范（标题） ## 核心规则 1. **必须**使用 TypeScript 严格模式（"strict": true） 2. **必须**为所有 API 端点添加输入验证 3. **禁止**直接使用原始 SQL 查询，必须通过 ORM 框架 4. **建议**使用标准错误响应格式（{code: number, message: string, data: any}） ## 安全要求 - 所有敏感数据必须加密传输 - 认证令牌有效期不超过 24 小时 - 防止 SQL 注入、XSS 攻击的具体措施
| 规则类型 | 路径 | 优先级 | 作用域 |
|---|---|---|---|
| 项目特定路径规则 | .claude/rules/*.md（带 paths 元数据） | 最高 | 仅匹配路径的文件 |
| 项目通用规则 | .claude/rules/*.md（无 paths 元数据） | 高 | 整个项目 |
| 项目根 CLAUDE.md | 项目根目录/CLAUDE.md | 中 | 整个项目 |
| 全局规则 | ~/.claude/rules/*.md | 低 | 所有项目 |
| 全局 CLAUDE.md | ~/.claude/CLAUDE.md | 最低 | 所有项目 |
关键原则：规则会自动合并，冲突时高优先级规则覆盖低优先级规则
通过 YAML 前置元数据限定规则适用范围，避免规则全局生效导致冲突
--- paths: - "src/frontend/**/*.tsx" # 仅前端 React 组件文件 - "src/frontend/**/*.ts" # 仅前端 TypeScript 文件 --- # React 前端开发规范 1. **必须**使用函数组件+Hook，禁止 Class 组件 2. **必须**使用 TypeScript 类型定义所有 Props 3. **建议**组件拆分粒度：单个组件不超过 200 行代码
规则可与权限配置结合，实现更严格的安全控制：
// .claude/settings.json
{
"permissions": {
"default": "deny",
"allow": ["read(**)", "edit(**)", "bash(npm run *)", "bash(git *)"],
"deny": ["bash(rm -rf *)", "bash(sudo *)", "read(.env*)"]
}
}
/rules 命令，查看当前生效规则--- 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` 模块添加类型注解
# 全局开发规范 ## 通用安全规则 1. **必须**对所有用户输入进行验证，防止注入攻击 2. **必须**处理所有异常，避免暴露敏感错误信息 3. **禁止**使用已废弃的库函数和 API ## 文档规范 1. **必须**为所有函数、类添加文档字符串 2. **建议**使用 Google 风格或 NumPy 风格文档 3. **必须**为复杂逻辑添加注释说明 ## 测试规范 1. **必须**为核心功能编写单元测试 2. **建议**测试覆盖率不低于 80% 3. **必须**在提交代码前运行所有测试
.claude/rules/ 目录是否存在）.md/restart 命令）.claude/ 目录纳入 Git，确保团队成员使用相同规则通过以上配置，你可以让 Claude Code 完全遵循项目的开发标准，生成更符合需求的高质量代码。
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 框架规范
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 而非常量）
通用规则无需限定 paths（或限定为 **/*），确保对所有文件生效：
# .claude/rules/common/security.md --- paths: "**/*" # 所有文件均适用 --- # 通用安全规则 1. **禁止**硬编码任何密钥、密码、Token 2. **必须**对用户输入做合法性校验 3. **必须**捕获并优雅处理所有异常，避免暴露堆栈信息
.claude/rules/ 下所有文件）> 全局级；路径精准匹配的规则 > 通用规则。python/security.md 和 common/security.md 对同一场景有不同要求），路径更精准的规则会覆盖通用规则（比如仅匹配 .py 文件的规则会覆盖 **/* 的通用规则）。rules/python/testing/unit.md 是合理的，更深则不易维护）。.md 文件命名要直观（如 coding-style.md 而非 rule1.md）。配置完成后，可通过以下方式验证：
/rules 命令，会列出所有加载的规则（包括子文件夹中的）；python/ 下的规则；common/ 下的规则。rules 下创建子文件夹分类管理规则，会递归加载所有 .md 规则文件；paths 元数据精准限定规则适用范围；问题：多种语言的 rules 是放在全局规则 ~/.claude/rules/ 下面还是按项目所需语言，仅把需要的语言放在项目 .claude/rules/ 下面？所有语言都放全局规则下面要方便些，但是会不会把不需要的语言的 rules 也加载到上下文消耗更多 token?
这个问题非常关键，核心要解决「便捷性」和「Token 效率」的平衡——结论先给到你：推荐把所有语言的通用规则放在全局 ~/.claude/rules/ 下，项目仅放该项目专属的定制化规则。下面详细解释原因和实操方案：
你担心的「加载不需要的语言规则消耗 Token」是合理的，但 Claude Code 有一个关键机制能避免这个问题：
规则是否进入上下文，取决于
paths元数据的匹配结果，而非文件是否存在于全局/项目目录。
简单来说：
java/、go/、python/ 所有文件夹，当你处理一个 .py 文件时，Claude 只会加载 paths 匹配 **.py 的规则（即 python/ 下的规则 + common/ 下全局匹配的规则）；java/、go/ 下的规则因为 paths 是 **.java/**.go，不会匹配当前 .py 文件，因此完全不会进入上下文，也不会消耗 Token；paths（默认匹配所有文件）」的规则，才会无条件进入上下文，这才是 Token 浪费的根源。| 方案 | 优点 | 缺点 | 适用场景 |
|---|---|---|---|
| 全局放所有语言规则 + 项目放定制规则 | 1. 一次配置，所有项目复用； 2. Token 仅消耗匹配路径的规则； 3. 项目级可覆盖全局规则（满足定制化） | 全局规则需做好 paths 精准匹配（轻微前期成本） | 90%+ 的场景（多语言/单语言项目都适用） |
| 项目仅放所需语言规则 | 1. 极致精简，无任何冗余文件； 2. 规则文件数量最少 | 1. 多项目重复配置，维护成本高； 2. 新增项目需手动拷贝对应语言规则 | 极轻量化单语言项目（如纯 Python 小工具） |
全局放所有语言的通用规则，是「一劳永逸」的最优解——前期只需花少量时间给每个规则文件配置精准的 paths，后续所有项目都能复用，且完全不浪费 Token。
~/.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 命名变量/函数
.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%）
paths：所有语言专属规则必须指定 paths: **/*.xx，绝对不要省略；/rules 命令，查看当前生效的规则列表，确认只有匹配当前文件的规则被加载。使用排除规则：对不需要的文件类型做排除，减少匹配范围：
--- paths: - "**/*.py" - "!tests/**/*.py" # 排除测试文件，避免规则冗余 ---
你可以通过以下步骤验证规则加载的 Token 消耗：
paths）；.py 文件，输入 /rules 命令；common/ + python/ 下的规则，java//go/ 规则不会出现在列表中；paths）是最优选择，既便捷又不浪费 Token；paths 元数据的精准匹配，而非规则文件的存放位置。这种配置方式既能享受「一次配置、多项目复用」的便捷，又能保证 Token 效率，是团队协作和个人开发的最佳实践。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
查找任何按下的键的javascript键代码、代码、位置和修饰符。 在线工具，Keycode 信息在线工具，online
JavaScript 字符串转义/反转义；Java 风格 \uXXXX（Native2Ascii）编码与解码。 在线工具，Escape 与 Native 编解码在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
使用 Prettier 在浏览器内格式化 JavaScript 或 HTML 片段。 在线工具，JavaScript / HTML 格式化在线工具，online
Terser 压缩、变量名混淆，或 javascript-obfuscator 高强度混淆（体积会增大）。 在线工具，JavaScript 压缩与混淆在线工具，online