---
title: "自定义与上下文排障"
description: "把 Rules、Context、MCP、Skills、Indexing、Ignore files 变成可排查的 Cursor 上下文治理路径。"
verifiedAt: "2026-05-09"
---
自定义能力不是装饰。Rules、Skills、MCP、indexing 和 ignore files 会直接决定 Agent 看见什么、相信什么、能调用什么、会不会被错误上下文带偏。

> [!NOTE]
> **核验日期**：2026-05-06。Rules、Skills、MCP、索引、ignore files 和兼容目录会随 Cursor 版本变化；团队规则上线前按官方文档复核。

## 1. 一句话判断

当 Agent 输出不稳定，先查上下文链路：规则是否正确、索引是否完成、忽略文件是否合理、MCP 是否安全、Skill 是否该被调用。

不要一上来换模型。大多数项目级失误来自上下文质量，而不是模型能力。

## 2. Rules：持续生效的项目约束

Rules 是 Agent 每次工作时可读取的持久指令。官方说明可按 global、project 或 specific files 作用域配置。

Project rules 存在 `.cursor/rules/`，适合提交到 git，让团队共享。创建方式是打开 command palette，搜索 `New Cursor Rule`。

规则类型包括：

- **Always Apply**：每次 conversation 都加入。
- **Apply Intelligently**：Agent 判断相关性。
- **Apply to Specific Files**：只对匹配 pattern 的文件生效。
- **Apply Manually**：只有 @mention 时使用。

规则排障看三件事：

- 是否过长，官方建议小于 500 行，长规则拆成多个文件。
- 是否有具体示例或 `@filename` 参考。
- 是否作用域错误，导致不该生效时也生效。

Team Rules 优先级高于 Project Rules，Project Rules 高于 User Rules。规则冲突时先查 Team Dashboard。

## 3. AGENTS.md 与 CLAUDE.md

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

边界：

- `AGENTS.md` / `CLAUDE.md` 总是应用到 conversation。
- 如果需要条件触发，用 `.cursor/rules/`。
- 兼容 Claude Code 的项目可以保留 `CLAUDE.md`，但要避免和 Cursor project rules 冲突。

## 4. Skills：可复用的多步骤流程

Skills 是更长、更具体的 workflow instruction。官方说明它们是 markdown 文件，常见位置包括：

- `.cursor/skills/`
- `.agents/skills/`
- `~/.cursor/skills/`
- `~/.agents/skills/`
- 兼容目录：`.claude/skills/`、`.codex/skills/`、`~/.claude/skills/`、`~/.codex/skills/`

用法：

- 输入 `/skill-name` 调用。
- 输入 `@skill-name` 作为上下文附加。
- 用 `/create-skill` 生成新 Skill。
- Cursor 2.4+ 可用 `/migrate-to-skills` 迁移部分 rules 和 commands。

经验判断：

- 短约束用 Rules。
- 多步骤、可重复、需要检查清单的流程用 Skills。

## 5. MCP：外部工具和数据源

MCP 让 Agent 能连接数据库、API、GitHub、Linear、Notion 等外部工具和数据源。

排障重点：

- Settings > Tools & MCP 是否启用对应 server。
- Output panel 中 MCP Logs 是否有错误。
- 环境变量是否在 Cursor 进程里可见。
- 项目级 `.cursor/mcp.json` 和全局 `~/.cursor/mcp.json` 是否冲突。
- Cloud Agents 是否在 dashboard 中配置了对应 MCP。
- 企业 allowlist 是否阻止了 server 或 tool。

权限重点：

- MCP server 可能读外部数据，也可能代表用户执行操作。
- 自动运行 MCP tool 前必须确认权限边界。
- 企业环境按 88 页的 MCP allowlist 管理。

## 6. Indexing 和 Ignore files

Cursor 打开项目后会自动索引代码库，官方说明索引会周期性同步，大约每五分钟拾取变化。

索引排障：

- 看底部 status bar 的 indexing 状态。
- command palette 搜索 `Reindex`，必要时重建索引。
- 大仓库优先排除 generated files 和 build artifacts。

`.cursorignore` 用来额外排除 Cursor indexing 和 AI context。官方说明 Cursor 默认已忽略 `.env`、`.git/`、lock files，并尊重 `.gitignore`。

`.cursorignore` 适合排除：

- generated files。
- secrets and credentials。
- binary files and assets。
- third-party code。

但要注意：terminal commands 和 MCP tools 在 Cursor 文件访问控制之外运行，仍可能读取 ignored files。真正安全边界要靠文件权限、密钥管理和 hooks。

## 7. 商业级验收

- Project rules 小而明确，并提交到 git。
- Team Rules、Project Rules、User Rules 的优先级没有冲突。
- `AGENTS.md` / `CLAUDE.md` 和 `.cursor/rules/` 职责清楚。
- Skills 用于多步骤流程，而不是塞进超长 rule。
- MCP server 有 owner、权限说明、日志和 allowlist。
- Indexing 状态可见，必要时能 Reindex。
- `.cursorignore` 排除了大文件、密钥、构建产物和无关第三方代码。
- 团队知道 `.cursorignore` 不是安全边界。

## 8. 常见失败点

- 一个 rule 写几千行，Agent 反而抓不到重点。
- Team Rules 和 Project Rules 冲突，用户只查本地文件。
- 把部署流程写成 Always Apply rule，导致每次任务都污染上下文。
- MCP server 缺环境变量，却误判为模型不会调用工具。
- `.cursorignore` 排除了关键源码，Agent 找不到上下文。
- 以为 ignored files 不能被终端命令读取。

## 官方来源

- [https://cursor.com/help/customization/rules.md](https://cursor.com/help/customization/rules.md)
- [https://cursor.com/help/customization/context.md](https://cursor.com/help/customization/context.md)
- [https://cursor.com/help/customization/mcp.md](https://cursor.com/help/customization/mcp.md)
- [https://cursor.com/help/customization/skills.md](https://cursor.com/help/customization/skills.md)
- [https://cursor.com/help/customization/indexing.md](https://cursor.com/help/customization/indexing.md)
- [https://cursor.com/help/customization/ignore-files.md](https://cursor.com/help/customization/ignore-files.md)

## 接下来去哪

<Cards>
  <Card title="继续下一页" description="103-models-usage-help" href="/docs/cursor/official/07-help-troubleshooting/103-models-usage-help" />
  <Card title="上下文理解篇" description="理解索引、规则和上下文链路" href="/docs/cursor/understanding/05-context-indexing-rules" />
  <Card title="MCP 与工具" description="继续看工具权限边界" href="/docs/cursor/understanding/06-mcp-tools-browser-terminal" />
</Cards>
