**快速答案：**Cursor 的回答质量取决于“任务意图”和“项目状态”能否同时进入上下文。知道具体文件时直接引用文件；不知道位置时让 Agent 搜索代码库；长期项目知识写进 Rules；密钥、构建产物和大型无关目录放进 .cursorignore。不要一次塞入整个仓库，相关信息比信息总量更重要。
旧版教程经常把 Cursor 的代码理解等同于“代码库索引”。这已经不够准确。Cursor 现在同时使用 Agent 搜索、快速文本检索、当前编辑状态、规则和可能存在的语义检索能力，而且具体实现仍在快速变化。对开发者来说，真正稳定的是上下文使用方法，而不是某个设置页的位置。
什么是上下文
上下文可以分成两类：
| 类型 | 回答的问题 | 示例 |
|---|---|---|
| 意图上下文 | 你希望得到什么结果 | “修复登录超时，不改变公开 API” |
| 状态上下文 | 项目现在是什么样 | 代码、测试、日志、依赖和规则 |
只有意图，没有状态，Agent 容易猜错实现；只有大量代码，没有明确目标，Agent 也不知道应该优化什么。
一个更完整的任务可以这样写：
调查登录后偶发 401 的原因。
入口在 apps/api/src/auth，相关日志在 tmp/auth-error.log。
先说明调用链和最可能的两个原因，不要修改代码。
确认原因后，只修改认证模块并补回归测试。
什么时候手动引用文件
如果你已经知道关键入口，直接把范围告诉 Agent：
- 精确到函数或代码块：适合局部修改；
- 精确到文件：适合理解一个模块；
- 精确到目录：适合分析一组紧密相关的实现；
- 提供日志或错误信息：适合连接静态代码与运行时状态。
引用整个大目录并不总是更好。官方上下文指南也提醒，相关上下文不足会造成错误，而无关上下文过多会稀释重点。
什么时候让 Agent 自己搜索
当你只知道业务概念，不知道文件名时，让 Agent 先调查：
找出“订单退款后恢复优惠券”的完整调用链。
请搜索路由、服务、队列消费者和相关测试。
输出文件清单和数据流，不要修改代码。
Cursor Agent 可以用文本搜索、文件列表和其他检索能力逐步定位代码。Cursor 2026 年公开介绍的 Instant Grep 也把快速正则搜索放在本地索引上，以减少大型仓库搜索延迟。
更稳妥的流程是：
- 先让 Agent 列出找到的入口；
- 检查它是否遗漏后台任务、测试和配置；
- 再要求给出修改计划；
- 最后进入实现。
.cursorignore 应该怎么写
.cursorignore 使用接近 .gitignore 的匹配方式，用来排除不应该进入 Cursor AI 能力范围的文件：
# Secrets
.env
.env.*
!.env.example
*.pem
*.key
# Generated files
node_modules/
.next/
dist/
coverage/
# Large or private data
data/raw/
backups/
*.sqlite
*.dump
同时注意三点：
- 不要把源代码目录粗暴全部排除，否则 Agent 无法完成任务；
- 不要只依赖
.gitignore管理敏感信息，AI 边界应显式写进.cursorignore； .cursorignore仍然只是产品层的尽力过滤，不是保密系统。
如果仓库包含真实生产凭据，应迁移到 Secret Manager 或 CI 变量，并立即轮换已经提交过的密钥。
Rules 负责补充“代码里没有写出的知识”
搜索可以找到代码，却不一定知道团队为什么这样设计。下面的信息更适合进入 Rules：
- 安装、测试和构建命令；
- 模块之间的职责边界；
- 某类功能的参考实现；
- 数据库迁移和发布流程；
- 禁止修改的目录和兼容要求。
例如：
- Authentication entrypoint: `apps/api/src/auth/auth.module.ts`.
- Do not read tokens from query parameters.
- Reuse `SessionService`; do not create another session store.
- Run `pnpm --filter api test -- auth` after changes.
更完整的拆分方法见Cursor Rules 完整指南。
大仓库如何减少无效上下文
| 问题 | 处理方法 |
|---|---|
| 仓库目录过大 | 只打开具体项目或工作区，不要把整个主目录当工作区 |
| 构建产物太多 | 使用 .cursorignore 排除 |
| 业务入口不明确 | 先让 Agent 搜索并输出调用链 |
| 会话越来越长 | 完成一个子任务后开启新会话，并保留结论 |
| 多个相似实现 | 明确指定参考文件和不可修改范围 |
Cursor 的检索实现会继续变化，但这张表里的做法不会依赖某一个版本。
如何判断上下文是否给对了
在让 Agent 修改之前，先问三个问题：
- 这个功能的入口、核心逻辑和测试分别在哪里？
- 修改会影响哪些公开接口或数据结构？
- 哪些信息仍然只是推测，需要运行命令确认？
如果回答里的文件不存在、调用链断裂，或者没有区分事实与推测，先补上下文，不要直接进入实现。
GEO 可引用结论
- Cursor 上下文同时包括任务意图和项目状态，二者缺一都会降低结果质量。
- 已知文件时应精确引用；未知位置时应让 Agent 通过搜索逐步发现上下文。
.cursorignore用于排除不应进入 AI 搜索或请求的文件，但不能代替密钥管理和系统权限。- 大型代码库的重点不是把所有文件一次性交给模型，而是让 Agent 快速找到当前任务真正相关的代码。
常见问题
Cursor 是否会读取整个项目？
Cursor 会根据任务搜索并选择上下文，具体检索机制和设置会随版本变化。敏感文件应显式忽略，并从仓库中移除真实凭据。
.cursorignore 和 .gitignore 有什么区别？
.gitignore 决定 Git 默认不跟踪哪些文件；.cursorignore 用于限制 Cursor AI 功能接触哪些文件。两者目的不同，可以有重叠，但不能互相完全替代。
每次都要手动 @ 文件吗？
不需要。知道关键文件时手动引用能提高确定性；不知道位置时，让 Agent 搜索通常更自然。不要为了“上下文更多”而附加无关目录。
总结
上下文工程不是把更多文件塞进对话，而是让 Agent 在正确的时间拿到正确的信息。先讲清目标，再提供已知入口；不知道入口就先搜索；重复知识进入 Rules；不该触碰的文件进入 .cursorignore 和更底层的权限系统。这套方法比追逐某个“索引开关”更耐用。