cursor-context-management

Cursor 上下文管理

概述

控制 Cursor 能看到的内容，让每次对话只包含生成可靠回答或编辑所需的最少相关且符合政策要求的上下文。

前置条件

• 明确的任务范围、获批的隐私设置、数据分类，以及可正常使用的忽略配置。
• 可供共享的相关文件和接口，其中不得包含凭据、客户数据或无关代码库的内容。

说明

1. 从所需的确切文件、符号和约束入手；避免不加筛选地使用 @Codebase。
2. 提交前检查上下文标签/附件，并移除过时或敏感的内容。
3. 主题或代码库边界发生变化时，开启新的聊天。
4. 根据源文件和测试验证生成的输出；上下文相关性不能取代验证。

输出

• 一组有文档记录的最小上下文，以及可供独立审核的限定范围结果。

错误处理

情况	安全的应对方式
上下文已过时或相互矛盾	开启新的、限定主题的聊天，并使用当前文件。
出现敏感路径	停止操作，移除该路径，修复排除配置，并遵循信息暴露处理流程。
模型遗漏关键信息	附上权威文件/接口，而不是扩展到整个代码库。

示例

如果要修复某个服务中的错误，请附上该服务的处理程序、接口和针对性测试，说明故障行为，并要求提供最小修复。如果对话开始讨论另一个服务，请开启新的聊天，而不是不断添加更多上下文。

优化 Cursor AI 对上下文的使用，以生成准确、相关的回答。上下文就是模型生成回答时看到的一切——良好管理上下文是提升输出质量最重要的手段。

上下文来源

Cursor 会在每次 AI 请求前从多个来源汇集上下文：

┌─ Always Included ─────────────────────────────────────┐
│  System prompt (Cursor internal)                      │
│  Active .cursor/rules/*.mdc with alwaysApply: true    │
│  Current file (for Tab, Inline Edit)                  │
└───────────────────────────────────────────────────────┘
┌─ Conditionally Included ──────────────────────────────┐
│  Selected code (highlighted before Cmd+L/Cmd+K)       │
│  @-mention targets (@Files, @Folders, @Code)          │
│  Glob-matched rules (.mdc with matching globs)        │
│  Conversation history (prior turns in chat)           │
│  Open editor tabs (lightweight reference)             │
└───────────────────────────────────────────────────────┘
┌─ On-Demand (explicit @-mention) ──────────────────────┐
│  @Codebase  → semantic search across indexed files    │
│  @Docs      → crawled external documentation          │
│  @Web       → live web search results                 │
│  @Git       → uncommitted diff or branch diff         │
│  @Lint Errors → current file lint diagnostics         │
└───────────────────────────────────────────────────────┘

上下文标签

当前上下文会以标签形式显示在 Chat/Composer 面板顶部：

[main.ts] [src/utils/] [@Web: next.js 15] [Rule: typescript-standards]

• 点击标签可展开并查看其内容
• 点击标签上的 x 可将其从上下文中移除
• 添加过多标签会占满上下文窗口，降低回答质量

按任务选择 @-提及策略

理解代码

@src/auth/middleware.ts @src/types/user.ts
Explain how the JWT validation works and what happens when a token expires.

对特定文件使用 @Files。除非需要整个目录，否则避免使用 @Folders——它会占用大量上下文。

调查错误

@src/hooks/useCart.ts @Lint Errors @Recent Changes
The cart total is NaN after the latest changes. What broke?

@Recent Changes + @Lint Errors 可为模型提供取证所需的上下文。

架构问题

@Codebase where are database queries made?

@Codebase 会在已索引的代码库中触发语义搜索。若不知道哪些文件相关，它适合用于探索。与定向提及 @Files 相比，它会占用更多上下文。

使用外部知识

@Docs Prisma @Web prisma client extensions 2025
How do I add soft-delete as a Prisma Client extension?

@Docs 使用预先索引的文档。@Web 会进行实时搜索。两者结合使用，可全面解答有关第三方工具的问题。

上下文预算管理

每个模型都有上下文限制。超出限制会导致模型悄无声息地丢弃信息：

模型	上下文窗口	实际可用上限
GPT-4o	128K tokens	~80K 可用
Claude Sonnet	200K tokens	~150K 可用
Claude Opus	200K tokens	~150K 可用
cursor-small	8K tokens	~5K 可用

上下文溢出的迹象

• 模型忘记对话早先的指示
• 回答变得笼统或重复
• 模型否定自己 3 轮之前说过的话
• 建议的代码忽略了你提供的文件上下文

缓解策略

1. 经常开启新对话。 每次对话只讨论一个主题。
2. 使用特定的 @Files，而非 @Folders。 @src/api/users.ts 优于 @src/api/。
3. 移除不再需要的上下文标签。 点击 x 移除过时文件。
4. 窄范围问题避免使用 @Codebase。 它会引入许多代码片段。如果知道文件位置，请使用 @Files。
5. 将大型任务拆分成多个步骤。 分别询问类型定义、实现和测试，可在不同轮次或聊天中进行。

自动与手动上下文

Cursor 在某些情况下会自动包含上下文：

功能	自动上下文
Tab 补全	当前文件 + 已打开的标签页 + 最近的编辑
行内编辑 (Cmd+K)	选中的代码 + 周边文件内容
聊天 (Cmd+L)	对话历史 + 明确添加的上下文
Composer (Cmd+I)	引用的文件 + 代码库搜索

对于 Chat 和 Composer，你可以通过 @-mentions 控制上下文。Tab 和行内编辑会自动管理自己的上下文。

使用 .cursorignore 控制上下文

阻止文件被纳入 AI 上下文：

# .cursorignore (project root)

# Secrets and credentials
.env
.env.*
**/secrets/
**/credentials/

# Large generated files
dist/
build/
node_modules/
*.min.js
*.bundle.js

# Data files that consume context budget
*.csv
*.sql
*.sqlite
fixtures/

注意： .cursorignore 仅尽力而为。它会阻止文件出现在索引和 AI 功能中，但不能作为保护机密信息的安全边界。请使用 .gitignore 和环境变量来实际管理机密信息。

进阶：将规则作为上下文

打开相关文件时，项目规则会自动注入上下文：

# .cursor/rules/database-patterns.mdc
---
description: "Database query patterns and conventions"
globs: "src/db/**/*.ts,src/repositories/**/*.ts"
alwaysApply: false
---
# Database Conventions
- Use parameterized queries exclusively
- All queries go through repository pattern
- Wrap multi-table operations in transactions
- Use connection pooling (pool size: 10)

编辑数据库文件时，此规则会自动加载，无需每次手动添加上下文，即可让 AI 遵循正确的约定。

企业注意事项

• 数据敏感性：使用 .cursorignore 排除包含个人身份信息、凭据或受监管数据的文件
• 隐私模式：确保发送给模型提供商的上下文代码不会被留存
• 对话规范：培训团队成员每项任务都开启新聊天，以避免上下文混杂
• 成本意识：使用 BYOK 时，上下文越大 = token 越多 = API 成本越高

资源

• @ 符号概览
• 代码库索引
• 忽略文件