Cursor Agent 實戰手冊

按 Cursor 官方文件獨立整理。涵蓋本機 Agent、精確脈絡、Project Rules、終端機、MCP、審查、CLI、Cloud Agents、私隱及疑難排解。

Cursor 由唯讀分析、計劃、編輯、執行到審查的流程 — 每個階段使用權限最低而足夠的模式，接受修改前檢查實際差異及測試結果。

1. 按風險選擇模式

模式	用途	能力
Ask	學習、診斷、計劃	唯讀搜尋
Agent	多檔案功能及修正	搜尋、編輯、終端機及修錯
Manual	準確的小範圍編輯	只限已選檔案
Custom	可重用專業流程	自選工具及指示

陌生工作由 Ask 開始；目標、範圍、測試及禁止動作清楚後才使用 Agent。用 Ctrl+. 切換模式，Ctrl+I 開啟 Agent。

2. 準備及索引程式碼庫

開啟專案根目錄並檢查 Git 狀態。
等待程式碼庫索引完成，檢索不完整時檢查索引狀態。
用 .gitignore 及 .cursorignore 排除依賴套件、產生檔案、密鑰及私人資料。
修改前先要求唯讀專案地圖。

在 Ask 模式梳理程式碼庫：進入點、架構邊界、建置及測試指令、資料儲存、
部署檔案及高風險區域。不要修改或執行指令。

3. 用 @ 提供精確脈絡

用 @code 指定符號、@file 指定檔案、@folder 指定有限模組，並附上權威網頁或文件。精確引用可減少無關檢索。

@file:src/auth/session.ts @file:src/api/login.ts @code:refreshSession
重現介面一直載入的原因並引用準確控制流程。
不要檢查或修改帳單及客戶匯出模組。

4. 撰寫可驗收任務並先計劃

目標：登入成功必須開啟 /admin。
驗收：錯誤密碼顯示行內提示；載入狀態一定結束；重新整理保留有效工作階段；測試通過。
限制：不得重設資料庫、升級依賴套件或修改正式環境。
先列出涉及檔案、測試、風險及回復計劃，批准前不要編輯。

廣泛修改應把計劃與實作分開；Cloud Agent 亦應在詳細計劃確認後執行。

5. 用 Project Rules 固化規範

受版本控制的規則存放於 .cursor/rules MDC 檔案，可設 Always、按 glob 自動附加、由 Agent 按描述要求，或以 @ruleName 手動引用。巢狀規則可限定單一程式碼庫內不同模組；全域偏好使用 User Rules；.cursorrules 已棄用。

---
description: Authentication safety and testing
globs: ["src/auth/**", "tests/auth/**"]
alwaysApply: false
---
- 不記錄權杖或密碼。
- 保持公開工作階段架構不變。
- 執行認證單元測試及登入瀏覽器測試。
- 新增依賴套件或修改遷移前先詢問。

可用 /Generate Cursor Rules 從成熟對話產生規則，再人工精簡。

6. 控制工具、終端機及 MCP

Agent 工具包括搜尋、讀寫及刪除檔案、終端機、網頁、Rules 和 MCP。自訂模式應關閉無關工具；陌生或高風險專案關閉 Auto-run。

按已批准計劃實作，只修改列出的檔案並執行針對性測試。
刪除、安裝依賴、遷移、連網、Git 提交或專案外指令必須先詢問。
不得讀取 .env 或憑證檔案。

MCP 應核對發佈者及啟動方式，密鑰不得進入版本控制，先測試唯讀工具，外部寫入必須批准。

7. 審查修改及驗證行為

開啟 Review changes，檢查每項新增及刪除。
拒絕無關格式調整或廣泛重寫。
執行 lint、類型檢查、針對性測試及建置。
開啟實際介面，檢查成功、錯誤、載入、空白狀態及重新整理。
確認 Git 狀態沒有敏感檔案。

逐項對照驗收條件，列出準確指令、結果、修改檔案及未驗證內容。
不得只憑 HTTP 狀態或智能體摘要判斷成功，必須操作實際介面。

8. 安全使用 Cursor CLI

curl https://cursor.com/install -fsS | bash
cursor-agent
cursor-agent "解釋認證模組；不要編輯"
cursor-agent -p "審查目前修改的安全問題" --output-format text
cursor-agent ls
cursor-agent resume

自動化預設使用唯讀審查任務、明確輸出格式、受限環境及有限提示；任何寫入或發佈流程均要固定版本及審計。

9. 委派給 Cloud Agents

Cloud Agents 可從 Cursor、網頁／流動裝置或支援的整合啟動。只連接目標程式碼庫，準備雲端環境，使用獨立分支，合併前人工審查。現行版本支援可重用環境快照、本機／雲端交接，以及用 /in-cloud 啟動隔離子智能體；/babysit 可持續檢查拉取請求。

在新分支只實作已批准計劃並執行文件規定的測試。
不得合併、部署、修改程式碼庫設定或存取正式環境密鑰。
返回差異摘要、證據、剩餘風險及待審查的拉取請求。

10. 私隱及安全邊界

在設定中選擇合適的 Privacy Mode。Cursor 表示 AI 請求會經過其後端；索引時上載程式碼片段計算嵌入，明文保留方式視乎私隱設定，嵌入及經混淆的中繼資料可能保存。路徑排除屬盡力防護，高敏感程式碼庫必須先取得機構批准並核對現行政策。

密鑰不得進入提示、Rules、終端機歷史、日誌或 MCP 設定。
禁止進入 AI 脈絡的內容應關閉索引或排除。
刪除、外部寫入、提交、推送、合併及部署保留批准。
審查 Cloud Agent 的程式碼庫、分支、環境及整合權限。

11. 常見疑難

問題	檢查
遺漏相關程式碼	索引、`.cursorignore`、準確 @ 引用、工作區根目錄
規則未生效	類型、描述、glob、巢狀範圍、手動引用
終端機 Shell 錯誤	Terminal: Select Default Profile
MCP 工具缺少	服務、設定、憑證、已啟用工具及日誌
修改循環或超出範圍	停止並返回 Ask／計劃，縮小脈絡及驗收範圍
雲端無法測試	環境快照、設定腳本、密鑰、網絡及服務依賴

12. 官方資料

資料來自官方 Agent 模式、工具、Rules、脈絡、CLI、網頁及流動 Agent、私隱及更新日誌。

編輯覆核日期：2026 年 8 月 11 日。本頁為獨立手冊，使用前請核對現行模式、模型、計劃、限制、指令、安全控制及資料政策。