Claude Code Rules 配置指南
在开发过程中，让 AI 遵循项目特定的编码规范和安全标准至关重要。Claude Code 的 Rules 机制正是为此而生，它允许你定义代码风格、安全限制和工作流规则。下面结合实战经验，聊聊如何高效配置这套系统。
基础配置与结构
文件位置与命名
Rules 的配置灵活性很高，主要取决于你的需求范围：
- 单一文件规则（简化版）：放在项目根目录的
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 | 最低 | 所有项目 |
进阶：分层管理与子文件夹
为了应对多语言项目，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
配置要点
- 保持 paths 元数据精准匹配：每个语言的规则文件依然通过
paths限定适用范围，避免不同语言规则冲突。 - 通用规则配置技巧：通用规则无需限定
paths（或限定为**/*），确保对所有文件生效。 - 优先级与冲突处理：子文件夹中的规则优先级依然遵循原有逻辑。若不同子文件夹的规则冲突，路径更精准的规则会覆盖通用规则。
注意：避免嵌套过深，建议最多嵌套 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%）
验证与常见问题
验证方法
- 自动加载机制：保存规则文件后，Claude Code 会自动检测并加载，无需重启。
- 查看生效规则：在交互界面输入
/rules命令，查看当前生效规则列表。 - 实际测试：生成代码检查是否符合规则要求。
常见问题排查
- 规则不生效：检查文件路径是否正确（
.claude/rules/目录是否存在），确认文件扩展名为.md，检查 YAML 前置元数据语法是否正确。必要时重启会话（输入/restart命令）。 - 规则冲突：检查是否有重复规则定义，调整规则优先级，或使用路径限定减少冲突范围。
- AI 忽略规则：规则是否过于复杂或冗长（建议拆分），表述是否明确（使用"必须/禁止"等词汇），检查是否有更高优先级规则覆盖当前规则。
最佳实践总结
- 模块化管理：按功能拆分规则文件，避免单个文件过大。
- 分层配置：项目规则定义项目特有规范，全局规则定义通用标准。
- 版本控制：将
.claude/目录纳入 Git，确保团队成员使用相同规则。 - 定期更新：根据项目发展和技术变化更新规则内容。
- 结合钩子：使用 Claude Code 的 Hooks 功能自动执行规则检查（如 PreToolUse 钩子运行代码格式化）。
通过以上配置，你可以让 Claude Code 完全遵循项目的开发标准，生成更符合需求的高质量代码。记得善用 paths 元数据来控制上下文大小，这是提升效率的关键。
