上下文、索引和 Rules

Cursor 出错时，很多人第一反应是换模型。真实项目里，更常见的问题是上下文治理没做好：索引不完整、Rules 太长或没触发、.cursorignore 排错了文件、AGENTS.md 和 Project Rules 冲突、任务 prompt 又没有写清范围。

本章目标：你会把 Cursor 上下文拆成三层：indexing 提供代码事实，Rules 提供长期规范，prompt 提供本次任务边界。

1. 三层上下文模型

flowchart TD
  Codebase["Codebase / Indexing"] --> Agent["Cursor Agent"]
  Rules["Rules / AGENTS.md / Team Rules"] --> Agent
  Prompt["Current Task Prompt"] --> Agent
  Agent --> Output["Plan / Edits / Commands / Review"]

三层职责不同：

Indexing：让 Cursor 找得到项目文件、符号、语义关系和搜索结果。
Rules：告诉 Agent 长期应该遵守什么，例如目录边界、测试策略、风格约束。
Prompt：告诉 Agent 这一次具体做什么、不能做什么、怎么验收。

不要把三者混在一起。把本次任务写进 Rule，会污染长期上下文；把长期规范每次手打进 prompt，会浪费上下文；索引没完成时让 Agent 改代码，会让它基于不完整事实行动。

2. Indexing：先确认项目可见

Cursor 打开项目后会索引代码库。Help Center 说明可以看 indexing 状态，必要时 reindex；.cursorignore 可用于额外排除 indexing 和 AI context。

常见排障顺序：

看 status bar 的 indexing 状态。
如果新增大量文件或重命名目录，手动 Reindex。
检查 .cursorignore 是否误排除了源码。
检查 generated files、build artifacts、binary assets 是否应该排除。
确认 .gitignore 和 .cursorignore 的边界。

.cursorignore 适合排除：

generated files。
build output。
large binaries。
secrets and credentials。
third-party vendored code。

但要注意：.cursorignore 不是安全边界。terminal commands 和 MCP tools 可能在 Cursor 文件上下文之外访问文件。真正的密钥安全要靠文件权限、凭据系统和最小授权。

3. Rules：长期约束，不是资料仓库

Cursor 官方 Rules 文档说明，Rules 是 persistent reusable context，会在匹配时放进 model context。它们适合保存反复生效的项目规则。

四类规则：

Project Rules：放在 .cursor/rules，进入 Git，适合团队共享。
User Rules：个人全局偏好，不适合承载团队规范。
Team Rules：Team / Enterprise dashboard 管理，用于组织统一要求。
AGENTS.md：放在项目根目录的 markdown 文件，Cursor 会在每次 Agent 启动时自动读——适合写简单跨工具通用规则（也被 Codex / Claude Code 等其他 Agent 工具识别为通用入口）。

Project Rules 还可以嵌套——把 .cursor/rules/ 放在子目录（如 src/api/.cursor/rules/），里面的规则只在该目录及其下的文件被引用时生效。monorepo 或多模块项目可以用这种方式，让"前端规则只对前端目录生效、API 规则只对 API 生效"，避免一份规则被无关任务拖出来。

真实项目优先 Project Rules，因为它可 review、可追溯、随代码演进。

4. Rule 触发方式

官方文档里的 Rule 行为可以这样理解：

Always Apply：每个 chat session 都加入，适合极少数硬规则——例如"禁止改 schema 文件"这种随时都要遵守的边界。
Apply Intelligently：Agent 根据 description 判断是否相关——description 字段写清"什么场景适用"，让 Agent 自己挑。
Apply to Specific Files：匹配 globs（文件路径模式，如 src/components/**/*.tsx）时触发——锁路径用，最适合按目录写的领域规则。
Apply Manually：只在 chat 里 @rule-name 主动调用——罕见场景或仅在特定任务下使用的规则放这一类。

Rules 可以用 .md 或 .mdc（Markdown + frontmatter 扩展，比 .md 多 description、globs、alwaysApply 字段）。如果要写这些字段，.mdc 更清晰。

一个小而有效的 project rule 示例：

---
description: Applies to React component changes under src/components.
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

When changing shared React components:
- Preserve existing props unless explicitly requested.
- Add or update focused tests when behavior changes.
- Do not introduce app-specific copy into shared components.