上下文、索引和 Rules

Cursor 出錯時，很多人第一反應是換模型。真實專案裡，更常見的問題是上下文治理沒做好：索引不完整、Rules 太長或沒觸發、.cursorignore 排錯了檔案、AGENTS.md 和 Project Rules 衝突、任務 prompt 又沒有寫清範圍。

本章目標：你會把 Cursor 上下文拆成三層：indexing 提供程式碼事實，Rules 提供長期規範，prompt 提供本次任務邊界。

1. 三層上下文模型

flowchart TD
  Codebase["Codebase / Indexing"] --> Agent["Cursor Agent"]
  Rules["Rules / AGENTS.md / Team Rules"] --> Agent
  Prompt["Current Task Prompt"] --> Agent
  Agent --> Output["Plan / Edits / Commands / Review"]

三層職責不同：

Indexing：讓 Cursor 找得到專案檔案、符號、語義關係和搜尋結果。
Rules：告訴 Agent 長期應該遵守什麼，例如目錄邊界、測試策略、風格約束。
Prompt：告訴 Agent 這一次具體做什麼、不能做什麼、怎麼驗收。

不要把三者混在一起。把本次任務寫進 Rule，會汙染長期上下文；把長期規範每次手打進 prompt，會浪費上下文；索引沒完成時讓 Agent 改程式碼，會讓它基於不完整事實行動。

2. Indexing：先確認專案可見

Cursor 開啟專案後會索引程式碼庫。Help Center 說明可以看 indexing 狀態，必要時 reindex；.cursorignore 可用於額外排除 indexing 和 AI context。

常見排障順序：

看 status bar 的 indexing 狀態。
如果新增大量檔案或重新命名目錄，手動 Reindex。
檢查 .cursorignore 是否誤排除了原始碼。
檢查 generated files、build artifacts、binary assets 是否應該排除。
確認 .gitignore 和 .cursorignore 的邊界。

.cursorignore 適合排除：

generated files。
build output。
large binaries。
secrets and credentials。
third-party vendored code。

但要注意：.cursorignore 不是安全邊界。terminal commands 和 MCP tools 可能在 Cursor 檔案上下文之外訪問檔案。真正的金鑰安全要靠檔案許可權、憑據系統和最小授權。

3. Rules：長期約束，不是資料儲存庫

Cursor 官方 Rules 文件說明，Rules 是 persistent reusable context，會在匹配時放進 model context。它們適合儲存反覆生效的專案規則。

四類規則：

Project Rules：放在 .cursor/rules，進入 Git，適合團隊共享。
User Rules：個人全域性偏好，不適合承載團隊規範。
Team Rules：Team / Enterprise dashboard 管理，用於組織統一要求。
AGENTS.md：放在專案根目錄的 markdown 檔案，Cursor 會在每次 Agent 啟動時自動讀——適合寫簡單跨工具通用規則（也被 Codex / Claude Code 等其他 Agent 工具識別為通用入口）。

Project Rules 還可以巢狀——把 .cursor/rules/ 放在子目錄（如 src/api/.cursor/rules/），裡面的規則只在該目錄及其下的檔案被引用時生效。monorepo 或多模組專案可以用這種方式，讓"前端規則只對前端目錄生效、API 規則只對 API 生效"，避免一份規則被無關任務拖出來。

真實專案優先 Project Rules，因為它可 review、可追溯、隨程式碼演進。

4. Rule 觸發方式

官方文件裡的 Rule 行為可以這樣理解：

Always Apply：每個 chat session 都加入，適合極少數硬規則——例如"禁止改 schema 檔案"這種隨時都要遵守的邊界。
Apply Intelligently：Agent 根據 description 判斷是否相關——description 欄位寫清"什麼場景適用"，讓 Agent 自己挑。
Apply to Specific Files：匹配 globs（檔案路徑模式，如 src/components/**/*.tsx）時觸發——鎖路徑用，最適合按目錄寫的領域規則。
Apply Manually：只在 chat 裡 @rule-name 主動呼叫——罕見場景或僅在特定任務下使用的規則放這一類。

Rules 可以用 .md 或 .mdc（Markdown + frontmatter 擴充套件，比 .md 多 description、globs、alwaysApply 欄位）。如果要寫這些欄位，.mdc 更清晰。

一個小而有效的 project rule 示例：

---
description: Applies to React component changes under src/components.
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

When changing shared React components:
- Preserve existing props unless explicitly requested.
- Add or update focused tests when behavior changes.
- Do not introduce app-specific copy into shared components.