ClaudeCoderules

Claude Code关于rules详解

2026-05-28

一个完整的rules文件是什么样的？

要编写一个 Claude Code 的规则文件（位于 .claude/rules/*.md），它需要包含两个部分：可选的 YAML Frontmatter（元数据属性） 和 Markdown 正文（规则内容），整个文件应该保持在200行代码以内。

一、Frontmatter 属性（定义“何时生效”）

Frontmatter 位于文件顶部，由 --- 包裹，使用 YAML 语法。支持的属性如下：

属性	类型	必需	说明
`paths`	string 或 string[]	否	该规则生效的路径匹配模式（glob 语法）。Claude 只有在访问匹配该模式的文件或目录时，才会加载此规则。例如 `"src/components/"` 或 `["src/", "!src/legacy/**"]`。
`description`	string	否	规则的简短描述，用于帮助 Claude 理解此规则的用途。虽然不是硬性必需，但强烈推荐，可以提高规则被正确调用的概率。
`alwaysApply`	boolean	否	如果设为 `true`，则该规则在每次会话开始时自动加载，不受 `paths` 限制。默认 `false`。慎用，以免撑爆上下文。
`priority`	number	否	优先级数字，数值越大优先级越高。当多个规则冲突时，高优先级规则覆盖低优先级。默认为 `0`。

最小示例（仅有 Frontmatter）

---
paths: "src/api/**"
description: "API 调用规范，仅在与后端交互的文件中生效"
---

完整示例

---
paths: 
  - "src/components/**/*.tsx"
  - "src/pages/**/*.tsx"
description: "React 组件编码规范"
alwaysApply: false
priority: 10
---

二、Markdown 正文属性（定义“规则内容”）

正文是普通的 Markdown，用于向 Claude 提供自然语言指令。虽然没有强制要求哪些“属性”，但遵循最佳实践会极大提升效果：

要素	推荐程度	说明
清晰的标题	必需	使用 `#` 开头，概括规则主题，例如 `# React 组件规范`。
分类分组	强烈推荐	用 `##` 二级标题划分子主题，如 `## 命名规范`、`## 状态管理`。
具体实例	强烈推荐	提供代码示例（好/坏对比），Claude 对示例的还原度远高于抽象描述。
验收标准	推荐	明确什么样的输出是可接受的，例如“所有组件必须有 PropTypes 定义”。
禁止项	推荐	明确指出“不要做什么”，例如“禁止使用 any 类型”。
引用外部文件	可选	使用 `@路径` 语法导入 `docs/` 中的详细文档。

正确示例（具体、可操作）

# React 组件规范

## 命名规范
- 组件文件名必须使用 PascalCase：`UserProfile.tsx`
- Hook 文件名必须使用 camelCase 前缀 `use`：`useAuth.ts`

## 代码结构
- 使用函数式组件，禁止 Class 组件
- 组件必须按以下顺序组织：
  1. 类型定义（Props, State）
  2. Hooks（useState, useEffect, 自定义Hook）
  3. 事件处理函数
  4. 渲染逻辑（return）

## ✅ 好例子
function Button({ label, onClick }: ButtonProps) {
  const [isLoading, setIsLoading] = useState(false);
  return <button onClick={onClick}>{isLoading ? '...' : label}</button>;
}

## ❌ 坏例子
class Button extends React.Component { ... } // 不要用 Class 组件

## 验收标准
- 每个组件文件必须导出对应的 Props 类型定义
- 所有事件处理函数必须使用 `useCallback` 包裹

三、文件自身属性（命名与位置）

文件扩展名：必须是 .md。
文件名：任意，建议语义化（如 react-components.md）。
存放位置：必须存放在.claude/rules/ 目录下。
编码：UTF-8。

四、`rules` 的底层运转机制：条件式上下文注入

普通 AI 助手需要你每次把规则复制粘贴进对话框。而 Claude Code 引入了 Path-Based Conditional Context Injection（基于路径的条件上下文注入）。

当你在终端或插件中让 Claude 修改或查看某个文件时，它的底层引擎会执行以下流水线：

[触发任务：修改 src/api/user.ts]
       │
       ▼
[扫描 .claude/rules/ 目录下的所有 .md 文件]
       │
       ▼
[读取 Frontmatter 中的 paths 表达式（或者 `paths 路径模式`）]
       │
       ▼
[命中匹配！仅将符合条件的 rules 拼接入当前 Prompt]
       │
       ▼
[未命中的 rules 自动被裁剪（不消耗 Token）]

这种机制保证了 Claude 在修改核心业务时拥有极其精准的垂直领域知识，而在做日常杂活时大脑保持绝对的清爽。

开源Rules参考

awesome-claude-code-toolkit

Everything Claude Code