Appearance
GitHub Copilot Sub-Agent 編排
使用 GitHub Copilot Sub-Agent 的 Coordinator/Worker 模式進行 context 隔離的 AI 輔助開發，搭配 OpenSpec Spec-Driven 完成從需求到歸檔的完整自動化流程。
概述
GitHub Copilot 支援四種 Agent 類型，其中 Sub-Agent 是最強大但也最常被忽視的工具。Sub-Agent 在父 Agent session 內被派生為獨立子任務執行者，核心特性是 context 隔離：每個 sub-agent 擁有完全獨立的 context window，不繼承父 agent 的對話歷史，完成任務後只回傳最終摘要，所有中間資料（檔案讀取、搜尋結果、推理過程）全部丟棄。
這個特性解決了 AI 輔助開發中的關鍵瓶頸：父 agent 嘗試在一個長對話中同時進行大量研究和實作時，context window 會被大量中間資料污染，導致輸出品質下降。Sub-Agent 讓「研究」和「實作」徹底分離，使主 agent 始終保持清晰的 context。
核心內容
四種 Agent 類型對比
| 類型 | 運行位置 | 自主程度 | 核心特性 |
|---|---|---|---|
| Local Agent | VS Code 本機 | 互動式 | 標準 Agent Mode，直接編輯程式碼 |
| Background Agent | 本機（VS Code 外） | 自主（本地） | 透過 Copilot CLI 啟動，可存活 VS Code 重啟 |
| Coding Agent | GitHub Actions 雲端 | 完全自主 | Issue → PR，非同步背景執行 |
| Sub-Agent | 父 Agent session 內 | 任務範圍內自主 | 獨立 context window，context 管理的利器 |
Sub-Agent 的 Context 隔離機制
- 父 Agent 派生 sub-agent，給它一個特定任務 prompt
- Sub-agent 在完全獨立的 context window 中工作（不繼承父 agent 對話歷史）
- Sub-agent 完成任務後，只回傳最終摘要/結果給父 agent
- 所有中間資料全部丟棄
結果：父 agent 得到精簡答案，context window 不被污染。
Sub-Agent 的能力邊界
| 可以做 | 不能做 |
|---|---|
| 讀取 workspace 檔案 | 存取父 agent 的對話歷史 |
| 執行終端指令 | 在呼叫之間保持狀態 |
| 搜尋 codebase | 作為獨立 session 運行 |
| 使用 MCP 工具（繼承父 agent 配置） | 建立 PR 或 branch |
| 與其他 sub-agent 平行執行 | 直接與使用者對話 |
Coordinator/Worker 模式
Sub-Agent 最強大的用法——Coordinator 不直接實作，只做任務分配和結果綜合：
Coordinator（主 Agent）
├── spec-researcher：唯讀分析 codebase 和 OpenSpec specs → 回傳 500 字以內摘要
├── task-implementer：執行單一具體 task → 回傳修改清單與驗證結果
├── code-reviewer：程式碼品質審查（唯讀）→ 回傳 APPROVED/NEEDS_REVISION/FAILED
└── Coordinator：綜合摘要，等待使用者確認後繼續核心規則：Coordinator 絕不跳過 sub-agent 直接實作（保持 coordinator context 精簡），每個 checkpoint 暫停等待使用者確認。
與 OpenSpec 的整合
Sub-Agent + OpenSpec 形成完整的 Spec-Driven 開發流程：
| 階段 | OpenSpec 指令 | Sub-Agent 角色 |
|---|---|---|
| 探索 | /opsx:discuss | spec-researcher 做 context 研究 |
| 規劃 | /opsx:propose | spec-researcher 分析依賴和影響 |
| 實作 | /opsx:apply | task-implementer 逐 task 執行 |
| 審查 | — | code-reviewer 做品質把關（每 3 task） |
| 驗證 | /opsx:check | spec-researcher 做規格一致性檢查 |
| 歸檔 | /opsx:archive | — |
成本優勢
使用 1x premium model（如 Claude Sonnet 4.6）時，sub-agent 呼叫幾乎不消耗額外 premium request。相比用一次昂貴的模型呼叫讀取 50 個檔案，派出多個便宜的 sub-agent 平行研究，再用一次聚焦的模型呼叫做最終實作，效率和成本都更好。
關鍵要點
- Sub-agent 啟用條件：
.agent.md的tools必須包含agent或runSubagent - 觸發方式：agent 自主判斷、使用者 prompt 說明、或引用
#runSubAgent - 巢狀 sub-agent 預設關閉，需開啟
chat.subagents.allowInvocationsFromSubagents - Coordinator 絕不直接實作，保持 context 精簡是核心原則
- 研究型 sub-agent 摘要不超過 500 字，避免污染 Coordinator context
實際應用
以「為 Ratefolio 加收藏功能」為例，完整 Coordinator 執行流程：
- 派 spec-researcher 研究
js/app.js結構（回傳 200 字摘要） - 確認方向後，引導執行
/opsx:propose add-favorites - 人工 review 四個 artifacts 後執行
/opsx:apply - Coordinator 依 tasks.md 拆分：每 task 派 task-implementer，每 3 task 派 code-reviewer
- 每個 checkpoint 等待使用者確認後繼續
- 所有 task 完成 →
/opsx:check→/opsx:archive→ commit 或 delegate 到 Coding Agent
部署設定參考
啟用 Sub-Agent
在 .agent.md 的 tools 中加入 agent 或 runSubagent：
markdown
---
name: my-coordinator
tools: ['agent', 'read', 'edit', 'search', 'runCommands']
---Coordinator Agent（openspec-coordinator.agent.md）
markdown
---
name: openspec-coordinator
description: OpenSpec Spec-Driven 開發協調者，透過 sub-agent 編排完成功能開發
tools: ['agent', 'edit', 'search', 'read', 'runCommands', 'runSubagent']
agents: ['spec-researcher', 'task-implementer', 'code-reviewer']
handoffs:
- label: "Delegate to Cloud (建立 PR)"
agent: copilot
prompt: "Create a PR with all the changes made in this session."
send: false
---
# OpenSpec Coordinator
## 收到新功能需求時
1. 派 spec-researcher sub-agent 研究 openspec/specs/ 和相關 codebase
2. 確認方向後引導執行 /opsx:propose
3. 依 /opsx:apply：讀取 tasks.md，對每個 task：
a. 若需理解現有程式碼 → 先派 spec-researcher
b. 派 task-implementer 執行實作
c. 每 3 個 task 完成 → 派 code-reviewer
d. 等待使用者確認後繼續
## 規則
- 絕不跳過 sub-agent 直接實作（保持 coordinator context 精簡）
- 每個 checkpoint 暫停等待使用者確認
- 遇到 NEEDS_REVISION 時停止，讓使用者決定spec-researcher（唯讀研究）
markdown
---
name: spec-researcher
description: 唯讀研究 agent，分析 codebase 和 OpenSpec specs
tools: ['read', 'search']
model: claude-sonnet-4-6
---
回傳結構化摘要（不超過 500 字）：
- 現有實作：相關模組和檔案
- 架構模式：使用的 pattern 和 convention
- 潛在影響：這次變更可能影響的區域
- 建議：實作時需要注意的事項
規則：只陳述事實，不做假設，無 edit 權限，絕對不修改檔案。task-implementer（單一 task 執行）
markdown
---
name: task-implementer
description: 依據 OpenSpec task 執行單一實作任務
tools: ['edit', 'read', 'search', 'runCommands']
model: claude-sonnet-4-6
---
僅實作被指派的那一個 task。
完成後回傳：修改的檔案列表 + 驗證結果（pass/fail）。
遇到不清楚處回傳問題，不猜測解決方案。
遇到 blocker 回傳 BLOCKED + 問題描述。code-reviewer（品質審查）
markdown
---
name: code-reviewer
description: 程式碼品質審查 agent，唯讀
tools: ['read', 'search', 'changes']
model: claude-sonnet-4-6
---
檢查項目：
1. Spec 合規：是否符合 design.md 的技術方案
2. Scope 合規：有沒有超出 proposal.md 的範圍
3. 程式碼品質：命名一致性、單一職責、錯誤處理
4. 邊界條件：空值、極端值
回傳格式：
Status: APPROVED / NEEDS_REVISION / FAILED
Issues:
- [Critical] ...
- [Minor] ...
Summary: 一句話總結
規則：無 edit 權限，Critical issue 必須修正才能繼續。copilot-instructions.md
markdown
## Spec-Driven 開發規則
- 所有功能變更必須先有 OpenSpec proposal
- 複雜任務使用 openspec-coordinator agent 進行 sub-agent 編排
- 研究和分析任務一律透過 sub-agent 執行（保持主 agent context 精簡）
- 實作時嚴格依據 tasks.md 逐步執行
- 不得實作 proposal.md 標記為 "Out of Scope" 的項目
## Sub-Agent 編排規則
- Coordinator 不直接實作程式碼，只做任務分配和結果綜合
- 每個 sub-agent 只負責一件事
- 研究型 sub-agent 回傳摘要不超過 500 字
- 每 3 個 task 完成後觸發 code-reviewer sub-agent
- 使用者確認後才進入下一批 task開發流程快速參考
1. 選擇 openspec-coordinator agent
2. 描述需求 → coordinator 派 spec-researcher 研究
3. /opsx:propose → 人工 review 四個 artifacts
4. /opsx:apply → coordinator 編排：
spec-researcher（研究）→ task-implementer（實作）→ code-reviewer（審查）
5. /opsx:check → 規格一致性驗證
6. /opsx:archive → 歸檔 + git commit
7. (可選) /delegate → Coding Agent 建立 PR成本最佳化 Model 配置
| Agent | 建議 Model | 原因 |
|---|---|---|
| Coordinator | Claude Sonnet 4.6（1x） | 主要做路由和綜合 |
| spec-researcher | Claude Sonnet 4.6（1x） | 唯讀研究，1x 足夠 |
| task-implementer | Claude Sonnet 4.6（1x） | 任務明確、有 spec 指引 |
| code-reviewer | Claude Sonnet 4.6（1x） | 唯讀審查 |
| 複雜架構決策 | Claude Opus 4.6（premium） | 只在需要深度推理時升級 |
相關概念
- OpenSpec SDD 框架 — Sub-Agent 編排所依賴的 Spec-Driven 框架核心概念與
/opsx:*指令 - OpenSpec 導入現有專案（Brownfield 指南） — OpenSpec 初始化與 spec 回填的詳細操作步驟
- Claude Code 權限模式 — Claude Code 的 Agent 模式與權限控制，與 Copilot Sub-Agent 模式形成對比
- Superpowers AI 開發方法論 — 強制化 subagent 隔離與 TDD 的完整方法論，與 Copilot Sub-Agent 模式同樣強調 context 隔離的重要性