---
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="/zh-Hant/docs/cursor/official/07-help-troubleshooting/103-models-usage-help" />
  <Card title="上下文理解篇" description="理解索引、規則和上下文鏈路" href="/zh-Hant/docs/cursor/understanding/05-context-indexing-rules" />
  <Card title="MCP 與工具" description="繼續看工具許可權邊界" href="/zh-Hant/docs/cursor/understanding/06-mcp-tools-browser-terminal" />
</Cards>
