使用 Agent 撰寫程式碼的最佳實務
程式開發代理正在改變軟體的開發方式。
現在的模型可以執行好幾個小時，完成雄心勃勃的多檔案重構，並且持續反覆直到測試通過。不過，要真正發揮代理的最大效益，需要了解它們的運作原理，並建立新的使用模式。
本指南將介紹使用 Cursor Agent 的各種技巧。無論你是剛接觸代理式程式開發，還是想了解我們團隊實際如何使用 Cursor，我們都會說明使用 Agent 撰寫程式碼的最佳實務。
理解 agent harness
一個 agent harness 是由三個元件構成：
- Instructions：引導代理行為的 system prompt（系統提示）與規則
- Tools：檔案編輯、程式碼庫搜尋、終端機指令執行等工具
- User messages：你用來指派工作與追問的提示與訊息
Cursor 的 agent harness 會為我們支援的每個模型協調這些元件。我們會根據內部評測與外部基準測試，為每個前沿模型專門調整 instructions與調整 tools。
harness 很重要，因為不同模型對相同提示的反應各不相同。一個大量訓練於以 shell 為主工作流程的模型，可能會偏好使用 grep 而不是專門的搜尋工具；另一個則可能需要明確指示，在編輯後呼叫程式碼靜態檢查（linter）工具。Cursor 的 agent 會替你處理這些細節，因此隨著新模型發佈，你可以專心在軟體開發本身。
從規劃開始
你能做的最關鍵改變，就是在寫程式前先進行規劃。
芝加哥大學的一項研究 發現，有經驗的開發者更傾向在撰寫程式碼前先做規劃。規劃能迫使你更清楚地思考自己要開發什麼，並為代理提供明確的目標去實現。
使用 Plan 模式
在 Agent 輸入框中按下 Shift+Tab 以切換 Plan 模式。Agent 不會立刻開始寫程式碼，而是會：
- 分析你的程式碼庫以找出相關檔案
- 針對你的需求提出釐清問題
- 建立包含檔案路徑與程式碼參照的詳細實作計畫
- 等待你核准之後才開始實作
計畫會以 Markdown 檔案開啟，你可以直接編輯，刪除不必要的步驟、調整做法，或補上 Agent 遺漏的脈絡。
提示： 按一下「Save to workspace」將計畫儲存到
.cursor/plans/。這可以為你的團隊建立文件，讓中斷的工作容易繼續，也能為未來在同一功能上工作的 Agent 提供脈絡。
不是每個任務都需要詳細計畫。對於快速修改，或是你已經做過很多次的任務，直接交給 Agent 處理就可以了。
從計畫重新開始
有時候代理產生的結果會和你想要的不一樣。與其試著透過後續提示來修正，不如回到原本的計畫。
還原變更，將計畫調整得更具體、更明確地描述你的需求，然後再執行一次。這通常比邊跑邊修正正在執行的代理來得更快，且能產生更乾淨的結果。
管理上下文
隨著你越來越習慣代理產生程式碼，你的工作就會變成為每個代理提供完成其任務所需的上下文。
讓 Agent 自動尋找脈絡
你不需要在提示中手動標記每個檔案。
Cursor 的 Agent 具有強大的搜尋工具，並能在需要時擷取所需的脈絡資訊。當你詢問「authentication flow（驗證流程）」時，Agent 會透過 grep 和語意搜尋找出相關檔案，即使你的提示中沒有出現完全相同的字詞。
保持簡單：如果你知道確切的檔案，就加上標記；如果不知道，就交給 Agent 來找。包含不相關的檔案可能會讓 Agent 誤判什麼才是重要的。
Cursor 的 Agent 也有一些實用工具，例如 @Branch，能讓你提供自己目前正在處理內容的脈絡。像是「Review the changes on this branch」或「What am I working on?」這樣的指令，就成為讓 Agent 了解你目前工作任務的自然方式。
什麼時候該開始新的對話
一個很常見的問題是：我應該繼續這個對話，還是重新開啟一個新的對話？
在以下情況下請開始新的對話：
- 你要切換到不同的任務或功能
- 代理似乎感到困惑，或一直重複犯同樣的錯誤
- 你已經完成一個具邏輯性的工作階段
在以下情況下請繼續目前的對話：
- 你正在對同一個功能持續迭代
- 代理需要引用先前對話中的脈絡
- 你正在除錯它剛剛產生或建構的內容
過長的對話可能會讓代理失去焦點。經過多輪互動與多次摘要後，脈絡中會累積雜訊，代理可能因此分心或轉去處理不相關的任務。如果你注意到代理的效果開始下降，就該開始一個新的對話。
參考過去的成果
當你開始一個新的對話時，使用 @Past Chats 來參考先前的工作，而不是把整個對話複製貼上。Agent 可以選擇性地從對話歷史中讀取，只擷取它所需要的脈絡。
這比重複整段對話要來得更有效率。
擴充代理功能
Cursor 提供兩種主要方式來自訂代理的行為：適用於每次對話的靜態上下文 Rules（規則），以及代理在適當情況下可以使用的動態能力 Skills（技能）。
Rules：為你的專案提供靜態上下文
Rules 提供持續生效的指示，影響代理如何與你的程式碼互動。你可以把它們想成永遠存在的上下文，代理在每一次對話一開始都會先看到這些內容。
在 .cursor/rules/ 中以資料夾形式建立 Rules，每個資料夾內包含一個 RULE.md 檔案：
# Commands
- `npm run build`: Build the project
- `npm run typecheck`: Run the typechecker
- `npm run test`: Run tests (prefer single test files for speed)
# Code style
- Use ES modules (import/export), not CommonJS (require)
- Destructure imports when possible: `import { foo } from 'bar'`
- See `components/Button.tsx` for canonical component structure
# Workflow
- Always typecheck after making a series of code changes
- API routes go in `app/api/` following existing patterns讓規則專注在關鍵事項上：要執行的指令、要遵循的模式，以及程式碼庫中典型範例的指引。請引用檔案，而不是複製其內容；這能讓規則保持精簡，並在程式碼變更時避免規則變得過時。
在規則中應避免的做法：
- 複製整份風格指南（請改用 linter）
- 紀錄所有可能的指令（代理已經熟悉常見工具）
- 為極少發生的邊界/例外情況新增指令
Tip: 先從簡單開始。只有在你注意到代理一再犯下相同錯誤時，才新增規則。在你理解自己的模式之前，不要過度優化。
請將規則提交到 Git，讓整個團隊都能受益。當你看到代理犯錯時，就更新對應的規則。你甚至可以在 GitHub issue 或 PR 中標記 @cursor，讓代理替你更新規則。
Skills：動態能力與工作流程
Agent Skills 擴充了代理能執行的功能與工作流程。Skills 將領域特定知識、工作流程與指令稿封裝成模組，讓代理在相關時加以呼叫。
Skills 定義在 SKILL.md 檔案中，內容可以包含：
- Custom commands：可重複使用的工作流程，可在代理輸入中用
/觸發 - Hooks：在代理執行動作前後觸發的指令稿
- Domain knowledge：代理可視需要載入、針對特定任務的操作指示
與一律會被納入的 Rules 不同，Skills 會在代理判斷有相關性時才動態載入。這讓你的上下文視窗保持精簡，同時仍然讓代理能存取專門能力。
範例：長時間執行的代理迴圈
一種強大的模式是使用 Skills 來建立可長時間執行的代理，持續迭代直到達成目標。以下說明如何建立一個 hook，讓代理持續工作直到所有測試都通過。
首先，在 .cursor/hooks.json 中設定 hook：
{
"version": 1,
"hooks": {
"stop": [{ "command": "bun run .cursor/hooks/grind.ts" }]
}
}hook 腳本（.cursor/hooks/grind.ts）會從 stdin 讀取上下文資訊，並回傳一個 followup_message 以繼續迴圈：
import { readFileSync, existsSync } from "fs";
interface StopHookInput {
conversation_id: string;
status: "completed" | "aborted" | "error";
loop_count: number;
}
const input: StopHookInput = await Bun.stdin.json();
const MAX_ITERATIONS = 5;
if (input.status !== "completed" || input.loop_count >= MAX_ITERATIONS) {
console.log(JSON.stringify({}));
process.exit(0);
}
const scratchpad = existsSync(".cursor/scratchpad.md")
? readFileSync(".cursor/scratchpad.md", "utf-8")
: "";
if (scratchpad.includes("DONE")) {
console.log(JSON.stringify({}));
} else {
console.log(JSON.stringify({
followup_message: `[迭代 ${input.loop_count + 1}/${MAX_ITERATIONS}] 繼續工作。完成後請將 DONE 更新至 .cursor/scratchpad.md。`
}));
}這種模式適用於：
- 持續執行（並修正）直到所有測試都通過
- 持續迭代 UI，直到符合設計稿
- 任何以目標為導向且成功可被驗證的任務
提示： 具備 hooks 的 Skills 可以與安全工具、機密管理工具以及可觀測性平台進行整合。請參閱 hooks 文件 以瞭解合作夥伴整合方式。
Agent Skills 目前僅在 Nightly 發行通道中可用。請開啟 Cursor 設定，選擇 Beta，將更新通道設為 Nightly，然後重新啟動。
除了寫程式之外，你還可以將代理連接到你每天使用的其他工具。MCP（Model Context Protocol） 讓代理可以讀取 Slack 訊息、調查 Datadog 日誌、除錯來自 Sentry 的錯誤、查詢資料庫等等。
包含圖片
Agent 可以直接從你的提示中處理圖片。你可以貼上螢幕截圖、拖曳設計檔，或引用圖片路徑。
從設計到程式碼
貼上設計稿，然後請 Agent 幫忙實作。Agent 會讀取圖片，並對齊版面配置、色彩與間距。你也可以使用 Figma MCP server。
視覺除錯
擷取錯誤狀態或異常 UI 的畫面，並請代理進行調查。這通常比用文字描述問題更快。
代理也可以控制瀏覽器自行擷取畫面、測試應用程式，並驗證介面上的變更。詳情請參閱瀏覽器文件。
常見工作流程
以下是一些在各種任務類型中都十分實用的代理模式。
測試驅動開發
代理可以自動撰寫程式碼、執行測試並反覆迭代：
- 請代理撰寫測試，依照預期的輸入／輸出配對來設計。請明確說明你正在做 TDD，這樣可以避免它為尚不存在的功能建立模擬實作。
- 請代理執行測試並確認測試會失敗。 明確說明在這個階段不要撰寫任何實作程式碼。
- 在你對測試滿意之後，提交（commit）這些測試。
- 請代理撰寫能通過測試的程式碼，並指示它不要修改測試。告訴它持續迭代，直到所有測試都通過為止。
- 在你對變更滿意後，提交（commit）實作。
當代理有明確的目標可以反覆對照時，表現會最佳。測試讓代理可以進行變更、評估結果，並逐步改進，直到成功為止。
瞭解程式碼庫
在接手新的程式碼庫時，可以使用 Agent 來學習與探索。就像向隊友請教一樣提出問題：
- 「在這個專案中，logging 機制是如何運作的？」
- 「我要如何新增一個新的 API endpoint？」
- 「
CustomerOnboardingFlow處理了哪些邊界／極端情況？」 - 「為什麼我們在第 1738 行呼叫
setUser()，而不是createUser()？」
Agent 會同時使用 grep 與語義搜尋來檢索整個程式碼庫並找出答案。這是快速上手陌生程式碼最快的方法之一。
Git 工作流程
Agent 能搜尋 Git 歷史紀錄、解決合併衝突，並自動化你的 Git 工作流程。
例如，一個會執行 commit、push，並開啟 PR（拉取請求）的 /pr 指令：
為當前變更建立拉取請求。
1. 使用 `git diff` 查看已暫存和未暫存的變更
2. 根據變更內容撰寫清晰的提交訊息
3. 提交並推送到當前分支
4. 使用 `gh pr create` 開啟 PR（拉取請求），並填寫 title 和描述
5. 完成後返回 PR URL這類指令非常適合一天之內會多次執行的工作流程。將它們儲存為 Markdown 檔案放在 .cursor/commands/ 中，並提交到 Git，如此整個團隊都能使用。
以下是我們使用的其他指令範例：
/fix-issue [number]：使用gh issue view取得 issue 詳細資訊，尋找相關程式碼、實作修復，並建立一個 PR（拉取請求）/review：執行程式碼檢查工具（linters）、檢查常見問題，並總結可能需要關注的地方/update-deps：檢查已過時的相依套件，逐一更新，並在每次更新後執行測試
Agent 可以自動使用這些指令，因此你只要用一次 / 呼叫就能委派整個多步驟的工作流程。
程式碼審查
AI 產生的程式碼需要審查，Cursor 提供了多種方式。
產生過程中
觀看 Agent 的工作過程。差異檢視會在變更發生時即時顯示。如果你發現 Agent 朝著錯誤方向前進，按下 Escape 鍵以中斷並重新引導。
Agent review
在 Agent 執行完後，點擊 Review → Find Issues 來啟動專門的審查。Agent 會逐行分析建議的修改並標記潛在問題。
針對所有本機變更，開啟「Source Control」分頁並執行 Agent Review，與你的主分支進行比較。
適用於 PR 的 Bugbot
將程式碼推送到版本控制系統後，即可獲得對 PR（拉取請求）的自動化審查。Bugbot 會運用進階分析，及早發現問題，並為每個 PR 提出改進建議。
架構圖
在進行重大變更時，可以請代理幫你產生架構圖。試著這樣對它下指令：「Create a Mermaid diagram showing the data flow for our authentication system, including OAuth providers, session management, and token refresh.」這些圖表對撰寫文件很有幫助，也能在程式碼審查之前先發現潛在的架構問題。
平行執行代理
Cursor 讓你可以輕鬆同時執行多個代理，而不會彼此干擾。我們發現，讓多個模型嘗試處理同一個問題，然後挑選最佳結果，能夠大幅提升最終輸出品質，特別是在處理較困難的任務時。
原生 worktree 支援
Cursor 會自動為並行執行的代理建立並管理 git worktrees。每個代理都在自己的 worktree 中執行，擁有獨立的檔案與變更，因此代理可以在彼此互不干擾的情況下編輯、建置與測試程式碼。
若要在 worktree 中執行代理，請從代理下拉選單中選取 worktree 選項。當代理執行完成後，按一下 Apply，即可將其變更合併回你目前的工作分支。
同時執行多個模型
一個很強大的使用方式是，讓相同的提示詞同時在多個模型上執行。從下拉選單中選取多個模型，送出你的提示詞，然後將結果並排比較。Cursor 也會建議它認為最好的解法。
這在以下情況特別有用：
- 困難的問題上，不同模型可能會採取不同的解法
- 比較不同模型系列之間的程式碼品質
- 找出某個模型可能忽略的邊界案例
當你並行執行許多代理時，請設定通知與聲音，讓你知道它們什麼時候完成。
委派給雲端代理
雲端代理非常適合那些你原本只會丟進待辦清單的工作：
- 在處理其他事情時順帶發現的 Bug 修復
- 針對最近程式碼變更的重構
- 為既有程式碼產生測試
- 文件更新
你可以依照任務在本機代理與雲端代理之間切換。你可以從 cursor.com/agents、Cursor 編輯器或手機啟動雲端代理。離開桌機時，能在網頁或手機上查看工作階段。雲端代理在遠端沙盒中執行，因此你可以闔上筆電，稍後再回來查看結果。
以下說明雲端代理在幕後如何運作：
- 描述任務以及任何相關背景
- 代理會 clone 你的 repo 並建立分支
- 它會自主執行，完成後會開啟 pull request
- 完成時你會收到通知（透過 Slack、電子郵件或網頁介面）
- 檢查變更，準備好後再合併
提示： 你可以在 Slack 中用「@Cursor」觸發代理。了解更多。
針對棘手錯誤的 Debug Mode
當一般與代理互動的方式在處理某個錯誤時遇到困難，Debug Mode 會提供一種不同的做法。
與其憑猜測嘗試修復，Debug Mode 會：
- 產生多個關於問題可能出在哪裡的假設
- 在你的程式碼中加入日誌（logging）語句
- 要求你在收集執行階段資料的同時重現錯誤
- 分析實際行為以精準找出根本原因
- 根據證據進行有針對性的修復
這最適合用在：
- 你能重現、但無法找出原因的錯誤
- 資源競爭（race condition）與時間相關問題
- 效能問題與記憶體洩漏
- 曾經可以運作、後來壞掉的回歸錯誤（regressions）
關鍵在於提供如何重現問題的詳細背景與步驟。你描述得越具體，代理所加入的監測與記錄就越有幫助。
建立你的工作流程
最能善用 Agent 的開發者通常有幾個共同特點：
他們會撰寫具體的提示詞。 Agent 在收到明確指示時，成功率會大幅提升。比較一下「add tests for auth.ts」和「Write a test case for auth.ts covering the logout edge case, using the patterns in __tests__/ and avoiding mocks.」這兩者。
他們會反覆調整設定。 從簡單開始。只有在你發現 Agent 一再犯同樣錯誤時，才新增規則。只有在你找出想要重複執行的工作流程後，才新增指令。在你真正了解自己的模式之前，不要過度優化。
他們會仔細審查。 AI（人工智慧）產生的程式碼看起來可能正確，但其實存在細微錯誤。閱讀 diff，並仔細檢查變更。Agent 運作得越快，你的審查流程就越重要。
他們會提供可驗證的目標。 Agent 不知道的問題就無法修正。使用具型別的語言、設定 linter、撰寫測試。給 Agent 明確的訊號，以判斷變更是否正確。
他們把 Agent 當成有能力的協作者。 要它先提出規劃，請它說明理由，對你不認同的做法提出質疑。
Agent 正在快速進步。雖然這些模式會隨著新模型演進，但我們希望這能幫助你從現在開始，就能更高效地與程式碼 Agent 合作。
開始使用 Cursor's agent 來試試這些技巧。