自定义与上下文排障

自定义能力不是装饰。Rules、Skills、MCP、indexing 和 ignore files 会直接决定 Agent 看见什么、相信什么、能调用什么、会不会被错误上下文带偏。

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/context.md
• https://cursor.com/help/customization/mcp.md
• https://cursor.com/help/customization/skills.md
• https://cursor.com/help/customization/indexing.md
• https://cursor.com/help/customization/ignore-files.md

接下来去哪