Claude Code 的规则配置方法，包括基础配置、优先级机制、子文件夹管理以及全局与项目级规则的权衡。通过 YAML 元数据限定路径范围，可实现多语言项目的精准规则控制，有效平衡便捷性与 Token 消耗。内容涵盖文件结构、最佳实践及常见问题解决，帮助开发者让 AI 遵循特定开发标准。
建议直接使用别人沉淀好的 rules，比如：来自 Anthropic 黑客马拉松获胜者的完整 Claude Code 配置集合。
Claude Code 的 Rules 是用于定义代码规范、安全限制、工作流规则的核心配置机制，能让 AI 遵循项目特定的开发标准。以下是详细配置方法：
CLAUDE.md 或用户主目录的 ~/.claude/CLAUDE.md.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 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
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML 转 Markdown 互为补充。 在线工具，Markdown 转 HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML 转 Markdown在线工具，online