AI编码助手规则体系构建：从Cursor实践看工程化提效

1. 项目概述：为什么我们需要为AI编码助手制定“规则”？

如果你和我一样，从VSCode切换到Cursor，最初可能只是被它“能聊天、能写代码”的噱头所吸引。但用了一段时间后，我发现一个核心问题：AI助手虽然强大，但它就像一个新来的、天赋异禀但毫无经验的实习生。你让它写个API接口，它可能给你生成一个RESTful风格的；但你的项目内部约定可能是GraphQL，或者有一套自研的RPC框架。结果就是，你花在审查和修改AI生成代码上的时间，甚至比自己从头写还要多。这完全违背了提升效率的初衷。

这正是digitalchild/cursor-best-practices这个项目试图解决的核心痛点。它不是一个简单的功能列表，而是一套关于如何“驯化”Cursor，让它真正理解并融入你个人或团队开发生态的系统工程。其核心思想是：通过一套结构化的规则（Rules）和上下文（Context）文件，将你的项目规范、技术栈偏好、代码风格乃至工作流程，“灌输”给Cursor。最终目标，是让Cursor生成的每一行代码，都像是你自己写出来的一样——符合规范、风格统一、直接可用。

简单来说，这就像是为你的AI助手编写一本详尽的《项目开发手册》。没有它，Cursor是在“盲猜”；有了它，Cursor是在“按图索骥”。接下来，我将结合自己近半年的深度使用和团队推广经验，为你拆解如何从零开始，构建一套高效、可维护的Cursor规则体系。

2. 规则体系深度解析：从全局到局部的控制力

Cursor的规则系统设计得非常精巧，它通过多层级的规则应用，实现了从粗到细的粒度控制。理解这个层次结构，是有效利用它的第一步。很多人上来就埋头写.mdc文件，却忽略了全局设置，导致事倍功半。

2.1 规则优先级：当多条规则冲突时，谁说了算？

这是最容易被忽视，却至关重要的部分。Cursor内部有一个明确的规则评估顺序，理解它才能避免规则互相“打架”。

1. 本地（手动）规则：优先级最高。当你在聊天框或Composer中使用@ruleName显式引用某条规则时，这条规则会立即被激活并置于最高优先级。这用于临时覆盖其他规则，处理特殊情况。
2. 自动附加规则：当AI处理的任务涉及的文件路径，匹配了某条规则中定义的globs模式（如src/api/**/*.ts），这条规则会被自动附加到上下文中。这是实现“按场景生效”的核心机制。
3. 代理请求规则：AI助手自己判断是否需要某条规则。这要求规则必须有清晰的description字段，AI会根据描述和当前任务的相关性来决定是否采用。这给了AI一定的自主权，去调用它认为有帮助的通用规则。
4. 始终应用规则：在规则文件中设置了alwaysApply: true，或者在User Rules中定义的全局规则。这些规则作为底线，在所有场景下生效。

实操心得：优先级意味着“覆盖”。你可以利用这一点进行分层设计。例如，在User Rules里设置“所有响应请用中文”，这是一个底线。但在某个项目的.mdc规则里，你可以设置alwaysApply: true的规则“本项目API响应需遵循{code, data, message}格式”。当处理该项目的API文件时，项目规则会与全局规则共同作用。而如果你临时用@englishOnly引用一条“本次对话请用英文”的规则，它会暂时覆盖全局的中文要求。

2.2 用户规则：奠定你的个人编码基调

User Rules位于Cursor的设置界面中（Cmd + ,打开设置，搜索Rules）。这里配置的规则会应用于你账号下的所有项目，是塑造AI与你交互风格的“人格基底”。

它的内容就是纯文本指令，不支持.mdc的YAML头或复杂格式。但这恰恰是它的优势：简单、直接、全局生效。

你应该在这里放什么？

• 交互风格：比如“请用简洁、直接的语言回答，避免客套话和冗余解释。”
• 全局编码偏好：比如“除非特别说明，否则请使用TypeScript并严格类型检查。”、“请为所有生成的函数和复杂逻辑添加JSDoc注释。”
• 安全与质量红线：比如“生成的代码中绝对禁止出现硬编码的密码、密钥或敏感信息。”、“在提供涉及文件系统或网络操作的代码时，必须包含基本的错误处理。”

// 一个我的User Rules示例 - 请使用中文进行回复和代码注释。 - 在提供解决方案时，请先简要说明思路，再给出代码。 - 生成的代码应优先考虑可读性和可维护性，其次才是性能优化。 - 对于可能产生副作用的操作（如删除文件、写入数据库），必须给出明确警告。

注意事项：User Rules不宜过长或过于具体。它应该是原则性的、跨项目通用的。如果把某个项目的具体技术栈（如“使用Zustand而非Redux”）放在这里，就会在其他项目中造成干扰。记住，这里是“个人工作习惯”，不是“项目规范”。

2.3 项目规则：.mdc文件——团队协作的基石

项目规则是这套实践的灵魂所在，它存储在项目根目录的.cursor/rules/文件夹下，每个规则是一个独立的.mdc（Markdown Cursor）文件。这个目录应该被加入版本控制（如Git），从而确保团队每个成员使用的AI助手都遵循同一套标准。

一个.mdc文件由两部分组成：

1. YAML Frontmatter（元数据）：用于定义规则的属性，如描述、作用范围、应用方式。
2. 规则内容（Markdown）：具体的指令和规范，用Markdown列表或段落书写。

2.3.1 解剖一个完整的.mdc规则文件

让我们看一个比官方示例更贴近真实场景的规则：一个针对React组件开发的规则。

--- description: React组件开发规范 - 适用于所有使用TypeScript和Tailwind CSS的组件 globs: - src/components/**/*.tsx - src/components/**/*.ts alwaysApply: false priority: high --- # React组件开发指南 当创建或修改React组件时，请严格遵守以下规范： ## 组件定义 - 使用函数式组件，配合`React.FC`类型（或直接标注参数类型）。 - 组件文件名使用`PascalCase`，如`UserProfileCard.tsx`。 - 默认导出组件本身。 ## Props与类型 - 使用`interface`定义组件的Props。 - 为可选Props设置默认值，或在interface中标记为可选（`?`）。 - 禁止使用`any`类型。 ## 样式与结构 - 本项目使用**Tailwind CSS**进行样式开发。请优先使用Tailwind工具类，禁止在组件中编写`*.module.css`或`styled-components`。 - 容器元素默认使用`div`，语义化标签仅在明确时使用（如`<section>`, `<article>`）。 - 复杂组件需使用`@apply`提取重复的Tailwind类到CSS中，保持JSX整洁。 ## 状态与副作用 - 简单状态使用`useState`。 - 复杂状态逻辑或需要跨组件共享时，使用项目中的`useStore`自定义Hook（基于Zustand）。 - 副作用必须被`useEffect`正确管理，并注意清理函数。 ## 示例参考 请参考现有组件 `@src/components/common/Button.tsx` 和 `@src/components/layout/Header.tsx` 的结构和风格。

元数据字段解读：

• description: 必填。清晰描述规则用途，供AI理解和用户在规则列表中识别。
• globs: 关键字段。定义此规则自动附加的文件路径模式。支持数组，可匹配多个模式。
• alwaysApply: 默认为false。若为true，则此规则会在项目任何上下文中被加载，慎用，以免造成上下文污染。
• priority(可选): 提示AI此规则的重要性。

规则内容撰写技巧：

• 结构化：使用Markdown标题和列表，让内容清晰可读（对人、对AI都是如此）。
• 具体化：避免“写出高质量的代码”这种模糊要求，取而代之的是“函数长度不超过50行”、“圈复杂度低于10”。
• 提供锚点：使用@文件名的语法直接链接到项目中的典范代码，这是最强大的上下文提供方式。AI可以直接读取这些文件的内容作为参考。

2.3.2 规则类型与策略

根据alwaysApply和globs的设置，以及是否被手动引用，规则在实践中表现为几种类型：

踩坑实录：初期我曾把所有规范塞进一个alwaysApply: true的project-guide.mdc里，结果发现Cursor的上下文窗口很快被占满，导致它在处理简单任务时也反应迟钝，甚至遗忘核心指令。教训是：规则一定要细粒度、场景化拆分。一个庞大的规则文件远不如十个精准的小规则有效。

3. 核心实践：构建你的项目上下文体系

规则（Rules）告诉AI“怎么做”，而上下文（Context）文件则告诉AI“这是什么”。两者结合，才能让AI真正理解你的项目。instructions.md和roadmap.md是官方推荐的两个核心上下文文件。

3.1instructions.md：项目的“总说明书”

这个文件是你给AI的“项目入职手册”。它不应该放在.cursor/rules/里，而应该放在项目根目录或显眼的位置。它的目标是让一个完全不了解项目的人（或AI）快速掌握全貌。

一份优秀的instructions.md应包含哪些部分？

1. 项目简介：用一两句话说明项目是做什么的，解决什么问题。
2. 技术栈：精确到版本号。例如：“前端：React 18.2 + TypeScript 5.0 + Vite 5.0；状态管理：Zustand 4.4；UI库：Ant Design 5.12；CSS框架：Tailwind CSS 3.3”。
3. 项目结构：解释主要目录的职责。不要只列文件夹，要说明为什么这样设计。

   src/ ├── api/ # 所有API请求层封装，基于axios，已配置拦截器和错误统一处理 ├── components/ # 通用业务组件，按领域子目录划分 ├── hooks/ # 自定义React Hooks ├── stores/ # Zustand状态仓库 ├── utils/ # 纯函数工具库 └── pages/ # 页面级组件，对应路由

4. 核心架构与模式：解释关键设计决策。例如：“数据流采用单向数据流，组件通过调用stores/中的action来改变状态，禁止组件间直接传递回调函数深嵌套。”
5. 开发与构建命令：npm run dev启动什么？npm run build有什么特殊参数？
6. 编码规范速查：虽然细节在规则文件里，但这里可以放一些最核心、最易忘的，比如“接口命名前缀用I还是不用？”、“async函数必须用try-catch包裹吗？”

你可以用这样一个Prompt来让AI帮你生成初稿：“你是一个资深技术文档工程师。请根据当前项目结构、package.json和主要源代码，为我生成一份详细的instructions.md文件，需包含项目概述、技术栈、目录结构说明、开发指南和编码规范摘要。”

3.2roadmap.md：指引长期开发方向

这个文件用于规划未来。当AI在协助你开发一个新功能时，如果它能看到这个功能在整体路线图中的位置，以及后续可能关联的模块，它就能给出更具前瞻性的代码建议，减少未来的重构。

内容示例：

# 项目开发路线图 ## 当前版本 (v1.2.0) - [ ] 用户个人中心页面重构 - [ ] 集成实时消息通知WebSocket服务 - [ ] 后台管理系统增加数据仪表盘 ## 下一阶段 (v1.3.0) - 性能优化：实现组件级代码分割（React.lazy） - 引入PWA支持，实现离线缓存 - 国际化(i18n)框架调研与基础搭建 ## 未来构想 - 移动端原生应用（React Native）可行性研究 - 微前端架构改造，拆分主应用与子应用

当AI在帮你写“用户个人中心”的代码时，它看到后续有“国际化框架”的计划，可能会提醒你：“当前写的硬编码文本，是否需要提前抽离到潜在的i18n键值结构中？” 这种前瞻性建议非常有价值。

3.3 忽略文件：.cursorignore的妙用

Cursor会索引项目文件以提供上下文，但像node_modules、dist、*.log这类文件不仅无用，还会浪费索引资源，拖慢响应速度。.cursorignore文件的作用类似于.gitignore，用于排除这些文件。

# .cursorignore 示例 node_modules/ dist/ build/ *.log *.tmp coverage/ .DS_Store .env*.local

重要提示：.cursorignore只影响Cursor的后台索引和自动上下文加载。你依然可以在聊天中通过@文件名手动引用被忽略的文件。这与.gitignore的行为不同。

4. 高级技巧与Composer高效用法

掌握了规则和上下文，你已经能解决80%的问题。剩下的20%在于如何与Cursor高效交互，尤其是利用好其核心功能——Composer。

4.1 Composer模式：Agent与Normal的选择

Cursor的Composer有两种模式，对应不同的使用场景：

• Normal Mode（默认）：你选中代码，按下Cmd+K，输入指令。AI会根据当前打开的文件和选中的代码块来理解上下文。这是最常用、最精准的模式，适合局部代码的生成、解释、重构和调试。因为上下文非常聚焦，AI的答案通常更准确。

• Agent Mode（Cmd+.）：你提供一个高层次的任务描述（如“为产品列表添加分页功能”），AI会自主分析项目结构，定位相关文件，并可能执行一系列操作（打开文件、编辑代码、甚至运行命令）。它更强大，但也更不可控。适合探索性任务或当你对代码库不熟悉时，让AI帮你寻找切入点。

实操心得：对于明确的修改任务，永远优先使用Normal Mode。先自己导航到相关文件，选中要修改的代码区域，再用Composer。这相当于给AI画了一个清晰的“作战地图”，它能给出极其精准的建议。滥用Agent Mode容易导致AI“迷路”，修改了不该改的文件。

4.2 上下文命令：精准投喂信息

这是大幅提升AI理解准确度的关键。在聊天框或Composer指令中，除了文字描述，一定要多用@命令来提供精确上下文。

• @src/components/Form/UserForm.tsx：直接引用一个文件。AI会读取其全部内容。
• @src/api/：引用整个目录。AI会了解这个目录下的文件结构（但不会读取所有内容，除非特别要求）。
• “请参考这段代码的逻辑：” @code src/utils/validation.js:15-30：引用一个文件的特定行号。这是最精准的锚点。
• @docs README.md：引用项目文档。
• @web “React useEffect cleanup best practices”：让AI临时搜索网络信息（谨慎使用，可能慢且信息不确定）。

一个高效的工作流：

1. 接到任务：“修改登录接口，增加图形验证码校验。”
2. 先找到现有的登录接口文件src/api/auth.ts， 打开它。
3. 找到处理登录的函数login， 选中它。
4. 按下Cmd+K， 输入：“在这个login函数中，在调用post请求之前，增加对captcha参数的校验。校验逻辑请参考项目中已有的验证码工具：@src/utils/captcha.ts。校验失败时，抛出ValidationError。”
5. AI会基于你提供的精确代码位置和参考工具文件，生成几乎可以直接接受的代码。

4.3 规则与上下文的组合拳

最强大的用法是将规则、上下文文件和@命令结合起来。

假设你有一条规则叫api-response-format.mdc，定义了所有API控制器必须返回{ success, data, message }格式。 你正在编写一个新的用户控制器user.controller.ts。

你可以这样操作：

1. 打开（或创建）user.controller.ts。
2. 在Composer中输入：“创建一个获取用户列表的GET端点。请遵循@api-response-format规则，并且分页参数请使用项目通用的PaginationParams接口，定义在@src/types/common.ts中。”
3. Cursor会同时加载api-response-format规则和common.ts类型文件作为上下文，生成的代码会天然符合你的项目规范，无需二次调整。

5. 常见问题与避坑指南

在实际部署和团队推广这套实践的过程中，我遇到了不少典型问题。这里汇总一下，希望能帮你绕开这些坑。

5.1 规则不生效或效果不佳

• 问题：写了.mdc规则，但AI似乎完全无视。
• 排查：
  1. 检查文件位置：规则文件必须放在.cursor/rules/目录下，且扩展名为.mdc。
  2. 检查YAML语法：---包裹的元数据部分必须是有效的YAML。最常见的错误是缩进用了Tab键（必须用空格），或冒号后没加空格。
  3. 检查globs模式：globs模式是相对于项目根目录的。src/**/*.ts会匹配所有TS文件，而./src/**/*.ts可能无法正确匹配。使用在线Glob测试工具验证你的模式。
  4. 规则冲突：检查是否有alwaysApply: true的规则与你的场景化规则冲突。或者User Rules中的指令与项目规则矛盾。记住优先级顺序。
  5. 上下文过载：如果同时激活了太多规则（尤其是内容很长的规则），可能会挤占有限的上下文窗口，导致AI“忘记”了某些指令。精简规则内容，拆分大规则。

5.2 AI生成的代码风格飘忽不定

• 问题：有时生成符合规范的代码，有时又回到它的默认风格。
• 解决：
  1. 强化规则的具体性：不要写“使用清晰的命名”，要写“变量名使用camelCase，函数名使用动词开头如fetchUserData，组件名使用PascalCase”。
  2. 提供“榜样”代码：在规则中多用@引用项目内公认写得好的文件。AI非常擅长模仿。
  3. 在指令中明确重申：在给AI下指令时，可以再次强调关键规范。例如：“请创建一个React组件，注意使用函数式组件和TypeScript，Props用interface定义，样式全部使用Tailwind类名。”
  4. 检查规则作用范围：确保你正在编辑的文件路径，匹配了对应规则的globs模式。

5.3 团队协作时规则同步问题

• 问题：团队成员更新了规则，其他人如何快速同步？
• 最佳实践：
  1. 版本控制：确保.cursor/rules/目录和instructions.md等核心上下文文件都提交到Git。
  2. 规则变更通知：在团队内建立简单约定，当有人更新重要规则（如API规范、组件规范）时，在Pull Request描述中说明，或在团队频道简单通知。
  3. 编写SETUP.md：在项目根目录创建一个简单的SETUP.md，其中一步就是“拉取代码后，请确认Cursor已正确加载项目规则”。可以引导团队成员在Cursor中检查规则列表。
  4. 定期回顾：在团队技术会议上，可以花几分钟回顾一下常用规则的有效性，根据大家的反馈进行优化。

5.4 如何开始：渐进式采用策略

如果你面对一个已有的大型项目，感到无从下手，不要试图一次性编写所有规则。

1. 从痛点开始：找出AI最常出错的领域。是API格式不统一？还是组件结构混乱？就从这里写第一条规则。
2. 创建instructions.md：用AI辅助，快速生成一份项目概述。这能立即提升AI对项目的整体理解。
3. 制定1-2条核心alwaysApply规则：比如“所有错误必须用统一类抛出”、“所有API响应遵循固定格式”。这是底线。
4. 按模块扩展：接下来一周，当你需要开发或修改src/components/Button相关文件时，为components目录编写一条规则。下一周，处理api目录时，再写一条。积少成多。
5. 鼓励团队贡献：建立一个共享文档或频道，让大家记录“如果AI能自动遵守XX规则就好了”的想法，然后将其转化为正式的.mdc文件。

经过几个月的实践，这套方法已经将我团队的平均代码审查通过率提升了超过50%，因为AI生成的第一版代码就已经非常接近最终要求。它更像是一个严格遵循团队规范的超级实习生，而不是一个需要你反复纠正的新手。花时间投资在规则和上下文建设上，初期看似有成本，但从长期来看，它在代码质量、团队协作和开发体验上带来的回报是巨大的。