Cloud Agent Best Practices

Cloud Agent 的可靠性主要取決於環境、上下文、工具和驗收方式，而不是 prompt 寫得多長。

閱讀目標：讀完本章，你應該能把 Cloud Agent 從“能用”提升到“可重複上線使用”，並知道失敗時優先補哪裡。

1. 官方建議的核心

Cursor 官方 Best Practices 可以壓成一句話：把 Cloud Agent 當成低上下文但很能幹的遠端開發者，提前給它環境、資訊和工具。

維度	不可靠做法	穩定做法
環境	讓 agent 自己猜依賴和啟動方式	先配置 Cloud agent setup
secrets	prompt 裡貼 key 或讓 agent 追問	dashboard Secrets tab
網路	執行後才發現出站被擋	提前配 egress allowlist
測試	專案本地都跑不起來	repo 能像人類開發者一樣本地測試
上下文	只給一句“修一下”	`agents.md`、rules、skills、明確任務 spec
工具	只靠 shell 和搜尋	MCP、自定義 CLI、專案專用工具

Cloud Agent 不是魔法 runner。人類開發者本地都難以復現的問題，agent 在 VM 裡通常也會更難。

2. 先把環境配好

先讀並落實 Cloud agent setup。最少要能完成：

clone repo。
install dependencies。
run build。
run tests。
start app。
access required external services。
read necessary secrets。

環境配置可以包含 Dockerfile、environment setup commands、start commands、secrets、network rules 和 repo-specific instructions。

如果 Cloud Agent 經常卡在安裝依賴、找不到命令、埠衝突、缺少 token，這不是“模型不行”，是環境沒準備好。

3. 檢查訪問邊界

Cloud Agent 開始前先檢查三類訪問。

類別	檢查點
Secrets	API keys、database credentials、third-party tokens 是否在 Secrets tab 中配置
Egress controls	網路限制開啟後，本地開發需要的 URL 是否都 whitelisted
Local testability	repo 是否能在不依賴不可達外部服務的情況下跑核心測試

對商業專案，建議把這些內容寫到 repo 裡的 agent instructions：哪些服務可用，哪些必須 mock，哪些命令是官方驗收路徑。

4. 用 skills 和 agents.md 給上下文

官方建議用 skills 和 agents.md 配置 agent。目標不是堆文件，而是把專案里人類開發者反覆需要知道的事結構化。

agents.md 適合寫：

monorepo 中常用 package 的啟動和測試方式。
關鍵 microservices 的除錯入口。
程式碼修改邊界。
常見失敗日誌的解釋。
PR 交付標準。
禁止觸碰的路徑和安全紅線。

skills 適合寫：

某個服務如何本地除錯。
第三方依賴如何臨時配置。
複雜測試資料如何構造。
瀏覽器驗證流程。
release、migration、benchmark 這類固定工作流。

判斷標準很簡單：如果同一條說明已經對人類新人講過三次，就應該沉澱給 agent。

5. 給 agent 合適的工具

官方也強調，agent 很多時候受限於工具訪問。MCP 和 custom tools 能讓它接觸和人類開發者一樣的系統。

可以補的工具：

工具型別	用途
MCP	資料庫、issue tracker、日誌系統、內部 API、文件系統
Custom CLI	啟動服務、查日誌、重放測試、生成 fixture、跑診斷
Scripted checks	format、lint、unit、e2e、security scan、content audit
Browser tools	開啟應用、截圖、驗證 UI flow

但工具不是越多越好。每個工具都應該有用途、許可權邊界和驗收訊號。敏感工具優先用 HTTP MCP 或受控服務端代理，減少直接把憑據暴露給 VM 的機會。

6. 把工具塑造成 agent 好用的形狀

官方提到，某些模型會忘記 package.json 自定義命令的引數，也會被噪音 build logs 分散。解決方向不是繼續寫更長 prompt，而是把工具改成更適合 agent 呼叫。

更好的工具通常具備：

一個命令完成一個明確動作。
預設引數安全。
輸出短、穩定、可 grep。
失敗時給下一步建議。
支援 --json 或機器可讀摘要。
把噪音日誌摺疊到檔案，終端只輸出結論。
能在 CI、Cloud Agent 和本地一致執行。

例如，與其讓 agent 記住一串 workspace 命令，不如提供 repo-dev start api、repo-dev test checkout、repo-dev diagnose auth 這類穩定入口。

7. 任務 spec 模板

每次交給 Cloud Agent 的任務，至少要包含：

欄位	內容
Goal	要達成的使用者可見結果
Scope	允許修改的檔案、模組、頁面或服務
Non-goals	明確不做的事
Context	相關 issue、日誌、截圖、失敗命令、業務規則
Commands	必跑的 build / test / audit / screenshot 命令
Secrets	需要哪些 secrets，以及不能輸出什麼
Evidence	期待的 diff、日誌、artifact、PR comment 或截圖
Rollback	出錯時如何撤回或關閉 automation

任務越像正式工單，Cloud Agent 越容易交付可 review 的結果。

8. 商業級驗收

Cloud Agent 輸出後，不要只看 summary。按證據驗收：

PR diff 是否只觸碰 scope 內檔案。
build / lint / tests 是否真實執行。
UI 改動是否有 screenshot 或 video artifact。
MCP / external tool 呼叫是否符合許可權預期。
secrets、客戶資料、後臺截圖是否沒有進入 artifacts。
CI failure autofix 是否沒有超過團隊允許邊界。
失敗時是否能從 logs 看清下一步。

如果一次任務需要人工大量補問，先修 instructions、環境和工具，再繼續放更多工。

9. 迭代順序

當 Cloud Agent 質量不穩定，按這個順序修：

環境：依賴、start、test、secrets、網路。
上下文：agents.md、rules、skills、示例。
工具：MCP、自定義 CLI、短輸出診斷命令。
任務 spec：目標、scope、驗收、禁止項。
自動化：只有前四項穩定後再加 schedule、webhook 或 PR trigger。

不要先做 Automations。自動化會放大不穩定性。

本章自檢

repo 是否能被 Cloud Agent 像人類開發者一樣安裝、啟動、測試？
secrets 和 egress 是否在 dashboard 和網路規則中準備好？
agents.md 或 skills 是否覆蓋常見服務和測試路徑？
是否給 agent 提供了短、穩、可驗證的工具？
每個任務是否有明確 evidence，而不是隻要自然語言總結？

透過標準：你能連續執行 3 個 Cloud Agent 任務，且每次都有可復現命令、清晰 diff、必要 artifacts 和低返工率。

官方來源

Cursor Cloud Agent Best Practices —— 官方環境、secrets、egress、skills、agents.md、MCP 和 custom tools 建議。
Cursor Cloud Agent Setup —— 官方環境配置。
Cursor Skills —— 官方 skills 背景。
Cursor MCP —— 官方 MCP 背景。
Cursor Cloud Agent Security —— 官方網路和安全邊界。