1. 项目概述：一个为 Cursor 编辑器量身定制的规则集

如果你和我一样，日常重度依赖 Cursor 这款 AI 驱动的代码编辑器，那你肯定也经历过这样的时刻：面对一个复杂的重构任务，你满怀期待地输入指令，结果 AI 助手生成的代码要么风格混乱，要么逻辑跑偏，甚至引入了你项目里明令禁止的 API。每次都得花大量时间去纠正、去解释，效率反而被拉低了。这正是我当初决定动手整理 paul-s-cursor-rules 这个项目的初衷。

简单来说， paul-s-cursor-rules 是一个专门为 Cursor 编辑器设计的、高度定制化的 AI 助手行为规则集。它不是一个插件，也不是一个扩展，而是一套写在 .cursorrules 文件里的“指令集”。你可以把它理解为给 Cursor 内置的 AI 助手（无论是 Claude 还是 GPT 模型）制定的一份详尽的“员工手册”和“编码规范”。这份手册里，明确规定了 AI 在为你写代码时，应该遵循什么样的代码风格、使用哪些特定的库或框架、避免哪些常见的错误模式，甚至是如何组织文件和命名变量。

这个项目的核心价值，在于将开发者个人的编码习惯、项目团队的工程规范，乃至对特定技术栈的深度理解， 固化 成 AI 可读、可执行的规则。它极大地减少了与 AI 的沟通成本，让 AI 生成的代码从“第一稿”开始就更贴近你的预期，从而真正将 AI 编程从“有趣的玩具”转变为“可靠的生产力工具”。无论你是独立开发者想要保持代码一致性，还是团队 leader 希望统一新成员的 AI 辅助产出，这套规则集都能提供一个清晰、可复现的起点。

2. 核心设计思路：从模糊指令到精确约束

为什么我们需要一个专门的规则文件，而不是每次在聊天框里重复输入那些要求？这背后是对 AI 协作模式效率瓶颈的深刻反思。在与 Cursor 的日常交互中，我发现了几个关键痛点，而 paul-s-cursor-rules 的设计正是为了系统性地解决它们。

2.1 解决上下文遗忘与指令衰减

Cursor 的 AI 助手基于大语言模型，存在固有的“上下文窗口”限制。虽然它能记住当前会话中的对话历史，但一旦你关闭文件、切换项目，或者开始一个新的聊天，之前反复强调的规则（比如“请使用 async/await 而不是 .then() ”、“请为 React 组件编写 TypeScript 接口”）很容易被遗忘或淡化。你不得不像复读机一样，在每个新任务开始时重新声明基础规则，这不仅繁琐，还可能导致规则在多次复述中产生细微偏差。

.cursorrules 文件作为项目根目录下的一个配置文件，为 AI 提供了 持久化、项目级 的上下文。只要文件存在，AI 在处理该项目下的任何文件、回答任何问题时，都会优先加载并遵循这些规则。这相当于为 AI 助手建立了一个长期记忆的“知识库”，确保规则的一致性贯穿整个项目生命周期。

2.2 统一代码风格与质量门禁

每个开发者、每个团队都有自己偏好的代码风格：是使用单引号还是双引号？函数命名用 camelCase 还是 snake_case ？ import 语句应该如何排序？如果没有明确规则，AI 可能会根据其训练数据中的“常见模式”生成代码，这很可能与你项目的现有风格冲突，导致代码库出现风格“补丁”，影响可读性和维护性。

通过 .cursorrules ，我们可以将 ESLint、Prettier 等工具的部分规则，或者团队内部约定的风格指南，用自然语言清晰地描述出来。例如，你可以规定：“所有 React 函数组件必须使用 const 声明，并采用箭头函数形式”、“接口（Interface）命名必须以大写字母 I 开头”。AI 会将这些规则视为必须遵守的约束，从而生成风格统一的代码，减少了后续手动格式化的工作量。

2.3 嵌入领域知识与最佳实践

对于特定的技术栈或框架，存在许多经过验证的最佳实践和容易踩坑的“反模式”。例如，在 Next.js 应用中，知道何时使用 use client 与 use server ；在 TanStack Query 的使用中，正确设置查询键（queryKey）的结构；在 Zustand 状态管理时，避免不必要的重复渲染。

将这些领域知识写入 .cursorrules ，相当于让 AI 助手在你专精的领域内“开了小灶”。它不再仅仅依赖通用的编程知识，而是能结合你项目的具体技术选型，生成更地道、更高效的代码。这尤其有利于快速上手新技术或确保团队在复杂技术栈上保持统一的实现水准。

2.4 设计原则：明确、具体、可执行

在编写 paul-s-cursor-rules 时，我始终坚持几个核心原则，这也是规则集能否生效的关键：

1. 指令明确，避免歧义 ：不用“写出高质量的代码”这种模糊表述，而是用“函数长度不应超过 30 行”、“每个函数只做一件事”来具体定义“高质量”。
2. 正向引导为主，负面禁止为辅 ：多告诉 AI“应该怎么做”，而不是仅仅“不能做什么”。例如，“使用可选链操作符（ ?. ）和空值合并操作符（ ?? ）来处理可能为 null 或 undefined 的值”，就比“不要写一堆 if 判断空值”更清晰。
3. 结构化组织，便于维护 ：将规则分门别类，例如分为 [代码风格] 、 [React 规范] 、 [TypeScript 规范] 、 [性能与安全] 等区块。这样不仅人类阅读起来清晰，AI 在解析和引用时也更容易定位相关规则。
4. 提供示例，加深理解 ：对于复杂的规则，附上一个简短的代码示例比纯文字描述有效得多。这能帮助 AI 更好地理解你的意图，生成符合预期的代码。

3. 规则集结构深度解析

一份有效的 .cursorrules 文件不是规则的简单堆砌，而是一份有层次、有逻辑的“智能合约”。下面我以 paul-s-cursor-rules 的典型结构为例，拆解每个部分的设计意图和编写要点。

3.1 全局配置与角色定义

文件的开头部分，通常用于设定 AI 助手的“角色”和本次交互的“基本法”。这超越了具体的代码风格，定义了协作的基调。

# Paul‘s Cursor Rules

**角色**：你是一位经验丰富、注重细节的资深全栈工程师，专注于构建可维护、高性能的 Web 应用程序。你对 TypeScript、React、Next.js 和现代前端工具链有深刻理解。

**核心原则**：
1.  **实用性优先**：生成的代码必须能够直接运行，解决实际问题，避免过度设计。
2.  **一致性至上**：严格遵循本项目已有的代码模式和风格。
3.  **持续学习**：如果我的指令与既定规则冲突，以我的最新指令为准，但可以礼貌地指出潜在的不一致。

为什么这样设计？

• 角色设定 ：这为 AI 设定了一个“人设”，让它倾向于采用资深工程师的思维模式，比如更关注边界条件、错误处理和长期维护成本，而不仅仅是实现功能。
• 核心原则 ：明确了优先级。“实用性优先”防止 AI 陷入设计模式的教条主义；“一致性至上”是维护代码库整洁的生命线；“持续学习”的条款则巧妙处理了规则与临时指令的矛盾，赋予了开发者最终决定权，同时保留了 AI 提供建议的空间。

3.2 代码风格与格式化规范

这是规则集中最具体、最“琐碎”但也最立竿见影的部分。目标是让 AI 生成的代码看起来就像是你自己亲手写的一样。

## [代码风格]

### 语法与格式
- **引号**：统一使用单引号（‘’），JSX 属性中的字符串值也使用单引号。
- **分号**：语句末尾必须添加分号。
- **缩进**：使用 2 个空格进行缩进，禁止使用 Tab。
- **行宽**：最大行宽为 100 个字符，超出应合理换行。
- **括号风格**：采用 “One True Brace Style“（1TBS），即左大括号不换行。
  - *示例*：`if (condition) { // ... }`，而不是 `if (condition) \n{ // ... }`

### 命名约定
- **变量/函数**：`camelCase`。
- **类/组件/接口/类型**：`PascalCase`。
- **常量**：全大写 `SCREAMING_SNAKE_CASE`，仅适用于真正恒定不变的值。
- **布尔变量/函数**：应以 `is`， `has`， `can`， `should` 等前缀开头（如 `isLoading`, `hasPermission`）。

### 导入与导出
- **导入顺序**：1. 第三方库（如 `react`）， 2. 绝对路径别名导入（如 `@/components`）， 3. 相对路径导入（如 `./utils`）。每组内部按字母顺序排序。
- **避免通配符导入**：禁止使用 `import * as`，除非是访问命名空间对象的特殊情况（如 `import * as Sentry from ‘@sentry/nextjs‘`）。
- **默认导出**：对于 React 组件，优先使用默认导出（`export default Component`）。工具函数、常量、类型定义使用命名导出。

实操心得 ：

• 这部分规则最好与你项目中已有的 .prettierrc 或 .eslintrc 配置对齐。你可以直接将这些工具的配置项“翻译”成自然语言描述。一致性是最高目标。
• “命名约定”尤为重要。清晰的命名是代码自文档化的基础。强制布尔变量使用前缀，能极大提升条件判断逻辑的可读性。

3.3 技术栈特定规则

这里是体现规则集“深度”的地方。针对项目主要使用的框架和库，制定精细化的约束。

## [React 与 Next.js 规范]

### 组件设计
- **函数组件**：全部使用 `const` 声明的箭头函数。
- **Props 类型**：必须使用 TypeScript 接口（`interface`）定义，并添加详细的 JSDoc 注释说明。
- **Hooks 规则**：遵守 React Hooks 规则（只在顶层调用，不在条件/循环中调用）。自定义 Hook 必须以 `use` 前缀开头。
- **避免内联函数**：在 JSX 中传递的事件处理函数，应优先在组件外部定义，以避免不必要的重新渲染。

### Next.js 特定
- **数据获取**：在 App Router 中，优先使用 React 的 `async/await` 在 Server Component 中获取数据。仅在 Client Component 中需要时使用 `useEffect` 和状态。
- **元数据**：为每个页面（`page.tsx`）或布局（`layout.tsx`）定义完整的 `metadata` 对象。
- **图片优化**：始终使用 `next/image` 组件，并显式设置 `width`, `height` 或 `fill` 属性以及 `alt` 文本。

## [TypeScript 规范]
- **严格模式**：启用所有严格检查（`strict: true`）。
- **避免 `any`**：严禁使用 `any` 类型。如果暂时无法确定类型，可使用 `unknown` 并配合类型守卫。
- **类型推断**：在变量声明能明显推断出类型时，无需显式标注（如 `const count = 0`）。
- **接口 vs 类型别名**：定义对象形状时，优先使用 `interface`，因为它更适合扩展（declaration merging）。`type` 用于联合类型、交叉类型或元组。

注意事项 ：

• 技术栈规则需要你对该技术有较深的理解，才能总结出真正影响代码质量和开发体验的要点。盲目罗列官方文档的内容意义不大。
• 规则应随着技术栈更新而迭代。例如，随着 React Server Components 的成熟，规则可能需要强调更多服务端组件的使用模式。

3.4 安全、性能与错误处理

这部分规则旨在防范于未然，引导 AI 生成健壮性更高的代码。

## [性能与安全]

### 性能
- **列表渲染**：动态列表必须为每个项提供稳定且唯一的 `key` 属性，禁止使用数组索引。
- **记忆化**：对于开销较大的计算，或作为 props 传递给子组件的回调函数，应考虑使用 `useMemo` 和 `useCallback` 进行记忆化。
- **代码分割**：识别大型第三方库，并建议使用 `next/dynamic` 进行动态导入。

### 安全
- **XSS 防护**：在渲染用户输入数据时，必须进行转义或使用安全的 API（如 React 默认转义，但使用 `dangerouslySetInnerHTML` 时必须确保内容可信）。
- **敏感信息**：代码中不得出现任何真实的 API 密钥、密码或令牌。使用环境变量（`process.env`）代替，并在规则中提醒我检查是否已配置。
- **依赖安全**：当建议安装新的 npm 包时，应附带一句提醒：“建议检查该包的维护状态、每周下载量和已知漏洞（如通过 `npm audit`）”。

### 错误处理
- **异步操作**：所有 `fetch` 或数据库操作必须使用 `try...catch` 包裹，并进行适当的错误处理和用户反馈。
- **边界情况**：对于可能为 `null`/`undefined` 的值、数组空状态、网络请求失败等，必须提供清晰的兜底处理或 UI 状态。

核心价值 ：

• 这些规则将安全意识和性能考量“前置”到了代码生成阶段。AI 在编写一个 fetch 调用时，会“自动”想到加 try...catch 和错误状态，这比事后人工审查补漏要高效得多。
• 关于敏感信息的提醒，是一个非常好的安全实践，能有效避免开发者无意中将密钥提交到版本库。

4. 高级技巧与动态规则

基础的静态规则能解决80%的问题，但要让 AI 助手真正变得“聪明”和“贴心”，还需要一些高级技巧。 paul-s-cursor-rules 也探索了这些动态交互的可能性。

4.1 上下文感知与条件规则

规则不是一成不变的，可以根据当前正在编辑的文件或任务上下文进行微调。这需要你在规则中使用一些“逻辑性”的描述。

## [上下文相关规则]

- **当在 `/app/api/` 目录下的文件中工作时**：
  - 你正在编写 Next.js Route Handler。
  - 优先使用 `NextResponse` 返回标准化的 JSON 响应。
  - 仔细验证用户输入（请求体、查询参数），并返回适当的 HTTP 状态码（200， 400， 401， 500等）。
  - 所有数据库或外部 API 调用必须是异步的。

- **当在文件名包含 `.test.`， `.spec.` 或位于 `__tests__` 目录的文件中工作时**：
  - 你正在编写测试代码。
  - 测试描述应清晰说明被测试的行为。
  - 优先使用 `describe`， `it` 或 `test` 块组织用例。
  - 每个测试用例应独立，并包含必要的 `beforeEach`/`afterEach` 清理。

实现效果 ：当你在 app/api/users/route.ts 中向 AI 提问时，它会自动切换到“API 开发模式”，生成的代码会天然包含错误处理和正确的响应格式。这比你在每个 API 文件里手动输入“请按照 Next.js API Route 规范编写”要高效得多。

4.2 引导式提问与代码审查

规则不仅可以约束输出，还可以引导 AI 主动提问，进行初步的“代码审查”，这能弥补 AI 有时过于“听话”而缺乏批判性思维的缺点。

## [交互与审查]

- **在实现复杂功能前**：如果我的指令比较模糊或涉及重大架构变更，请先询问澄清性问题，或提供1-2个简要的实现方案供我选择。
- **生成代码后**：在提供代码片段的同时，可以附上一个简短的“审查要点”列表，指出：
  1.  这段代码可能存在的性能瓶颈（如潜在的无限循环、昂贵的重复计算）。
  2.  是否有未处理的边界情况或错误。
  3.  是否遵循了本项目制定的所有相关规则。
  4.  是否有更简洁或更现代的实现方式可选。

个人体会 ：这个“审查要点”功能非常有用。它把 AI 从一个被动的代码生成器，变成了一个初级的结对编程伙伴。虽然它的审查深度无法替代人类，但能快速抓住一些显而易见的疏漏，比如忘记加 key ，或者使用了已弃用的 API，在开发过程中能起到很好的实时提醒作用。

4.3 与 .cursor/misc 的配合使用

Cursor 还有一个更灵活但更临时的功能： /misc 指令。你可以在聊天框中输入 /misc 来加载项目根目录下 .cursor/misc 文件中的内容，作为一次性或项目期的补充上下文。

我的策略是：

• .cursorrules ：存放 长期稳定、普适 的规则。比如代码风格、核心框架规范、安全基线。这些是项目的“宪法”。
• .cursor/misc ：存放 临时性、任务特定 的上下文。比如当前正在实现的一个复杂业务逻辑的流程图、某个第三方 API 的接口文档摘要、本次冲刺需要特别关注的重构重点等。这是项目的“临时法案”。

两者结合，既能保持核心规则的稳定，又能为特定的开发任务提供高度聚焦的上下文，灵活性大大增强。

5. 实战：从零搭建并优化你的规则集

看了这么多理论，你可能已经跃跃欲试。别急，直接从 paulpham157/paul-s-cursor-rules 复制一份固然方便，但最好的规则集一定是为你自己量身定制的。下面是我的“分步构建法”。

5.1 第一阶段：基础搭建（快速启动）

1. 创建文件 ：在你的项目根目录下，创建一个名为 .cursorrules 的文件。
2. 设定角色与原则 ：参考第3.1节，用几句话定义你希望 AI 扮演的角色（如“严谨的后端工程师”、“富有创意的前端开发者”）和几条最核心的合作原则。
3. 移植基础风格 ：打开你项目的 .prettierrc.js 或 .eslintrc.js ，将里面关于引号、分号、缩进、行宽等最基础的格式化规则，“翻译”成自然语言，放入 [代码风格] 章节。
4. 定义命名约定 ：写下你的团队或个人最坚持的命名规则。这是提升代码一致性的第一步。

完成以上步骤，你就有了一个最小可用的规则集。把它保存，然后在 Cursor 中打开项目，AI 助手就已经开始受到这些规则的约束了。你可以先尝试一些简单的代码生成任务，比如“创建一个工具函数格式化日期”，观察输出是否符合你的风格。

5.2 第二阶段：按需深化（迭代增强）

不要试图一次性写完所有规则。在接下来一周的实际开发中，采用“遇到问题，就补充规则”的策略。

• 场景 ：AI 生成的 React 组件用了 function 关键字，而你团队统一用箭头函数。
• 行动 ：在 .cursorrules 的 [React 规范] 部分添加一条：“所有 React 函数组件必须使用 const Component = () => {} 箭头函数形式声明。”
• 场景 ：AI 在写 API 路由时，直接返回了对象，没有用 NextResponse.json() 。
• 行动 ：在 [Next.js 规范] 或新增的 [API 规范] 部分添加对应规则。

每次补充规则后，可以在类似场景下再次测试，看 AI 是否纠正了行为。这个过程就像在“训练”你的专属助手。

5.3 第三阶段：提炼与抽象（形成体系）

经过几周的积累，你的 .cursorrules 文件可能会变得冗长。此时需要进行一次整理和提炼：

1. 分类合并 ：将分散的规则按主题归类（风格、React、TypeScript、Node.js、测试等）。
2. 去芜存菁 ：删除那些很少被触发或实际效果不明显的规则。
3. 补充原理 ：为一些关键规则添加简短的“ 为什么 ”说明。这不仅有助于未来的你回顾，也能帮助 AI 更好地理解规则的意图。例如，在“禁止使用数组索引作为 key ”的规则后，可以加上“ 因为索引不稳定，在列表项顺序变化时会导致 React 渲染错误和性能问题。 ”
4. 添加示例 ：为最复杂或最容易出错的规则配上代码示例。一个正例和一个反例，效果最佳。

5.4 第四阶段：团队共享与协同进化

如果你的规则集在个人项目中效果显著，就可以考虑推广到团队。

1. 建立基线 ：将你的 .cursorrules 文件提交到团队项目的代码库根目录。
2. 团队评审 ：在团队会议上展示和讨论这份规则集。收集反馈，看看是否有其他成员有特殊的习惯或遇到了你没覆盖到的问题。这是一个统一团队编码风格的好机会。
3. 设立负责人 ：指定一人（或轮流）作为规则集的维护者，负责定期根据团队的技术栈演进和遇到的新问题，更新规则集。
4. 文档化 ：可以在团队的内部 Wiki 或 README 中，简要说明 .cursorrules 文件的存在和目的，引导新成员主动利用它。

6. 常见问题与效果调优

在实际使用和推广 paul-s-cursor-rules 模式的过程中，我遇到并总结了一些典型问题和优化策略。

6.1 规则冲突或指令被忽略

问题 ：有时你给的临时指令会与 .cursorrules 中的某条规则冲突，AI 可能无法正确处理。 案例 ：规则要求“使用单引号”，但你临时要求“在这个字符串里使用双引号，因为里面包含了单引号”。 解决 ：这通常不是问题。如我在核心原则中设定的“持续学习”条款，AI 应以你的最新指令为准。如果发现 AI 僵化地遵守规则，你可以在指令中更明确地指出：“ 忽略 .cursorrules 中关于引号的规则 ，在此处使用双引号，因为字符串内容为 It‘s great 。” 清晰的指令可以覆盖规则。

6.2 规则过多导致性能下降或混淆

问题 ：规则集写得过于庞大和复杂（比如超过100条），可能会让 AI 陷入困惑，或者响应速度变慢。 解决 ：

• 优先级 ：确保最重要的规则放在前面。AI 处理上下文时，前后的权重可能不同。
• 精简 ：定期回顾，合并类似的规则，删除极少使用的规则。规则集的质量远重于数量。
• 模块化 ：对于超大型项目，可以考虑拆分。例如，在项目子目录（如 packages/server/ ）下放置一个针对后端规则的 .cursorrules 文件。Cursor 会优先使用当前文件最近的上层目录中的规则文件。

6.3 对新项目或文件的适配问题

问题 ：将一个为成熟项目制定的、包含大量技术栈特定规则的 .cursorrules 文件，直接用于一个全新的、技术栈不同的项目，可能会产生干扰。 解决 ：

• 项目特异性 ： .cursorrules 应该被视为项目资产的一部分。开启新项目时，从你的“规则模板库”中挑选适合的规则重新组合，而不是直接复制粘贴。
• 条件注释 ：你可以在规则文件中使用简单的条件描述。例如：“ 如果本项目使用 Vue.js ：则组件定义采用单文件组件（SFC）格式与 Composition API。” 虽然 AI 不能像程序一样解析 if ，但这种明确的上下文描述能引导它在正确场景应用规则。

6.4 如何评估规则集的有效性

主观感受 ：最直接的感受是，你还需要反复纠正 AI 生成的代码吗？纠正的频率是否显著下降？ 客观检查 ：

1. 代码审查 ：定期查看 AI 生成或协助修改的代码，检查其是否符合规则集的要求。
2. 风格检查工具 ：运行 Prettier 或 ESLint 检查 AI 生成后的代码。理想情况下，应该很少或没有格式化和基础风格错误。
3. 团队反馈 ：询问团队成员，在使用 AI 助手时，是否感觉输出更可预测、更符合项目规范了。

6.5 规则不是银弹

必须清醒认识到， .cursorrules 是一个强大的 约束和引导工具 ，但它不能替代开发者的思考和审查。

• 逻辑错误 ：AI 可能生成风格完美但逻辑错误的代码。规则无法防止这一点。
• 架构设计 ：复杂的系统架构决策，仍然需要人类工程师的主导。
• 业务理解 ：AI 无法深刻理解你的业务领域，生成的代码可能在业务逻辑上有瑕疵。

因此，我的经验是： 将 .cursorrules 视为一个确保“代码卫生”和“风格统一”的自动化助手，同时将你的脑力节省下来，专注于更重要的逻辑验证、架构设计和业务实现上。 它负责让代码“看起来对”，而你负责确保代码“真的对”。

最后，我想分享一个我个人的小技巧：我会在我的 .cursorrules 文件末尾，加上一条“元规则”：

## [关于本文件]
- 本文件是动态更新的，旨在让我们（你和我）的合作更高效。
- 如果你发现某条规则不再适用，或者有更好的实践，请在你的回复中提醒我。
- 我们的共同目标是产出可维护、高质量的代码。

这仿佛是与 AI 助手建立了一种“合作契约”，提醒它（也提醒我自己）这份文件是活的，是服务于高效协作的，而不是一套僵化的教条。这种心态，或许才是用好 paul-s-cursor-rules 这类工具的关键。