Cursor进阶指南：用注记、Rules与Skills构建上下文与行为约束体系

1. 为什么进阶用法不是“背更多快捷键”，而是理顺三件事

先说一个我观察了很久的现象：很多人用了 Cursor 一两个月，水平还停留在“聊天框里写 Prompt、拖文件进对话、复制代码回来”的状态。不是说这样不行，毕竟它也能干活。可一旦你开始维护一个像样的项目，要求它连续改三个文件、保持风格统一、别动不该动的地方，这种用法就会立刻卡壳。

真正把 Cursor 用出差距的，从来不是谁记住了更多快捷键，而是谁更早弄懂了它提供的那套“上下文与约束系统”。聊到进阶，绕不开的就三个词：@注记、Rules、Skills。我自己刚接触时也误以为这是三个独立功能，结果越用越发现，它们是同一个体系的三个层次：@注记 决定模型“看到什么”，Rules 决定模型“按什么规矩做”，Skills 决定模型“能调用什么成套动作”。

举个例子。你让 AI “帮我看看登录模块为什么 token 失效”，它如果不知道你的项目里 login 相关的文件散在哪些位置、不知道你们团队接口错误码规范、不知道你希望它只诊断不要擅自改写，那么它给出的答案通常非常“正确但没用”。问题往往不是你提问能力差，而是边界没有交代清楚。

这里我顺手列一个我自己心里常惦记的对照表，方便你理解三者在日常开发里的分工：

当你不再把每一次对话当成“重新教一个新同事”，而是当成“给一个熟悉团队规则的老同事递资料”，整个用法就变了。接下来我按这三个层次一个一个拆，每一步都会给出我实际验证过的操作和判断标准。

2. @注记：别让它“自己去找”，而是精准指定要读什么

2.1 引用文件是“定位”，不是“丢链接”

@注记，或者你在 Cursor 右上角看到的 Mention，本质上就是给模型划定上下文范围。最基础的操作大家都会：输入框里打一个 @，选择某个文件，或者继续输入文件名过滤。

但真正拉开效率差距的，不是“会不会选文件”，而是“选到哪一层、以什么粒度选、选完以后怎么补一句约束”。

我见过最普遍的低效用法，是让 AI 自己去代码库里翻文件。比如有人会写：“帮我找一下用户登录相关的所有代码，然后分析为什么退出登录偶尔失败。”听起来没问题，可一旦项目里同名文件多、接口服务被拆到多个模块里，AI 可能在代码索引里找到一堆相似文件，然后做出一个“看起来合理但猜错目标”的回答。

更稳的做法是：先花十几秒把真正相关的入口文件、类型定义、接口请求文件分别用 @ 引用出来。当对话中出现了这几个文件的实际内容，它就不会凭空去“猜”你在讲哪一段逻辑。

比如我常这样写：

text复制请分析 @/src/modules/auth/login.tsx 里的表单提交逻辑，
并参考 @/src/api/auth.ts 里面的请求封装，
只诊断 token 过期之后为什么没有正确跳转到登录页，
不要修改任何代码，最后给我一条定位结论和两条修复建议。

这个地方有个很容易被忽略的点：把文件引用放在一句话里时，它就成了整次对话的“上下文锚点”。后面你再追问“那这里为什么会这么写”“如果改成这样呢”，AI 会自动以这个锚点为准，而不会突然跳去理解另一个无关模块。想让上下文更聚焦，就把锚点放在指令前面；想让 AI 综合多个文件再输出，就把引用集中放在同一句里。

2.2 “引用什么”比“引用多少”更重要

还有一种误区，是认为引用越多越好，恨不得把整个 src 目录拖进去。确实可以用 @ 选择文件夹，但这种把“整个项目”喂给模型的用法，未必换来更精准的回答。

它带来两个问题：一是上下文窗口被大量低价值文件占满，关键文件的相对权重反而被稀释；二是生成时越界概率变大，模型看着整个目录的代码，就很容易顺手改些你没让它碰的东西。

所以我对文件引用的建议是三个字：够用就好。如果你要改的是一个组件，优先引用：

• 当前组件文件本体
• 它依赖的类型或接口定义
• 你希望它保持一致风格的另一个同类文件
• 如果有现成的规则文件，引用规则

不要把自己都不确定是否相关的文件也塞进去。上下文这个东西，给多了和给少了，都会让模型的平均表现下降。给少了它会猜，给多了它会乱。

还有一个小技巧：当你引用文件夹时，一定要在提示语里补一句“只需要关注其中与 XX 相关的部分”。因为模型的综合能力很强，它会主动找出文件夹里和主题相关的片段。你的指令越明确，它筛出来的东西越准。否则它可能因为你提到了一个关键词，就把整个文件夹里所有沾边的内容都当成了重点。

2.3 把 @注记当“现场资料夹”而不是永久规则

有个边界需要提醒：@注记是单次会话级别的临时能力，它是“你此刻告诉它看这个”，而不是“以后每次都遵守”。所以涉及长期偏好、禁改文件、风格要求之类的东西，不要靠每次 @ 来重复，那样既累又容易遗漏。这些应该下沉到下一层：Rules。

我已经无数次在团队里看到这样的场景：有人把一个文件用 @ 引用进来，叮嘱 AI “以后所有代码都必须按这个文件的风格写”，然后关闭对话，新开一个窗口继续写代码，发现 AI 完全不记得上一条约定。原因很简单——那不是规则的生效方式，它在那个有引用的对话里才成立。

正确的分工是：这次相关，用 @；以后相关，写进 Rules。

3. Rules：三层规则体系，把“行为准则”钉到项目里去

3.1 全局、项目、对话规则分别放什么

Rules 是 Cursor 里用来沉淀长期约定的一层机制。很多人第一次接触它是在设置面板里找到一个“Rules”输入框，然后在里面写一句话：“你是一个资深前端工程师，请写出高质量的代码。”

这句话不能说没用，但基本等于没写。它没有可操作性，没有约束边界，也没有触发条件。真正的 Rules 写法，应该像公司里的员工手册，而不是贴在墙上的口号。

在实践里，我把 Rules 按放的位置分成三层：

第一层：用户级 Rules。放在全局设置里，适用于所有项目。只放那些你跨项目都不希望改变的偏好，比如默认回复语言、禁止使用某些不安全的写法、不喜欢在代码里生成哪些冗余注释。这里不能多，一多就成了给所有项目背上无差别负担。

第二层：项目级 Rules。放在项目的 .cursor/rules 目录下。这层才是真正的主力，因为它可以针对当前项目单独设计。比如这是一个 React + TypeScript 项目，规则就会写清楚：组件用函数组件、状态管理用 Zustand、接口请求必须走 @/api 封装、不要直接修改 lock 文件，等等。

第三层：写在对话里的一次性规则。这其实是很多人容易忽视的：你可以在每次提问时，不通过 @ 引用任何文件，而是直接把约束条件写在话里。比如“只输出方案，不要写代码”“暂时不要改动测试文件”“先给我一个最小复现路径”。它灵活、不产生全局影响，适合临时性的边界控制。

之所以要分三层，是因为不同约束的生命周期完全不同。全局偏好一年可能就改两三次，项目约束跟着项目走，而对话约束只活几分钟。你把它们混在一处，AI 就没法判断哪些是“弱提醒”、哪些是“硬约束”，最后表现就会很飘。

3.2 Rules 文件怎么组织才不乱

项目级 Rules 最好写在 .cursor/rules 目录里，并用 项目名-用途.mdc 这种命名方式。Cursor 支持用 Markdown 写规则文件，可以在文件头部标注触发范围。

举一个我实际常用的结构：

markdown复制---
description: 本规则适用于前端的 API 数据请求和类型检查
globs: src/api/**/*.ts
alwaysApply: false
---

- 所有请求函数必须显式声明入参类型和返回类型
- 不许把业务错误直接抛给用户，需要统一转成错误码
- 新接口必须补在 api 目录对应文件里，禁止直接在组件内调用 fetch

注意上面那个 globs 字段。它的价值在于让规则文件只在特定目录或文件类型下才被激活。如果某个规则对全项目生效，你可以不写 globs 或直接设置成 **/*；如果只想约束 API 层的文件，就写成 src/api/**/*.ts。这样做之后，AI 在改组件的时候并不会把 API 层那一大堆约束也背上，既省上下文，又减少误触发。

写规则内容还有一个很实用的建议：每条规则尽量是一句可判定的话，而不是一段抒情表达。像“请提高代码质量”这种话，模型不知道怎么样才算通过。但“方法超过 50 行时必须拆分为独立函数”这种规则，模型就能立刻判断自己有没有做到。规则要写“边界”，而不是写“期望”。

3.3 让规则真正“活”起来，而不是躺在仓库里

另一个很多人问我的问题是：为什么我配了 Rules，感觉它没生效？

这个问题我先反问一句：你是怎么确认它没生效的？是模型生成了违反规则的代码，还是你根本不知道它有没有读过规则？多数情况是后者。Cursor 里的规则文件默认会被模型作为上下文参考，可如果你在提问时没有主动引用规则文件，模型大多是“知道有”，而不是完整“读过”。所以要让某条规则在关键时刻生效，最稳的方式依然是在提示词里把对应规则文件用 @ 引用出来，或者用斜杠命令唤起规则。

但我也要说一个非常重要的关键词：别把规则文件本身当保险箱。规则文件不是一把锁，模型不会像程序执行 if...else 那样严格校验每一条。更现实的理解是：Rules 给你提供的是“高概率的执行倾向”。它的价值在于把大量你不想反复交代的共识前置到模型面前，从而降低对话中的偏差，而不是百分之百杜绝犯错。

我自己使用规则的习惯是：核心约束写在全局/项目 Rules 里，但真正改关键代码时，不会只依赖规则的自动加载，还会在这一轮提示词里把相关规则或者相关代码片段再次 @ 出来。两层叠一起，稳定性会明显高很多。

4. Skills：把复杂工作流打包成一个“作业包”

聊到 Skills，基本就到了 Cursor 进阶里最容易被高估、也最容易做错的地方。很多人听说有 Skills 这回事，第一个反应是去搜“skills 下载”，或者找别人的技能包来装。但在我看来，理解它的内部逻辑，比囤一堆别人做的技能重要得多。

4.1 Skill 到底是什么：不止是“高级提示词”

你可以把 Skill 理解成一个“可复用的作业包”。它由一组文件组成，里面包含背景说明、执行步骤、输入输出定义、甚至范例输出。当你在对话中调用它时，模型会按照作业包里的流程去执行任务，而不是靠聊天框里临时写的一句话临场发挥。

为什么会需要它？因为有些任务步骤太固定，几乎每次都是同样套路。比如“为新写的 API 接口生成单元测试”，如果靠每次手写提示词，你很容易漏掉边界条件测试，或者生成的测试风格和项目既有测试不一致。但如果把“生成接口单测”的标准动作写成一个 Skill，下次只要触发它，模型就会自动按里面的步骤来：先看接口文件、提取入参类型、补正常路径用例、补异常路径用例、最后检查覆盖率。

这就相当于你把自己平时做同类任务时脑子里那套流程，外化成一个文件，让 AI 可以随时调用。

4.2 手把手写一个最小 Skill：目录、描述和正文

一个 Cursor Skill 通常是这样组织的：在项目目录下建一个 .cursor/skills/技能名/SKILL.md。整个技能的核心就是这一个 Markdown 文件；如果逻辑复杂，你也可以在同一个子目录放多个相关文件，比如 examples.md、template.md，并在 SKILL.md 里引用它们。

下面是我常用的一个最小可运行写法。假设团队需要一个“代码审查”技能，帮助你在提交 PR 前自动检查改动质量，我习惯这么写：

markdown复制---
name: code-review
description: 当你需要审查本次代码改动是否存在潜在问题时使用。
---

# 代码审查

你是一名谨慎的代码审查者。不要直接修改变动内容，只做分析和评论。

## 执行步骤

1. 获取当前改动相关的 diff 信息，并结合用户 @ 提供的文件理解上下文
2. 检查以下维度：
   - 类型安全性：是否存在 any 类型与隐式类型问题
   - 边界条件：空值、超长输入、并发冲突是否处理
   - 状态一致性：异步操作是否有竞态，loading / error / success 状态是否完备
3. 把问题按严重程度分成 P0 / P1 / P2 三档输出
4. 每条问题必须给出行号、原因和修复建议

## 输出格式

按以下结构汇报：
- 本次审查范围
- P0 阻断问题列表
- P1 建议修复问题列表
- P2 可选优化项
- 一句总体结论

注意上面的 name 和 description。它们非常关键，因为模型判断是否要使用这个技能，主要靠的就是 description 里描述的场景是否和当前任务匹配。description 写得好不好，直接决定了触发准不准。如果你写得太模糊，比如“用于代码助手”，那么它在任何场景都可能不触发，也可能乱触发；如果你写得太窄，比如“只用于审查 API 目录下的代码”，那么你在审查前端组件时它就不会被调用。

写 description 有一个诀窍：把触发条件和输出目标都概括进去，并且尽量用你在真实提问时会出现的表达方式。比如你可以写“当你发现代码有潜在风险、不确认提交是否安全、想检查类型问题和状态连贯性时使用”。这样模型在读取到这一句时，更容易在当前对话话题与技能之间建立起匹配关系。

4.3 别只做“拿来主义”，能导入也要能改

市面上确实有很多现成 Skills，比如有人分享的“前端分镜”“结构图生成”“接口字段校验”技能，这些大多也是 Markdown 格式。下载下来之后放进 .cursor/skills 目录里，很多确实可以做到“开箱即用”，因为它本质上不是不可逆的编译产物，而是一份文档。

但我不建议拿到一个 Skill 就无脑导入。第一步该做的是打开它的 SKILL.md 读一遍，看看它的 description 是否符合你的用法、正文里引用的路径是否和你项目一致。我见过太多复制进来却发现毫无反应的例子，最后排查下来无非两种原因：一种是 description 写得太空，触发不了；另一种是正文里引用了别的目录结构，例如写死了某个绝对路径，但下载者项目里根本没有那个目录。

更重要的是：你自己在编写重复性任务时总结出来的流程，往往是世界上任何现成技能包都替代不了的。比如你在团队里习惯“先跑数据库迁移、再执行回归脚本、最后提交一份带失败率的测试报告”，这种高度个性化的流程，完全值得自己沉淀成一个内部 Skill。你把它们放在项目的 .cursor/skills 文件夹里，入库以后全团队都能共享，这可比每次打开文档复制提示词高效很多。

5. 三件套合体实战：一次登录模块改造的完整过程

前面把三者的原理拆开了，这节我串起来演示一次。假设我在维护一个中后台项目，最近登录模块存在偶发“登录态失效但不跳登录页”的问题。

按照旧习惯，我可能会直接问 AI：“为什么登录过期了不跳登录页？帮我修一下。”

这种提问，AI 会给你一个通用答案，很可能是基于经验的猜测，它不知道你的鉴权中间件写在哪个目录，也不知道你们项目的路由守卫逻辑长什么样。用上三件套之后，整个流程就清晰了。

第一步：标记上下文。 我先用 @ 把与登录态相关的文件拉进来。可能是 /src/router/index.tsx、/src/store/auth.ts、/src/service/request.ts，这几个文件通常是登录态判断与接口响应的关键节点。先不急着让它改，而是要求它串联这三个文件，解释一下登录过期后实际走了什么逻辑。

第二步：用 Rules 控制修改边界。 项目里有几条规则是必须遵守的，例如“不要直接修改 request 封装层”“不要改动路由结构，只修跳转逻辑”“所有状态变更必须走 store 里的 action”。这些规则已经在 .cursor/rules 里，但我在这一轮特意把 @.cursor/rules/auth-restriction.mdc 也引用进对话，相当于在本轮对话里把约束从“后台规则”提升为“显式提醒”。

第三步：调用 Skill 做固定动作。 如果我已经写了一个名为“bug-diagnosis”的技能，里面规定了分析问题时要先复现、再定位范围、再查边界条件、最后给出修复建议，那么我在提示词里直接输入 @bug-diagnosis 或让它根据我的问题自动匹配，它就会沿用这套固定流程。这时候你得到的分析，远比一条零散的大模型回答更有方向感。

第四步：验证。 在让它给出具体补丁前，我会再补一句话：“先不要生成代码，把定位结论按 log、预期行为、实际行为、可疑点四部分列出来，我再决定怎么改。”这本质上是一层临时对话规则。它防止模型还没等你看清问题，就直接把代码全改了。

整个过程下来你可能发现，任何一步都不是灵丹妙药，但它们组合在一起之后，模型的稳定性确实高很多。以前问一个复杂问题，全凭运气；现在更像是你给一个协作习惯明确的外包工程师下了一张带备注的任务单，对方按着既定作业流程走，出错率自然就降下来了。

6. 我踩过的几个进阶坑，建议你提前绕开

6.1 坑一：Rules 写太多，结果每条都成了“耳边风”

我开始用 Rules 时犯过一个典型错误：恨不得把所有代码规范都塞进去，写了满满二十条。结果模型大部分时候确实不会违背这些规则，但它的上下文也被大量低相关性规则占掉了一部分，导致关键判断反而没那么敏锐了。

后来我学到的一条原则是：规则宁可少，也不要滥。只写那些你真的会因为 AI 违反而生气的约束。如果你无所谓它用普通函数还是箭头函数，就不要把“统一用箭头函数”这条放进去。每个额外的规则都是在增加上下文开销和判断负担。精减到十条以内的硬规则，通常比三十条软约束有效得多。

6.2 坑二：拿别人 Skill 直接 Copy 进项目，却从没测试过触发

我见过太多的“装了五十个 Skills 但几乎没生效”的人。他们以为是软件出了问题，其实是技能包里的 description 没有踩中自己的真实用法。比如一个技能描述是英文，但你全部用中文提问，它的匹配率就会低不少。描述如果缺少触发场景，模型甚至可能根本不知道什么时候该把它翻出来。

所以导入新技能后，第一件事就是在空对话里手动把它 @ 出来，看技能内容能否承载你想要的行为；然后模拟你平时会问的真实问题，看它能不能自动触发。不触发就把 description 里补充一些和你的问题相近的关键词，直到一次能中为止。

6.3 坑三：把上下文和技能全堆到同一轮对话里，让它顾此失彼

“帮我审查代码、生成单元测试、修复优化、顺便更新接口文档”，这种一口气想把所有事情做完的提示方式，哪怕是配了技能和规则也很难稳定。一个技能如果步骤复杂，就单独执行一轮，执行完确认结果后再往下走。把多个任务压在同一轮，相当于让你同时写三份不同的文档，结果通常是哪份都写不细致。

我给自己的硬性要求是：一轮对话只做一类判断。要么是分析，要么是修复，要么是生成测试。如果技能里已经设计了顺序，那就在一次内做完；如果没有，就果断拆开。模型擅长的是“照着明确流程执行”，而不是“自己分配任务先后”，把任务链条拆清楚，是对它最大的帮助。

6.4 坑四：以为把规则写进项目文件，AI 就一定会遵守

这一点已经重复多次，但确实重要：规则文件只是一个“倾向性引导”，不是一个编译期强制校验器。即使你把“严禁修改 src/util 目录”写得再清楚，新对话里模型也可能因为没有加载那个规则文件而越界。要求稳，关键操作前就得主动 @ 规则或相关代码，用上下文锚定它。

我的习惯是：把长期规则放 .cursor/rules 作为兜底，把每次会话的关键约束放进提示词作为本轮的显式指令。两者配合使用，才是规则体系的正解，而不是写完一份文件就再也不管。

6.5 坑五：凭感觉判断“它没生效”，而不是去拆解原因

最后这个坑很多人都会踩：看到结果不满意，立刻说“这个功能不行”“规则没生效”。实际上绝大多数“没生效”，根因都在于触发方式和预期不匹配。代码世界里讲究可观测性，配置规则和技能也一样。你越能定位到是哪一环掉了链子，就越不会冤枉一个工具。

我会建议你在调试阶段把三层逐步排查：一是技能有没有被触发，用 @ 手动触发一次做对照；二是规则有没有被读入，让 AI 先复述它理解的规则再开工；三是上下文是否足够，把相关文件 @ 出来后结果是否变好了。分三步排查下来，问题基本都出这三处中的某一处。

Skills 和 Rules 是我近一年里在 Cursor 上投入最多时间的两个方向。它们能不能用出效果，不取决于你是不是买到了更贵的订阅，也不取决于你是不是囤了别人五百个技能包。真正起作用的，是你有没有把自己的工作流提炼成稳定输入和明确规则。把这一套跑通之后，你会发现自己写提示词的时间变短了，AI 一次做对的概率却变高了。