Claude Code subagent 適合什麼專案：使用場景、邊界和避坑清單

很多人第一次看到 Claude Code subagent，會下意識把它理解成「多開幾個 AI，一起寫程式」。這個理解只對了一半。

更準確地說，subagent 適合解決三類問題：隔離上下文、拆分獨立子任務、讓某個角色長期使用固定規則。它不是所有專案都需要的加速器。如果任務很小、邊界不清，或者多個代理會反覆爭搶同一個檔案，硬拆 subagent 反而會讓結果更亂。

這篇文章用專案視角回答：Claude Code subagent 到底適合什麼專案，什麼時候該用，什麼時候別用，以及專案級 subagent 應該怎麼設計。

先給結論：這些專案最適合用 subagent

專案/任務類型	是否適合	為什麼
大型程式碼庫初次接手	很適合	可讓不同 subagent 分別讀 API、資料庫、前端、測試目錄
多模組並行排查	很適合	子任務彼此獨立，不必把所有上下文塞進主會話
PR 或大改動程式碼審查	很適合	可拆成 bug、安全、效能、測試覆蓋審查
測試失敗和日誌分析	適合	日誌雜訊大，交給專門 subagent 過濾
文件、遷移、依賴升級評估	適合	適合讀材料、列影響面、給遷移清單
單檔小 bug 修復	不太適合	拆分成本高於收益
需求還沒想清楚的探索	不適合	subagent 需要明確邊界
多個代理同時改同一批檔案	高風險	容易衝突、覆蓋、重複修改

一句話：subagent 適合「可以拆開、能獨立完成、最後只需要交付結論或小範圍結果」的任務。

subagent 真正解決的是上下文管理

Claude Code 官方文件裡強調，subagent 是獨立的 agent 實例。主 agent 可以把聚焦任務交給它，subagent 用自己的上下文工作，再把最終結果返回主會話。

這意味著它的核心價值不是單純多執行緒，而是：

上下文隔離：日誌、測試輸出、文件摘錄、目錄掃描結果不會污染主會話。
角色固定：例如 code-reviewer 永遠只做只讀審查，test-runner 永遠只跑測試和分析失敗。
工具權限控制：某些 subagent 只允許 Read/Grep/Glob。
並行調研：多個獨立方向可以同時跑，最後由主會話整合。
專案經驗沉澱：把團隊常用審查口徑寫進 .claude/agents/。

所以判斷一個專案適不適合 subagent，不要先問「能不能更快」，而要問「這個任務是否會產生大量上下文，是否能拆成清晰角色」。

適合場景一：大型程式碼庫摸底

剛接手陌生專案時，最常見的問題不是「程式碼怎麼改」，而是「我根本不知道從哪裡看」。

這時 subagent 很有用。主會話只負責提出問題和彙總結論，把探索任務拆出去：

api-reader：只看路由、控制器、介面鑑權。
db-reader：只看 schema、migration、ORM model。
frontend-reader：只看頁面結構、狀態管理、元件入口。
test-reader：只看測試框架、覆蓋範圍、執行命令。

每個 subagent 最後只返回 5 到 10 條結論。主會話不用背下整個倉庫細節，只需要拿到一張結構化地圖。

這特別適合 monorepo、歷史包袱較重的業務系統、前後端混合倉庫、測試與部署腳本散落的專案，以及技術債評估。

如果你正在設計 Codex 和 Claude Code 的接力方式，可以把這類「讀倉庫、摸結構」任務放在 Claude Code subagent 側，再把結論交給 Codex 執行更長的修改流程。相關思路可以看：/zh-tw/2026/07/10/codex-claude-code-task-handoff-guide/。

適合場景二：程式碼審查拆角色

subagent 很適合做程式碼審查，因為審查天然可以按關注點拆開：

bug-reviewer：找邏輯錯誤、空值、邊界條件、回歸風險。
security-reviewer：看權限、輸入校驗、密鑰、注入、越權。
performance-reviewer：看迴圈、查詢、快取、渲染、並發瓶頸。
test-reviewer：看測試是否覆蓋真實風險，而不是只補 snapshot。

但要注意邊界：審查型 subagent 最好預設只讀。

更穩妥的流程是：

主會話收集 diff。
多個只讀 subagent 分別審查。
主會話合併結論，決定改哪些。
由主會話或一個明確的 fixer subagent 做小範圍修改。

如果你關注「Claude Code 和 Codex 程式碼審查流程怎麼搭」，可以看這篇閉環流程文章：/zh-tw/2026/07/10/claude-code-codex-code-review-workflow/。

適合場景三：測試失敗和日誌雜訊處理

自動化測試失敗時，主會話最容易被大量輸出拖慢。前端 E2E、後端整合測試、CI 日誌，失敗資訊常常夾在幾百行輸出裡。

這類任務很適合交給 test-runner subagent：

執行指定測試命令；
截取失敗用例；
歸納失敗原因；
標出最可能相關的檔案；
不直接修程式，只返回排查建議。

subagent	建議工具	適合任務
`test-runner`	`Bash, Read, Grep`	跑測試、讀日誌、定位失敗
`log-analyzer`	`Read, Grep, Glob`	分析日誌和錯誤堆疊
`coverage-reviewer`	`Read, Grep, Glob`	找缺失測試和高風險分支

如果你已經用 Claude Code hooks 自動執行測試，可以讓 hooks 負責「觸發」，subagent 負責「解釋失敗」：/zh-tw/2026/07/10/claude-code-hooks-auto-run-tests/。

適合場景四：大重構前的影響面分析

大重構最怕一上來就改。subagent 更適合先做「只讀偵察」。

例如替換認證模組、升級資料庫存取層、重構前端狀態管理，可以讓多個 subagent 分別回答：

哪些檔案直接依賴舊介面？
哪些測試覆蓋了這塊邏輯？
哪些呼叫路徑最容易破壞相容性？
是否存在文件、腳本、設定也要同步改？
哪些地方應該先加測試再動手？

關鍵是：subagent 輸出影響面，不要急著輸出 patch。

主會話拿到影響面後，再決定一次性改、分階段改，還是先補測試。這也有助於長任務中斷後恢復，因為每個階段都有清晰結論。可參考：/zh-tw/2026/07/10/ai-agent-long-task-resume-guide/。

不適合場景：別把所有任務都拆成 subagent

subagent 有成本。它會消耗額外上下文、額外等待時間，也會增加協調複雜度。

通常不建議用於：

1. 小到可以直接解決的問題

例如 typo、import、CSS class、一行空值判斷、設定項更新。主會話直接做最快。

2. 邊界不清的需求

「幫我最佳化這個專案」「讓頁面更好看」這類需求，拆分前需要先問清目標、約束和驗收標準。

3. 需要頻繁協商的任務

subagent 適合獨立工作，不適合每改兩行就重新討論設計。

4. 多個代理同時寫同一批檔案

更好的方式是先只讀審查，再由一個執行者統一落地。

5. 高風險外部操作

涉及生產環境、真實帳號、付費 API、刪除資料、改權限、發郵件或訊息的任務，不要輕易交給背景 subagent 自動執行。

專案級 subagent 應該怎麼設計

Claude Code 支援把 subagent 寫成 Markdown 檔案。專案級 subagent 通常放在：

1

.claude/agents/

全域可複用的 subagent 通常放在：

1

~/.claude/agents/

專案級適合寫進倉庫，因為它反映的是這個專案自己的約定，例如測試命令、目錄結構、審查重點、禁止修改的檔案、輸出格式。

一個最小只讀程式碼審查 subagent 可以這樣寫：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


---
name: code-reviewer
description: Use when the task needs a read-only review of code changes for bugs, regressions, security risks, and missing tests.
tools: Read, Grep, Glob
---

# Code Reviewer

只做只讀審查，不修改檔案。

重點檢查：

- 邏輯錯誤和邊界條件
- 可能的回歸風險
- 安全和權限問題
- 缺失的測試
- 與專案現有風格不一致的實作

輸出格式：

1. 先列高風險問題。
2. 每個問題給出檔案路徑和原因。
3. 沒有發現問題時明確說明。
4. 不要輸出大段重寫後的程式碼。

最重要的不是正文有多長，而是 description 要寫清楚。Claude Code 會根據 description 判斷何時呼叫這個 subagent。

常見 subagent 組合

實際專案裡，不建議一開始就建十幾個 subagent。先從 3 到 5 個高頻角色開始：

名稱	工具	作用
`code-reviewer`	`Read, Grep, Glob`	只讀審查 bug、回歸和測試缺口
`test-runner`	`Bash, Read, Grep`	執行測試並解釋失敗
`docs-researcher`	`Read, Grep, Glob`	整理專案文件、遷移說明、約定
`security-reviewer`	`Read, Grep, Glob`	審查權限、輸入、密鑰、注入風險
`refactor-planner`	`Read, Grep, Glob`	大改前分析影響面和分階段計畫

如果某個 subagent 經常只輸出泛泛建議，說明角色太虛。要麼縮小任務範圍，要麼補充專案規則。

怎麼呼叫 subagent

可以用自然語言顯式呼叫：

1

Use the code-reviewer subagent to review the current diff. Do not modify files.

也可以點名具體 subagent，例如 @code-reviewer，或用命令列啟動：

1

claude --agent code-reviewer

關鍵任務盡量顯式點名，不要完全依賴自動委派。尤其是審查、測試、遷移評估，明確說「只讀」「不要改檔案」「只返回結論」會穩定很多。

一個實用判斷公式

如果不確定要不要用 subagent，可以問 5 個問題：

任務能不能按模組、目錄、角色或關注點拆開？
子任務之間是否相對獨立？
子任務輸出能不能壓縮成明確結論？
是否需要不同工具權限？
上下文隔離收益是否大於額外 token 和等待成本？

如果 5 個問題裡有 3 個以上答案是「是」，就適合嘗試 subagent。只有 1 個是「是」，大概率不值得拆。

避坑清單

subagent 名稱要具體，不要叫 helper、assistant、worker。
description 要寫觸發場景。
審查型 subagent 預設只讀。
寫程式型 subagent 一次只負責一個小範圍。
大重構先做影響面分析，再決定誰來改。
測試 subagent 應返回失敗摘要，不要把完整日誌塞回主會話。
多個 subagent 的輸出由主會話合併。
高風險操作要限制工具和範圍。
專案級規則放 .claude/agents/，個人習慣放 ~/.claude/agents/。
定期刪掉低頻、重複、輸出品質差的 subagent。

總結

Claude Code subagent 最適合的專案，不是「所有想用 AI 的專案」，而是有明確模組、明確角色、明確邊界的大中型開發任務。

它適合做程式碼庫摸底、專項審查、測試失敗分析、遷移影響面評估和專案級固定角色沉澱；不適合小改動、模糊需求、頻繁協商和多個代理同時寫同一批檔案。

真正好用的 subagent，不在於數量多，而在於邊界清楚。主會話負責目標、取捨和最終落地；subagent 負責把某個局部問題查深、查準、查乾淨。這樣用，它才會從「多一個 AI」變成專案工作流裡真正可靠的一環。