要用 Cursor 完成小型程式設計任務，先界定一個可觀察的行為，限制它可修改的檔案，寫明測試指令，要求它先提交唯讀計劃，然後只批准最小而有用的修改。審查產生的 diff 時，要當作另一位開發人員的程式碼看待；執行範圍最窄的測試，並用 Git 記錄實際改了甚麼。獲准時，Agent 可以檢查、編輯和執行工具，但它流暢的解釋並不能證明程式碼正確。［1］［2］

本教學把這套流程應用在一個刻意簡單的例子：為純 JavaScript 工具函數 parseRetryCount 加入整數範圍驗證，並為新的邊界行為補上單元測試。它不涉及網絡請求、憑證、依賴更新、產生的檔案或大規模重構。數據和審批界線可先參閱較全面的如何使用 AI；如果工作超出一個可審查的行為，請改用另一篇如何用 AI 協助程式設計。

關鍵要點

小任務只有一個行為、一組很窄的檔案，以及一個可執行的驗收檢查。

把目標、非目標、容許檔案、預期個案和指令寫進任務卡。

第一輪只讀不寫，先核對計劃才開始編輯；Cursor 為此提供 Plan Mode。［4］

審查 diff 和終端機指令時，不依賴 Agent 的總結。

先執行最相關的最小測試，再考慮較大範圍的項目關卡。

把 Cursor checkpoint 視為方便的還原點，而不是 Git 紀錄的替代品。

1. 甚麼情況適合用 Cursor 完成小型程式設計任務？

「小」看的是不確定性和影響範圍，而不是提示字數。適合交給 Agent 的任務，只改變你能檢查的程式碼中的一個行為，涉及的檔案不多，最後有一個確定性的檢查。「拒絕 0–10 以外的重試次數」是小任務；「改善我們的重試系統」不是，因為它可能牽涉解析、API 契約、持久化儲存、介面文案、遙測和相容性。

開啟 Agent 模式前，先問四個問題：

能否用一句話描述這個行為，而不需要「然後再」？
能否說出實作檔案和測試檔案，或透過唯讀搜尋找出它們？
能否列出正常、邊界和無效個案？
有沒有一個安全的指令，能在不改變外部狀態的情況下證明這個窄行為？

如果任務需要機密、生產環境權限、數據庫結構遷移、不熟悉的產生程式碼、新依賴、破壞性指令、跨服務契約變更，或一個尚未有審查人拍板的設計決定，就停下來拆分任務。這些並非 Agent 做不到，只是需要不同的計劃和審批級別。

例子假設程式庫已有 src/parseRetryCount.js 和 test/parseRetryCount.test.js。預期契約是：接受 0 至 10 的整數，或以十進制表示的整數字串，並傳回該整數；解析出的整數超出範圍時拋出 RangeError。格式錯誤輸入的現有行為維持不變。最後這一句可防止 Agent「好心」重寫全部解析語義。

2. 提示之前先寫 Cursor 任務卡

任務卡把含糊的對話變成可審查的變更要求。當 Agent 提議順手清理相鄰程式碼時，它亦是一個穩定的參照。Cursor Rules 可以提供持續的項目指引，但今次任務的驗收準則仍應寫在要求之中。規則是可重用的脈絡，不能取代對今次改動的精確描述。［3］

目標
- 為 parseRetryCount 加入 0–10 範圍驗證。

非目標
- 不重構無關的解析程式碼。
- 不改匯出、呼叫方、依賴、格式化設定或 package 腳本。

容許檔案
- src/parseRetryCount.js
- test/parseRetryCount.test.js

預期行為
- 接受 0 和 10。
- -1 和 11 拋出 RangeError。
- 格式錯誤輸入的現有行為維持不變。

驗證
- 執行現有的 parseRetryCount 單元測試指令。
- 報告確切指令和結束結果。

安全
- 第一輪只檢查。計劃獲批前不編輯、不執行指令。

不要只因為某個檔案就在旁邊，就把它列為容許檔案。如果 Agent 發現必須修改另一個檔案，它應說明原因並等候。檔案清單改變屬於範圍變更，不是實作細節。

3. 要求唯讀檢查和計劃

如可行，先使用提問或計劃類互動，或明確禁止編輯和執行指令。要求 Cursor 找出函數、它的匯出、直接呼叫方、現有測試慣例，以及範圍最窄的測試指令。Cursor 的 Agent 文件描述了一個能搜尋程式庫和使用工具的環境；正因具備這些能力，權限界線更形重要。［1］［2］Cursor 現行的 Plan Mode 文件，描述了在編碼前研究程式庫並產生實作計劃的規劃環節。［4］

使用以下提示：

以唯讀模式檢查任務卡和程式庫。

傳回：
1. parseRetryCount 目前的行為，附檔案和行號參照；
2. 界定格式錯誤輸入行為的現有測試；
3. 逐個檔案列出的最小改動方案；
4. 確切的最窄測試指令；
5. 假設、風險，以及容許檔案清單不足夠的任何理由。

暫時不要編輯檔案、安裝套件、改變 Git 狀態或執行指令。

把回覆與程式庫對照。親自開啟被參照的檔案。確認建議的測試指令確實存在於項目設定中，並且 Agent 沒有把名稱相似的輔助函數混淆。如果計劃包括「順道清理解析器」，就刪去這一步。如果它找不出格式錯誤輸入的現有語義，就要求它保留這些語義，並在改變行為前先提出刻畫現況的測試。

4. 只授權最小修改

計劃正確後，只授權修改這兩個檔案並執行獲批的測試。有用的指示會寫明可以做甚麼，以及甚麼情況需要再次暫停：

只在兩個容許檔案中實作已批准的範圍檢查和測試。
保持公開匯出和格式錯誤輸入的現有行為不變。
不要重新格式化無關的程式碼行，也不要引入依賴。
執行任何指令前先展示 diff。修改其他檔案或執行其他指令前先詢問。

實作可能是在現有解析之後加入一段檢查：

if (value < 0 || value > 10) {
  throw new RangeError("retry count must be between 0 and 10");
}

這段程式碼只作示意，並非適用於所有程式庫的修補。真實函數可能使用不同的變數、錯誤慣例或類型政策。除非任務卡明確要求改變，否則 Agent 應依循本地現有模式。

拒絕以下自動指令：具破壞性的、沒有任務理由卻要求提升權限的、存取機密的、連接生產系統的、意外修改鎖定檔的、安裝套件的、改寫 Git 紀錄的，或對無關檔案執行大範圍格式化的。指令效果不清楚時亦應暫停。「應該是安全的」並不是權限模型。

5. 除了總結，diff 裏還要檢查甚麼？

Agent 的總結只是導航輔助，diff 才是審查對象。逐行閱讀每處改動，並從四方面提問。

審查範疇	問題
行為	0 和 10 是否被接受？-1 和 11 是否被拒絕？格式錯誤輸入是否維持不變？
失敗路徑	錯誤類型是否一致？錯誤訊息是否只在測試或呼叫方需要之處保持穩定？
測試	測試是否涵蓋上下邊界及剛好越界的數值？測試會否不經新分支也能通過？
範圍	是否只改了容許檔案？格式、匯出、呼叫方、快照或設定有否意外變動？

留意類型轉換帶來的意外。JavaScript 的比較可能把字串轉成數字，所以若範圍驗證放在刻意解析之前，可能會意外接受舊函數拒絕的值。留意會誤拒 0 的寬鬆真值判斷。檢查 NaN、小數、空白和帶正負號的字串是否已有既定行為。任務卡要求保留這些決定，而不是重新設計。

依賴、權限、機密和危險指令，可用 AI 生成程式碼審查清單核對。如果 diff 超出你有把握審查的範圍，即使程式碼看似合理，也應視為停止條件。

6. 先跑最窄的測試，再選擇較大範圍的關卡

審查 diff 後，執行獲批的單元測試。記錄確切指令、結束代碼和相關結果。不要把「測試應該會通過」或看似一片綠色的總結當作證據。如果指令安全又已獲批，可以讓 Cursor 執行，但你仍要檢查輸出。

合理的次序是：

執行 parseRetryCount 的測試檔案或具名測試；
通過後，執行涵蓋直接呼叫方的最小套件測試；
只有在程式庫政策或影響範圍有要求時，才執行 lint、類型檢查或完整測試套件；
格式化工具或快照更新後，再看一次 diff。

較大範圍的關卡是一項決定，不是儀式。兩行的純函數改動可能只需套件測試和標準 CI；被多處呼叫的共用工具函數，則可能需要更大的測試套件。如果無關測試失敗，先另行記錄，確認今次改動是否影響它們，才決定是否繼續修改程式碼。

想把測試設計得更紮實，可參考 AI 生成測試流程，當中講解正常、邊界、失敗和不變量個案。不要為了令測試套件轉綠，而讓 Agent 削弱現有斷言。

7. 為何持久紀錄要靠 Git，而不是 checkpoint？

測試之後，從程式庫而不只是聊天面板查看 Git 狀態和 diff。確認未追蹤檔案、產生的成品、鎖定檔和設定沒有意外改變。如果團隊要建立 commit，它應只包含已審查的範圍，並走一般的審閱程序。

Cursor checkpoint 可以協助你回到 Agent 之前的某個狀態。應把它視為編輯器本機的還原輔助，而不是版本控制：checkpoint 可能不包括你的人手修改，可能只存在於本機編輯器，也不是共用、可審查的項目紀錄。

短期試驗可以使用 checkpoint。持久的來源紀錄和協作，應使用 Git 狀態、diff、分支、commit 和遠端審閱。還原任何 checkpoint 前，先檢查會覆蓋甚麼，並保護無關的工作。

8. 任務何時算完成，何時應該停下？

只有預期行為、已審查的 diff、測試和範圍四者一致，任務才算完成。保存一份簡潔的完成紀錄：

任務：parseRetryCount 範圍驗證
已審查檔案：src/parseRetryCount.js、test/parseRetryCount.test.js
行為：接受 0–10；拒絕範圍以外的整數
保留：匯出及格式錯誤輸入的行為
測試指令：[確切指令]
結果：[結束代碼及簡要結果]
Git 範圍：[已審查的 diff 或 commit 參照]
未解決問題：[無，或明確列出]
審查人：[姓名]

如果 Agent 需要未獲批准的檔案、無法解釋某處改動、提議新增依賴、遇上互相矛盾的測試、需要憑證、要求執行破壞性指令、擴大公開契約，或產生的 diff 大到無法當作一個行為審查，就停下來重新規劃。停下來是成功的範圍控制，不是自動化失敗。

Cursor 任務提示及 diff 檢查表應包括甚麼？

根據附上的任務卡完成一項小型程式設計任務。
第一階段只讀：檢查程式碼和測試，傳回計劃、風險、對容許檔案的判斷
以及確切的驗證指令。等候批准。

批准後，只編輯列出的檔案，保留無關行為和風格。
執行指令前先展示 diff。涉及額外檔案、依賴、網絡存取、提升權限、
破壞性指令或較大範圍測試時，先詢問。

最後列出：改變了的行為、修改的檔案、確切指令及結束代碼、
餘下假設和 Git diff 範圍。絕不可把未執行的測試說成已通過。

接受之前，核對：只有一個行為；只改了容許檔案；沒有意外依賴；有正常和邊界測試；涵蓋失敗路徑；有確切的指令輸出；沒有無關格式化；清楚說明任何餘下未知項；Git diff 與任務卡一致。

常見問題

甚麼樣的程式設計任務才算小？

它只有一個可觀察的行為、一組很窄而可審查的檔案、較低的外部風險和一個確定性測試。如果它改變多個契約或需要設計決定，就拆分或重新規劃。

應使用 Ask 類模式還是 Agent 類模式？

發現問題和審查風險時，使用唯讀的提問或計劃互動。只有在計劃、檔案範圍和指令獲批後，才使用可編輯的 Agent。模式名稱可能改變，權限界線更重要。

怎樣令 Cursor 不越出檔案範圍？

列出容許檔案，並告訴它在觸碰其他檔案前停下。然後核對程式庫狀態和完整 diff。提示只是指示，Git 輸出才是證據。

何時應拒絕 Cursor 自動指令？

對於作用不明、具破壞性、需提升權限、讀取機密、面向生產環境、安裝依賴或更改 Git 紀錄的指令，以及任何超出已批准任務卡的指令，都應拒絕或暫停。

應如何審查 diff？

檢查預期行為、錯誤路徑、邊界測試、公開介面，以及每一個意外的檔案或格式變化。不要只依賴文字總結。

應執行哪些測試？

由最窄的單元測試開始，再按直接呼叫方、程式庫政策和影響範圍擴大。記錄確切指令和結果，並把無關的失敗分開記錄。

Cursor checkpoint 和 Git 一樣嗎？

不一樣。把 checkpoint 視為 Agent 改動的本機還原點。Git 提供持久、可檢查的項目紀錄和協作功能，所以 checkpoint 絕不能取代已審查的 Git diff。

來源

Sources checked 2026 年 8 月 31 日。

Cursor, “Agent overview” — https://cursor.com/docs/agent/overview
Cursor, “Agent security and run modes” — https://cursor.com/docs/agent/security/run-modes
Cursor, “Rules” — https://cursor.com/docs/rules
Cursor, “Plan Mode” — https://cursor.com/docs/agent/plan-mode

如何用 Cursor 完成小型程式設計任務：由任務卡到 Git 覆核