1. 项目概述：一份来自一线开发者的 Cursor AI 助手深度调教指南

如果你和我一样，每天都在和代码打交道，并且已经将 Cursor 作为主力开发工具，那你肯定有过这样的体验：有时候它聪明得像个十年经验的老手，能精准理解你的意图，写出优雅的代码；有时候却又像个刚入行的实习生，反复纠结于一些基础语法，或者给出一些看似合理但完全跑不通的方案。这种“薛定谔的智能”很大程度上取决于你如何与它沟通，以及你为它设定的“工作准则”。

今天要分享的，就是我基于个人长期实践，整理并开源的一套 Cursor AI 助手规则集。它不是一个简单的提示词合集，而是一套经过实战检验的、旨在将 Cursor 的 Agent 模式（特别是配合 Claude 3.7 Sonnet 或 Gemini 2.5 Pro 这类思考型模型）调教成一位高效、可靠、懂你项目上下文的“虚拟开发伙伴”的系统性方法。核心目标很简单： 让 AI 助手的行为更可预测、更符合工程规范，最终提升我们作为开发者的心流体验和产出效率。

这套规则集完全开源，你可以直接拿去用，也可以基于你的技术栈和编码习惯进行深度定制。接下来，我会详细拆解它的设计思路、两种核心使用方法、背后的原理，以及我在实际使用中积累的大量“踩坑”经验和独家技巧。

2. 核心设计思路与方案选型：为什么是 .cursorrules 文件？

在深入具体规则之前，我们必须先理解 Cursor 中规则（Rules）的工作机制，以及为什么我最终选择了以项目级 .cursorrules 文件为核心的方案。

2.1 Cursor 规则的三种作用域与优劣分析

Cursor 的规则系统大致分为三个层级，各有其适用场景和局限性：

  1. 全局规则（Global Rules / User Rules） ：在 Cursor 设置中配置，对所有项目、所有聊天会话生效。

    • 优点 ：设置一次，处处生效。适合定义一些普适性的、与具体项目无关的顶层原则，比如“始终用中文回复”、“优先考虑代码的可读性而非极致的性能优化”。
    • 缺点 ：过于宽泛，无法承载具体的项目上下文（如技术栈、代码规范、目录结构）。当规则复杂时，容易与项目特定需求冲突。

  2. 工作区规则（Workspace Rules） ：通常通过在工作区根目录放置 .cursorrules 文件来实现。这是 本方案的核心 。

    • 优点 ： 高度定制化 。每个项目都可以有一套独一无二的规则，完美契合项目特定的技术栈（React/Vue/Node.js）、代码风格（ESLint/Prettier 配置）、架构约定（如目录规范、API 设计模式）。规则与项目代码共存，便于版本管理。
    • 缺点 ：需要为每个项目单独配置。不过，这恰恰是优点，因为它保证了规则的精准性。

  3. 框架/语言特定规则（Framework/Language-specific Rules） ：一种更细粒度的规则，通常放在项目内的 .cursor/rules/ 目录下，可以为特定的文件类型或框架（如 react.cursorrule , python.cursorrule ）定义行为。

    • 优点 ： 极其精准 。可以为不同技术场景定义最专业的行为，例如，在处理 .tsx 文件时自动应用 React Hooks 的最佳实践，在处理 .py 文件时遵循 PEP 8。
    • 缺点 ：管理成本稍高，需要维护多个规则文件。通常作为工作区规则的补充。

我的选择逻辑 ：经过大量实践，我发现将 核心的、项目通用的协作逻辑 放在工作区级的 .cursorrules 文件中，再根据需要引入框架特定规则作为补充，是平衡效率与效果的最佳实践。全局规则则保持极简，仅用于设定最基本的交互语言。

2.2 新旧两种使用模式的演进与对比

我的开源仓库中提供了两种使用模式，这反映了我个人工作流的演进。

方式一（旧版）：全局规则 + 项目规则分离 这种方式要求你在 Cursor 设置中粘贴一段较长的全局规则，同时在每个项目根目录创建 .cursorrules 文件并填入另一套规则。它的设计初衷是进行清晰的职责分离。但实际使用中，我发现存在两个问题：一是新手设置步骤稍显繁琐；二是当你想快速在不同项目间试验不同规则集时，需要来回修改全局设置，不够灵活。

方式二（新版）：极简全局规则 + 强项目规则 这是我现在主要推荐和使用的方式。它的理念是： 将几乎所有的“智能”都下放到项目级的 .cursorrules 文件中 。

  • 全局规则 ：可以简化到只剩一句，例如 Always respond in Vietnamese. （或其他你偏好的语言）。它的唯一作用就是设定默认交互语言。
  • 项目规则 ： .cursorrules 文件承载了所有的核心指令，包括 AI 的角色设定、工作流程、代码规范、沟通方式等。你只需要将这个文件复制到你的项目根目录，然后在 Cursor 聊天时，通过 @ 引用或添加为上下文文件，即可激活全套规则。

这种方式的好处显而易见： 项目隔离性极强，切换无成本，版本控制友好 。你可以在 A 项目用一套 React 规则，在 B 项目用一套 Python 后端规则，互不干扰。这也是目前社区更主流的做法。

3. 核心规则解析与实战配置要点

现在，让我们深入看看 .cursorrules 文件里到底写了什么，以及每一部分的设计意图。我将以仓库中 2/ 目录下的新版规则文件为例进行拆解。

3.1 角色与核心工作原则定义

规则文件的开头，通常会为 AI 定义一个明确的角色。这不仅仅是起个名字，更是设定其行为模式的“总纲”。

# Role: Senior Full-Stack Developer Assistant

## Core Principles
- **Think step by step**: Before writing any code, outline the plan. Use a scratchpad.
- **Precision over speed**: Prefer accurate, working solutions over quick guesses.
- **Ask clarifying questions**: If a requirement is ambiguous, ask before proceeding.
- **Write maintainable code**: Follow project conventions, use meaningful names, add comments for complex logic.
  • 为什么是“高级全栈助手”？ 这个角色暗示 AI 需要具备宽广的技术视野，能处理前后端、数据库等多种任务，而不是一个只会写单一样板的代码生成器。
  • “逐步思考”原则 ：这是激活 Claude 3.7 Sonnet 等模型“思考”能力的关键。要求 AI 先规划再执行，能极大减少它“一本正经地胡说八道”的概率。 scratchpad （草稿纸）是它进行内部推理的暂存区。
  • “精准优于速度” ：直接对抗 AI 倾向于快速给出第一个可能答案的惯性。强调正确性和可靠性，这在实际开发中至关重要。
  • “主动提问” ：将 AI 从一个被动的执行者，转变为一个主动的协作者。当需求不清时，鼓励它像人类同事一样向你确认，避免南辕北辙。
  • “可维护性” ：将代码质量要求内化为规则，确保生成的代码不是一次性的，而是易于他人（以及未来的你）理解和修改的。

3.2 工作流程与 scratchpad.md 的妙用

规则中会详细定义 AI 处理复杂任务的标准操作程序（SOP）。

## Workflow for Complex Tasks
1.  **Analyze & Plan**: Break down the user‘s request. List all files that need to be created, modified, or examined. Output this plan first.
2.  **Scratchpad**: Create or update a `scratchpad.md` file in the project root. Use it to record:
    - Detailed step-by-step reasoning.
    - Code snippets before finalizing.
    - Decisions made and alternatives considered.
    - Any questions for the user.
3.  **Execute**: After the plan is approved (or if no clarification is needed), proceed to implement changes one step at a time.
4.  **Review & Summarize**: After completing the task, provide a concise summary of what was changed and why.
  • 流程的价值 ：这模仿了专业开发者的工作流——分析、设计、实现、复盘。强制 AI 输出计划，让你能在它“动手”之前就看清其思路，及时纠偏。
  • scratchpad.md 的核心作用 ：这个文件是 AI 的“思考过程可视化”工具。所有内部的推理、草稿代码、决策权衡都会记录在这里。这带来了几个巨大好处：
    1. 可追溯性 ：你可以随时查看 AI 为什么这么写，考虑了哪些方案。
    2. 上下文管理 ：对于超长对话，AI 可能会“忘记”早期的决策。 scratchpad.md 作为一个持久化的、可被引用的记录，帮助维持上下文一致性。
    3. 减少幻觉 ：将思考过程外化，使得逻辑错误更容易在早期被发现。

重要心得 ： scratchpad.md 文件会随着对话进行而不断增长。虽然 Cursor 能很好地处理它作为上下文，但为了优化 token 使用（避免触及模型上下文长度上限）和保持“工作记忆”的清晰， 我强烈建议在完成一个大型任务模块后，主动让 AI 对 scratchpad.md 进行总结和清理 。你可以发出这样的指令：“任务已完成得很好，现在请总结一下 scratchpad.md 中的关键决策和已完成事项，然后清理掉已解决的部分，为后续任务腾出空间。” 然后，开启一个新的聊天会话继续工作。这就像给你的AI助手做一次“记忆碎片整理”。

3.3 代码与沟通风格的具体要求

这部分规则将抽象原则转化为具体、可执行的指令。

代码规范示例： 

## Code Style (Adapt per project)
- **Language**: Use TypeScript for front-end, Python for back-end unless specified.
- **Imports**: Group and sort imports (third-party, internal).
- **Naming**: `camelCase` for variables/functions, `PascalCase` for classes/components.
- **Error Handling**: Never use empty catch blocks. Log errors appropriately.
- **Comments**: Comment the “why”, not the “what”. Use JSDoc/TSDoc for public APIs.

这些规则需要你根据项目实际情况调整。例如，如果你的项目用 snake_case ，就在这里修改。关键在于 提供明确的、无歧义的指引 ，让 AI 不需要猜测你的偏好。

沟通风格示例： 

## Communication Style
- Be concise but thorough.
- When proposing solutions, list options with pros/cons.
- Use bullet points for lists, code blocks for code.
- Confirm understanding before major changes: “I‘ll do X, which will affect Y and Z. Proceed?”

这定义了 AI 与你交互的“人格”。让它像一位专业的同事一样沟通：简洁、有条理、在关键操作前寻求确认。这能显著提升协作效率，减少因误解导致的返工。

4. 完整实操流程：从零配置到高效协作

让我们以一个全新的 Node.js + TypeScript 项目为例，完整走一遍使用这套规则的流程。

4.1 环境准备与基础配置

  1. 安装与设置 Cursor ：确保你已安装最新版的 Cursor IDE，并拥有一个可用的 AI 模型 API 密钥（如 Anthropic Claude、Google Gemini 或 OpenAI）。在 Cursor 设置中配置好模型。
  2. 获取规则文件 ：访问我的 GitHub 仓库 ( paulpham157/paul-s-cursor-rules )，将 2/ 目录下的 .cursorrules 文件内容复制下来。
  3. 创建项目 ： 
    mkdir my-ts-api && cd my-ts-api
npm init -y
npm install typescript ts-node @types/node --save-dev
npx tsc --init
  4. 配置项目规则 ：在项目根目录创建 .cursorrules 文件，粘贴复制的内容。 现在，根据你的项目进行关键定制 ：
    • 修改 Code Style 部分，确保语言、命名约定等与你的 tsconfig.json 和团队规范一致。
    • 如果你有项目的 README.md 或设计文档，可以将核心内容精简后作为“项目背景”添加到规则文件开头，帮助 AI 快速理解项目。

4.2 激活规则并开始第一个任务

  1. 在 Cursor 中打开 my-ts-api 项目。
  2. 打开 Cursor 的聊天面板（快捷键 Cmd/Ctrl + K ）。
  3. 关键步骤：添加规则上下文 。你有两种方式：
    • 方式A（推荐） ：在聊天输入框里，输入 @ ，然后选择项目根目录下的 .cursorrules 文件。这会将整个文件内容作为上下文提供给本次聊天。
    • 方式B ：如果 .cursorrules 文件已经在编辑器中打开，直接开始聊天即可，Cursor 通常会智能地将其作为上下文。
  4. 验证规则生效 ：在聊天框输入：“你已经了解本项目的工作规则了吗？请简述你的角色和接下来处理任务的首要步骤。” 一个配置正确的 AI 助手应该会回答：“我是您的高级全栈开发助手。我的核心原则是逐步思考、精准优先。处理任务时，我会首先分析需求并制定计划，记录在 scratchpad.md 中，经确认后再执行。”

4.3 实战任务演示：创建一个用户注册 API 端点

现在，我们提出一个具体需求，观察规则如何引导 AI 的行为。

你的指令 ：“我们需要一个用户注册的 POST 接口 /api/auth/register 。请求体包含 email 和 password 。需要验证邮箱格式和密码强度，密码需加密存储。使用 Express 框架。”

AI 在规则驱动下的典型响应流程：

  1. 分析与计划阶段 ：

    “我来为您实现这个注册接口。首先，我将制定一个计划：

    1. 分析需求：创建 Express 路由，处理 POST 请求。
    2. 检查依赖：项目是否已安装 express , validator , bcrypt 等包？如果没有，需要先安装。
    3. 创建目录结构：建议在 src/routes/auth.ts 中定义路由，在 src/controllers/authController.ts 中处理逻辑，在 src/models/User.ts 中定义用户模型（如果使用ORM）。
    4. 实现验证：使用 validator 库或正则表达式验证邮箱和密码。
    5. 实现密码加密：使用 bcrypt 哈希密码。
    6. 模拟数据存储：目前先使用内存数组，后续可连接数据库。
    7. 错误处理：定义清晰的错误响应格式。

    我将把详细思考和代码草稿记录在 scratchpad.md 中。您看这个计划可行吗？或者您有特定的项目结构或库偏好？”

    你看，它没有直接写代码，而是先输出了一个结构化的计划，并主动向你确认。这完全遵循了规则中的“Think step by step”和“Ask clarifying questions”。

  2. 在你确认后，它开始执行 ：

    • 它会创建或更新 scratchpad.md ，里面可能记录了：“决定使用 express-validator 进行中间件验证，因为它更集成。密码强度要求：至少8位，含字母和数字...”
    • 然后，它开始依次创建或修改文件。例如，创建 src/routes/auth.ts ： 
      import { Router } from 'express';
import { register } from '../controllers/authController';
import { validateRegister } from '../middleware/validation'; // 它可能会提议创建这个中间件文件

const router = Router();

router.post('/register', validateRegister, register);

export default router;
    • 在整个过程中，它会在聊天中通报关键进展，比如“已创建路由文件，现在开始编写控制器逻辑...”。

  3. 任务完成与总结 ：

    “已完成用户注册接口的实现。总结如下：

    • 创建了 src/routes/auth.ts 路由文件。
    • 创建了 src/controllers/authController.ts ，包含密码加密（使用bcrypt）和逻辑处理。
    • 创建了 src/middleware/validation.ts ，使用 express-validator 验证邮箱和密码。
    • 更新了主 app.ts 文件以挂载 /api/auth 路由。
    • 所有代码均遵循项目的 TypeScript 配置和约定的代码风格。
    • 模拟用户数据暂存在内存数组中。 您可以运行 npm run dev 启动服务器，并使用 Postman 测试 POST http://localhost:3000/api/auth/register 。”

通过这个流程，你可以看到，一个复杂的任务被分解成了可管理、可审查的步骤。你始终掌控着进程，并且对 AI 的每一步决策都心中有数。

5. 高级技巧、常见问题与排查实录

即使有了完善的规则，在实际使用中还是会遇到各种问题。下面是我积累的一些高阶技巧和常见坑位解决方案。

5.1 模型选择与性能调优

  • 首选模型 ：规则集（特别是强调逐步思考的规则）是为 Claude 3.7 Sonnet (thinking) 和 Gemini 2.5 Pro 这类具备强推理和长上下文能力的模型优化的。它们的“思考”过程能很好地与 scratchpad 机制配合。
  • 避免“MAX”模式 ：对于日常开发任务，标准的“thinking”或“pro”模式通常足够，且响应更快、成本更低。“MAX”模式适用于极其复杂、需要深度推理的单次任务，但不适合作为持续对话的默认选项。
  • 上下文长度管理 ：这是影响大任务稳定性的关键。除了定期清理 scratchpad.md ，还有两个技巧：
    1. 对话分片 ：将一个大型项目（如“重构整个用户模块”）拆分成多个独立的聊天会话（如“重构用户模型层”、“重构用户API端点”、“重构用户界面组件”）。每个会话专注于一个子上下文，效果更好。
    2. 关键信息摘要 ：在开启新会话继续旧任务时，先让 AI 根据之前的 scratchpad.md 或代码变更，撰写一段简短的“项目当前状态摘要”，然后将这个摘要和规则一起作为新会话的上下文。这比传入整个历史聊天记录更高效。

5.2 规则冲突与优先级问题

有时，项目级的 .cursorrules 可能会和全局规则，或者 .cursor/rules/ 下的特定规则产生冲突。

  • 现象 ：AI 的行为出现矛盾，比如一边要求写注释，一边生成的代码又没有注释。
  • 排查与解决 ：
    1. 检查规则作用域 ：在 Cursor 中，规则优先级通常是： 文件/框架特定规则 > 工作区规则 ( .cursorrules ) > 全局规则 。确认你是否在 .cursor/rules/ 下放置了可能覆盖主规则的特定规则。
    2. 简化规则 ：如果规则文件过长或指令间存在潜在矛盾，AI 可能无法完全遵循。尝试精简你的 .cursorrules 文件，确保核心指令清晰、无歧义。将过于细节的风格要求（如“缩进用2个空格”）交给项目的 .prettierrc 或 .eslintrc 文件，并通过规则告诉 AI：“请遵循项目中的 Prettier 和 ESLint 配置格式化代码。”
    3. 使用明确的指令覆盖 ：在聊天中，你可以直接给出强指令来临时覆盖规则。例如，如果规则要求写测试但本次你只想快速原型，可以说：“ 忽略测试编写规则，本次只需实现核心功能。 ”

5.3 当 AI “不听话”或“变笨”时

  • 问题 ：AI 开始忽略规则，或者给出的代码质量明显下降。
  • 可能原因与对策 ：
    1. 上下文丢失 ：最可能的原因。检查 .cursorrules 文件是否还在当前聊天的上下文中。尝试在输入框重新 @ 一下这个文件。
    2. 模型过热或随机性 ：即使是同一个模型，在不同时间点也可能有状态波动。 最有效的解决方法是开启一个新的聊天会话 ，并重新载入规则上下文。这相当于“重启”了AI助手。
    3. 规则过于复杂 ：如果规则文件超过几千字，模型可能无法有效处理所有指令。考虑将规则拆分为核心行为规则（放在 .cursorrules ）和具体的代码风格指南（放在项目 README 或独立文档中，需要时让 AI 参考）。
    4. Prompt 不够清晰 ：你的指令本身可能模糊。学习使用更清晰的“结构化Prompt”，例如：“ 角色 ：你是我的前端助手。 任务 ：在 components/Button.tsx 中创建一个可复用的按钮组件。 要求 ：1. 支持 primary 、 secondary 两种类型；2. 支持 disabled 状态；3. 使用 Tailwind CSS 类；4. 用 TypeScript 定义 Props 接口。 输出 ：只给我最终的代码文件。”

5.4 针对特定技术栈的规则增强

我的仓库里引用了 awesome-cursorrules 中的框架特定规则。你可以将这些规则放入你项目的 .cursor/rules/ 目录来获得更专业的行为。

  • 操作步骤 ：

    1. 在项目根目录创建 .cursor/rules/ 文件夹。
    2. 从 awesome-cursorrules 仓库找到你需要的规则文件，例如 react.cursorrule 。
    3. 将其复制到 .cursor/rules/ 下。
    4. 现在，当你在项目中编辑 .jsx / .tsx 文件并与 AI 聊天时，它会自动融合 React 特定规则（如偏好函数组件、Hooks 使用规范）和你的主规则。

  • 自定义规则 ：你可以仿照这些规则，为你团队特有的技术栈（如内部的 UI 组件库、特定的状态管理方案）创建自定义规则。规则的本质就是文本指令，大胆地去定义你期望的 AI 行为模式。

6. 总结与个人使用体会

经过长达数月的日常使用和迭代，这套 .cursorrules 驱动的工作流已经深度融入我的开发习惯。它带来的最大改变，是 将我与 Cursor 的交互从“随机性的问答”变成了“可预期的协作” 。

我不再需要每次都对 AI 重复同样的基础要求（“用TypeScript”、“写注释”、“先想后做”）。规则文件就像一个永不疲倦的项目导师，在我每次开启聊天时，默默地为 AI 助手设定好工作基调。这节省了大量的沟通成本，让我能更专注于描述真正的业务逻辑和复杂问题。

几个让我感触最深的点：

  1. scratchpad.md 是灵魂 ：它不仅是 AI 的思考记录，更是我的“决策审计日志”。在回顾代码时，查看当时的 scratchpad 能立刻回想起为什么选择方案 A 而不是方案 B，这对于团队知识沉淀和后期维护价值巨大。
  2. 规则需要“养” ：没有一套规则是放之四海而皆准的。我最开始也是从别人的规则用起，但在使用过程中，不断遇到“哎，这里我希望它这样做”的情况，就立刻去修改 .cursorrules 文件。久而久之，这套规则就变成了完全贴合我个人编码习惯的“外挂大脑”。我强烈建议你也走这个路径：先用起来，再根据自己的痛点去调整。
  3. 心态转变：从“命令者”到“引导者” ：使用高级 AI 助手的最佳心态，不是给它下死命令，而是为它设定清晰的目标和边界，然后引导它思考。规则文件就是设定边界，而清晰的、分步骤的 Prompt 就是引导。当你结合这两者时，生产力提升是最显著的。

最后，开源这份规则集，是希望它能成为一个起点。如果你觉得有用，欢迎直接使用。如果你有更好的想法，更欢迎 Fork 和贡献。在 AI 辅助编程这个快速发展的领域，最好的工具永远是我们这些实践者共同塑造的。希望这套规则能帮助你，让你的 Cursor 变得更聪明、更懂你，真正成为你开发路上得力的伙伴。

Logo
DeepSeek技术社区

欢迎加入DeepSeek 技术社区。在这里，你可以找到志同道合的朋友，共同探索AI技术的奥秘。

更多推荐

cover

AI动态简报之算力基建篇

avatar DeepSeek技术社区
cover

端侧小模型 vs 云端大模型双轨部署：规则分流还是训练路由器的工程选择

avatar DeepSeek技术社区
cover

Agent 工具权限爆炸？最小权限原则与 DeepSeek 多租户隔离实践

avatar DeepSeek技术社区