---
title: "上下文、索引和 Rules"
description: "让 Cursor 真的理解项目：索引负责事实，Rules 负责长期约束，prompt 负责本次目标。"
verifiedAt: "2026-05-09"
---

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

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

## 1. 三层上下文模型

```mermaid
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。

常见排障顺序：

1. 看 status bar 的 indexing 状态。
2. 如果新增大量文件或重命名目录，手动 Reindex。
3. 检查 `.cursorignore` 是否误排除了源码。
4. 检查 generated files、build artifacts、binary assets 是否应该排除。
5. 确认 `.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 示例：

```text
---
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.
```

这条 rule 短、可触发、和文件范围绑定。比把整份前端规范复制进去更有效。

## 5. AGENTS.md、CLAUDE.md 和 Project Rules 的边界

官方 Help Center 说明 Cursor 会读取项目根目录的 `AGENTS.md`，也会像读取 `AGENTS.md` 一样读取 `CLAUDE.md`。

建议分工：

- `AGENTS.md`：跨工具通用的项目入口、基本工作规则。
- `.cursor/rules/`：Cursor 专用、可条件触发的详细规则。
- `CLAUDE.md`：兼容 Claude Code 的项目导航和规则。
- User Rules：个人偏好，不写团队要求。

如果这些文件内容冲突，优先清理冲突，而不是继续叠加。规则越多，Agent 越可能被互相矛盾的指令拖偏。

## 6. Rules 写作标准

官方最佳实践强调 focused、actionable、scoped。

应该做：

- 保持 rule 短，官方建议低于 500 行。
- 一个 rule 只解决一个主题。
- 用 `description` 或 `globs` 控制触发。
- 给具体例子。
- 引用 canonical 文件，不复制全文。
- 当 Agent 反复犯同一类错误时再新增 rule。

不要做：

- 把整份 style guide 塞进 Always Apply。
- 写“代码要优雅、要高质量”这种不可执行要求。
- 把少见 edge case 写成长期规则。
- 在 Team Rules、Project Rules、AGENTS.md 里重复同一句话。

## 7. 上下文验收清单

开始重要任务前，先确认：

- Indexing 已完成。
- `.cursorignore` 没排除关键源码。
- Project Rules 和 Team Rules 没冲突。
- `AGENTS.md` / `CLAUDE.md` 不和 `.cursor/rules` 打架。
- 本次 prompt 写清目标、范围、禁止动作和验证命令。
- 任务中需要的文件能被 Cursor 找到。
- 敏感文件没有依赖 `.cursorignore` 作为唯一保护。

如果 Agent 一直误解项目，先查这张清单，再考虑换模型。

## 官方来源

- [Cursor Rules](https://cursor.com/docs/rules.md)：官方 Rules 类型、frontmatter、globs、创建方式和最佳实践。
- [Cursor Rules Help](https://cursor.com/help/customization/rules.md)：Help Center Rules 入门说明。
- [Cursor Context Help](https://cursor.com/help/customization/context.md)：Help Center 上下文说明。
- [Cursor Indexing Help](https://cursor.com/help/customization/indexing.md)：索引状态、Reindex 和项目可见性说明。
- [Cursor Ignore Files Help](https://cursor.com/help/customization/ignore-files.md)：`.cursorignore` 行为和边界。

## 接下来去哪

<Cards>
  <Card title="上一篇" description="先把 Ask、Agent、Plan、Debug 和 Tab 分清。" href="/docs/cursor/understanding/04-agent-plan-ask-debug-tab" />
  <Card title="下一篇" description="继续理解 MCP、Browser、Terminal 和工具权限。" href="/docs/cursor/understanding/06-mcp-tools-browser-terminal" />
  <Card title="官方 Rules" description="查看官方重组页里的 Rules frontmatter 和触发逻辑。" href="/docs/cursor/official/02-context-customization/20-rules" />
</Cards>
