1. 项目概述：GauntletAI Cursor Rules 是什么？

如果你和我一样，日常开发重度依赖 Cursor 这款 AI 驱动的 IDE，那你肯定遇到过这样的场景：每次开启一个新项目，或者在不同的项目间切换时，你都需要不厌其烦地告诉 AI 助手——“我们这里用 TypeScript，遵循 Airbnb 的 ESLint 规则，组件库是 shadcn/ui，状态管理用 Zustand……” 这些重复的上下文交代，不仅低效，还容易遗漏，导致 AI 生成的代码风格不一，甚至引入不符合项目规范的写法。

GauntletAI Cursor Rules 项目就是为了根治这个痛点而生的。简单来说，它是一个开源的、团队共享的 Cursor Rules 规则库。你可以把它理解为一套高度定制化的“AI 助手岗位说明书”或者“项目开发宪法”。通过预定义好的规则文件（ .mdc 格式），你可以让 Cursor 的 AI 助手在介入你项目的第一时间，就深刻理解你的技术栈偏好、代码规范、架构约束和最佳实践，从而生成更精准、更一致、更符合团队习惯的代码。

这个项目源自 Gauntlet AI 社区（一个以高强度和实战著称的 AI 与开发者社区）的实践沉淀。它不是某个官方团队的产品，而是一线开发者（比如 Patrick Skinner 等贡献者）在实际协作中，为了提升团队效率而自发整理和共享的智慧结晶。目前，它已经涵盖了前端 UI（如 shadcn/ui + Tailwind CSS v4）、DevOps 基础设施（Docker, Firebase）以及 AI 开发（提示工程）等多个领域的规则。最棒的是，它提供了一个极简的 CLI 工具，让你能通过一行命令，就将这些久经考验的规则部署到你的本地开发环境中。

2. Cursor Rules 的核心价值与工作原理

在深入如何使用这个规则库之前，我们有必要先搞清楚 Cursor Rules 本身到底在解决什么问题，以及它是如何运作的。这能帮助你更好地判断哪些规则适合你，以及如何定制自己的规则。

2.1 为什么我们需要规则？从“盲人摸象”到“心有灵犀”

在没有规则的情况下，Cursor 的 AI 助手（无论是 Composer 还是 Chat）就像一个刚入职的新同事，它对项目的了解是一片空白。尽管它能读取你当前打开的文件，但这种理解是局部的、临时的。当你问它“帮我创建一个登录表单组件”时，它可能会用原生 HTML 写一个，或者用你根本没安装的 UI 库，样式也可能杂乱无章。你需要反复纠正：“不，我们用 React”，“不，我们用 Tailwind CSS”，“按钮要用 Button 组件，不要用 button 标签”。

Cursor Rules 的本质，就是为 AI 助手提供 持久化的、结构化的项目上下文 。它通过 .mdc (Markdown Cursor) 文件，以接近自然语言但结构清晰的方式，告诉 AI：

1. 技术栈与依赖 ：这个项目使用 React + TypeScript，包管理器是 pnpm。
2. 代码风格与规范 ：函数使用箭头函数，组件采用默认导出，接口命名以 I 开头。
3. 架构与模式 ：数据获取使用 React Query，状态管理集中在 stores/ 目录下。
4. 组件库与设计系统 ：UI 组件一律从 @/components/ui 导入，这是基于 shadcn/ui 定制的。
5. 项目特定的约定 ：API 请求必须使用 src/lib/api-client 封装后的函数，错误处理遵循统一格式。

当这些规则被激活后，AI 助手在生成代码、回答问题、重构代码时，会优先遵循这些约定。它从一个需要你不断指导的“实习生”，变成了一个深刻理解项目背景和团队文化的“资深协作者”。

2.2 Cursor Rules 的四种类型与适用场景

Cursor Rules 不是一刀切的，它提供了四种不同的应用类型，对应不同的使用场景。理解这一点对编写和运用规则至关重要。

1. Always （始终应用）规则 ：

   • 特点 ：只要规则文件被放置在项目的 .cursor/rules/ 目录下，就会自动对所有 AI 交互生效。这是最“强势”的规则。
   • 适用场景 ： 项目级核心规范 。例如，基础的技术栈声明（“本项目使用 TypeScript”）、绝对不能违反的安全规范（“禁止使用 eval ”）、公司级的代码风格要求。使用时要非常谨慎，避免规则冲突或过度约束。

2. Auto Attached （自动附加）规则 ：

   • 特点 ：通过 globs 字段指定文件模式（如 *.tsx ， src/components/**/*.ts ）。只有当 AI 助手处理匹配这些模式的文件时，该规则才会被激活。
   • 适用场景 ： 领域/技术栈特定规范 。这是最常用、最灵活的规则类型。例如，一个名为 react-hooks.mdc 的规则，可以设置 globs: “*.tsx,*.ts” ，内容专门讲解本项目 React Hooks 的使用规范（如必须提供依赖数组，自定义 Hook 必须以 use 开头）。当你在 .js 文件中工作时，这个规则不会干扰。

3. Agent Requested （代理请求）规则 ：

   • 特点 ：规则文件头部有一个 description 字段。AI 助手在对话中，会根据你问题的上下文， 主动判断是否需要引用 这条规则。它不会自动加载，只在 AI 认为相关时被“召唤”。
   • 适用场景 ： 专题知识库或深度指南 。例如，一个 graphql-best-practices.mdc 规则，描述可以写“本项目 GraphQL API 的查询、变更及错误处理最佳实践”。当你问 AI “怎么优化这个 GraphQL 查询？”时，AI 可能会主动应用这条规则来提供更精准的建议。

4. Manual （手动）规则 ：

   • 特点 ：在 AI 聊天窗口中，通过输入 @规则名称 来显式调用。规则文件本身不设置 alwaysApply 或 globs 。
   • 适用场景 ： 临时或非常专用的指导 。比如你有一个处理特定第三方 API 集成（ @stripe-integration ）的规则，或者一个代码审查清单（ @review-checklist ），在需要的时候手动调用即可。

GauntletAI 规则库中的大部分规则，例如 shadcn.mdc ，都属于 Auto Attached 类型，它们通过 globs 精准地作用于前端组件文件，确保 UI 开发的规范性。

2.3 .mdc 文件的结构剖析

一个典型的规则文件由两部分组成： Frontmatter（元数据） 和 正文内容 。

Frontmatter 是写在文件开头，被 --- 包裹的 YAML 格式区域，用于定义规则的“身份”和“触发条件”。

---
description: “关于使用 shadcn/ui 和 Tailwind CSS v4 构建 React 组件的综合指南”
globs: “**/*.{tsx,ts}” # 对所有 TSX/TS 文件生效
alwaysApply: false # 表示这不是 Always 规则
---

• description ：规则的简要描述，对于 Agent Requested 规则尤为重要。
• globs ：文件匹配模式，决定规则何时被自动附加。支持通配符，如 *.tsx ， src/features/**/*.ts 。
• alwaysApply ：布尔值。设为 true 即为 Always 规则；设为 false 或省略，则根据 globs 或 description 判断类型。

正文内容 则是用 Markdown 格式书写的具体规则。这里就是你“培训”AI 的地方。

• 语言 ：使用清晰、直接、无歧义的指令性语言。避免模糊的“应该”、“最好”，多用“必须”、“使用”、“避免”。
• 结构 ：使用标题、列表、代码块来组织内容，使其易于 AI 解析。
• 示例 ：提供正反代码对比是最有效的方式。AI 通过示例学习的效果远超纯文字描述。
• 上下文 ：可以引用项目内的具体文件路径（如 @/components/ui/button.tsx ）来提供更具体的模板。

3. GauntletAI 规则库深度解析与实战应用

了解了基础原理，我们来看看 GauntletAI 这个规则库具体提供了什么宝贝，以及如何把它用到你的项目里。

3.1 现有规则分类与内容精讲

项目目前将规则分为三大类，我们逐一拆解其核心价值：

🎨 Frontend & UI Development ( --design )

• 规则文件 ： shadcn.mdc
• 核心价值 ：这不仅仅是一个“如何使用 shadcn/ui”的说明书。它深度融合了 Tailwind CSS v4 的最新实践。Tailwind v4 带来了重大的变革，比如引入了 @theme 指令、CSS 原生变量定义主题、以及新的实用类。该规则确保了 AI 在生成组件时，能采用符合 v4 规范的、现代 CSS 优先的写法，而不是陈旧的 v3 模式。它还很可能包含了响应式设计、无障碍访问（a11y）以及浏览器兼容性方面的内部最佳实践，这些是官方文档可能未深入涉及的团队经验。

⚙️ DevOps & Infrastructure ( --infra )

• docker.mdc ：聚焦于现代 DevOps 流程中的容器化最佳实践。我推测其内容会超越基础的 Dockerfile 编写，涵盖多阶段构建以减小镜像体积、安全扫描与漏洞处理、 .dockerignore 的优化配置、以及针对不同环境（开发、测试、生产）的部署模式。这对于确保应用在容器环境中运行的一致性和安全性至关重要。
• firebase.mdc ：这是一个针对特定技术栈（Firebase + Angular/Ionic）的深度指南。它应该详细规定了如何组织 Firestore 数据结构、安全规则的设计模式、Cloud Functions 的 TypeScript 编写规范、以及 Authentication 与前端框架的集成方式。对于使用这套技术栈的团队，它能极大统一后端服务的开发范式。

🤖 AI/ML Development ( --ai )

• prompting.mdc ：这个规则非常有意思，它是在用 Cursor Rules 来规范如何与 AI（包括 Cursor 自身）进行交互。内容可能包括：提示词的结构化模板（如 CRISPE 框架）、上下文管理的技巧（如何让 AI 记住长篇对话的核心）、以及针对代码生成的特定提示模式。这相当于为团队配备了一套“元提示”工具，提升整个团队利用 AI 的效率。

3.2 四种安装方法的场景化选择与实操细节

GauntletAI 提供了四种安装方式，各有优劣，适合不同场景。

🥇 方法一：CLI 安装（最推荐） 这是项目最大的亮点之一，极大降低了使用门槛。

# 安装所有规则
npx gauntlet-rules install --all

这条命令背后做了几件聪明事：

1. 零配置 ：使用 npx 直接运行远程 npm 包，无需全局安装 gauntlet-rules 。
2. 智能路径检测 ：它会自动在你的 用户主目录 （ ~ ）下创建 .cursor/rules/ 目录。这是 Cursor 的 全局规则目录 。放在这里的规则，会对你 所有项目 生效。这对于团队共享的、通用的基础规范（如公司技术栈、通用代码风格）非常合适。
3. 模块化选择 ：你可以通过 --design ， --infra ， --ai 参数按需安装，避免引入不必要的规则干扰。

注意 ：全局规则虽然方便，但如果你某个项目使用了截然不同的技术栈（比如一个 Vue 项目），某些规则（如 shadcn.mdc ）可能会产生冲突。此时需要考虑项目级规则。

📋 方法二：复制单个规则文件 适合当你只想试用某一个特定规则，或者想先研究一下规则内容时。

1. 在 GitHub 上打开目标规则文件（如 rules/design/shadcn.mdc ）。
2. 复制全部内容。
3. 在 Cursor 中打开你的项目，通过命令面板（ Cmd/Ctrl + Shift + P ）搜索并执行 “Create Cursor Rule” 。
4. 将内容粘贴到新建的文件中，保存。Cursor 会自动将其保存到当前项目的 .cursor/rules/ 目录下。

📦 方法三：克隆整个仓库 适合深度用户、贡献者，或者希望本地拥有所有规则并进行修改的开发者。

git clone https://github.com/PSkinnerTech/GauntletAI-Cursor-Rules.git

克隆后，你可以将整个 rules/ 文件夹，或者其中的子文件夹，直接拷贝到你项目的 .cursor/ 目录下。这种方式让你能完整地看到所有规则的原始结构和内容，方便学习和定制。

🔗 方法四：引用远程规则（高级用法） 在你自己项目的规则文件中，可以使用 @file 语法直接引用远程的规则内容。

@file https://raw.githubusercontent.com/PSkinnerTech/GauntletAI-Cursor-Rules/master/rules/design/shadcn.mdc

这种方式将规则内容“内联”到你的本地规则中。它的好处是能 自动同步远程更新 。但缺点也很明显：依赖网络，且如果远程文件被移动或删除，你的规则会失效。通常用于引用那些非常稳定、由权威维护的“基础规则”。

3.3 规则生效验证与调试

安装完成后，如何知道规则生效了？这里有几个验证方法：

1. 在 Cursor 中查看 ：打开 Cursor，进入你的项目。点击左侧边栏的“规则”图标（或通过 View -> Rules 打开）。你应该能看到已加载的规则列表。 Always 和匹配当前文件的 Auto Attached 规则会显示在这里。
2. 通过 AI 对话测试 ：最直接的方式是向 AI 提问。例如，在安装了 shadcn.mdc 规则后，在一个 .tsx 文件里问：“创建一个漂亮的按钮组件。” 观察 AI 生成的代码是否使用了 @/components/ui/button 导入和 Tailwind v4 的类名，而不是原生 button 或内联样式。
3. 检查规则作用域 ：如果规则没生效，首先检查文件路径。对于 Auto Attached 规则，确认你正在编辑的文件路径是否匹配 globs 模式。例如， globs: “src/components/**/*.tsx” 的规则，在 src/pages/index.tsx 文件中就不会被激活。

4. 贡献指南：编写属于你自己的高效规则

GauntletAI 是一个社区项目，其真正的生命力在于贡献。当你积累了自己的最佳实践时，将其转化为规则并分享出来，能惠及整个社区。以下是我根据官方最佳实践和自身经验总结的编写指南。

4.1 规则构思与结构设计

在动笔之前，先想清楚：

• 这个规则要解决什么具体问题？ （例如：“确保所有 API 调用都经过错误处理和日志记录”）
• 它的适用范围是什么？ （是整个项目，还是仅限 utils/ 目录下的文件？）
• 它应该是哪种类型？ （ Auto Attached 用于技术栈规范， Agent Requested 用于架构决策指南）

一个好的规则结构通常如下：

---
description: “本项目中 React 组件 Props 的类型定义与默认值规范”
globs: “**/*.{tsx,ts}”
---

# React 组件 Props 规范

## 类型定义
- 必须使用 `interface` 而非 `type` 来定义组件 Props。
- 接口名称格式：`组件名Props`，例如 `ButtonProps`。
- 每个属性都必须添加清晰的 JSDoc 注释。

## 默认值
- 使用 ES6 默认参数语法为可选 Props 提供默认值。
- 默认值应在函数签名处定义，而不是在函数体内。

## 示例

### ✅ 正确示例
```typescript
interface CardProps {
  /** 卡片的标题 */
  title: string;
  /** 是否显示阴影效果，默认为 true */
  elevated?: boolean;
}

export default function Card({ title, elevated = true }: CardProps) {
  return <div className={cn(‘card’, elevated && ‘shadow-md’)}>{title}</div>;
}

❌ 错误示例

type CardProps = { // 避免使用 type
  title: string;
  elevated?: boolean; // 缺少注释
};

export default function Card(props: CardProps) {
  const elevated = props.elevated ?? true; // 默认值应在参数处定义
  return <div className={`card ${elevated ? ‘shadow-md’ : ‘’}`}>{title}</div>;
}

### 4.2 内容编写的“要”与“不要”

**要这样做：**
*   **具体而明确**：“使用 `const` 声明变量，除非需要重新赋值” 比 “合理使用变量声明” 好得多。
*   **提供正反对比**：如上面的示例，AI 从对比中学习效率最高。
*   **引用项目资产**：使用 `@/lib/utils.ts` 来告诉 AI 项目中的工具函数位置。
*   **保持简洁聚焦**：一个规则最好只解决一个领域的问题。如果内容超过 500 行，考虑拆分成 `react-hooks.mdc`， `react-props.mdc` 等多个规则。
*   **使用模式匹配**：在 `globs` 中灵活使用通配符，将规则精准绑定到特定目录或文件类型。

**不要这样做：**
*   **避免模糊的指导**：“写出高质量的代码”这种话对 AI 没有帮助。
*   **不要创建巨型规则**：一个包含“前端所有知识”的规则难以维护，且可能因上下文过长影响 AI 性能。
*   **不要忽略更新**：当项目技术栈升级（如 Tailwind v3 到 v4），对应的规则必须同步更新，否则会引导 AI 写出过时的代码。

### 4.3 提交贡献的流程

1.  **Fork 与分支**：在 GitHub 上 Fork 原仓库，然后在本地创建特性分支：`git checkout -b feat/add-nextjs-rule`。
2.  **创建规则文件**：在 `rules/` 下选择合适的类别目录（或创建新目录），添加你的 `.mdc` 文件。命名要有意义，如 `nextjs-app-router.mdc`。
3.  **更新 README**：在 `README.md` 文件的对应分类表格中，添加你的规则信息（名称、描述、贡献者、版本）。
4.  **测试你的规则**：将规则文件复制到你的一个测试项目中，验证其是否能被正确加载，并且 AI 的行为符合预期。
5.  **发起 Pull Request**：提交清晰的 PR 描述，说明这个规则的目的、适用场景和测试情况。

## 5. 高级技巧与疑难排查

在实际使用和编写规则的过程中，你可能会遇到一些挑战。这里分享一些进阶心得和常见问题的解决方法。

### 5.1 规则冲突与优先级管理

当多个规则同时对同一个文件生效，且指令有冲突时，会发生什么？Cursor 的内部机制会尝试合并所有相关的上下文，但如果指令直接矛盾（一个说“用 `interface`”，一个说“用 `type`”），可能会导致 AI 行为不稳定或给出混乱的建议。

**解决策略：**
*   **作用域隔离**：这是最重要的手段。通过精细的 `globs` 配置，让规则只在特定的目录或文件类型下生效。例如，将后端 API 规则限制在 `server/` 目录，前端组件规则限制在 `client/` 目录。
*   **明确优先级**：在规则正文中，可以用“优先”、“首选”等词语来暗示优先级。但对于根本性冲突，最好重构规则，确保它们在不同维度上提供指导，而非直接对抗。
*   **使用项目级规则覆盖全局规则**：如果你在 `~/.cursor/rules` 有全局的“使用 `type`”规则，但在某个特定项目的 `.cursor/rules` 下放置了一个“使用 `interface`”的规则，那么在该项目内，**项目级规则通常具有更高优先级**。

### 5.2 提升规则效能的技巧

*   **利用 `@filename` 引用模板**：在规则中，你可以通过 `@filename` 语法引用项目内的一个具体文件作为模板。例如，在 `component.mdc` 规则中写：“新建组件请参考模板：`@/components/templates/ComponentTemplate.tsx`”。这比用文字描述结构要直观有效得多。
*   **创建“规则集”目录**：对于大型项目，可以在 `.cursor/rules` 下创建子目录，如 `frontend/`， `backend/`， `devops/`。将相关规则放入对应目录，Cursor 会递归读取。这有助于保持规则的组织性。
*   **为 `Agent Requested` 规则撰写吸引人的 `description`**：`description` 是 AI 判断是否调用该规则的依据。要写得像搜索引擎的关键词一样精准。例如，“本项目的 Redux Toolkit 切片（slice）创建规范与异步逻辑处理模式”就比“Redux 指南”要好得多。

### 5.3 常见问题排查表

| 问题现象 | 可能原因 | 解决方案 |
| :--- | :--- | :--- |
| 规则在列表中不显示 | 1. 文件未放在正确的 `.cursor/rules/` 目录下。<br>2. 文件扩展名不是 `.mdc`。<br>3. Frontmatter 格式错误（如 YAML 语法错误）。 | 1. 检查路径是否正确（用户目录 vs 项目目录）。<br>2. 确保文件全名为 `xxx.mdc`。<br>3. 检查 `---` 包裹的元数据区，确保缩进、冒号后空格等符合 YAML 规范。 |
| `Auto Attached` 规则未激活 | 1. 当前打开的文件不匹配 `globs` 模式。<br>2. `globs` 模式书写有误。 | 1. 确认文件路径和扩展名。例如，规则作用于 `*.tsx`，但你打开的是 `.js` 文件。<br>2. 使用简单的模式测试，如 `**/*.tsx`。 |
| AI 似乎忽略了规则内容 | 1. 规则内容过于冗长或模糊，AI 未能有效提取关键指令。<br>2. 多个规则指令冲突，导致 AI 困惑。<br>3. 你的问题或指令（Prompt）本身过于宽泛，覆盖了规则的约束。 | 1. 简化规则，使用更直接、更具指令性的语言，并增加代码示例。<br>2. 检查规则冲突，优化 `globs` 或修改内容。<br>3. 在提问时，可以尝试先让 AI “回顾一下关于 XX 的规则”，再提出具体需求。 |
| CLI 安装失败 | 1. 网络问题，`npx` 无法下载包。<br>2. 没有在项目目录或主目录执行命令。<br>3. 权限不足，无法在用户目录创建文件。 | 1. 检查网络连接，或尝试使用其他安装方法。<br>2. 确认命令行当前所在路径。<br>3. 在 macOS/Linux 上尝试使用 `sudo`（谨慎），或手动创建 `~/.cursor/rules` 目录。 |

### 5.4 个人经验：从“规则消费者”到“规则设计师”

我自己的使用路径是这样的：最开始，我只是下载了 GauntletAI 的 `shadcn.mdc` 规则，它立刻解决了我团队中 Tailwind 类名书写不一致的问题。然后，我观察到团队在编写 React Query 的 `useQuery` 时，错误处理逻辑五花八门。于是，我创建了第一个自定义规则 `react-query-error-handling.mdc`，规定了必须使用 `onError` 回调记录日志，并且错误信息要统一格式化。

这个规则生效后，新队员生成的代码立刻变得规范了。这让我意识到，Cursor Rules 不仅是给 AI 用的，更是**团队知识和经验的固化工具**。它把资深开发者头脑中的“最佳实践”变成了可执行、可传承的资产。现在，我们团队每引入一项新技术或形成一个新约定，第一件事就是讨论：“这个值得写成一条 Cursor Rule 吗？”

最后一个小建议：定期回顾和重构你的规则库。随着项目演进，有些规则会过时，有些可以合并。保持规则库的简洁和时效性，和编写代码一样重要。