打開 Claude Code 跑了一個大任務，結果它把 context window 塞到快溢出來，回應開始變慢、幻覺變多。你有遇過這種狀況嗎？

Sub-agents 就是為了解決這件事而存在的。

Skills、Commands、Subagents、Plugins 差在哪

這四個東西很容易搞混。先講清楚：

CLAUDE.md 是 always-on 的背景知識。每次 Claude Code 啟動都會載入。適合放專案規範、coding style、常用指令之類的東西。問題是它永遠佔 context，放太多會擠壓你實際工作的空間。

Skills 是 on-demand 的上下文。只有在觸發條件符合的時候才載入。每個 Skill 有一個 SKILL.md 檔案，裡面定義了名稱、描述、允許的工具、以及行為指引。跟 CLAUDE.md 的差別在於：不用的時候不佔空間。

Commands（斜線指令）是你手動觸發的捷徑。/review、/test、/deploy 這種。執行一段預定義的流程。

Sub-agents 是重點。它讓一個 Skill 能啟動獨立的子程序——有自己的 context window、自己的工具權限。做完之後回傳結果，不會污染主程序的 context。

Plugins 把 Skills、MCP Server、工具打包成可安裝的套件。用 claude plugin install 裝，用 claude plugin list 查。

Sub-agents 解決什麼問題

Claude Code 的 context window 有上限。當你在一個長 session 裡同時做 code review、跑測試、寫文件，context 會被各種中間結果塞滿。模型開始忘記前面說過什麼，回應品質直線下降。

Sub-agents 的做法是：把任務拆出去。

主程序說「我需要一個 code review」，然後啟動一個 sub-agent。這個 sub-agent 有乾淨的 context window，只載入 review 相關的 SKILL.md 和目標檔案。做完把結論交回來。主程序拿到結論繼續往下走，不用扛 review 過程中產生的所有中間 context。

概念上就像作業系統的 fork：子程序有自己的記憶體空間，結束後只把需要的結果傳回父程序。

怎麼設定 Sub-agent

在 SKILL.md 的 frontmatter 裡，可以指定這個 Skill 以 sub-agent 模式執行。關鍵設定：

1
2
3
4
5
6
7
8
9
10
---
name: my-review-skill
description: |
  Code review with security focus
allowed-tools:
  - Bash
  - Read
  - Grep
  - Glob
---

allowed-tools 很重要。你可以限制 sub-agent 只能用特定工具，不讓它亂改檔案或亂跑危險指令。比如一個純 review 的 sub-agent，只給 Read 和 Grep，不給 Edit 和 Bash。

Sub-agent 執行的時候，主程序的 context 是暫停的。不會互相干擾。做完之後，sub-agent 的完整 context 會被丟掉，只有最終輸出回到主程序。

實際使用場景

場景一：大型 PR Review

一個 1,200 行的 PR，如果在主 session 裡直接 review，產生的 context 量很大。拆成 sub-agent：

  1. 主程序分析 PR 結構，識別出哪些檔案有改動
  2. 對每個改動的模組啟動一個 review sub-agent
  3. 每個 sub-agent 只看自己負責的檔案，產出 review 結論
  4. 主程序彙整所有結論，產出最終 review

context 不會爆，每個 sub-agent 的專注度也更高。

場景二：平行跑測試和 lint

1
2
3
4
主程序
├── Sub-agent A: 跑 unit tests
├── Sub-agent B: 跑 linter
└── Sub-agent C: 檢查 type errors

三個 sub-agent 各自獨立，不會互相污染 context。結果回來之後主程序統一處理。

場景三：多步驟部署流程

部署前要做的事通常很多：跑測試、build、推 PR、合併、部署、健康檢查。每一步的 context 需求不同。用 sub-agent 拆開，每一步都在乾淨的環境裡執行。

跟 gstack 的關係

如果你看過 gstack（Y Combinator CEO Garry Tan 開源的 AI 工程工作流系統），它的 Sprint 工作流就是大量使用 sub-agent 的實際案例。

/office-hours 啟動一個 sub-agent 扮演 YC 導師、/review 啟動 Staff Engineer、/qa 啟動 QA Lead、/cso 啟動資安長。每個角色都是獨立的 sub-agent，有自己的 context 和工具權限。

這比在同一個 session 裡切換角色有效率得多。每個 sub-agent 只載入自己需要的知識，不會被其他角色的 context 干擾。

建立自己的 Skill + Sub-agent

步驟不複雜：

1. 建立 SKILL.md

在 .claude/skills/my-skill/ 底下建一個 SKILL.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
---
name: security-audit
description: |
  Run OWASP Top 10 security audit on the codebase.
  Trigger when user mentions "security audit" or "vulnerability scan".
allowed-tools:
  - Read
  - Grep
  - Glob
  - Bash
---

## Instructions

You are a senior security engineer. Audit the codebase for:

1. SQL injection
2. XSS
3. CSRF
4. Authentication bypass
5. Sensitive data exposure

Output a structured report with severity levels.

2. 設定觸發描述

description 裡寫清楚觸發條件。Claude Code 會根據使用者的輸入去比對，描述越精確，觸發越準。

3. 限制工具權限

allowed-tools 用白名單。安全審計只需要讀取能力，就不要給 Edit 和 Write。最小權限原則。

4. 測試

在 Claude Code 裡測試觸發是否正常、輸出格式是否符合預期。調整描述和指引直到穩定。

注意事項

Sub-agent 不是銀彈。幾個要注意的點：

每次啟動 sub-agent 都有開銷。如果任務本身很簡單（三行 code 的改動要 review），直接在主 session 做比較快，不值得啟動一個 sub-agent。

Sub-agent 之間不能直接通訊。如果 A 的結果需要給 B 用，必須回到主程序再轉發。這是設計上的限制，不是 bug——避免 sub-agent 之間形成不可控的依賴。

Context window 的上限不會因為用了 sub-agent 就變大。單一 sub-agent 還是受限於模型的 context size。好處是每個 sub-agent 的 context 是乾淨的，不會被其他任務的殘留佔據。

跟傳統的 Agent 框架比

LangChain、CrewAI 這些框架也有 multi-agent 的概念。差別在哪？

Claude Code 的 sub-agent 跑在同一個 CLI 環境裡，共享檔案系統但不共享 context。不需要額外的框架、不需要設定 API endpoint、不需要管 agent 之間的通訊協定。SKILL.md 一個檔案搞定。

代價是彈性比較低。你不能讓不同的 sub-agent 用不同的模型（LangChain 可以），不能做複雜的 agent 間協商。但對大部分工程任務來說，「拆出去跑、結果拿回來」已經夠用了。

簡單的東西做得好，比複雜的東西做得半吊子有用。

參考來源：Extend Claude with skills - Claude Code Docs
參考來源：Claude Code Sub-agents - Anthropic Academy
參考來源：Understanding Claude Code: Skills vs Commands vs Subagents vs Plugins
參考來源：A Mental Model for Claude Code: Skills, Subagents, and Plugins