用 Subagents 拆分任務

📖 本篇術語速查表

英文 / 縮寫	中文	一句話解釋
Subagent	子代理	為可並行 / 多角色任務設定的專門角色。
窄任務	narrow task	給 subagent 的任務要範圍明確、互不依賴。
許可權審批	permission	每個 subagent 的寫入範圍和審批要求。

不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你把一個大任務拆成清晰分工的 subagents。

你是 Codex Subagent 拆分顧問，幫我把一個大任務拆成職責清晰、互不衝突的 subagent 分工。

【角色】
你知道什麼時候該拆 subagent、內建角色怎麼用、寫給 subagent 的任務要窄、許可權和審批怎麼定、怎麼自定義 agents。

【輸入】
- 我要拆的大任務：___
- 它能否拆成互不依賴的子任務：___
- 每部分涉及的寫入範圍：___
- 是否需要不同許可權或模型：___

【工作流程】
1. 先判斷這個任務是否真適合拆（強序列就別拆）
2. 拆成職責窄、互不衝突的 subagent
3. 給每個 subagent 的任務描述、寫入範圍、許可權
4. 定彙總標準

【輸出規範】
▌一、是否適合拆的判斷
▌二、各 subagent 的角色與窄任務
▌三、寫入範圍與許可權審批
▌四、彙總標準

【硬約束】
- 強序列、下一步依賴上一步的任務不拆
- 各 subagent 寫入範圍不衝突，否則不推薦
- 任務要窄、明確，不給寬泛職責
- 涉及寫許可權的 subagent 預設收緊 + 審批
- 不確定的機制標註需查官方文件

Subagents 用來把複雜任務拆給多個專門 agent 並行處理，再由主 agent 彙總結果。它適合高度並行的探索、審查和事實核驗，不適合小任務或強序列任務。

Subagents 不是越多越強。每個 subagent 都會消耗模型和工具資源，也會增加上下文、審批和寫入衝突成本。

目前 Codex releases 預設啟用 subagent workflows，但 Codex 只會在你明確要求時 spawn subagents。官方文件也強調：每個 subagent 都會獨立做模型和工具工作，因此會比單 agent 消耗更多 tokens。

Subagents

檢視官方 subagents 設定和使用說明。

Skills vs Subagents

區分流程複用和任務拆分。

Team production

多 agent 進入團隊流程前先明確邊界和治理。

什麼時候該拆

flowchart TD
    Task["任務來了"]
    Independent{"子問題是否獨立?"}
    Outputs{"輸出是否能彙總?"}
    Write{"是否會寫同一批檔案?"}
    Use["適合 subagents"]
    Single["保持單 agent"]

    Task --> Independent
    Independent -->|否| Single
    Independent -->|是| Outputs
    Outputs -->|否| Single
    Outputs -->|是| Write
    Write -->|會衝突| Single
    Write -->|不會| Use

適合拆：

PR 同時做安全、測試、文件和架構審查。
大型程式碼庫探索多個模組。
一個 agent 查官方文件，另一個讀程式碼。
多個只讀維度可以並行。

不適合拆：

單檔案修改。
小 bug。
強依賴同一段上下文的除錯。
多個 worker 會改同一檔案。
non-interactive 環境無法處理審批。

內建角色怎麼用

Codex 內建三類 agents：

agent	用途	推薦邊界
`explorer`	read-heavy codebase exploration	只讀查證、回答具體程式碼庫問題。
`worker`	implementation and fixes	執行明確修改，必須有檔案 ownership。
`default`	general-purpose fallback	無特定角色時兜底。

新手建議先用只讀 explorer。需要寫檔案時，只給一個 worker 明確寫入範圍。不要讓多個 worker 同時改同一批檔案。

CLI 中可以用 /agent 切換 active agent thread，檢視或繼續某個 subagent 的上下文。任務結束後，讓主 agent close completed agent threads，避免後臺執行緒長期佔用上下文和狀態。

寫給 subagent 的任務要窄

好的 subagent 任務應該包含：

它負責什麼。
它不能碰什麼。
輸入範圍。
輸出格式。
是否只讀。
是否允許呼叫外部工具。

示例：

只讀檢查 PR diff 中的許可權和資料洩露風險。
不要修改檔案。
輸出按嚴重程度排序的 findings，每條包含檔案、證據和建議。

任務越窄，主 agent 越容易彙總。

許可權和審批

Subagents 的許可權邊界不能忽略：

它們可能繼承目前 sandbox。
它們可能觸發自己的審批請求。
它們可能讀取不同上下文。
它們可能產生寫入衝突。

建議：

初期全部只讀。
寫入任務只交給一個 worker。
明確檔案 ownership。
非互動任務避免需要審批的 subagent 動作。
結束後彙總每個 subagent 做了什麼。

官方行為要記住兩點：

Subagents inherit 目前 sandbox policy。
互動式 CLI 中，inactive thread 也可能彈出 approval request；approval overlay 會顯示來源 thread。

非互動流程中，如果某個動作需要新的 approval 但無法彈出視窗，該動作會失敗並把錯誤返回給 parent workflow。因此 CI、批處理、自動化裡更適合只讀 subagents 或預先收窄許可權邊界。

自定義 agents

當內建角色不夠用時，可以新增 custom agent：

~/.codex/agents/reviewer.toml
.codex/agents/reviewer.toml

每個 standalone TOML 檔案定義一個 agent，至少包含：

name = "reviewer"
description = "PR reviewer focused on correctness, security, and missing tests."
developer_instructions = """
Review code like an owner.
Prioritize correctness, security, behavior regressions, and missing test coverage.
"""

可以額外設定 model、model_reasoning_effort、sandbox_mode、mcp_servers、skills.config 等設定。全域併發和深度放在 [agents]：

[agents]
max_threads = 6
max_depth = 1
job_max_runtime_seconds = 1800

預設 agents.max_threads 是 6，agents.max_depth 是 1。不要輕易提高 depth，遞迴拆分會快速增加成本、等待時間和不可預測性。

常見坑

為了並行而並行。
子任務沒有明確交付物。
多個 worker 改同一檔案。
子結果都是自然語言，無法彙總。
沒有說明哪個結果是事實、哪個是推斷。
忘記 token 和工具呼叫成本。
讓 subagent 繼續無限拆分。

Subagents 的價值來自清晰分工，而不是數量。

驗收標準

使用 subagents 後，應能回答：

每個 subagent 負責什麼。
哪些只讀，哪些可寫。
輸出如何進入主結論。
是否真的更快或更全面。
是否產生衝突或重複判斷。
成本是否值得。

不能回答這些問題，就回到單 agent。