Cursor 使用指南 01#：优化你的提示词

在 AI 原生 IDE 赛道里，Cursor 算是前端开发者上手门槛最低的工具之一。但我接触下来发现，很多人用了两三个月，依然停留在 "写一句模糊需求，生成一堆模板代码，再自己返工改一半" 的状态，最后得出 "AI 写代码不靠谱" 的结论。

问题根本不在模型能力，而在提示词。Cursor 不是套了编辑器壳的通用大模型，它的核心优势是能感知项目内的代码结构、风格与依赖。写提示词的本质，从来不是 "描述需求"，而是精准地给 AI 注入上下文、划定执行边界、设定验收标准。

这是 Cursor 系列指南的第一篇，我们聚焦前端开发场景，从最基础的上下文控制到可复用的场景模板，把提示词的实用玩法讲透。

一、基础核心：把 @ 符号体系用到位

@ 符号是 Cursor 区别于普通 AI 聊天的灵魂，用不好等于浪费了这款工具一半的能力。

精确引用：@文件 / @# 符号

当你明确知道参考对象时，直接指定文件路径是精度最高的方式。

开发新组件时，@src/components/Button.tsx 可以让 AI 直接对齐现有组件的写法、参数风格与错误处理逻辑
只修改单个函数时，用 @#handleSubmit 仅注入对应符号的代码片段，节省 token 也避免无关内容干扰

实际项目里有个小经验：开发同业务模块的新组件时，优先引用同目录下的同类组件，比引用全局规范文件的风格对齐效果要好得多。

模块级引用：@文件夹

需要对齐整个模块的开发规范时，可以直接指定目录路径。比如开发新的用户侧页面，加上 @src/pages/user/，AI 会自动参考该目录下其他页面的路由写法、状态管理方式与结构分层。

有个常见误区要避开：不要直接 @ 整个 src 根目录。无关代码会严重稀释 AI 的注意力，反而更容易生成偏离项目逻辑的内容。

全局检索：@Codebase

不知道目标代码在什么位置时，用 @Codebase + 功能描述 做语义搜索。比如 @Codebase 查找项目中封装的请求拦截器，用来定位公共组件、工具函数、全局常量，比纯关键词全局搜索的准确率高很多。

文档引用：@Docs

Cursor 支持索引第三方官方文档，在提示词中加入 @Docs，可以有效避免 AI 生成过时的 API 用法。比如 @Docs React 实现一个受控表单组件，输出的内容会对齐官方最新的写法规范。

二、前端高频场景提示词模板

以下是日常前端开发中复用率最高的 8 类场景模板，可以直接修改参数使用，省去每次组织提示词的时间。

1. React/Vue 组件开发

适用场景：从零开发新组件，统一代码风格与规范

markdown 复制代码

基于 React 18 + TypeScript 开发一个【组件名称，如：用户信息卡片】组件
参考 @src/components/ReferenceCard.tsx 的代码风格与目录规范

功能需求：
1. 展示用户头像、昵称、等级、关注状态
2. 点击关注按钮触发回调，支持加载态
3. hover 时展示阴影过渡效果

Props 定义：
- userId: string，用户ID，必填
- userInfo: UserInfo 类型，用户信息，可选
- onFollow: (userId: string) => Promise<void>，关注回调

约束条件：
- 使用函数式组件 + Hooks
- 样式使用 Tailwind CSS，不新增单独 CSS 文件
- 补充完整的 TypeScript 类型定义，禁止使用 any
- 添加 JSDoc 注释说明组件用途和关键参数
- 不引入任何新的第三方依赖

2. 样式实现与 UI 还原

适用场景：为已有组件补样式、还原设计稿、响应式适配

diff 复制代码

为当前选中的组件实现样式，要求：

设计还原：
- 整体卡片布局，圆角 12px，内边距 16px
- 主色使用项目主题色 primary，次要文字用 text-secondary
- 标题字号 16px 加粗，正文字号 14px

技术约束：
- 仅使用 Tailwind CSS 类名，不写内联样式
- 适配移动端 / 桌面端两端，断点使用 md:
- 保持与 @src/styles/variables.css 中的设计变量一致
- 所有交互添加 200ms ease-in-out 过渡动画

只输出修改后的组件代码，不要多余解释

3. 状态管理模块开发

适用场景：新增 Zustand/Pinia/Redux 状态管理模块

markdown 复制代码

基于 Zustand 实现一个【购物车】状态管理 store
文件路径：src/store/cartStore.ts
参考 @src/store/baseStore.ts 的封装规范

需求：
1. 管理状态：商品列表 cartList、总价 totalPrice、选中状态
2. 提供方法：添加商品、删除商品、修改数量、全选/取消全选、清空购物车
3. 商品数量最小为1，不能减到0
4. 总价自动根据选中商品计算

约束：
- 使用 TypeScript 完整类型定义
- 异步操作统一处理 loading 状态
- 不要直接修改状态，全部通过 setter 方法更新
- 添加持久化，存储到 localStorage

4. 组件重构与优化

适用场景：老组件重构、逻辑拆分、代码质量提升

markdown 复制代码

重构 @src/components/GoodsList.tsx 组件

重构目标：
1. 拆分复杂业务逻辑，提取为自定义 Hooks
2. 优化渲染性能，减少不必要的重渲染
3. 补充缺失的类型定义和注释
4. 拆分过长的 JSX，提取子组件

约束：
- 完全保持原有功能与对外 Props 不变
- 不引入新的第三方依赖
- 遵循项目现有代码风格
- 输出重构后的完整代码，并在关键改动处添加注释说明

5. Bug 定位与修复

适用场景：排查组件异常、逻辑错误、控制台报错

markdown 复制代码

分析 @src/pages/OrderList.tsx 中的 Bug

现象描述：
切换订单状态标签时，列表数据没有刷新，显示的还是上一个状态的内容

复现步骤：
1. 进入订单列表页，默认显示「全部」订单
2. 点击「待付款」标签，列表未更新
3. 刷新页面后才显示正确数据

请先定位根本原因，再给出修复方案，最后输出修改后的代码
修复时只改动问题相关逻辑，不要修改无关代码

6. 前端性能优化

适用场景：列表卡顿、首屏加载慢、渲染性能优化

markdown 复制代码

对 @src/components/LongList.tsx 组件进行性能优化

当前问题：
数据量超过 100 条时，滚动出现明显掉帧，渲染卡顿

优化方向：
1. 排查不必要的重渲染，使用 memo / useMemo / useCallback 优化
2. 实现虚拟列表，只渲染可视区域内容
3. 图片添加懒加载处理

约束：
- 保持原有功能和交互完全不变
- 优先使用 React 原生优化手段
- 每一处优化都标注原因和预期收益

7. 单元测试编写

适用场景：为工具函数、组件补充测试用例

less 复制代码

为 @src/utils/formatPrice.ts 编写单元测试
使用 Vitest 测试框架，参考 @src/utils/__tests__/formatDate.test.ts 的写法

测试用例覆盖：
1. 正常金额格式化，保留两位小数
2. 整数金额自动补两位小数
3. 0、null、undefined 等边界值处理
4. 负数金额场景
5. 超大金额千分位展示

输出完整的测试代码，保持与现有测试一致的风格

8. 需求拆解与技术方案

适用场景：接到新需求后，先输出方案再落地开发

markdown 复制代码

需求描述：实现一个用户头像上传裁剪功能，支持本地图片选择、拖拽裁剪、预览、上传到服务器

请输出完整的前端开发方案，包含：
1. 需要新增/修改的文件清单与各自职责
2. 核心实现步骤与技术选型说明
3. 需要注意的边界情况与异常处理
4. 建议的自测用例

只输出方案，不要写具体代码

三、高阶提效技巧

掌握基础模板之后，这几个技巧可以让提示词的产出质量再上一个台阶。

负面指令：明确划定边界

AI 很容易 "画蛇添足"，提前明确禁止项，能减少大量返工。前端开发高频的负面指令包括：

typescript 复制代码

禁止使用 any 类型
禁止引入新的第三方依赖
禁止修改原有 Props 定义
不要添加多余的 console.log
不要改写原有注释

关键约束可以用大写英文标注，比如 NEVER use any type，强化指令权重。

风格锚定：用参考文件替代 "遵循规范"

不要只写 "遵循项目代码规范" 这种空泛表述，直接指定参考文件，风格对齐度会有明显提升。

less 复制代码

严格遵循 @src/utils/request.ts 的错误处理模式
命名规范参考 @types/common.ts 中的定义
组件写法完全对齐 @src/components/BaseModal.tsx

Plan 模式：复杂任务先审后做

涉及多文件修改的复杂任务，一定要开启 Plan 模式。在提示词末尾加上一句：

先列出需要修改的文件清单和具体执行步骤，我确认后再开始修改代码

可以有效避免 AI 随意修改无关文件、引入不必要的依赖，这是长期使用下来最能降低翻车概率的习惯。

增量迭代：不要追求一步到位

不要指望一条提示词生成完美代码。AI 输出基础版本后，用短句逐步微调的效率远比重写长提示词更高：

把这个按钮改成禁用态样式
补充一下空数据的占位图
给这个请求加上错误提示

四、项目级配置：.cursorrules 一劳永逸

对于长期维护的项目，没必要每次写提示词都重复技术栈、编码规范。在项目根目录创建 .cursorrules 文件，一次性写入项目规则，后续所有 AI 交互都会自动遵循。

前端项目参考配置：

markdown 复制代码

# 技术栈
- 框架：React 18 + TypeScript 5
- 样式：Tailwind CSS 3
- 状态管理：Zustand
- 构建工具：Vite
- 测试：Vitest + Testing Library

# 编码规范
- 组件使用函数式组件 + Hooks
- 文件命名：组件用大驼峰，工具函数用小驼峰
- 所有导出函数和组件必须添加 JSDoc 注释
- 类型定义统一放在 src/types 目录

# 禁止项
- 禁止使用 any 类型
- 禁止直接操作 DOM
- 禁止引入未在 package.json 中声明的依赖
- 禁止使用已废弃的 React API

配置完成后，即使是非常简短的提示词，AI 也会自动按照项目规范生成代码。

五、几个实操习惯

最后分享几个没有技术含量，但能大幅减少踩坑的使用习惯：

批量修改前先 commit。开启 Agent 模式或执行多文件修改前，先提交 Git 基线，一旦 AI 修改不符合预期，可以快速回滚。
改完必看 Diff。不要全盘接受 AI 的修改，通过差异对比只保留合理改动，拒绝 AI 自作主张的 "优化"。
按需切换模型。简单样式、基础 CRUD 用轻量模型节省成本；复杂逻辑、架构设计切换深度思考模型。
小范围修改用内联编辑 。局部代码调整用 Ctrl+K 内联编辑，比打开聊天面板交互效率更高。

提示词从来不是什么玄学技巧，本质是和 AI 高效协作的沟通方式。把上下文、约束、边界交代清楚，Cursor 才能从 "代码生成玩具" 变成真正能提升产能的开发工具。