跳转到主内容Rules:把项目规则拆成可管理的模块
上一篇讲了命令和快捷键,这篇聊 Rules——Claude Code 的模块化规则系统。
为什么还需要 Rules
第五篇我们讲了 CLAUDE.md,它是给 Claude Code 的「入职文档」,所有规则写在一个文件里。用了一段时间后你会发现一个问题:CLAUDE.md 越写越长。
安全规范、代码风格、测试要求、Git 提交格式、部署注意事项……全堆在一起,一百多行,找个东西得翻半天。改一条规则还怕影响其他的。
Rules 就是来解决这个问题的。它让你把规则按主题拆成独立的文件,每个文件管一件事。就像把一本厚手册拆成几张卡片——安全是安全的卡片,风格是风格的卡片,各管各的。
Rules 放在哪
规则文件放在 .claude/rules/ 目录下,每个 .md 文件是一条规则:
my-project/
├── .claude/
│ └── rules/
│ ├── security.md # 安全规范
│ ├── code-style.md # 代码风格
│ ├── testing.md # 测试要求
│ └── git-commit.md # Git 提交格式
├── CLAUDE.md
├── src/
└── ...
Claude Code 会自动识别这个目录下所有的 .md 文件。没有 globs 的规则始终生效,有 globs 的规则在操作匹配文件时才加载。
项目级 vs 用户级
和 CLAUDE.md 一样,Rules 也有两个作用范围:
| 位置 | 作用范围 | 适合放什么 |
|---|
项目/.claude/rules/ | 当前项目 | 项目编码规范、架构约定、团队约定 |
~/.claude/rules/ | 所有项目 | 你个人的通用偏好 |
项目级的 .claude/rules/ 应该提交到 git,这样团队里每个人用 Claude Code 时都会自动加载同一套规范。
用户级的 ~/.claude/rules/ 放你个人的偏好,比如「回复用中文」「不要过度工程化」。这些规则不跟着项目走,跟着你走。
规则文件怎么写
一个规则文件由两部分组成:frontmatter(元数据)和正文(规则内容)。
最简形式
最简单的规则文件,不需要 frontmatter,直接写内容就行:
不要在代码中使用 console.log 做日志,使用项目统一的 logger 工具。
生产代码中禁止出现 debugger 语句。
保存为 .claude/rules/no-console-log.md,完事。Claude Code 每次启动都会读到它。
带 frontmatter 的完整形式
当你需要更精细的控制——比如让规则只在特定文件类型生效——就用 frontmatter:
---
description: TypeScript 代码风格规范
globs: "*.ts,*.tsx"
---
- 不使用 `any` 类型,必须显式声明类型
- 优先使用 `interface` 而不是 `type`,除非需要联合类型
- 组件 props 用独立的 interface 定义,命名为 `XxxProps`
- 异步函数统一用 async/await,不混用 .then()
| 字段 | 说明 | 示例 |
|---|
description | 规则的简要描述 | "安全相关规范" |
globs | 文件匹配模式,只有操作匹配的文件时规则才生效 | "*.ts,*.tsx" 或 ["src/**/*.py", "tests/**/*.py"] |
alwaysApply | 设为 true 则无论是否匹配文件都始终加载 | true |
globs 是 Rules 相比 CLAUDE.md 最大的优势之一。你可以让 CSS 相关的规则只在编辑样式文件时生效,数据库规则只在碰 SQL 文件时触发,避免不相关的规则占用上下文。
什么时候用 Rules,什么时候用 CLAUDE.md
- 项目基本信息(技术栈、目录结构)
- 简短的通用规则(三五条)
- 部署流程说明
- 常用命令列表
- 规则按主题分类,且每类有好几条
- 需要用
globs 按文件类型匹配
- 团队多人协作,不同人负责不同规则
- 规则需要独立开关(删掉一个 .md 文件就禁用了那条规则)
一个实际的分工方式:CLAUDE.md 写项目概况和基本规则(50 行以内),细分的编码规范放 Rules。
实际示例
安全规则
.claude/rules/security.md:
---
description: 安全规范,所有代码都必须遵守
---
- 永远不要把 API 密钥、密码、token 硬编码在代码中,使用环境变量
- 不要在 git 中提交 .env 文件、密钥文件或数据库文件
- API 路由不要在响应中暴露内部错误堆栈信息,对外统一返回友好的错误消息
- 用户输入必须做校验和转义,防止注入攻击
- 敏感操作(删除、修改权限等)需要做身份验证检查
这类规则没有 globs,因为安全规范适用于所有文件。
代码风格
.claude/rules/code-style.md:
---
description: TypeScript/React 代码风格
globs: "*.ts,*.tsx"
---
- 组件用函数式写法,不用 class 组件
- 一个文件只导出一个主组件,辅助组件放同目录下单独文件
- 函数不超过 50 行,超过就拆分
- 优先用 early return 减少嵌套
- 变量命名用 camelCase,组件命名用 PascalCase
- UI 组件优先用 shadcn/ui,不要自己造轮子
测试规则
.claude/rules/testing.md:
---
description: 测试规范
globs: "*.test.ts,*.test.tsx,*.spec.ts"
---
- 测试文件和源文件放同一目录,命名为 xxx.test.ts
- 每个测试用 describe 分组,it 描述用中文
- 不要 mock 数据库,用测试专用的 SQLite 内存数据库
- 测试之间不能有依赖关系,每个测试独立运行
- 断言要具体,不要只断言 "不抛错",要断言具体的返回值
Git 提交规则
.claude/rules/git-commit.md:
---
description: Git 提交规范
---
- 提交信息用英文,格式:type: description
- type 只用这几个:feat / fix / docs / refactor / test / chore
- description 首字母小写,不加句号
- 每次提交只做一件事,不要把不相关的修改混在一起
- 提交前确认没有把 .env、node_modules、数据库文件加进去
数据库规则
.claude/rules/database.md:
---
description: 数据库操作规范
globs: "*.sql,**/db/**,**/migrations/**"
---
- 使用 better-sqlite3 的同步 API,不要用 ORM
- 每个数据库变更必须写迁移文件,不要手动改数据库
- 迁移文件命名:001_create_users.sql,序号递增
- SELECT 语句明确列出字段名,不要用 SELECT *
- 表名用复数小写(users, posts),字段名用 snake_case
用 globs 让规则按需生效
globs 是 Rules 的杀手级特性。看几个匹配模式:
# 只匹配 TypeScript 文件
globs: "*.ts,*.tsx"
# 只匹配 src 目录下的文件
globs: "src/**/*"
# 只匹配测试文件
globs: "*.test.ts,*.spec.ts"
# 匹配多种模式(用数组)
globs: ["src/**/*.ts", "lib/**/*.ts"]
# 匹配数据库相关文件
globs: "*.sql,**/db/**,**/migrations/**"
没有 globs 的规则文件始终生效(和写在 CLAUDE.md 里效果一样)。有 globs 的规则只在 Claude Code 操作匹配的文件时才会加载到上下文——这既省了上下文窗口空间,也避免不相关的规则干扰 Claude Code 的判断。
社区开源规则集
自己写规则是个不断积累的过程。好消息是,社区已经沉淀了不少现成的规则集可以直接复用。
GitHub 上的 Everything Claude Code 项目收集了大量社区贡献的规则文件,覆盖了常见的技术栈和场景。你可以把适合自己项目的规则直接复制到 .claude/rules/ 目录下,再根据实际情况微调。
不用从零开始造轮子。先用社区现成的,用着用着你就知道哪些规则对自己的项目有用,哪些需要调整。
管理技巧
命名要清晰。 文件名就是规则的标识:security.md、code-style.md、testing.md,一眼看出管什么。
一个文件管一件事。 不要把安全规范和代码风格混在一个文件里。拆开后,修改一类规则不会影响其他类。
临时禁用某条规则? 直接把那个 .md 文件改个后缀(比如改成 .md.bak)或者移到别的地方。不需要删除,也不需要注释。
别写太多。 和 CLAUDE.md 一样,规则越精炼越好。Claude Code 本身就知道怎么写好代码,你只需要写它可能犯错的地方、你项目特有的约定。20 条精准的规则比 100 条泛泛的规则有用得多。
团队协作时提交到 git。 .claude/rules/ 目录应该进版本管理。新人加入团队,clone 代码,打开 Claude Code,所有规范自动生效——不用专门培训。
下一篇讲 Skills——Claude Code 的可复用工作流封装。如果 Rules 是「什么能做什么不能做」,Skills 是「这件事该怎么一步步做」。
本篇要点:
- Rules 是 CLAUDE.md 的模块化补充,按主题拆分规则文件
- 规则文件放
.claude/rules/ 目录,每个 .md 文件是一条规则
- 用
globs 让规则只在匹配的文件类型上生效
- 项目级规则提交 git 共享,用户级规则放
~/.claude/rules/
- CLAUDE.md 写项目概况,Rules 写细分规范,配合使用