Cursor 项目级重构与协作指南

先搞清楚它的三层能力

Cursor 不只是"有 AI 的 VS Code"，它现在有三层明确分开的能力：

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

很多人一直停留在 Tab 补全阶段，没体验到 Cursor 真正拉开差距的 Agent 模式。

上手前的几个设置

.cursorrules 文件

在项目根目录创建 .cursorrules（或 .cursor/rules/），作用类似项目级系统提示——你可以在里面写清楚技术栈、代码规范、命名约定和禁止事项。Cursor 的 AI 会在每次操作时参考这个文件。

写法示例：

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

如果你和 AI 协作经常出现风格不一致的问题，大概率是这个文件没写或没写好。

模型选择

Settings → Models 里可以选择不同的模型。日常 Tab 补全用快速模型就行，重要的重构任务值得切到更强的模型。不同模型在速度、质量和 token 消耗上差异很大。

@ 引用机制

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

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

这是让 AI 理解上下文的关键。不用 @ 的话 AI 只看到当前打开的文件，给出的建议往往文不对题。

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

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

1. 让它先理解现状

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

2. 让它出方案而不是直接改

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

3. 用 Agent 模式执行

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

4. 每一步看 diff

Cursor 会在编辑器里高亮标注每一处改动，红色删除绿色新增。不要跳过这步——尤其看 AI 自己加的逻辑。有疑问就在 Chat 里追问让它解释。可以用检查点（Checkpoint）功能随时回退到之前的状态。

5. 跑一遍验证

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

Tab 补全的几个实用技巧

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

Agent 模式的正确期望

Agent 模式确实能读文件、改代码、跑命令，但不是"说一句话自动搞定所有事"。

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

最容易踩的坑

坑 1：不用 .cursorrules 也不用 @ 引用

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

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

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

坑 3：Checkpoint 不用白不用

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

坑 4：把所有事都丢给 Agent

Agent 适合执行边界明确的任务，不适合替你做架构决策。"帮我设计一下数据库 schema"这种事，你应该先想清楚再让它实现，而不是让它从头设计。

它和 Claude Code 怎么选

简单说：Cursor 适合在编辑器里持续做代码级别的事（写代码、改组件、调样式、修 bug），Claude Code 适合在终端里做仓库级别的事（理解大型项目、批量修改、处理脚本和自动化）。

两者可以同时用：用 Claude Code 做全局性的分析和大范围改动，用 Cursor 做局部精细的代码编辑和调试。不冲突。