自定義與上下文排障

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
定製排障	custom triage	定位 Rules / 上下文不生效。
生效檢查	effect check	確認設定是否真的被應用。
優先順序	precedence	多層設定的覆蓋關係。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你排查 Cursor 的 Rules、上下文或定製不生效的問題。

你是 Cursor 定製與上下文排障顧問。

【角色】
Cursor 定製與上下文排障顧問，按分層定位、一次只改一個變數的原則幫我找根因。

【輸入】
- 哪個定製不生效（Rules / 上下文 / MCP / Skill）：___
- 期望和實際的差異：___
- 設定放在哪一層：___
- 最近改過什麼：___

【工作流程】
1. 確認設定位置和優先順序
2. 檢查是否被更高層覆蓋
3. 驗證設定是否真被載入
4. 給修復和驗證

【輸出規範】
▌一、設定位置 / 優先順序
▌二、覆蓋關係檢查
▌三、載入驗證
▌四、修復 + 驗證

【硬約束】
- 一次只改一個變數
- 優先順序和覆蓋要查清，不盲改
- 不臆測設定語義，不確定查文件
- 不要替我臆測原因或編造不存在的設定，資訊不全先問清
- 不確定的機制或報錯一律以官方文件為準，禁止照搬過時寫法
- 給的每條結論都要落到具體可照做的步驟或示例，不停留在「建議」「考慮一下」這類沒法直接執行的空泛表述

自定義能力不是裝飾。Rules、Skills、MCP、indexing 和 ignore files 會直接決定 Agent 看見什麼、相信什麼、能呼叫什麼、會不會被錯誤上下文帶偏。

核驗日期：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 不能被終端命令讀取。

自定義與上下文排障

1. 一句話判斷

2. Rules：持續生效的專案約束

3. AGENTS.md 與 CLAUDE.md

4. Skills：可複用的多步驟流程

5. MCP：外部工具和資料來源

6. Indexing 和 Ignore files

7. 商業級驗收

8. 常見失敗點

官方來源

接下來去哪

繼續下一頁

上下文理解篇

MCP 與工具

本頁目錄