Cursor 上下文引用实战：@Files / @Folders / @Code / @Docs / @Web / @Git 怎么选
六步速览
- 先写清任务目标与不要动的范围，再决定引用什么
- 能点名文件 →
@Files；能圈选函数 →@Code - 模块级摸底或批量改 →
@Folders，但必须收窄目录、先列表后修改 - 需要官方写法 →
@Docs；需要查报错/变更日志 →@Web - 写变更说明、对照 diff →
@Git - 发送前用自检清单过一遍：引用是否还能再减？
对应三原则：少而准 · 先分析后实现 · 权威依据不靠背 API。
说明：不同 Cursor 版本菜单文案可能略有差异，以你本地输入
@后出现的列表为准。核心原则通用。
三种上下文从哪来
和「用 AI 从 0 到 1 做一个项目」里「引用上下文」的习惯一脉相承：Agent 表现差，往往不是模型不够聪明，而是该看的没给、不该看的塞太多。
| 来源 | 放什么 | 何时生效 |
|---|---|---|
| 自然语言 | 任务目标、约束、验收标准 | 每次对话 |
@ 引用 | 本次必须读的文件、目录、符号、文档、网页、Git 变更 | 你点名时 |
| Rules / Skills / AGENTS.md | 长期项目约定、完整工作流 | 自动或 @ 触发 |
几条硬习惯：
- 能
@Files就不要只说「登录那块」 - 能
@Code就不要整文件粘贴 - 该查文档时用
@Docs/@Web，别让模型凭记忆编 API - 引用有预算：附件越多，噪声与跑偏概率越高
和站内其他文章的分工：
| 文章 | 本文只补这一块 |
|---|---|
| Cursor Rules | Rules 是持久约定；@ 是单次任务的附件 |
| Cursor Skills | Skills 是完整工作流；@ 是精确指路 |
| 0 到 1 协作流程 | 那里讲 Ask/Plan/Agent；这里讲输入框里怎么引用 |
全文地图
| 你想干什么 | 优先引用 | 配合模式 |
|---|---|---|
| 改已知文件、补测试 | @Files + @Code | Agent |
| 摸清某目录再小改 | @Folders（收窄） | 先 Ask/Plan，再 Agent |
| 按官方文档加功能 | @Docs + @Files | Plan → Agent |
| 查报错、版本差异 | @Web + @Files（配置/锁文件） | Ask |
| 写 commit / 审查未提交变更 | @Git | Ask 或 Agent |
| 延续上一轮结论 | @Past Chats + 重新 @ 关键文件 | 视任务 |
分类型怎么用
1. @Files：点名单个或多个文件
适合： 改已知实现、对照配置排错、按现有风格补测试。
示例：
阅读 @src/services/auth.ts 与 @src/routes/login.ts，
为「记住登录」补齐服务端校验；不要改无关路由。
避免： 一次甩十几个「说不定有用」的文件。
Prompt 见 附录：点名文件改功能。
2. @Folders：指定目录
适合： 模块级重构、在某一层做一致性修改、先摸清结构再动手。
示例：
只在 @src/components/forms 内排查未统一的错误提示文案，
先列出问题清单，等我确认后再改；不要动 forms 以外的文件。
注意： 目录越大，越要在话术里加边界——「只读 / 先列表 / 不得超出该目录」。
Prompt 见 附录：目录摸底与小改。
3. @Code：精确到符号或选中片段
适合： 改某个函数、追调用方、解释难读逻辑。比整文件更省上下文、指代更稳。
示例：
基于 @Code(parseInvoiceTotal)，说明税率字段为空时的行为，
并补单测覆盖该分支。
Prompt 见 附录：围绕符号分析与修改。
4. @Docs：已索引或预置的文档源
适合： 按框架/库的当前推荐写法实现功能（React Router、Cloudflare Workers、UI 库等）。
示例：
按 @Docs(Cloudflare Workers) 的推荐方式，
为 @src/index.ts 增加只读 health 路由，给出可运行改动。
避免： 文档版本与 package.json 大版本不一致时，在提示里写明版本，或改用 @Web 查对应版本文档。
Prompt 见 附录：按官方文档实现。
5. @Web：临时检索公开网页
适合： 查报错原文、变更日志、刚发布的 API、社区同类问题线索。
示例：
使用 @Web 检索「Vite 6 SSR import.meta.env undefined」，
对照 @vite.config.ts，给出最小修复方案与风险说明，并列出参考链接。
注意： 要求 Agent 列出参考链接；关键结论你仍需点开核对。
Prompt 见 附录：报错与版本排查。
6. @Git：提交、分支或 diff
适合： 写变更说明、回顾某次提交、基于未提交 diff 做审查或补测试。
示例：
基于 @Git 查看当前未提交变更，
按「为何改」写 3 条 commit message 候选，侧重动机而非文件清单。
与「AI 辅助的 Git 工作流」的关系：那篇讲流程；这里强调在 Cursor 里用 @Git 把 diff 喂给模型。
Prompt 见 附录：基于 diff 写说明与审查。
7. 其他常见引用（按版本可能出现）
| 引用 | 典型用途 |
|---|---|
@Past Chats | 延续先前结论；仍建议重新 @ 关键文件 |
@Rules | 确认某条 Rule 是否适用 |
| 截图 / 图片 | UI 偏差、报错弹窗、设计稿对照 |
原则不变：引用是为了减歧义，不是为了堆材料。
五种组合配方
日常任务可按下面配方组合 @，不必每次从零想。
配方 A：修一个具体 Bug
@Files(报错相关) + @Code(可疑函数) + 粘贴报错原文
→ 要求：先给根因假设与验证步骤，再改代码配方 B：按官方文档加功能
@Docs(框架) + @Files(入口) + @Folders(相关模块，可选)
→ 要求：标出文档依据；偏离本地风格时先询问配方 C：理解近期变更并补测试
@Git(未提交或指定 commit) + @Folders(测试目录)
→ 要求：只补测本次行为变化，不重构生产代码配方 D：文档说可以、项目里不行
@Docs 或 @Web + @Files(配置) + @Files(package.json / lockfile)
→ 要求：先比对版本，再给最小可行修复配方 E：小范围 UI 调整
截图 + @Files(页面组件) + @Files(样式/Token 文件)
→ 要求：只改视觉与文案，不改路由与数据层配方与模式怎么配：
| 配方 | 步骤多、跨文件 | 建议模式 |
|---|---|---|
| A、E | 否 | 直接 Agent |
| B、C、D | 是 | 先 Ask/Plan，再 Agent |
| 任何配方 | 不确定范围 | 先 Ask，收窄后再 Agent |
常见踩坑
引用选错
| 踩坑 | 后果 | 更好做法 |
|---|---|---|
| 只说「登录那块」 | 找错文件、改错层 | @Files / @Code 点名 |
@Folders 甩整个 src | 噪声大、乱改 | 收窄目录 + 「先列表后修改」 |
| 该查文档却让模型背 API | 过时方法、幻觉 | @Docs / @Web |
| 一次引用无关测试、设计稿 | 任务稀释 | 按配方只留必要附件 |
长对话不新开、不重新 @ | 早期错误结论被延续 | 新任务 + 重新 @ 关键文件 |
与 Rules / Skills 打架
| 踩坑 | 对策 |
|---|---|
| 口头约束与 Rules 重复又矛盾 | 重复约束写进 Rules，对话里 @ 文件即可 |
| 该用 Skill 却手写长 Prompt | 固定流程收成 Skill，@ 只补本次上下文 |
@Folders 扫到不该改的生成目录 | Rules 里标明忽略路径；@ 时写清不得触碰的目录 |
发送前
| 踩坑 | 对策 |
|---|---|
| 没写「不要动什么」 | 每条 Agent 任务带负面边界 |
| 复杂任务一步做完 | 拆成「只读分析」与「实现」两轮 |
| 敏感路径进云端 | 先脱敏；或只用本地/企业合规工具 |
一分钟自检（发送前）
- [ ] 是否点名了真正要改/要读的文件或符号？
- [ ] 是否写清了不要动的范围？
- [ ] 需要权威依据时，是否加了
@Docs或@Web？ - [ ] 引用数量是否还能再减？
- [ ] 任务是否应拆成「先只读 / 再实现」两轮？
什么时候可以少引用
不必每个任务都 @ 一堆东西：
| 任务类型 | 可弱化 | 不能省 |
|---|---|---|
| 单行 typo、注释 | @Folders、截图 | 仍 @Files 目标文件 |
| 解释项目结构（首次接入） | @Web | @Folders 顶层 + AGENTS.md |
| 延续刚聊完的同文件小改 | 重新 @ 全部附件 | @Files 当前文件或 @Past Chats |
| 按 Skill 跑固定流程 | 重复贴长约束 | Skill + 本次相关的 @Files |
不能跳的核心： 任务目标、负面边界、以及「权威依据从哪来」这三件事，至少要说清一件。
附录：Prompt 模板
按场景复制使用。正文中已标注对应链接。
点名文件改功能
阅读 @【文件路径】，实现「【功能描述】」。
约束：
- 不得修改该文件以外的代码，除非我另行同意
- 保持现有命名与错误处理方式
- 完成后列出已手动验证的路径目录摸底与小改
只分析 @【目录路径】，不要修改任何文件。
输出：
1）目录职责一句话
2）与「【任务主题】」相关的文件清单
3）建议的修改顺序与风险点
等我确认后再进入修改阶段。围绕符号分析与修改
基于 @Code(【符号名】)：
1）说明当前行为与边界情况
2）指出与【需求/问题】相关的调用链（只列文件名与符号名）
3）给出最小改动方案；未确认前不要写代码按官方文档实现
按 @Docs(【文档源名】) 的当前推荐方式，在 @【入口文件】 实现「【功能】」。
要求：
- 实现中注明依据的文档章节或 API 名称
- 若与仓库现有风格冲突，先列出差异再动手
- 不得引入文档未要求的额外依赖报错与版本排查
报错信息如下：
【粘贴完整报错】
请使用 @Web 检索可能原因，并对照 @【配置文件】与 @package.json（或锁文件）。
输出：
1）最可能的 2～3 个根因（附参考链接）
2）推荐的最小修复步骤
3）如何本地验证修复是否有效
不要直接大改，先给方案。基于 diff 写说明与审查
基于 @Git 查看【当前未提交变更 / 指定 commit】：
1）用 3～5 条 bullet 说明「为何改」，避免只列文件名
2）标出是否有破坏性变更或需他人知晓的配置改动
3）若用于合并前审查：是否超出【第一期/本期范围】？是否引入文档未定义的接口字段？
只读分析，不要修改代码。配方 B 完整示例（文档 + 实现）
我要按官方方式增加「【功能名】」。
上下文：
- @Docs(【框架名】)
- @【相关源文件】
请先 Plan：
1）需要改哪些文件
2）依赖文档中的哪几段
3）如何验证
计划确认后，再分步 Agent 实现；每步只改计划中的文件。发送前自检（可贴给 Ask）
我准备发送下面这条 Agent 任务。请当审查员，只读检查：
1）@ 引用是否过多或过少？
2）负面边界是否写清？
3）是否应先 Plan 再 Agent？
4）是否缺 @Docs / @Web 导致可能幻觉？
【粘贴拟发送的任务】
