---
title: "上下文、索引和 Rules"
description: "讓 Cursor 真的理解專案：索引負責事實，Rules 負責長期約束，prompt 負責本次目標。"
verifiedAt: "2026-05-09"
---

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

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

## 1. 三層上下文模型

```mermaid
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。

常見排障順序：

1. 看 status bar 的 indexing 狀態。
2. 如果新增大量檔案或重新命名目錄，手動 Reindex。
3. 檢查 `.cursorignore` 是否誤排除了原始碼。
4. 檢查 generated files、build artifacts、binary assets 是否應該排除。
5. 確認 `.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 示例：

```text
---
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.
```

這條 rule 短、可觸發、和檔案範圍繫結。比把整份前端規範複製進去更有效。

## 5. AGENTS.md、CLAUDE.md 和 Project Rules 的邊界

官方 Help Center 說明 Cursor 會讀取專案根目錄的 `AGENTS.md`，也會像讀取 `AGENTS.md` 一樣讀取 `CLAUDE.md`。

建議分工：

- `AGENTS.md`：跨工具通用的專案入口、基本工作規則。
- `.cursor/rules/`：Cursor 專用、可條件觸發的詳細規則。
- `CLAUDE.md`：相容 Claude Code 的專案導航和規則。
- User Rules：個人偏好，不寫團隊要求。

如果這些檔案內容衝突，優先清理衝突，而不是繼續疊加。規則越多，Agent 越可能被互相矛盾的指令拖偏。

## 6. Rules 寫作標準

官方最佳實踐強調 focused、actionable、scoped。

應該做：

- 保持 rule 短，官方建議低於 500 行。
- 一個 rule 只解決一個主題。
- 用 `description` 或 `globs` 控制觸發。
- 給具體例子。
- 引用 canonical 檔案，不復制全文。
- 當 Agent 反覆犯同一類錯誤時再新增 rule。

不要做：

- 把整份 style guide 塞進 Always Apply。
- 寫“程式碼要優雅、要高質量”這種不可執行要求。
- 把少見 edge case 寫成長期規則。
- 在 Team Rules、Project Rules、AGENTS.md 裡重複同一句話。

## 7. 上下文驗收清單

開始重要任務前，先確認：

- Indexing 已完成。
- `.cursorignore` 沒排除關鍵原始碼。
- Project Rules 和 Team Rules 沒衝突。
- `AGENTS.md` / `CLAUDE.md` 不和 `.cursor/rules` 打架。
- 本次 prompt 寫清目標、範圍、禁止動作和驗證命令。
- 任務中需要的檔案能被 Cursor 找到。
- 敏感檔案沒有依賴 `.cursorignore` 作為唯一保護。

如果 Agent 一直誤解專案，先查這張清單，再考慮換模型。

## 官方來源

- [Cursor Rules](https://cursor.com/docs/rules.md)：官方 Rules 型別、frontmatter、globs、建立方式和最佳實踐。
- [Cursor Rules Help](https://cursor.com/help/customization/rules.md)：Help Center Rules 入門說明。
- [Cursor Context Help](https://cursor.com/help/customization/context.md)：Help Center 上下文說明。
- [Cursor Indexing Help](https://cursor.com/help/customization/indexing.md)：索引狀態、Reindex 和專案可見性說明。
- [Cursor Ignore Files Help](https://cursor.com/help/customization/ignore-files.md)：`.cursorignore` 行為和邊界。

## 接下來去哪

<Cards>
  <Card title="上一篇" description="先把 Ask、Agent、Plan、Debug 和 Tab 分清。" href="/zh-Hant/docs/cursor/understanding/04-agent-plan-ask-debug-tab" />
  <Card title="下一篇" description="繼續理解 MCP、Browser、Terminal 和工具許可權。" href="/zh-Hant/docs/cursor/understanding/06-mcp-tools-browser-terminal" />
  <Card title="官方 Rules" description="檢視官方重組頁裡的 Rules frontmatter 和觸發邏輯。" href="/zh-Hant/docs/cursor/official/02-context-customization/20-rules" />
</Cards>
