Cursor 项目级重构与协作指南

先搞清楚它的三层能力

Cursor 有三层明确分开的能力：

1. Tab 补全：写代码时按 Tab 接受下一步预测，类似 Copilot 但带更多上下文
2. Chat（Cmd+L / Ctrl+L）：在侧边栏和 AI 对话，可以 @ 引用文件、文档和代码符号
3. Agent 模式：让 AI 自主读文件、改代码、跑终端命令，一次处理多步任务

很多人一直停留在 Tab 补全阶段，没体验到 Agent 模式。

上手前的几个设置

规则文件

新版 Cursor 推荐在 .cursor/rules/ 目录下放规则文件，旧版的 .cursorrules（根目录）也仍然支持。作用类似项目级系统提示——写清楚技术栈、代码规范、命名约定和禁止事项，Cursor 的 AI 会在每次操作时参考。

写法示例：

技术栈：Next.js 15 + TypeScript + Tailwind CSS + Prisma
组件命名：PascalCase
工具函数：camelCase
禁止：不要用 any 类型，不要删测试文件
偏好：服务端组件优先，需要交互的部分才用客户端组件

和 AI 协作经常出现风格不一致，大概率是这个文件没写好。

模型选择

Settings → Models 里可以选择不同的模型。日常 Tab 补全用快速模型就行，重要的重构任务值得切到更强的模型。

@ 引用机制

Chat 和 Agent 里输入 @ 可以引用：

• @file：指定具体文件作为上下文
• @folder：整个文件夹
• @docs：外部文档（可以添加自定义文档源）
• @web：让 AI 搜索网页获取最新信息
• @codebase：搜索整个代码库

不用 @ 的话 AI 只看到当前打开的文件，给出的建议往往文不对题。

一个实际的项目级重构流程

拿"把一个 React 组件从 class 组件改成函数组件 + hooks"举例：

1. 让它先理解现状

Ctrl+L 打开 Chat，@file 引用目标组件，问："这个组件的状态管理和生命周期是怎么组织的，依赖了哪些外部 props 和 context。"先确认它真的看懂了代码结构。

2. 让它出方案再动手

先让它列一个改造方案：哪些 state 用 useState、哪些副作用用 useEffect、哪些逻辑可以抽成自定义 hook、有没有需要特别处理的边界情况。看方案没问题再让它动手。

3. 用 Agent 模式执行

确认方案后切到 Agent 模式（Ctrl+L 打开 Chat，在模式切换里选 Agent）。它会自己读文件、改代码、处理相关 import 和类型定义。如果涉及多个文件，Agent 会连带处理。

4. 每一步看 diff

Cursor 会在编辑器里高亮标注每一处改动，红色删除绿色新增。有疑问就在 Chat 里追问让它解释。可以用 Checkpoint 功能随时回退到之前的状态。

5. 跑一遍验证

在 Agent 模式里直接让它跑 npm run build 或 npm test。如果报错，它会自动读报错信息尝试修复。"改代码 → 跑构建 → 看报错 → 修复"这个闭环是 Cursor 比纯 Chat 工具效率高的地方。

Tab 补全的几个实用技巧

• 不只是补全当前行：Tab 会预测你下一步要做什么。写完一个 if 分支，Tab 可能直接补出整个 else 逻辑。
• 拒绝后重新引导：如果 Tab 给的建议不对，按 Esc 拒绝，继续自己写几个字，它会调整预测方向。
• 注释驱动：先写一行注释描述你想要什么（// 处理用户未登录的情况，重定向到登录页），Tab 直接补出对应实现。
• 跨文件感知：在 A 文件改了类型定义，切到 B 文件时 Tab 会自动建议对应的更新。
• Ctrl+K 行内编辑：选中一段代码，Ctrl+K 输入指令让它改——比如"把这个 for 循环改成 map"。比 Chat 更快，因为直接在代码里操作。

Agent 模式的正确期望

• 小到中型任务（改一个组件、修一个 bug、加一个接口）：通常一轮搞定，效率很高。
• 大型重构（重新组织模块结构、迁移框架版本）：需要分阶段喂任务，每步确认。一口气让它做完几乎必然出问题。
• 调试：给它报错信息，它会自己找代码、看日志、尝试修复。修复方案有时治标不治本，需要你判断根因是否真正解决。
• 如果连续三轮还是同一个错误：停下来自己看一眼报错，给它一个更准确的提示，比让它继续盲试高效得多。

最容易踩的坑

坑 1：不用规则文件也不用 @ 引用

AI 看不到你脑子里的上下文。不给规则文件、不用 @ 引用，它就只能根据当前打开的文件猜，准确率大打折扣。

坑 2：Agent 改了你没预期到的文件

Agent 有时会"顺手"改你没让它改的文件。每次执行完务必看完整的文件改动列表，不只看你预期的那几个文件。

坑 3：Checkpoint 不用白不用

在 Agent 做大改动之前先创建 Checkpoint，出了问题一键回退，比 Git stash 和 undo 都方便。

坑 4：把架构决策也丢给 Agent

Agent 适合执行边界明确的任务。"帮我设计一下数据库 schema"这种事，先想清楚再让它实现。

它和 Claude Code 怎么选

Cursor 适合在编辑器里持续做代码级别的事（写代码、改组件、调样式、修 bug），Claude Code 适合在终端里做仓库级别的事（理解大型项目、批量修改、处理脚本和自动化）。两者可以同时用，不冲突。