书籍 / Cursor / Claude 编程实战：AI 辅助开发完全指南
第 5 章

Cursor Chat 完全指南——@ 符号、上下文控制与高效提问模板

第5章：Cursor Chat 完全指南——@ 符号、上下文控制与高效提问模板

Cursor Chat 的核心是 @ 引用系统：用 @文件名精确定位代码、用 @Codebase 搜索整个项目、用 @Web 获取最新技术信息、用 @Git 分析代码历史。但大多数人只会直接发问——这样等于让 AI 蒙着眼睛回答。本章把 @ 系统讲透，讲清楚上下文控制对答案质量的决定性影响，并给出 20 个高频场景的即用提问模板。

先选对工具：Chat vs Cmd+K vs Composer

很多人在 Chat 里做本该用 Cmd+K 完成的事，浪费时间；也有人用 Cmd+K 去做需要 Composer 的多文件任务，然后抱怨 AI 不够聪明。工具选对了，效率才能提升。

场景 用什么 原因
理解一段复杂代码的逻辑 Chat 需要解释和对话，可以追问细节
把当前函数的某几行改写 Cmd+K 选中代码直接改，不需要额外上下文，速度最快
给函数加 JSDoc 注释 Cmd+K 选中函数，描述要求，一步到位
添加一个涉及多个文件的新功能 Composer 需要跨文件协调修改，Chat 只能建议，你还要手动操作
排查一个 bug Chat 先理解 → Cmd+K 再修 先用 Chat + @ 引用相关文件搞懂原因，再用 Cmd+K 精确修改
学习一个不熟悉的 API 用法 Chat + @Docs 需要文档参考，可以多轮追问
把整个模块迁移到新技术栈 Composer 或 Claude Code 涉及大量文件，需要 Agent 级别的执行能力

@ 引用系统完全手册

在 Chat 输入框输入 @ 会弹出引用菜单。这是 Cursor Chat 和普通 ChatGPT 最根本的区别——你可以精确控制 AI 看到哪些信息。

@文件名（最常用）

把特定文件的完整内容发给 AI。比让 AI 自己猜相关文件精准得多。

@src/auth/middleware.ts 这个中间件为什么会让所有请求都返回 401？
我检查了 token 是正确的，但每个请求都被拦截了。

@prisma/schema.prisma @src/repositories/UserRepository.ts
这两个文件的 User 模型字段是否一致？我怀疑有不同步的问题。

可以同时 @ 多个文件。当问题涉及两个文件之间的关系（比如 schema 和 repository 是否匹配），必须同时引用两个，AI 才有足够信息回答。

@Codebase（语义搜索整个项目）

不会把整个代码库塞进上下文（那会超出 token 限制），而是在向量索引中做语义搜索，找到最相关的代码片段。适合你不知道相关代码在哪个文件时使用。

@Codebase 项目里有没有重复的数据库连接初始化代码？
我在好几个地方看到 new PrismaClient()，想统一到一个地方管理。

@Codebase JWT token 是在哪里生成的、又在哪里被验证的？
帮我列出所有相关文件和大概的行号。

@Codebase vs @文件名的选择： 知道相关代码在哪个文件时，用 @文件名（更精准，不浪费 token）；不知道时，用 @Codebase（让 AI 去搜）。

@Web（实时搜索互联网）

让 AI 搜索最新内容，解决训练数据过期的问题。2024 年后发布的库版本、新 API 变化、最新最佳实践，都应该加 @Web。

@Web React 19 的 use() hook 和 Suspense 结合怎么用？有什么已知的坑吗？

@Web Bun 1.x 的 HTTP server API 和 Node.js 的有什么区别？
我要把一个 Express 应用迁移到 Bun。

注意：@Web 搜索到的内容质量参差不齐，重要信息建议去官方文档二次验证。

@Docs（引用官方文档）

Cursor 内置了主流框架的文档索引（React、Next.js、Tailwind CSS 等）。还可以在 Cursor Settings → Features → Docs 添加自定义文档 URL——把内部 API 文档或第三方库文档加进来，AI 直接参考精确文档而不是凭记忆回答。

@Docs/Next.js App Router 的 generateMetadata 函数怎么处理动态路由参数？
给我一个博客文章页面的完整 SEO 配置示例。

@Docs/Prisma Prisma 的 upsert 在什么情况下会失败？
和先查再更新的方式相比，并发安全性如何？

@Git（分析代码历史）

引用 Git 提交历史和 diff，让 AI 帮你理解代码变更。排查"这个 bug 是什么时候引入的"特别有用。

@Git 最近5次提交改了什么？这些改动可能导致用户登录失败吗？

@Git 这个文件最近是被谁在什么时候修改的？根据 commit message 分析改动的意图。

@Git 帮我整理最近两周的提交记录，生成一个面向非技术人员的 CHANGELOG 草稿。

上下文控制——这是影响质量的关键

AI 回答质量差，90% 的原因是上下文给错了。不是 AI 不够聪明，是你给的信息不够，或者给错了。

坏示例：

这个函数有 bug，帮我改一下

AI 不知道是哪个函数，会随机猜测或者给出一个通用的模板答案，对你毫无帮助。

好示例：

@src/payment/stripe.ts 第 45-67 行的 createPaymentIntent 函数
在处理金额为 0 的订单时会抛出这个错误：
  StripeInvalidRequestError: amount must be at least 50 cents

场景：我们的平台允许免费订单（全额优惠券），这时候金额是 0。
请修复这个问题，要求：
1. 金额为 0 时跳过 Stripe 调用，直接标记订单为已支付
2. 金额大于 0 时走正常的 Stripe 流程
3. 不要修改函数签名（调用方很多）

高质量提问的结构公式

[@ 相关文件] + [当前状态/问题现象] + [期望结果] + [约束条件]

20 个高频场景提问模板

理解代码类（1-5）

# 场景 模板
1 理解陌生函数 @文件名 解释 [函数名] 的工作原理。重点说明：(1) 输入输出；(2) 关键逻辑步骤；(3) 可能的边界情况。
2 理解整个模块 @目录/ 这个模块的职责是什么？各文件之间的依赖关系是怎样的？画一个简单的调用流程。
3 理解设计决策 @文件名 为什么这里用 [模式/方法] 而不是 [替代方案]？有没有注释说明原因？
4 找重复代码 @Codebase 项目里有没有重复实现 [功能] 的代码？列出所有相关文件和函数名。
5 理解数据流 @路由文件 @服务文件 @仓库文件 当用户下单时，数据是如何从 HTTP 请求流转到数据库的？每一层做了什么处理？

Debug 类（6-10）

# 场景 模板
6 分析报错 @相关文件 遇到这个错误：[完整错误信息]。分析：(1) 根本原因；(2) 触发条件；(3) 最佳修复方案。
7 排查逻辑 bug @文件名 第 [X-Y] 行。输入 [输入值]，期望输出 [期望值]，实际输出 [实际值]。找出逻辑错误在哪里。
8 排查性能问题 @文件名 这个函数在数据量 [N] 条时执行需要 [时间]。分析可能的性能瓶颈，重点看：N+1 查询、不必要的循环、缺少索引的查询条件。
9 排查内存泄漏 @文件名 这个组件/服务在长时间运行后内存持续增长。检查：事件监听器是否正确移除、定时器是否清理、闭包是否持有大对象引用。
10 分析错误日志 @Codebase 分析这段错误日志：[粘贴日志]。找出：(1) 错误的调用链；(2) 问题最可能出在哪个文件；(3) 修复建议。

重构类（11-15）

# 场景 模板
11 提取函数 @文件名 第 [X-Y] 行的代码可以提取成独立函数吗？给出建议的函数名、参数列表、返回值类型，以及提取后的完整代码。
12 消除重复 @文件A @文件B 这两个文件都实现了 [功能]，代码几乎相同。给出消除重复的方案：放到哪里、如何参数化差异、调用方如何修改。
13 改善命名 @文件名 这些变量/函数的命名不够清晰：[列出名称]。根据它们的实际用途，给出更好的命名建议，并说明改名原因。
14 简化复杂逻辑 @文件名 第 [X-Y] 行的嵌套 if/else 太深，可读性差。在保持完全相同行为的前提下，给出更简洁的写法。
15 评估重构风险 @Codebase 如果我修改 [函数/接口]，会影响哪些调用方？列出所有需要同步修改的地方，以及改动的风险等级。

学习新技术类（16-20）

# 场景 模板
16 类比学习 @Web 我熟悉 [技术A]，现在要学 [技术B]。用 [技术A] 的概念类比解释 [技术B] 的核心概念，举一个同样功能的代码对比例子。
17 评估是否值得学 @Web 我的项目是 [描述]，现在考虑用 [新技术]。和我现在用的 [现有方案] 相比，具体有什么优势？什么情况下不值得迁移？
18 了解常见坑 @Web @Docs/框架名 [功能/API] 有哪些常见的使用错误？每个错误给一个反例代码和正确写法。
19 项目内实践 @现有文件 参考这个文件的风格，用 [新技术/模式] 改写 [目标函数]。保持测试可通过，给出改写后的完整代码。
20 最佳实践检查 @文件名 对照 [框架/库] 的当前最佳实践，这个实现有没有过时或不推荐的写法？列出具体的问题和现代写法。

多轮对话技巧

什么时候开新 Chat

持久化重要信息的正确方式

本章要点

  1. 先选对工具：Chat 用于理解和多文件问题，Cmd+K 用于精确修改选中代码，Composer 用于跨文件功能开发——不要用错工具然后怪 AI 不够聪明
  2. @ 引用决定答案质量：知道文件位置用 @文件名，不知道用 @Codebase，需要最新信息用 @Web，需要文档支撑用 @Docs，排查历史问题用 @Git
  3. 上下文越精确，答案越有用：提问模板是"相关文件 + 问题现象 + 期望结果 + 约束条件"，缺少任何一项都会降低答案质量
  4. 对话污染是真实问题：超过 20 轮的对话、任务类型切换时，果断开新 Chat，不要试图在一个对话里解决所有问题
  5. 重要信息要持久化：架构约定放 .cursorrules，API 决策写文档，不要依赖 AI 的"记忆"——它没有跨对话记忆
本章评分
4.9  / 5  (58 评分)

💬 留言讨论