自定義與上下文排障

自定義能力不是裝飾。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

接下來去哪