---
description: Create Cursor Rules - 编写 .mdc rules 规则的元规则。触发：用户要求创建、修改规则mdc、添加编码标准、设置项目约定、配置文件特定模式。
alwaysApply: false
---

# Create Cursor Rules - 编写规则的规则

该规则用于指导 AI 编写高质量的 `.mdc` 规则文件：

**当用户要求创建新规则时：**

- 确定规则的应用方式（Always/Intelligently/Specific Files/Manually）
- 控制在 500 行以内
- 提供具体示例而非模糊指导
- 通过 `@规则名` 引用避免重复内容

**当规则超过 500 行时：**

- 拆分为多个可组合的规则
- 通过引用建立规则关联

---

## ⚠️ 核心原则

好的规则应当：**聚焦、可操作、范围明确**

| 推荐 ✅          | 避免 ❌                    |
| ---------------- | -------------------------- |
| 具体操作指令     | 模糊建议（"遵循最佳实践"） |
| 实际代码示例     | 仅提供抽象概念             |
| 引用文件而非复制 | 整篇粘贴代码               |
| 项目特定模式     | 重复 linter 已有的检查     |
| ≤ 500 行         | 长篇大论                   |
| 常用模式和工作流 | 极少出现的边缘情况         |
| 引用代码库示例   | 复制代码库已有内容         |

> 💡 规则应像清晰的内部文档，而非冗长的风格指南。

---

## 📐 Frontmatter 配置

```markdown
---
description: "简短描述规则用途和触发条件（包含关键词）"
alwaysApply: false
globs:
  - "**/components/**"
---
```

| 字段          | 说明                                     |
| ------------- | ---------------------------------------- |
| `description` | Agent 判断相关性的依据，应包含触发关键词 |
| `alwaysApply` | `true` 每次应用，`false` 由 Agent 决定   |
| `globs`       | 文件匹配模式（如 `**/api/**`）           |

**应用方式决策**：

| 应用方式                | `alwaysApply` | `globs`  | `description` | 使用场景       |
| ----------------------- | ------------- | -------- | ------------- | -------------- |
| Always Apply            | `true`        | -        | 可选          | 项目基础信息   |
| Apply Intelligently     | `false`       | -        | **必需**      | 工作流程       |
| Apply to Specific Files | `false`       | **必需** | 建议          | 特定目录的规范 |
| Apply Manually          | `false`       | -        | 可选          | 模板、辅助工具 |

---

## ✍️ 编写原则

**DO - 推荐**：

- ✅ 具体技术术语和文件路径
- ✅ 完整可用的代码示例
- ✅ 决策表明确条件分支
- ✅ `@filename` 引用文件而非复制
- ✅ 聚焦在常用模式和工作流

**DON'T - 避免**：

- ❌ 模糊描述（"适当地"、"合理地"、"最佳实践"）
- ❌ 仅抽象概念而无示例
- ❌ 重复代码库已有内容
- ❌ 记录所有边缘情况
- ❌ 照搬官方文档或风格指南
- ❌ 重复 linter 功能（缩进、引号等）
- ❌ 逐条记录常见工具命令（Agent 已知 npm、git 等）

---

## 🚫 规则中应避免的内容

### 1. 重复 linter 功能

```markdown
❌ 避免：使用 2 空格缩进、单引号、分号...
✅ 改进：项目特定约定（组件 PascalCase、Hook 以 use 开头）

> 💡 代码格式由 ESLint + Prettier 自动处理
```

### 2. 复制代码库内容

```markdown
❌ 避免：粘贴完整 request.ts（100+ 行）
✅ 改进：引用 @utils/request.ts + 关键配置片段
```

### 3. 记录所有边缘情况

```markdown
❌ 避免：列举所有 HTTP 状态码（200, 201, 202...599）
✅ 改进：常见状态码决策表 + 引用完整逻辑
```

---

## 📝 规则示例

### 示例 1: 用于前端组件和 API 校验规范规则mdc

```markdown
---
description: "前端组件和 API 校验规范。关键词：组件、API、校验"
alwaysApply: false
globs:
  - "**/components/**"
  - "**/api/**"
---

# 前端组件和 API 校验规范

**当在 components 目录工作时：**

- 样式一律使用 Tailwind
- 动画使用 Framer Motion
- 遵循组件命名约定

**当在 API 目录工作时：**

- 所有校验使用 zod
- 使用 zod schema 定义返回类型
- 导出由 schema 生成的类型
```

---

### 示例 2: 用于Express 服务与 React 组件规则的mdc

```markdown
---
description: "Express 服务与 React 组件模板。关键词：Express、React、模板"
alwaysApply: false
---

# Express 服务与 React 组件模板

该规则提供 Express 服务模板：

**当创建 Express 服务时使用此模板：**

- 遵循 RESTful 原则
- 包含错误处理中间件
- 设置合适的日志记录

@express-service-template.ts

---

该规则定义 React 组件结构：

**React 组件应遵循以下结构：**

- 顶部为 Props 接口
- 组件使用命名导出
- 样式放在底部

@component-template.tsx
```