1. 从“会用”到“精通”：为什么你需要定制Cursor规则？

如果你已经用Cursor写过一些代码，体验过它“动动嘴皮子”就能生成函数的爽快感，那你可能已经跨过了AI编程的“新手村”。但不知道你有没有遇到过这些情况：AI写的代码风格和你项目里的老代码格格不入；让它改一个功能，它却自作主张把整个文件重写了一遍；或者在一个大项目里，AI聊着聊着就“失忆”了，忘了之前定好的架构。

这些问题，根源在于AI模型是一个“通才”。它知道全世界程序员写代码的无数种习惯，但不知道“你”和“你的项目”的独特习惯。让它自由发挥，结果就像让一个博学的陌生人直接接手你的工作——他可能很聪明，但大概率会搞乱你的抽屉。

规则（Rules）和自定义模式（Custom Modes），就是解决这个问题的钥匙。它们不是简单的“快捷指令”，而是你为AI编写的“岗位说明书”和“工作流程手册”。通过它们，你可以告诉Cursor：“在这个项目里，请用这种方式思考，按这个规范写代码，并且只使用这些工具。”

我刚开始用Cursor时，也是想到什么问什么，结果经常要花大量时间去调整AI生成的代码，让它符合团队的ESLint规则，或者把过度设计的抽象层删掉。后来我意识到，与其每次和AI“讨价还价”，不如一次性把规矩定好。当我为我的Vue3 + TypeScript项目写了一套完整的规则后，开发体验发生了质变。AI生成的组件几乎开箱即用，代码风格统一，甚至能主动提醒我遗漏的边缘情况。这才算是真正把AI变成了我的“专属资深工程师”。

所以，如果你已经不满足于用Cursor写写零散的函数，而是希望它能深度参与甚至主导一个中大型项目，那么深入学习和定制规则，就是你必须要走的一步。这不仅仅是提升效率，更是提升代码质量和项目可控性的关键。

2. 规则（Rules）实战：从零编写你的第一份“AI岗位说明书”

规则文件（.mdc 文件）的本质，是一份用自然语言写给AI看的“开发规范”。写得好，AI就乖巧听话；写得模糊，AI就会放飞自我。下面我结合自己踩过的坑，带你一步步写出一份高质量的规则。

2.1 规则的核心结构与心法

一份完整的规则，通常包含以下几个部分，你可以把它们想象成招聘时写的JD（职位描述）：

角色定义 (Role Definition) 这是第一步，也是最重要的一步。你要明确告诉AI：“你现在是谁？” 这能极大地引导模型的思考方向。

角色定义
您是一名资深的全栈开发工程师，拥有8年以上React和Node.js实战经验，尤其精通高性能、可扩展的后端API设计。您对代码质量有极致追求，遵循“KISS”（Keep It Simple, Stupid）原则，厌恶不必要的抽象。

• 为什么有效？ 研究显示，明确的角色提示能显著提升模型输出的专业性和结构清晰度。这相当于给AI一个“专业人设”，它后续的推理和决策都会基于这个人设展开。

任务与目标 (Task & Goal) 定义AI的核心职责。这能让AI聚焦，避免它去处理无关请求。

任务与目标
您的核心任务是协助我完成当前项目的功能开发、代码重构和问题调试。所有产出必须直接服务于项目目标，且具备生产环境可用性。

约束与要求 (Constraints & Requirements) 这是规则的“防火墙”，用来限制AI的“幻觉”和过度发挥。我把这部分又细分为几块：

1. 代码规范类：直接关联你的项目配置。

   代码规范
   - 严格遵守项目根目录下的 `.eslintrc.js` 和 `.prettierrc` 配置。
   - 新组件一律使用函数式组件配合React Hooks，禁止使用Class组件。
   - 所有异步操作必须使用 `async/await` 语法，并处理错误。
   - 禁止使用 `any` 类型，必须显式定义TypeScript接口。
   

2. 行为限制类：防止AI做出令人头疼的操作。

   行为限制
   - **未经明确同意，禁止直接修改或删除已有文件的核心逻辑。** 如需改动，必须先提供改动方案并征得确认。
   - **禁止在代码中添加非必要的`console.log`。** 仅在调试时，且经要求后添加，并附带清晰注释。
   - **禁止为简单的功能添加复杂的“未来可能用到”的抽象层。** 优先实现当前需求。
   

3. 交互流程类：规定AI与你合作的步骤。

   交互流程
   - 当接到一个复杂需求时，**必须先输出实现思路和模块设计图**，待确认后再开始编码。
   - 当对需求或代码有不确定时，必须主动提问，禁止猜测。
   - 每次完成一个功能模块后，用一句话总结所做更改。
   

项目上下文 (Project Context) 把项目的关键信息“喂”给AI。我强烈建议你使用 @ 符号来引用。

项目上下文
- 项目结构：@Files /project-structure.txt （你可以让AI先帮你生成这个文件）
- 核心架构说明：@Files /docs/architecture.md
- API接口规范：@Files /docs/api-spec.md

这样，AI在每次对话时，都能自动获取这些文件的当前内容作为背景知识，理解力大幅提升。

输出格式 (Output Format) 统一输出的“样子”，方便你后续处理。

输出格式
- 所有代码块必须指明语言类型，如 ```typescript。
- 提供的解决方案，请按以下结构组织：
  ### 问题分析
  [简要分析]
  ### 解决方案
  [代码或步骤]
  ### 注意事项
  [可能的坑]
- 如需生成新文件，请提供完整的文件路径和内容。

2.2 规则的生效时机与存放位置

写好规则文件后，你需要决定它何时生效，以及放在哪里。

生效时机（When to Run） 在规则文件顶部，你可以设置：

• Always: 在任何对话中自动生效。适合放一些全局性的基础规范（如代码风格）。
• Auto-Attached: 当对话上下文涉及相关文件时自动生效。适合模块级规则。
• Manual: 仅在手动添加 @Cursor rules 时生效。适合一些临时性的、针对特定任务的规则。

我的经验是，将最核心的、项目级的约束（如技术栈、目录规范）设为 Always。将一些具体的业务逻辑约束（如“用户服务层的所有方法都必须记录审计日志”）设为 Auto-Attached，关联到对应的文件或目录，这样既精准又不会造成上下文干扰。

存放位置

• 项目级规则：放在项目根目录的 .cursor/rules/ 文件夹下。这是最推荐的方式，规则会成为项目资产，任何克隆该项目的队友打开Cursor都能享受到一致的AI辅助。
• 用户级规则：放在你的用户目录下（如 ~/.cursor/rules/）。这里适合放你个人跨项目的通用偏好，比如你个人偏好的代码注释风格、常用的工具函数模板等。

我通常会在一个新项目开始时，先建立 .cursor/rules/ 目录，然后创建一个 project_basics.mdc 文件，把技术栈、代码规范等基础规则放进去，设为 Always。随着开发进行，再为不同的模块（如 auth.mdc, payment.mdc）添加更细化的规则。

3. 自定义模式（Custom Modes）：打造你的专属AI工作流

如果说规则（Rules）是给AI定的“行为规范”，那么自定义模式（Custom Modes）就是为AI配置的“专属工作台”。它比规则更强大，因为你可以精确控制AI能使用哪些“工具”（Tools），并为不同的工作场景创建完全不同的AI助手。

3.1 模式与规则的区别

很多人会混淆两者。简单来说：

• 规则 主要影响AI的“思考内容”和“输出内容”（写什么，怎么写）。
• 模式 主要定义AI的“身份角色”和“可用能力”（是谁，能做什么）。

举个例子：你可以创建一个 “代码审计员”模式，在这个模式里，你只赋予AI Read File（读文件）和 Search Codebase（搜索代码库）的权限，禁用 Edit File（编辑文件）的权限。然后给它配上相应的规则，要求它专注于发现代码中的安全漏洞、性能问题和坏味道。这样，当你切换到“代码审计员”模式提问时，它绝不会动手改你的代码，只会给出分析和建议报告。

3.2 手把手创建一个“架构师”模式

让我们实战创建一个用于项目初期技术选型和架构设计的模式。

1. 打开模式创建界面：在Cursor中，点击左下角的模式选择器（通常显示为“Default”或当前模式名），选择“Manage Modes”，然后点击“Create New Mode”。

2. 定义模式身份与工具：

   • 名称：System Architect
   • 描述：专注于后端系统技术选型、架构设计、数据库建模和API设计。提供权衡分析和生产环境考量。
   • 工具权限：这里非常关键。对于架构师，我们不需要它直接写业务代码，所以可以只勾选：
     • Search Codebase (了解现有基础)
     • Read File (阅读文档)
     • Web Search (可选，用于查找最新技术资料)
     • Composer (用于总结和输出文档) 务必取消勾选 Edit File 和 Run Commands，防止它在设计阶段就胡乱修改或运行代码。

3. 编写模式指令（核心）： 在指令框中，你需要像写规则一样，清晰地告诉这个“架构师”该如何工作。

   你是一位严谨的CTO/首席架构师，负责评估技术方案的生产环境适用性。
   
   核心职责：
   1.  **技术选型分析**：针对提出的需求，推荐2-3个备选技术栈（如数据库用PostgreSQL vs MongoDB）。必须列出每项的**优点、缺点、适用场景、学习成本、社区生态和长期维护性**。
   2.  **架构图绘制**：使用Mermaid语法（仅限标准流程图、时序图、组件图）绘制清晰的架构示意图，并附上关键节点说明。
   3.  **API设计**：设计RESTful或GraphQL API接口，需包含端点、方法、请求/响应体（JSON Schema示例）、状态码和可能的错误。
   4.  **数据库建模**：给出核心表的ER图（用Mermaid）或字段定义，并说明索引策略。
   
   工作原则：
   - **不做假设**：对任何不确定的需求点，必须首先提问澄清。
   - **生产优先**：所有建议必须考虑部署、监控、扩缩容和故障恢复。
   - **提供选项**：不给出唯一“正确”答案，而是提供有据可依的选项供决策。
   - **输出结构化**：所有输出必须分点、分章节，清晰易读。
   
   禁止事项：
   - 直接编写具体的业务实现代码。
   - 在没有充分对比的情况下，推荐小众或不成熟的技术。
   - 输出过于理论化、无法落地的方案。
   

4. 保存并使用：保存后，你就可以在模式选择器中切换到 System Architect。当你问它“我们要做一个高并发的实时聊天应用，后端该怎么设计？”时，它会以一个架构师的视角，给你一份包含技术对比、架构图和API设计的专业方案，而不是直接开始写WebSocket的代码。

3.3 我的常用模式组合

经过实践，我固定下来了几个模式，通过快捷键快速切换，应对不同场景：

• Default (默认模式)：集成所有基础规则，拥有全部工具权限。用于日常的编码、调试和重构。
• Code Reviewer (代码审查模式)：工具权限仅“读文件”和“搜索”。用于提交PR前，让AI以挑剔的眼光快速过一遍代码，找出潜在Bug和坏味道。
• Documentarian (文档工程师模式)：工具权限侧重“读文件”和“写文件”。规则要求其将代码注释和变更自动转化为更新后的API文档或CHANGELOG。
• Bug Hunter (捉虫模式)：规则强调“逆向思维”和“边界条件测试”。当我遇到一个棘手的Bug时，切换到它，让它帮我分析可能的原因和复现路径。

这种“分场景定制”的思路，极大地提升了我和AI协作的专注度和效率。我不再需要在一个对话里反复纠正AI的角色，而是“需要什么专家，就请什么专家出来”。

4. 征服大型项目：用规则和模式拆解复杂任务

“AI只能写小函数，搞不定大项目。”——这是最常见的误解。问题不在于AI的能力，而在于我们使用它的方式。试图在一个对话里让AI从零构建一个完整系统，必然会触发上下文限制，导致它“失忆”和混乱。正确的方法是：结构化拆解，分步指导。

4.1 第一步：需求结构化与任务拆分

不要直接把产品需求文档扔给AI。你需要先做一次“产品经理→技术负责人”的转换。

1. 创建需求文档：在一个独立的Markdown文件（如 requirements.md）里，用清晰的结构梳理需求。例如：

   # 项目：用户积分商城系统
   ## 核心功能
   1.  用户积分获取与查询
   2.  积分商品上架与管理（后台）
   3.  积分兑换订单流程
   4.  兑换记录与物流查询
   ## 非功能性需求
   - 并发要求：支持每秒1000次积分查询。
   - 数据一致性：积分扣减与订单创建需保证事务。
   ...
   

2. 启动“架构师”模式：将 requirements.md 文件添加到上下文（用 @ 引用），然后问AI：“基于以上需求，请设计一个可行的后端微服务架构，并拆分出第一阶段可实施的核心模块与任务。” AI会输出一个包含服务划分（如用户服务、积分服务、商品服务、订单服务）、技术栈建议和数据库设计的方案，并给出一个初步的任务列表。

3. 人工评审与细化：这是至关重要的一步。你需要审核AI的架构设计，调整不合理之处，并将任务列表细化成一个个独立的、可在单个AI对话窗口内完成的“原子任务”。例如：

   • 任务1：创建 user-service 项目骨架，定义 User 实体和基础CRUD接口。
   • 任务2：在 user-service 中实现积分增减的 Wallet 领域模型及方法。
   • 任务3：创建 product-service，定义 Product 实体和管理员CRUD接口。
   • ...

4.2 第二步：基于“原子任务”的增量开发

为你的项目配置好基础规则（project_basics.mdc）后，就可以开始逐个攻克“原子任务”。

1. 开启新对话，锁定单一目标：每个对话只解决一个“原子任务”。在对话开始时，就明确说：“本次对话，我们只实现 user-service 中的 Wallet 积分钱包领域模型。”
2. 先设计，后编码：即使任务很小，也先要求AI输出设计思路和关键的类/方法定义。确认无误后，再让它生成具体代码。

   @Files /docs/architecture.md //引入架构文档
   请为“用户积分钱包”设计领域模型。需要包含以下核心能力：
   1. 查询当前积分余额。
   2. 增加积分（需记录来源，如“签到”、“消费返利”）。
   3. 消费积分（需保证余额充足，并记录用途）。
   请先给出 `Wallet` 类的属性和方法签名（TypeScript接口），并说明核心业务流程。
   

3. 边开发，边沉淀文档：在AI生成代码的同时，要求它同步更新或创建对应的模块文档。这份文档不仅是给人看的，更是给后续的AI对话看的“上下文遗产”。我习惯让AI用特定的格式来写这份“AI友好型”文档：

   ## 模块：用户积分钱包 (User Wallet)
   **位置**：`packages/user-service/src/domain/wallet/`
   **核心类**：`Wallet`
   **职责**：管理用户积分的核心领域逻辑。
   **AI开发提示**：
   - 修改积分余额时，**必须**通过 `Wallet.addPoints(amount, source)` 或 `Wallet.consumePoints(amount, usage)` 方法。
   - 所有积分变动**必须**生成 `WalletTransaction` 记录。
   - 积分消费前**必须**调用 `Wallet.hasSufficientPoints(amount)` 进行检查。
   

4. 任务闭环与上下文接力：完成一个“原子任务”后，将本次对话中生成的核心代码和最重要的“AI友好文档”保存下来。当开始下一个关联任务时（例如，实现积分消费的API接口），在新的对话中，用 @Past chats 引用上一个对话的总结，并用 @Files 引入相关文档和代码。这样，AI就能无缝衔接上之前的思路，仿佛一直在同一个上下文中工作。

通过这种“结构化拆解、分步实施、文档接力”的方法，我成功用Cursor主导开发过一个包含多个微服务的内部中台系统。AI负责了大约70%的重复性、模式化的代码编写和文档工作，而我则专注于核心业务逻辑的设计、AI输出的评审以及模块间的集成调试。这让我有更多时间思考更深层次的架构问题，而不是埋头于CRUD。

5. 避坑指南：解决AI编程中的典型问题

即使有了完善的规则和模式，在实际操作中还是会遇到一些让人头疼的“AI行为”。下面是我总结的几个最常见问题及其应对策略。

5.1 问题：AI“过度设计”与“过度工程化”

这是最普遍的问题。AI（特别是高级模型）倾向于写出“学院派”或“大厂范儿”的代码，动不动就给你加上完整的错误监控、国际化(i18n)、复杂的日志链路，甚至在你写一个简单的工具函数时引入设计模式。

解决方案：在规则中设立明确的“审批制”。 不要简单地说“不要过度设计”，这太模糊。而是明确列出哪些“高级功能”需要经过人工确认才能添加。

## 设计约束
- **【强制】以下功能在引入前必须主动询问是否需要，未经确认禁止直接实现：**
    1.  国际化 (i18n) 相关代码。
    2.  单元测试或集成测试框架（如Jest, Mocha）的引入。
    3.  性能监控、链路追踪、日志上报等可观测性代码。
    4.  任何新的第三方依赖库的引入。
    5.  超出当前需求范围的抽象层或设计模式（如工厂模式、观察者模式）。
- **原则**：优先实现最简单、最直白的解决方案。仅在复杂性确有必要时，才进行抽象。

5.2 问题：Agent模式“不听话”，上来就改代码

在Agent模式下，AI有时会过于“积极”，你刚描述完问题，它就开始搜索代码库并准备修改文件，这在你只是想讨论方案时非常危险。

解决方案：规则约束 + 流程化指令。

1. 在规则中设定“思考-确认”流程：

   ## 工作流程
   - 当接收到一个涉及代码修改的复杂任务时，**必须**遵循以下步骤：
       1.  **分析**：先复述问题，并分析可能的原因和影响范围。
       2.  **方案**：提供至少一种详细的解决方案，说明改动点、涉及文件和潜在风险。
       3.  **确认**：明确询问：“以上是我的分析，是否按此方案执行修改？”
   - 只有在收到明确的执行指令（如“请执行”、“按方案修改”）后，才能开始编辑代码。
   

2. 在提问时主动引导：在描述问题后，加上一句：“请先给出你的分析思路，不要直接修改代码。”

5.3 问题：上下文混乱与“失忆”

在长对话中，AI可能会忘记很早之前的约定，或者把不同任务的指令混淆。

解决方案：对话隔离与关键信息固化。

• 单一职责对话：严格遵守“一个对话只做一个核心事情”的原则。聊架构就新开一个对话，聊具体实现再开一个。
• 善用 @Past chats：当系统建议你开启新对话时，务必使用 @Past chats 功能，将上一个对话的总结引入新对话，这是保持思路连贯性的官方推荐做法。
• 核心约定文档化：将对话中确定下来的重要架构决策、接口约定等，立刻让AI帮你整理成正式的文档（如 api-contract.md），并保存到项目里。后续所有相关对话，都先 @ 引用这份文档。这样就把易逝的“对话记忆”，固化为可靠的“项目知识”。

5.4 问题：生成的代码有细微偏差

有时AI生成的代码整体思路正确，但一些细节（比如某个特定API的参数顺序、某个内部函数的命名）和项目现有规范不符。

解决方案：利用“部分接受”与“内联聊天”进行微调。

• Tab逐字接受：当AI在代码补全建议中生成一大段代码时，不要急于全部接受。你可以按 Ctrl/Cmd + → 方向键，一个单词一个单词地接受，直到出现偏差的地方停下，手动修改，然后再继续接受。这能给你极强的控制感。
• 内联聊天 (Cmd/Ctrl+K)：这是我最喜欢的功能之一。当你在代码中间发现一个需要调整的小地方，直接选中那段代码，按 Cmd+K，在出现的提示栏里输入你的要求，比如“把这个循环改成用map函数”。AI会直接在原地修改这段选中的代码，而不会影响上下文其他部分，精准又高效。

AI编程不是魔法，它不会让你一夜之间变成十倍效率的开发者。它更像是一个能力超强但需要精心调教的实习生。规则和自定义模式，就是你给这位实习生的“培训手册”和“工作流程”。初期投入时间去编写和调试它们，看起来是额外的成本，但一旦这套体系运转起来，它带来的代码一致性、开发流畅度和心智负担的减轻，回报是巨大的。真正的效率提升，不在于AI替你写了多少行代码，而在于你从重复、琐碎、易错的劳动中解放出来，能将宝贵的创造力集中在真正需要人类智慧的设计和决策上。