【AIGC】Claude Code Rules配置

建议直接使用别人沉淀好的rules，比如：来自 Anthropic 黑客马拉松获胜者的完整 Claude Code 配置集合。

1. Claude Code Rules 配置基础篇

Claude Code的Rules是用于定义代码规范、安全限制、工作流规则的核心配置机制，能让AI遵循项目特定的开发标准。以下是详细配置方法：

一、规则文件基础配置

1. 规则文件位置与命名

• 项目级规则（优先级最高）：项目根目录下的 .claude/rules/ 文件夹，所有 .md 文件会自动加载

  project-root/
  └── .claude/
      └── rules/
          ├── coding-style.md    # 编码风格规则
          ├── security.md        # 安全规范规则
          └── testing.md         # 测试标准规则
  

• 全局规则（跨项目复用）：用户主目录下的 .claude/rules/ 文件夹

  ~/.claude/rules/
  

• 单一文件规则（简化版）：项目根目录的 CLAUDE.md 或用户主目录的 ~/.claude/CLAUDE.md

2. 规则文件格式

规则文件使用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	最低	所有项目

关键原则：规则会自动合并，冲突时高优先级规则覆盖低优先级规则

三、高级规则配置技巧

1. 路径特定规则（最实用）

通过YAML前置元数据限定规则适用范围，避免规则全局生效导致冲突

---
paths:
  - "src/frontend/**/*.tsx"  # 仅前端React组件文件
  - "src/frontend/**/*.ts"   # 仅前端TypeScript文件
---

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

2. 规则内容编写最佳实践

1. 简洁性原则：单个规则文件控制在100行以内，避免AI处理负担过重
2. 明确性原则：使用"必须/禁止/建议"等强指令词汇，避免模糊表述
3. 分层原则：按功能拆分规则文件（编码风格、安全、测试等），便于维护
4. 可执行性原则：规则需具体可操作，如指定具体库版本、配置参数值

3. 与settings.json配合使用

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

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

四、规则生效与验证

1. 自动加载机制：保存规则文件后，Claude Code会自动检测并加载，无需重启
2. 验证方法：
   • 在Claude Code交互界面输入 /rules 命令，查看当前生效规则
   • 测试AI生成代码，检查是否符合规则要求
   • 如规则未生效，检查文件路径和命名是否正确

五、示例：完整规则配置

1. 项目级规则示例（.claude/rules/python-style.md）

---
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`模块添加类型注解

2. 全局规则示例（~/.claude/CLAUDE.md）

# 全局开发规范

## 通用安全规则
1. **必须**对所有用户输入进行验证，防止注入攻击
2. **必须**处理所有异常，避免暴露敏感错误信息
3. **禁止**使用已废弃的库函数和API

## 文档规范
1. **必须**为所有函数、类添加文档字符串
2. **建议**使用Google风格或NumPy风格文档
3. **必须**为复杂逻辑添加注释说明

## 测试规范
1. **必须**为核心功能编写单元测试
2. **建议**测试覆盖率不低于80%
3. **必须**在提交代码前运行所有测试

六、常见问题解决

1. 规则不生效：

   • 检查文件路径是否正确（.claude/rules/ 目录是否存在）
   • 确认文件扩展名为 .md
   • 检查YAML前置元数据语法是否正确
   • 重启Claude Code会话（输入 /restart 命令）

2. 规则冲突：

   • 检查是否有重复规则定义
   • 调整规则优先级（项目规则覆盖全局规则）
   • 使用路径限定减少冲突范围

3. AI忽略规则：

   • 规则是否过于复杂或冗长（建议拆分）
   • 规则表述是否明确（使用"必须/禁止"等词汇）
   • 检查是否有更高优先级规则覆盖当前规则

七、最佳实践总结

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

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

需要我给你一个可直接复制使用的Claude Code规则模板包（含编码风格、安全规范、测试标准三个常用规则文件）吗？

2. 进阶篇：Rules下建子文件夹管理不同语言

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框架规范

三、子文件夹规则配置要点

1. 保持 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 而非常量）

2. 通用规则（common）的配置技巧

通用规则无需限定 paths（或限定为 **/*），确保对所有文件生效：

# .claude/rules/common/security.md
---
paths: "**/*"  # 所有文件均适用
---

# 通用安全规则
1. **禁止**硬编码任何密钥、密码、Token
2. **必须**对用户输入做合法性校验
3. **必须**捕获并优雅处理所有异常，避免暴露堆栈信息

3. 优先级与冲突处理

• 子文件夹中的规则优先级依然遵循原有逻辑：项目级（.claude/rules/ 下所有文件）> 全局级；路径精准匹配的规则 > 通用规则。
• 若不同子文件夹的规则冲突（如 python/security.md 和 common/security.md 对同一场景有不同要求），路径更精准的规则会覆盖通用规则（比如仅匹配 .py 文件的规则会覆盖 **/* 的通用规则）。

4. 注意事项

• 避免嵌套过深：建议最多嵌套 2 层（如 rules/python/testing/unit.md 是合理的，更深则不易维护）。
• 文件命名清晰：每个 .md 文件命名要直观（如 coding-style.md 而非 rule1.md）。
• 避免规则重复：通用规则只放所有语言共用的内容，语言专属规则仅补充该语言特有的规范。

四、验证子文件夹规则是否生效

配置完成后，可通过以下方式验证：

1. 在 Claude Code 交互界面输入 /rules 命令，会列出所有加载的规则（包括子文件夹中的）；
2. 让 AI 生成对应语言的代码（如“写一个Python工具函数”），检查是否遵循 python/ 下的规则；
3. 生成通用代码（如“写一个README说明”），检查是否遵循 common/ 下的规则。

总结

1. Claude Code 支持在 rules 下创建子文件夹分类管理规则，会递归加载所有 .md 规则文件；
2. 推荐按“通用（common）+ 语言专属（python/go/java）”分层，配合 paths 元数据精准限定规则适用范围；
3. 子文件夹规则的优先级逻辑不变，路径精准匹配的语言规则会覆盖通用规则，避免冲突。

3. 全局规则 or 项目级规则？

问题：多种语言的rulse是放在全局规则~/.claude/rules/ 下面还是按项目所需语言，仅把需要的语言放在项目.claude/rules/ 下面？所有语言都放全局规则下面要方便些，但是会不会把不需要的语言的rules也加载到上下文消耗更多token?

这个问题非常关键，核心要解决「便捷性」和「Token 效率」的平衡——结论先给到你：推荐把所有语言的通用规则放在全局 ~/.claude/rules/ 下，项目仅放该项目专属的定制化规则。下面详细解释原因和实操方案：

一、核心问题：Token 消耗的真相

你担心的「加载不需要的语言规则消耗 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。

三、实操配置方案（兼顾便捷+Token 效率）

1. 全局规则（~/.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命名变量/函数

2. 项目规则（.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%）

3. 关键优化：避免 Token 浪费的小技巧

1. 精准配置 paths：所有语言专属规则必须指定 paths: **/*.xx，绝对不要省略；
2. 拆分规则文件：单个规则文件控制在 200 行以内，Claude 加载更高效；
3. 使用排除规则：对不需要的文件类型做排除，减少匹配范围：

   ---
   paths:
     - "**/*.py"
     - "!tests/**/*.py"  # 排除测试文件，避免规则冗余
   ---
   

4. 验证加载结果：输入 /rules 命令，查看当前生效的规则列表，确认只有匹配当前文件的规则被加载。

四、Token 消耗验证方法

你可以通过以下步骤验证规则加载的 Token 消耗：

1. 全局配置好所有语言规则（带精准 paths）；
2. 在项目中打开一个 .py 文件，输入 /rules 命令；
3. 查看输出的规则列表，只会显示 common/ + python/ 下的规则，java//go/ 规则不会出现在列表中；
4. 这说明这些未匹配的规则完全没有进入上下文，不会消耗 Token。

总结

1. 全局放所有语言的通用规则（带精准 paths）是最优选择，既便捷又不浪费 Token；
2. 项目规则仅存放定制化内容，无需重复配置通用规则，减少维护成本；
3. Token 消耗的关键是 paths 元数据的精准匹配，而非规则文件的存放位置。

这种配置方式既能享受「一次配置、多项目复用」的便捷，又能保证 Token 效率，是团队协作和个人开发的最佳实践。