Subagents
基於 Cursor 官方 Subagents 文件解釋上下文隔離、並行執行、內建 subagents、自定義檔案、欄位和呼叫方式。
Subagents（子代理）是 Cursor Agent 可以委派任務的專門 AI assistants。官方文件說明，每個 subagent 都有自己的 context window（上下文視窗，模型一次能看到的總資訊量），處理特定型別工作，並把結果返回給 parent agent（父代理，發起委派的主 agent）。
閱讀目標：讀完本章，你應該能判斷什麼時候用 subagent，什麼時候改用 skill，並能寫出一個 project-level verifier subagent。
1. 為什麼需要 Subagents
官方給出四個核心價值。
| 價值 | 說明 |
|---|---|
| Context isolation | 長研究、探索和日誌不會佔滿主 conversation |
| Parallel execution | 多個 subagents 可以同時跑不同工作流 |
| Specialized expertise | 可以配置 prompts、tool access、models |
| Reusability | 自定義 subagents 可以跨專案複用 |
flowchart TD
Parent["Parent Agent"] --> TaskA["Explore codebase"]
Parent --> TaskB["Run commands"]
Parent --> TaskC["Verify result"]
TaskA --> SubA["Explore subagent context"]
TaskB --> SubB["Bash subagent context"]
TaskC --> SubC["Verifier custom subagent"]
SubA --> ResultA["Summary"]
SubB --> ResultB["Command findings"]
SubC --> ResultC["Pass / incomplete / issues"]
ResultA --> Parent
ResultB --> Parent
ResultC --> ParentSubagent 從 clean context 開始。它不會自動繼承 prior conversation history，parent agent 需要在 prompt 裡放入必要上下文。
2. Foreground 和 Background
官方把 subagent 執行模式分成兩類。
| Mode | 行為 | 適合 |
|---|---|---|
| Foreground | parent 等 subagent 完成，立即拿結果 | 後一步依賴前一步輸出 |
| Background | parent 立即繼續，subagent 獨立工作 | 長任務、並行工作流 |
如果下一步實現必須等審計結果，使用 foreground。只是讓另一個 agent 同時做文件、搜尋或驗證，用 background。
3. 內建 Subagents
官方內建三個 subagents，Agent 會在合適時自動使用，不需要你配置。
| Subagent | 用途 | 為什麼隔離 |
|---|---|---|
| Explore | 搜尋和分析 codebase | 搜尋會產生大量中間輸出 |
| Bash | 執行一系列 shell commands | command output 通常很囉嗦 |
| Browser | 透過 MCP tools 控制瀏覽器 | DOM snapshot 和 screenshot 噪聲大 |
這些內建 subagents 的目標是把噪聲留在子上下文，只把最終 finding 返回給主對話。Explore subagent 預設使用更快模型，可以並行跑多次搜尋。
4. Subagents 還是 Skills
官方給出的判斷：
| 用 Subagents | 用 Skills |
|---|---|
| 需要單獨 context window | 任務是單一用途 |
| 多個 workstreams 並行 | 快速、可重複 action |
| 需要多步驟專業角色 | 一次完成 |
| 需要獨立驗證 | 不需要分離上下文 |
比如“生成 changelog”更像 skill；“用獨立上下文驗證一個複雜實現是否真的完成”更像 subagent。
5. 檔案位置和優先順序
自定義 subagent 是 Markdown 檔案，放在專案或使用者目錄。
| 型別 | 位置 | 作用域 |
|---|---|---|
| Project | .cursor/agents/ | 當前專案 |
| Project | .claude/agents/ | 當前專案，Claude compatibility |
| Project | .codex/agents/ | 當前專案，Codex compatibility |
| User | ~/.cursor/agents/ | 當前使用者所有專案 |
| User | ~/.claude/agents/ | 當前使用者所有專案，Claude compatibility |
| User | ~/.codex/agents/ | 當前使用者所有專案，Codex compatibility |
優先順序：
- Project subagents 優先於 user subagents。
- 同名衝突時，
.cursor/優先於.claude/或.codex/。
6. 檔案格式
每個 subagent 是一個帶 YAML frontmatter 的 Markdown 檔案。
---
name: verifier
description: Validates completed work. Use after tasks are marked done to confirm implementations are functional.
model: inherit
readonly: true
---
You are a skeptical validator.
When invoked:
1. Identify what was claimed to be completed.
2. Check that the implementation exists and is functional.
3. Run relevant tests or verification steps.
4. Report what passed, what is incomplete, and what still needs work.支援欄位：
| Field | Required | Default | 用途 |
|---|---|---|---|
name | No | filename 派生 | display name 和 identifier，建議 lowercase hyphen |
description | No | none | Agent 讀取它來判斷是否委派 |
model | No | inherit | 使用 parent model 或指定模型 ID |
readonly | No | false | 限制寫許可權，不允許 file edits 和 state-changing shell commands |
is_background | No | false | 是否後臺執行，不阻塞 parent |
model 可以是 inherit，也可以是特定 model ID。官方提醒：team admin restriction、Max Mode requirement、plan limitation 都可能讓 Cursor fallback 到相容模型。
7. 呼叫方式
Agent 可以自動委派，也可以顯式呼叫。
自動委派取決於：
- task complexity and scope。
- project 中 custom subagent descriptions。
- 當前上下文和可用工具。
顯式呼叫可以用 /name：
/verifier confirm the auth flow is complete
/debugger investigate this error
/security-auditor review the payment module也可以自然語言呼叫：
Use the verifier subagent to confirm the auth flow is complete
Run the security-auditor subagent on the payment module8. 恢復和常見模式
每次 subagent execution 會返回 agent ID。你可以用這個 ID 恢復 subagent conversation：
Resume agent abc123 and analyze the remaining test failures常見模式：
- Verification agent：獨立驗證 claimed work 是否真的完成。
- Orchestrator pattern：Planner、Implementer、Verifier 依次交接。
- Debugger：捕獲 error、stack trace、復現步驟，定位 root cause。
深讀：為什麼 verifier 應該 readonly 起步
Verifier 的職責是獨立驗證，而不是繼續實現。讓 verifier 預設只讀，可以避免它把“發現問題”和“順手修改”混在一起。
如果驗證結論需要修復，回到 parent agent 或單獨建立 implementer 任務。這樣責任邊界更清楚：誰驗證，誰實現，誰最終合併。
本章自檢
完成本章後，用這 3 個問題檢查自己是否真正理解：
- Subagent 為什麼能節省主 conversation 的 context？
- 什麼任務應該用 skill，而不是 subagent？
- Project subagent 和 user subagent 的優先順序是什麼？
透過標準：你能寫出一個 .cursor/agents/verifier.md，並解釋它的 description、model、readonly 和呼叫方式。
官方來源
- Cursor Subagents —— 官方說明上下文隔離、並行、內建 subagents、自定義檔案位置、欄位、呼叫和恢復。
- Cursor Skills —— 官方說明何時用 skill 而不是 subagent。
- Cursor Models & Pricing —— 官方模型 ID 和可用性以當前頁面為準。