Claude Code 手冊

Appearance

Claude How To

子代理 (Subagents) - 完整參考指南 (Complete Reference Guide) ​

子代理 (Subagents) 是專業化的 AI 助手，Claude Code 可以將任務委派給它們。每個子代理都有特定目的，使用獨立於主對話的脈絡視窗 (Context Window)，並可配置特定工具 (Tools) 與自訂系統提示詞 (System Prompt)。

目錄 (Table of Contents) ​

  1. 概觀 (Overview)
  2. 主要優勢 (Key Benefits)
  3. 檔案位置 (File Locations)
  4. 設定 (Configuration)
  5. 內建子代理 (Built-in Subagents)
  6. 管理子代理 (Managing Subagents)
  7. 使用子代理 (Using Subagents)
  8. 可恢復代理 (Resumable Agents)
  9. 鏈接子代理 (Chaining Subagents)
  10. 子代理的持久化記憶體 (Persistent Memory for Subagents)
  11. 背景子代理 (Background Subagents)
  12. Worktree 隔離 (Worktree Isolation)
  13. 派生子代理 (Forked Subagents)
  14. 限制可產生的子代理 (Restrict Spawnable Subagents)
  15. claude agents CLI 指令 (claude agents CLI Command)
  16. 代理團隊（實驗性）(Agent Teams (Experimental))
  17. 外掛子代理安全性 (Plugin Subagent Security)
  18. 架構 (Architecture)
  19. 脈絡管理 (Context Management)
  20. 何時使用子代理 (When to Use Subagents)
  21. 最佳實踐 (Best Practices)
  22. 此資料夾中的範例子代理 (Example Subagents in This Folder)
  23. 安裝說明 (Installation Instructions)
  24. 檔案結構 (File Structure)
  25. 相關概念 (Related Concepts)
  26. 可可觀測性 (Observability)
  27. 其他資源 (Additional Resources)

概觀 (Overview) ​

子代理 (Subagents) 透過以下方式在 Claude Code 中實現委派任務執行 (Delegated Task Execution)：

  • 建立具有獨立脈絡視窗 (Context Windows) 的隔離 AI 助手 (Isolated AI Assistants)
  • 提供專門領域所需的自訂系統提示詞 (Customized System Prompts)
  • 執行工具存取控制 (Tool Access Control) 以限制功能
  • 防止複雜任務造成的脈絡污染 (Context Pollution)
  • 實現多個專業任務的平行執行 (Parallel Execution)

每個子代理皆獨立運作於全新的環境中，僅接收其任務所需的特定脈絡 (Context)，然後將結果返回給主代理 (Main Agent) 進行綜合彙整。

快速開始 (Quick Start)：請 Claude 為您建立子代理（「建立一個審查安全性的子代理」），或直接新增 .claude/agents/<name>.md 檔案 — 請參閱下方的 管理子代理 (Managing Subagents)。

注意 (Note)：自 v2.1.198 起，/agents 指令不再開啟互動式建立精靈 (Interactive Creation Wizard)。請透過直接要求 Claude 或編輯 .claude/agents/ 檔案來建立與管理子代理。

主要優勢 (Key Benefits) ​

優勢 (Benefit)說明 (Description)
脈絡保留 (Context preservation)運作於獨立脈絡中，防止污染主對話 (Main Conversation)
專業知識 (Specialized expertise)為特定領域進行微調，具備更高的成功率
可重複使用性 (Reusability)可跨不同專案使用，並與團隊共享
彈性權限 (Flexible permissions)針對不同子代理類型提供不同的工具存取層級
可擴充性 (Scalability)多個代理可同時處理不同面向

檔案位置 (File Locations) ​

子代理檔案可以儲存在多個不同作用域 (Scopes) 的位置：

優先順序 (Priority)類型 (Type)位置 (Location)作用域 (Scope)
1 (最高)CLI 定義 (CLI-defined)透過 --agents 標記 (JSON)僅限目前工作階段 (Session only)
2專案子代理 (Project subagents).claude/agents/目前專案 (Current project)
3使用者子代理 (User subagents)~/.claude/agents/所有專案 (All projects)
4 (最低)外掛代理 (Plugin agents)外掛 agents/ 目錄透過外掛 (Via plugins)

當存在重複名稱時，較高優先順序的來源優先採用。

巢狀 .claude/ 優先權 (Nested .claude/ precedence) (v2.1.178)：當相同的代理名稱在多個巢狀 .claude/agents/ 目錄中定義時（例如具有套件層級 .claude/ 資料夾的 Monorepo），最接近目前工作目錄 (Current Working Directory) 的定義獲勝。相同的最接近獲勝規則亦適用於巢狀工作流程 (Workflow) 與輸出樣式 (Output-style) 定義。

設定 (Configuration) ​

檔案格式 (File Format) ​

子代理定義於 YAML Frontmatter 中，隨後是以 Markdown 撰寫的系統提示詞 (System Prompt)：

yaml
---
name: your-sub-agent-name
description: Description of when this subagent should be invoked
tools: tool1, tool2, tool3  # Optional - inherits all tools if omitted
disallowedTools: tool4  # Optional - explicitly disallowed tools
model: sonnet  # Optional - sonnet, opus, haiku, or inherit
permissionMode: default  # Optional - permission mode
maxTurns: 20  # Optional - limit agentic turns
skills: skill1, skill2  # Optional - skills to preload into context
mcpServers: server1  # Optional - MCP servers to make available
memory: user  # Optional - persistent memory scope (user, project, local)
background: false  # Optional - run as background task
effort: high  # Optional - reasoning effort (low, medium, high, xhigh, max)
isolation: worktree  # Optional - git worktree isolation
initialPrompt: "Start by analyzing the codebase"  # Optional - auto-submitted first turn
experimental:  # Optional - experimental settings block
  cacheTtl: "1h"  # Cache TTL for this subagent: "5m" or "1h" (v2.1.248+)
hooks:  # Optional - component-scoped hooks
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/security-check.sh"
---

Your subagent's system prompt goes here. This can be multiple paragraphs
and should clearly define the subagent's role, capabilities, and approach
to solving problems.

設定欄位 (Configuration Fields) ​

欄位 (Field)必填 (Required)說明 (Description)
name是唯一識別碼（小寫英文字母與連字號）。尋找時採規範化處理（不區分大小寫與分隔符號 — 請參閱下文），但自 v2.1.218 起，包含 : 的名稱會被拒絕：: 保留給外掛命名空間使用
description是目的之自然語言描述。包含 "use PROACTIVELY"（主動使用）以鼓勵自動呼叫
tools否以逗號分隔的特定工具清單。省略則繼承所有工具。支援 Agent(agent_name) 語法以限制可產生的子代理
disallowedTools否以逗號分隔的子代理不得使用的工具清單
model否使用的模型：sonnet、opus、haiku、完整模型 ID 或 inherit。預設為已設定的子代理模型
permissionMode否manual（在 v2.1.200 中從 default 改名 — default 仍被接受為舊名稱）、acceptEdits、dontAsk、bypassPermissions、plan、auto。自 v2.1.212 起，Task 工具的 mode 呼叫參數已被棄用並忽略 — 子代理預設繼承父工作階段的權限模式，除非在此覆寫
maxTurns否子代理可執行的代理輪次 (Agentic Turns) 最大數量
skills否以逗號分隔的預載技能清單。在啟動時將完整的技能內容注入子代理的脈絡中。v2.1.133+： 子代理亦可透過 Skill 工具探索專案、使用者與外掛技能 — 與主工作階段目錄相同，不再局限於其自身的嵌入集合。
mcpServers否提供給子代理使用的 MCP 伺服器 (MCP Servers)
hooks否元件作用域掛鉤 (Component-scoped Hooks) (PreToolUse, PostToolUse, Stop)
memory否持久化記憶體目錄作用域：user、project 或 local
background否子代理預設已在背景執行 (v2.1.198)。設定為 true 可強制始終在背景執行並防止行內 (Inline) 執行
effort否推理精力程度 (Reasoning Effort Level)：low、medium、high、xhigh 或 max。覆寫工作階段精力程度；可用層級取決於模型
isolation否設定為 worktree 可賦予子代理自身的 Git Worktree
initialPrompt否當子代理作為主代理執行時自動送出的第一輪提示詞
color否子代理在任務清單與逐字稿中的顯示顏色。接受 red、blue、green、yellow、purple、orange、pink 或 cyan
experimental否實驗性設定區塊 (v2.1.248+)。experimental.cacheTtl 設定此子代理的快取 TTL — "5m" 或 "1h"

子代理模型環境變數 (Subagent Model Environment Variables) ​

有兩個環境變數會影響子代理在何種模型上執行：

變數 (Variable)版本 (Version)說明 (Description)
CLAUDE_CODE_SUBAGENT_MODEL—設定用於子代理的模型
CLAUDE_CODE_SUBAGENT_MODEL_FORCEv2.1.257+設定為 1 可強制子代理模型覆寫子代理 Frontmatter 中的 model:

優先順序在 v2.1.251 中變更 (Precedence changed in v2.1.251)：在該版本之前，CLAUDE_CODE_SUBAGENT_MODEL 優先級最高並會覆寫代理 Frontmatter — 包括 model: inherit。從 v2.1.251 開始，子代理自身的 model: Frontmatter 獲勝。當您希望環境變數再次覆寫 Frontmatter 時（例如將整個評估執行固定於單一模型），請設定 CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 (v2.1.257+)。

主執行緒代理 Frontmatter 遵從 (Main-Thread Agent Frontmatter Honoring) (v2.1.117+/v2.1.119+) ​

當代理作為主執行緒代理呼叫時（透過 claude --agent <name> 或 --print 模式），會遵從以下 Frontmatter 欄位：

欄位 (Field)版本 (Version)備註 (Notes)
mcpServersv2.1.117+當代理透過 claude --agent <name> 作為主執行緒代理呼叫時載入
permissionModev2.1.119+針對內建代理透過 --agent <name> 時遵從
tools / disallowedToolsv2.1.119+在 --print 模式（非互動式/腳本化使用）中遵從

範例 — 帶有 mcpServers 與 permissionMode 的代理：

yaml
---
name: secure-researcher
description: Research agent with scoped MCP access and restricted permissions
permissionMode: acceptEdits
mcpServers:
  notion:
    type: http
    url: https://mcp.notion.com/mcp
  github:
    type: http
    url: https://api.github.com/mcp
tools: Read, Grep, Glob
---

You are a research agent. You may query Notion and GitHub through the
configured MCP servers, and read local files, but you cannot write or
execute commands outside of accepted edits.

執行方式：

bash
claude --agent secure-researcher

工具設定選項 (Tool Configuration Options) ​

選項 1：繼承所有工具（省略欄位）

yaml
---
name: full-access-agent
description: Agent with all available tools
---

選項 2：指定個別工具

yaml
---
name: limited-agent
description: Agent with specific tools only
tools: Read, Grep, Glob, Bash
---

關於 Glob/Grep 的說明 (v2.1.113+)： 在原生 macOS/Linux 建置中，Glob 與 Grep 是透過 Bash 工具以 bfs/ugrep 形式提供，而非作為獨立工具。Windows 和 npm-JS 建置仍將其作為獨立工具公開。作者仍可在 allowedTools 中引用 Glob/Grep；後端替換過程是透明的。

選項 3：條件式工具存取

yaml
---
name: conditional-agent
description: Agent with filtered tool access
tools: Read, Bash(npm:*), Bash(test:*)
---

基於 CLI 的設定 (CLI-Based Configuration) ​

使用 --agents 標記與 JSON 格式為單一工作階段定義子代理：

bash
claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

--agents 標記的 JSON 格式：

json
{
  "agent-name": {
    "description": "Required: when to invoke this agent",
    "prompt": "Required: system prompt for the agent",
    "tools": ["Optional", "array", "of", "tools"],
    "model": "optional: sonnet|opus|haiku"
  }
}

注意 (Note)：自 v2.1.243 起，--agents 不再靜默忽略無效的 JSON 或無效的代理定義 — Claude Code 會退出並顯示明確的錯誤，與 --mcp-config 的行為一致。

代理定義的優先順序 (Priority of Agent Definitions)：

代理定義依照以下優先順序載入（首個符合者獲勝）：

  1. CLI 定義 (CLI-defined) - --agents 標記（僅限工作階段，JSON）
  2. 專案層級 (Project-level) - .claude/agents/（目前專案）
  3. 使用者層級 (User-level) - ~/.claude/agents/（所有專案）
  4. 外掛層級 (Plugin-level) - 外掛 agents/ 目錄

這允許 CLI 定義在單一工作階段中覆寫所有其他來源。

內建子代理 (Built-in Subagents) ​

Claude Code 包含數個始終可用的內建子代理：

代理 (Agent)模型 (Model)目的 (Purpose)
general-purpose繼承複雜的多步驟任務 (Complex, multi-step tasks)
Plan繼承為計劃模式進行研究 (Research for plan mode)
Explore繼承（上限為 Opus）唯讀程式碼庫探索 (Read-only codebase exploration)（快速/中等/非常深入）
claude繼承萬用代理，處理不適合更專業代理的任務；擁有子代理可用的每種工具。也是分派背景工作階段的預設代理
statusline-setupSonnet當您使用 /statusline 設定狀態列時執行
claude-code-guideHaiku回答有關 Claude Code 功能的問題

通用子代理 (General-Purpose Subagent) ​

屬性 (Property)數值 (Value)
模型 (Model)繼承自父代理 (Inherits from parent)
工具 (Tools)所有工具 (All tools)
目的 (Purpose)需要複雜推理的探索與修改任務

使用時機：需要同時進行探索與修改並結合複雜推理的任務。

計劃子代理 (Plan Subagent) ​

屬性 (Property)數值 (Value)
模型 (Model)繼承自父代理 (Inherits from parent)
工具 (Tools)Read, Glob, Grep, Bash
目的 (Purpose)在計劃模式中自動用於研究程式碼庫

使用時機：當 Claude 在提出計劃之前需要理解程式碼庫時。

探索子代理 (Explore Subagent) ​

屬性 (Property)數值 (Value)
模型 (Model)繼承工作階段模型，上限為 Opus (v2.1.198)。設定 model: haiku 可保持快速與低成本
模式 (Mode)嚴格唯讀 (Strictly read-only)
工具 (Tools)Glob, Grep, Read, Bash（僅限唯讀指令）
目的 (Purpose)快速搜尋與分析程式碼庫

使用時機：在不進行變更的情況下搜尋/理解程式碼。

深入程度 (Thoroughness Levels) - 指定探索深度：

  • "quick"（快速） - 最小化探索的快速搜尋，適合尋找特定模式
  • "medium"（中等） - 中度探索，平衡速度與深入度，預設方式
  • "very thorough"（非常深入） - 跨多個位置與命名慣例的綜合分析，可能需要較長時間

Claude 子代理 (Claude Subagent) ​

屬性 (Property)數值 (Value)
模型 (Model)繼承自父代理 (Inherits from parent)
工具 (Tools)子代理可用的每一種工具
目的 (Purpose)萬用代理，用於不適合更專業代理的任務

使用時機：當任務與更專業的內建代理不符合時。它也是分派背景工作階段的預設代理；其啟動的權限模式取決於該工作階段如何啟動。

狀態列設定子代理 (Statusline Setup Subagent) ​

屬性 (Property)數值 (Value)
模型 (Model)Sonnet
工具 (Tools)Read, Write, Bash
目的 (Purpose)設定 Claude Code 狀態列顯示

使用時機：當設定或自訂狀態列時。

Claude Code 指南子代理 (Claude Code Guide Subagent) (claude-code-guide) ​

屬性 (Property)數值 (Value)
模型 (Model)Haiku（快速、低延遲）
工具 (Tools)唯讀 (Read-only)
目的 (Purpose)回答有關 Claude Code 功能與使用的問題

使用時機：當使用者詢問關於 Claude Code 如何運作或如何使用特定功能的問題時。

管理子代理 (Managing Subagents) ​

建立或管理子代理最簡單的方法是直接詢問 Claude：

text
Create a subagent that reviews code for security vulnerabilities.

Claude 會為您撰寫 .claude/agents/<name>.md 檔案，並選擇合理的 Frontmatter（工具、模型、描述）。隨後您可以手動修改該檔案或要求 Claude 調整。

注意 (Note)：/agents 指令不再開啟互動式建立精靈（已於 v2.1.198 移除）。現在它會引導您詢問 Claude 或直接編輯 .claude/agents/ 檔案。

直接檔案管理 (Direct File Management) ​

bash
# 建立專案子代理
mkdir -p .claude/agents
cat > .claude/agents/test-runner.md << 'EOF'
---
name: test-runner
description: Use proactively to run tests and fix failures
---

You are a test automation expert. When you see code changes, proactively
run the appropriate tests. If tests fail, analyze the failures and fix
them while preserving the original test intent.
EOF

# 建立使用者子代理（在所有專案中可用）
mkdir -p ~/.claude/agents

使用子代理 (Using Subagents) ​

自動委派 (Automatic Delegation) ​

Claude 會根據以下條件主動委派任務：

  • 您請求中的任務描述
  • 子代理設定中的 description 欄位
  • 目前脈絡與可用工具

若要鼓勵主動使用，請在 description 欄位中包含 "use PROACTIVELY" 或 "MUST BE USED"：

yaml
---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after writing or modifying code.
---

明確呼叫 (Explicit Invocation) ​

您可以明確要求特定的子代理：

> Use the test-runner subagent to fix failing tests
> Have the code-reviewer subagent look at my recent changes
> Ask the debugger subagent to investigate this error

不區分大小寫與分隔符號的 subagent_type 比對 (v2.1.140)：subagent_type（在 Agent 工具呼叫或 --agent 標記中）比對時不區分大小寫並忽略分隔符號樣式 — code-reviewer、Code Reviewer 與 code_reviewer 都會解析為相同的代理。這解決了長期以來微小的大小寫差異會靜默退回至預設代理的問題。

@-Mention 呼叫 (@-Mention Invocation) ​

使用 @ 前綴可確保呼叫特定的子代理（繞過自動委派啟發式演算法）：

> @"code-reviewer (agent)" review the auth module

全工作階段代理 (Session-Wide Agent) ​

使用特定代理作為主代理來執行整個工作階段：

bash
# 透過 CLI 標記
claude --agent code-reviewer

# 透過 settings.json
{
  "agent": "code-reviewer"
}

列出可用代理 (Listing Available Agents) ​

使用 claude agents 指令列出所有來源設定的所有代理：

bash
claude agents

可恢復代理 (Resumable Agents) ​

子代理可以保留完整脈絡並繼續之前的對話：

bash
# 初次呼叫
> Use the code-analyzer agent to start reviewing the authentication module
# 返回 agentId: "abc123"

# 稍後恢復代理
> Resume agent abc123 and now analyze the authorization logic as well

使用情境 (Use cases)：

  • 跨多個工作階段的長期研究
  • 不會遺失脈絡的迭代式調整
  • 維持脈絡的多步驟工作流程

鏈接子代理 (Chaining Subagents) ​

依序執行多個子代理：

bash
> First use the code-analyzer subagent to find performance issues,
  then use the optimizer subagent to fix them

這實現了將一個子代理的輸出傳遞給另一個子代理的複雜工作流程。

子代理的持久化記憶體 (Persistent Memory for Subagents) ​

memory 欄位為子代理提供了一個跨對話持久存在的目錄。這允許子代理隨著時間累積知識，儲存可以在工作階段之間持久保留的筆記、發現與脈絡。

記憶體作用域 (Memory Scopes) ​

作用域 (Scope)目錄 (Directory)使用情境 (Use Case)
user~/.claude/agent-memory/<name>/跨所有專案的個人筆記與偏好設定
project.claude/agent-memory/<name>/與團隊共享的專案特定知識
local.claude/agent-memory-local/<name>/不提交至版本控制的本地專案知識

運作方式 (How It Works) ​

  • 記憶體目錄中 MEMORY.md 的前 200 行會自動載入到子代理的系統提示詞中
  • Read、Write 與 Edit 工具會自動為子代理啟用，以管理其記憶體檔案
  • 子代理可以根據需要在其記憶體目錄中建立額外檔案

設定範例 (Example Configuration) ​

yaml
---
name: researcher
memory: user
---

You are a research assistant. Use your memory directory to store findings,
track progress across sessions, and build up knowledge over time.

Check your MEMORY.md file at the start of each session to recall previous context.
mermaid
graph LR
    A["子代理 (Subagent)<br/>工作階段 1"] -->|寫入| M["MEMORY.md<br/>（持久化）"]
    M -->|載入至| B["子代理 (Subagent)<br/>工作階段 2"]
    B -->|更新| M
    M -->|載入至| C["子代理 (Subagent)<br/>工作階段 3"]

    style A fill:#e1f5fe,stroke:#333,color:#333
    style B fill:#e1f5fe,stroke:#333,color:#333
    style C fill:#e1f5fe,stroke:#333,color:#333
    style M fill:#f3e5f5,stroke:#333,color:#333

背景子代理 (Background Subagents) ​

子代理預設在背景執行 (v2.1.198)。當子代理執行時，Claude 會繼續處理主對話，並在完成時收到通知，因此您不再需要等待子代理返回即可繼續。

設定 (Configuration) ​

因為背景執行已是預設值，Frontmatter 中的 background: true 會強制子代理始終在背景執行，並防止其進行行內 (Inline) 執行：

yaml
---
name: long-runner
background: true
description: Performs long-running analysis tasks in the background
---

快捷鍵 (Keyboard Shortcuts) ​

快捷鍵 (Shortcut)動作 (Action)
Ctrl+B將目前執行的子代理任務移至背景
Ctrl+F終止所有背景代理（按兩次確認）

停用背景任務 (Disabling Background Tasks) ​

設定環境變數以完全停用背景任務支援：

bash
export CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1

Worktree 隔離 (Worktree Isolation) ​

isolation: worktree 設定可給予子代理獨立的 Git Worktree，允許其獨立進行變更而不影響主要工作樹 (Main Working Tree)。

設定 (Configuration) ​

yaml
---
name: feature-builder
isolation: worktree
description: Implements features in an isolated git worktree
tools: Read, Write, Edit, Bash, Grep, Glob
---

運作方式 (How It Works) ​

mermaid
graph TB
    Main["主要工作樹 (Main Working Tree)"] -->|產生| Sub["帶有隔離 Worktree<br/>的子代理 (Subagent)"]
    Sub -->|進行變更於| WT["獨立的 Git<br/>Worktree + 分支"]
    WT -->|無變更| Clean["自動清理"]
    WT -->|有變更| Return["返回 worktree<br/>路徑與分支"]

    style Main fill:#e1f5fe,stroke:#333,color:#333
    style Sub fill:#f3e5f5,stroke:#333,color:#333
    style WT fill:#e8f5e9,stroke:#333,color:#333
    style Clean fill:#fff3e0,stroke:#333,color:#333
    style Return fill:#fff3e0,stroke:#333,color:#333
  • 子代理在獨立分支上的專屬 Git Worktree 中運作
  • 若子代理未進行任何變更，Worktree 將被自動清理
  • 若存在變更，Worktree 路徑與分支名稱將返回給主代理進行審查或合併

派生子代理 (Forked Subagents) ​

派生子代理 (context: fork) 在派生時會繼承父代理的完整對話脈絡 (Context)，而非從全新狀態開始。這對於探索替代路徑而不會遺失目前已完成的工作非常有用。

可用性 (Availability)：在 v2.1.117 中 GA。自 v2.1.232 起，派生模式 (Fork mode) 在互動式工作階段中預設開啟 — 無論是否為官方建置。在非互動式模式 (claude -p) 與 Agent SDK 中預設維持關閉。在早於 v2.1.232 的 Claude Code 上，或要在預設關閉之處開啟，請設定 CLAUDE_CODE_FORK_SUBAGENT=1。

派生模式子代理會在背景執行。 在派生模式開啟時 — 正如互動式工作階段中的預設狀態 — Claude Code 會在背景執行子代理，無論是否為派生子代理。

設定 (Configuration) ​

yaml
---
name: alternative-explorer
description: Explore an alternative implementation path while preserving parent context
context: fork
tools: Read, Edit, Bash, Grep, Glob
---

You are a forked subagent. You inherit the parent's full conversation and
may explore an alternative approach. Return your findings and the parent
will decide whether to adopt them.

明確啟用派生模式 (Enabling Fork Mode Explicitly) ​

v2.1.232+ 上的互動式工作階段無需標記。在舊版本、無頭 (Headless) 執行或 Agent SDK 中請使用：

bash
export CLAUDE_CODE_FORK_SUBAGENT=1
claude

何時使用派生對比全新脈絡 (When to Use Fork vs Clean Context) ​

情境 (Scenario)context: fork全新脈絡 (Clean context) (預設)
探索替代實作是否（會遺失脈絡）
利用現有脈絡進行長期研究是否
獨立的專業任務否是
避免脈絡污染否是

限制可產生的子代理 (Restrict Spawnable Subagents) ​

您可以使用 tools 欄位中的 Agent(agent_type) 語法來控制允許給定子代理產生的子代理。這提供了一種將特定子代理加入許可清單 (Allowlist) 以進行委派的方法。

注意 (Note)：在 v2.1.63 中，Task 工具重命名為 Agent。現有的 Task(...) 引用仍可作為別名運作。

範例 (Example) ​

yaml
---
name: coordinator
description: Coordinates work between specialized agents
tools: Agent(worker, researcher), Read, Bash
---

You are a coordinator agent. You can delegate work to the "worker" and
"researcher" subagents only. Use Read and Bash for your own exploration.

在此範例中，coordinator 子代理只能產生 worker 與 researcher 子代理。即使在其他地方定義了其他子代理，它也無法產生它們。

claude agents CLI 指令 (claude agents CLI Command) ​

claude agents 指令會按來源（內建、使用者層級、專案層級）分組列出所有已設定的代理：

bash
claude agents

此指令：

  • 顯示來自所有來源的所有可用代理
  • 按來源位置對代理進行分組
  • 當較高優先順序層級的代理遮蔽較低層級的代理時標示覆寫 (Overrides)（例如與使用者層級代理同名的專案層級代理）

代理團隊（實驗性）(Agent Teams (Experimental)) ​

代理團隊 (Agent Teams) 可協調多個 Claude Code 實例共同處理複雜任務。與子代理（委派子任務並返回結果）不同，團隊成員 (Teammates) 獨立運作並擁有自己的脈絡視窗，並可透過共享郵件箱系統直接彼此傳送訊息。

官方文件 (Official Documentation)：code.claude.com/docs/en/agent-teams

注意 (Note)：代理團隊屬於實驗性功能，預設為停用。需要 Claude Code v2.1.32+。在使用前請先啟用。

子代理對比代理團隊 (Subagents vs Agent Teams) ​

面向 (Aspect)子代理 (Subagents)代理團隊 (Agent Teams)
委派模型 (Delegation model)父代理委派子任務，等待結果團隊領導者 (Team Lead) 協調工作，團隊成員獨立執行
脈絡 (Context)每個子任務全新脈絡，結果濃縮返回每個團隊成員維持自身持久的脈絡視窗
協調 (Coordination)順序或平行，由父代理管理具有自動相依性管理的共享任務清單
通訊 (Communication)結果僅返回給父代理（無代理間通訊）團隊成員可透過郵件箱直接彼此傳送訊息
工作階段恢復 (Session resumption)支援內嵌 (In-process) 團隊成員不支援
最適合 (Best for)聚焦、定義明確的子任務需要代理間通訊與平行執行的複雜工作

啟用代理團隊 (Enabling Agent Teams) ​

設定環境變數或將其新增至您的 settings.json：

bash
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

或在 settings.json 中：

json
{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

啟動團隊 (Starting a team) ​

啟用後，請在提示詞中要求 Claude 與團隊成員協同工作：

User: Build the authentication module. Use a team — one teammate for the API endpoints,
      one for the database schema, and one for the test suite.

Claude 會自動建立團隊、指派任務並協調工作。

顯示模式 (Display modes) ​

控制團隊成員活動的顯示方式：

模式 (Mode)標記 (Flag)說明 (Description)
Auto（自動）--teammate-mode auto自動為您的終端機選擇最佳顯示模式
In-process（內嵌） (預設)--teammate-mode in-process在目前終端機中行內 (Inline) 顯示團隊成員輸出
Split-panes（分割窗格）--teammate-mode tmux在獨立的 tmux 或 iTerm2 窗格中開啟每個團隊成員
iTerm2--teammate-mode iterm2(v2.1.186+) 在專屬 iTerm2 窗格中產生團隊成員。需要 it2 CLI；Auto 模式在找不到時會發出警告
bash
claude --teammate-mode tmux

您也可以在 settings.json 中設定顯示模式：

json
{
  "teammateMode": "tmux"
}

注意 (Note)：分割窗格模式需要 tmux 或 iTerm2。在 VS Code 終端機、Windows Terminal 或 Ghostty 中不可用。

導覽 (Navigation) ​

在分割窗格模式中使用 Shift+Down 在團隊成員之間進行導覽。

團隊設定 (Team Configuration) ​

團隊設定儲存於 ~/.claude/teams/{team-name}/config.json。

團隊成員模型選擇 (Teammate Model Selection) ​

自 v2.1.234 起，"Default teammate model" /config 設定已被移除。團隊成員現在預設繼承團隊領導者的模型，除非產生呼叫明確指定了不同的模型。

架構 (Architecture) ​

mermaid
graph TB
    Lead["團隊領導者 (Team Lead)<br/>（協調者）"]
    TaskList["共享任務清單 (Shared Task List)<br/>（相依性）"]
    Mailbox["郵件箱 (Mailbox)<br/>（訊息）"]
    T1["團隊成員 1 (Teammate 1)<br/>（獨立脈絡）"]
    T2["團隊成員 2 (Teammate 2)<br/>（獨立脈絡）"]
    T3["團隊成員 3 (Teammate 3)<br/>（獨立脈絡）"]

    Lead -->|指派任務| TaskList
    Lead -->|傳送訊息| Mailbox
    TaskList -->|接收工作| T1
    TaskList -->|接收工作| T2
    TaskList -->|接收工作| T3
    T1 -->|讀取/寫入| Mailbox
    T2 -->|讀取/寫入| Mailbox
    T3 -->|讀取/寫入| Mailbox
    T1 -->|更新狀態| TaskList
    T2 -->|更新狀態| TaskList
    T3 -->|更新狀態| TaskList

    style Lead fill:#e1f5fe,stroke:#333,color:#333
    style TaskList fill:#fff9c4,stroke:#333,color:#333
    style Mailbox fill:#f3e5f5,stroke:#333,color:#333
    style T1 fill:#e8f5e9,stroke:#333,color:#333
    style T2 fill:#e8f5e9,stroke:#333,color:#333
    style T3 fill:#e8f5e9,stroke:#333,color:#333

關鍵元件 (Key components)：

  • 團隊領導者 (Team Lead)：建立團隊、指派任務並進行協調的主 Claude Code 工作階段
  • 共享任務清單 (Shared Task List)：具有自動相依性追蹤的同步任務清單
  • 郵件箱 (Mailbox)：供團隊成員溝通狀態與協調的代理間訊息傳遞系統
  • 團隊成員 (Teammates)：獨立的 Claude Code 實例，各自擁有獨立的脈絡視窗

任務指派與訊息傳遞 (Task assignment and messaging) ​

團隊領導者將工作拆分為任務並指派給團隊成員。共享任務清單處理：

  • 自動相依性管理 (Automatic dependency management) — 任務會等待其相依任務完成
  • 狀態追蹤 (Status tracking) — 團隊成員在工作時更新任務狀態
  • 代理間訊息傳遞 (Inter-agent messaging) — 團隊成員透過郵件箱傳送訊息進行協調（例如：「資料庫 Schema 已準備就緒，您可以開始撰寫查詢」）

計劃核可工作流程 (Plan approval workflow) ​

對於複雜任務，團隊領導者會在團隊成員開始工作之前建立執行計劃。使用者審查並核可計劃，確保團隊的方法在進行任何程式碼變更前符合預期。

團隊的掛鉤事件 (Hook events for teams) ​

代理團隊引入了兩個額外的掛鉤事件 (Hook Events)：

事件 (Event)觸發時機 (Fires When)使用情境 (Use Case)
TeammateIdle團隊成員完成其目前任務且無待處理工作時觸發通知、指派後續任務
TaskCompleted共享任務清單中的任務被標記為完成時執行驗證、更新儀表板、鏈接相依工作

最佳實踐 (Best practices) ​

  • 團隊規模 (Team size)：將團隊規模保持在 3-5 名成員，以達到最佳協調效果
  • 任務大小 (Task sizing)：將工作拆分為各自需要 5-15 分鐘的任務 — 足夠小以利平行化，足夠大以確保具實質意義
  • 避免檔案衝突 (Avoid file conflicts)：將不同的檔案或目錄指派給不同的團隊成員，以防止合併衝突 (Merge Conflicts)
  • 從簡單開始 (Start simple)：在第一個團隊中使用內嵌 (In-process) 模式；熟悉後再切換至分割窗格
  • 明確的任務描述 (Clear task descriptions)：提供具體、可執行的任務描述，以便團隊成員可以獨立工作

限制 (Limitations) ​

  • 實驗性 (Experimental)：功能行為可能會在未來版本中變更
  • 無工作階段恢復 (No session resumption)：內嵌團隊成員在工作階段結束後無法恢復
  • 每個工作階段一個團隊 (One team per session)：無法在單一工作階段中建立巢狀團隊或多個團隊
  • 固定領導權 (Fixed leadership)：團隊領導者角色無法轉移給團隊成員
  • 分割窗格限制 (Split-pane restrictions)：需要 tmux/iTerm2；在 VS Code 終端機、Windows Terminal 或 Ghostty 中不可用
  • 無跨工作階段團隊 (No cross-session teams)：團隊成員僅存在於目前工作階段中

警告 (Warning)：代理團隊屬於實驗性功能。請先透過非關鍵工作進行測試，並監控團隊成員的協調情況以防出現意外行為。

外掛子代理安全性 (Plugin Subagent Security) ​

由外掛提供的子代理出於安全性考量，其 Frontmatter 功能受到限制。以下欄位在外掛子代理定義中不被允許：

  • hooks - 無法定義生命週期掛鉤 (Lifecycle Hooks)
  • mcpServers - 無法設定 MCP 伺服器 (MCP Servers)
  • permissionMode - 無法覆寫權限設定 (Permission Settings)

這可防止外掛透過子代理掛鉤提升權限或執行任意指令。

子代理輸出掃描 (Subagent Output Scanning) (v2.1.210+) ​

自 v2.1.210 起，Claude Code 會掃描每個子代理的最終報告，檢查是否存在模仿 Harness 本身輸出格式的文字 — 偽造的 <system-reminder> 樣式標籤、虛構的 Human:/Assistant: 輪次，或提及繞過權限標記與設定檔案路徑。這可以防範載於子代理輸出中的提示詞注入 (Prompt Injection)，例如擷取了包含旨在操縱父工作階段之偽造控制 Token 惡意網頁的子代理。

當掃描標記某些內容時，Claude Code 會對其進行中和 — 插入反斜線或像 [harness: subagent output matched instruction-shaped pattern(s): ...] 這樣命名觸發掃描內容的行內標記 — 並且預期父工作階段將被標記的文字視為要轉達的發現，而非要遵循的指令。掃描預設開啟且無文件記載的退出選項。它傾向於進行標記：即使未發生任何惡意行為，逐字引用真實標記名稱（例如 --dangerously-skip-permissions）的正當子代理報告也可能觸發標記 — 偽陽性 (False Positive) 比遺漏注入更可取。

子代理並發與深度限制 (Subagent Concurrency and Depth Limits) ​

每個工作階段的產生上限已移除。 Claude Code 自 v2.1.212 起將每個工作階段的子代理產生上限設為 200 個，但 v2.1.224 移除了該上限 — 長期執行的工作階段不再拒絕新代理，並且官方子代理參考資料現在明確指出 Claude 在一個工作階段中可產生的子代理總數沒有限制。用於覆寫它的 CLAUDE_CODE_MAX_SUBAGENTS_PER_SESSION 變數也隨之移除。

對子代理扇出 (Fan-out) 的兩項限制仍然適用，皆透過環境變數設定：

  • CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS (v2.1.217) - 一次同時執行的子代理最大數量。預設值：20。
  • CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH (v2.1.217) - 子代理產生自身子代理的最大巢狀深度 (Nesting Depth)。自 v2.1.219 起預設值為 3（在 v2.1.217–v2.1.218 中為 1）。將其設定為 1 可停用巢狀（請參閱 關鍵行為）。
bash
export CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS=20
export CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=5

架構 (Architecture) ​

高階架構 (High-Level Architecture) ​

mermaid
graph TB
    User["使用者 (User)"]
    Main["主代理 (Main Agent)<br/>（協調者）"]
    Reviewer["程式碼審查子代理<br/>(Code Reviewer Subagent)"]
    Tester["測試工程師子代理<br/>(Test Engineer Subagent)"]
    Docs["文件撰寫子代理<br/>(Documentation Subagent)"]

    User -->|詢問| Main
    Main -->|委派| Reviewer
    Main -->|委派| Tester
    Main -->|委派| Docs
    Reviewer -->|返回結果| Main
    Tester -->|返回結果| Main
    Docs -->|返回結果| Main
    Main -->|綜合彙整| User

子代理生命週期 (Subagent Lifecycle) ​

mermaid
sequenceDiagram
    participant User as 使用者 (User)
    participant MainAgent as 主代理 (Main Agent)
    participant CodeReviewer as 程式碼審查子代理<br/>(Code Reviewer Subagent)
    participant Context as 獨立脈絡視窗<br/>(Separate Context Window)

    User->>MainAgent: "開發新的驗證功能"
    MainAgent->>MainAgent: 分析任務
    MainAgent->>CodeReviewer: "審查這段程式碼"
    CodeReviewer->>Context: 初始化全新脈絡
    Context->>CodeReviewer: 載入審查者指示
    CodeReviewer->>CodeReviewer: 執行審查
    CodeReviewer-->>MainAgent: 返回審查結果
    MainAgent->>MainAgent: 融入結果
    MainAgent-->>User: 提供綜合彙整報告

脈絡管理 (Context Management) ​

mermaid
graph TB
    A["主代理脈絡 (Main Agent Context)<br/>50,000 個 Token"]
    B["子代理 1 脈絡 (Subagent 1 Context)<br/>20,000 個 Token"]
    C["子代理 2 脈絡 (Subagent 2 Context)<br/>20,000 個 Token"]
    D["子代理 3 脈絡 (Subagent 3 Context)<br/>20,000 個 Token"]

    A -->|全新狀態| B
    A -->|全新狀態| C
    A -->|全新狀態| D

    B -->|僅返回結果| A
    C -->|僅返回結果| A
    D -->|僅返回結果| A

    style A fill:#e1f5fe
    style B fill:#fff9c4
    style C fill:#fff9c4
    style D fill:#fff9c4

關鍵要點 (Key Points) ​

  • 每個子代理獲得一個全新的脈絡視窗 (Fresh Context Window)，不包含主對話歷史
  • 僅有相關脈絡 (Relevant Context) 會被傳遞給子代理以進行其特定任務
  • 結果會被濃縮 (Distilled) 並返回給主代理
  • 這可防止大型專案中的脈絡 Token 耗盡 (Context Token Exhaustion)

效能考量 (Performance Considerations) ​

  • 脈絡效率 (Context efficiency) - 代理保留主脈絡，實現更長的工作階段
  • 延遲 (Latency) - 子代理從全新狀態開始，收集初始脈絡時可能會增加延遲

關鍵行為 (Key Behaviors) ​

  • 預設開啟巢狀產生，深度為 3 (v2.1.219) - 子代理可在主對話下方最多三層產生自己的子代理。設定 CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH 可變更限制，或設定為 1 關閉巢狀。達到深度限制時，Claude Code 會對除 Fork 以外的每個子代理扣留 Agent 工具。（歷史：v2.1.172–v2.1.216 預設巢狀最多 5 層且無法變更；v2.1.217 使巢狀改為選擇性啟用，深度為 1；v2.1.219 將預設值設為 3。）使用 Agent(agent_type) 限制語法（請參閱 限制可產生的子代理）來控制給定子代理可產生的子代理
  • 背景權限 (Background permissions) - 背景子代理會自動拒絕任何未預先核可的權限
  • 推至背景 (Backgrounding) - 按 Ctrl+B 可將目前執行的任務推至背景
  • 逐字稿 (Transcripts) - 子代理逐字稿儲存於 ~/.claude/projects/{project}/{sessionId}/subagents/agent-{agentId}.jsonl
  • 自動壓縮 (Auto-compaction) - 子代理脈絡在大約 95% 容量時自動壓縮（使用 CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 環境變數覆寫）
  • 繼承延伸思考 (Extended thinking inherited) (v2.1.198) - 子代理與脈絡壓縮現在會繼承工作階段的延伸思考設定（以前總是停用）。沒有單獨的子代理思考欄位

額外控制 (Additional Controls) ​

  • 停用內建 Explore/Plan 代理 - 設定 CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1 可移除內建的 Explore 與 Plan 代理 (v2.1.198)
  • 附加至每個子代理提示詞 - 在非互動式 / --print 模式下，--append-subagent-system-prompt "<text>" 會將文字附加至每個子代理的系統提示詞 (v2.1.205)
  • 從檔案附加 - --append-subagent-system-prompt-file ./subagent-rules.txt 會從檔案讀取相同的附加文字，適用於過長而無法在命令列傳遞的提示詞。同樣僅限 -p，且不能與 --append-subagent-system-prompt 混合使用 (v2.1.261)

何時使用子代理 (When to Use Subagents) ​

情境 (Scenario)使用子代理 (Use Subagent)原因 (Why)
包含多個步驟的複雜功能是分離關注點 (Separate concerns)，防止脈絡污染
快速程式碼審查否不必要的額外開銷
平行任務執行是每個子代理擁有自己的脈絡
需要專業知識是自訂系統提示詞
長期執行的分析是防止主脈絡耗盡
單一任務否不必要地增加延遲

最佳實踐 (Best Practices) ​

設計原則 (Design Principles) ​

應該做 (Do)：

  • 從 Claude 產生的代理開始 - 先由 Claude 產生初始子代理，然後進行迭代自訂
  • 設計聚焦的子代理 - 擁有單一、明確的職責，而非由一個代理處理所有事情
  • 撰寫詳細的提示詞 - 包含具體指示、範例與約束條件
  • 限制工具存取 - 僅授予子代理目的所需的工具
  • 版本控制 - 將專案子代理提交至版本控制以供團隊協作

不該做 (Don't)：

  • 建立具有相同角色的重疊子代理
  • 給予子代理不必要的工具存取權
  • 對簡單的單一步驟任務使用子代理
  • 在單一子代理的提示詞中混雜不同關注點
  • 忘記傳遞必要的脈絡

系統提示詞最佳實踐 (System Prompt Best Practices) ​

  1. 明確說明角色 (Be Specific About Role)

    You are an expert code reviewer specializing in [specific areas]

  2. 清楚定義優先順序 (Define Priorities Clearly)

    Review priorities (in order):
1. Security Issues
2. Performance Problems
3. Code Quality

  3. 指定輸出格式 (Specify Output Format)

    For each issue provide: Severity, Category, Location, Description, Fix, Impact

  4. 包含行動步驟 (Include Action Steps)

    When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

工具存取策略 (Tool Access Strategy) ​

  1. 從嚴格限制開始 (Start Restrictive)：僅從必要的工具開始
  2. 僅在需要時擴充 (Expand Only When Needed)：隨著需求增加添加工具
  3. 可能時採用唯讀 (Read-Only When Possible)：對分析代理使用 Read/Grep
  4. 沙盒化執行 (Sandboxed Execution)：將 Bash 指令限制為特定模式

此資料夾中的範例子代理 (Example Subagents in This Folder) ​

此資料夾包含可直接使用的範例子代理：

1. 程式碼審查者 (code-reviewer.md) ​

目的 (Purpose)：綜合程式碼品質與可維護性分析

工具 (Tools)：Read, Grep, Glob, Bash

專長 (Specialization)：

  • 安全漏洞檢測 (Security vulnerability detection)
  • 效能最佳化識別 (Performance optimization identification)
  • 程式碼可維護性評估 (Code maintainability assessment)
  • 測試覆蓋率分析 (Test coverage analysis)

使用時機 (Use When)：您需要重點關注品質與安全性的自動化程式碼審查

2. 測試工程師 (test-engineer.md) ​

目的 (Purpose)：測試策略、覆蓋率分析與自動化測試

工具 (Tools)：Read, Write, Bash, Grep

專長 (Specialization)：

  • 單元測試撰寫 (Unit test creation)
  • 整合測試設計 (Integration test design)
  • 邊界條件識別 (Edge case identification)
  • 覆蓋率分析 (>80% 目標) (Coverage analysis)

使用時機 (Use When)：您需要建立完整的測試套件或進行覆蓋率分析

3. 文件撰寫者 (documentation-writer.md) ​

目的 (Purpose)：技術文件、API 文件與使用者指南

工具 (Tools)：Read, Write, Grep

專長 (Specialization)：

  • API 端點文件 (API endpoint documentation)
  • 使用者指南編寫 (User guide creation)
  • 架構文件編寫 (Architecture documentation)
  • 程式碼註解改善 (Code comment improvement)

使用時機 (Use When)：您需要建立或更新專案文件

4. 安全審查者 (secure-reviewer.md) ​

目的 (Purpose)：具備最小權限、專注於安全性的程式碼審查

工具 (Tools)：Read, Grep

專長 (Specialization)：

  • 安全漏洞檢測 (Security vulnerability detection)
  • 身份驗證/授權問題 (Authentication/authorization issues)
  • 資料暴露風險 (Data exposure risks)
  • 注入攻擊識別 (Injection attack identification)

使用時機 (Use When)：您需要無需修改能力的安全性稽核

5. 實作代理 (implementation-agent.md) ​

目的 (Purpose)：用於功能開發的全套實作能力

工具 (Tools)：Read, Write, Edit, Bash, Grep, Glob

專長 (Specialization)：

  • 功能實作 (Feature implementation)
  • 程式碼產生 (Code generation)
  • 建置與測試執行 (Build and test execution)
  • 程式碼庫修改 (Codebase modification)

使用時機 (Use When)：您需要子代理端到端地實作功能

6. 除錯者 (debugger.md) ​

目的 (Purpose)：針對錯誤、測試失敗與異常行為的除錯專家

工具 (Tools)：Read, Edit, Bash, Grep, Glob

專長 (Specialization)：

  • 根本原因分析 (Root cause analysis)
  • 錯誤調查 (Error investigation)
  • 測試失敗修復 (Test failure resolution)
  • 最小化修復實作 (Minimal fix implementation)

使用時機 (Use When)：您遇到 Bug、錯誤或異常行為

7. 資料科學家 (data-scientist.md) ​

目的 (Purpose)：SQL 查詢與資料洞察的資料分析專家

工具 (Tools)：Bash, Read, Write

專長 (Specialization)：

  • SQL 查詢最佳化 (SQL query optimization)
  • BigQuery 操作 (BigQuery operations)
  • 資料分析與視覺化 (Data analysis and visualization)
  • 統計洞察 (Statistical insights)

使用時機 (Use When)：您需要資料分析、SQL 查詢或 BigQuery 操作

8. 整潔程式碼審查者 (clean-code-reviewer.md) ​

目的 (Purpose)：根據整潔程式碼原則進行的可讀性與可維護性審查

工具 (Tools)：Read, Grep, Glob, Bash

專長 (Specialization)：

  • 命名、函式長度與參數數量 (Naming, function length, and argument count)
  • 重複與廢棄程式碼 (Duplication and dead code)
  • 註解品質與意圖 (Comment quality and intent)
  • 結構清晰度高於小聰明 (Structural clarity over cleverness)

使用時機 (Use When)：您希望進行獨立於正確性審查之外的風格與可維護性檢查

9. 效能最佳化者 (performance-optimizer.md) ​

目的 (Purpose)：識別並修復效能瓶頸

工具 (Tools)：Read, Edit, Bash, Grep, Glob

專長 (Specialization)：

  • 演算法複雜度與熱點路徑 (Algorithmic complexity and hot paths)
  • 記憶體配置與洩漏 (Memory allocation and leaks)
  • 快取與查詢最佳化 (Caching and query optimization)
  • 並發與 I/O 瓶頸 (Concurrency and I/O bottlenecks)

使用時機 (Use When)：程式碼有明顯可測量的緩慢且需要標靶式最佳化

安裝說明 (Installation Instructions) ​

描述您想要的子代理，並讓 Claude 建立檔案：

text
Create a project-level subagent that runs tests and fixes failures.
Give it access to Bash, Read, Edit, and Grep.

Claude 會帶有適當的 Frontmatter 撰寫 .claude/agents/<name>.md。審查產生的檔案，然後使用它。（/agents 互動式建立精靈已於 v2.1.198 移除 — 請直接詢問 Claude 或編輯檔案。）

方法 2：複製至專案 (Method 2: Copy to Project) ​

將代理檔案複製到您專案的 .claude/agents/ 目錄：

bash
# 導覽至您的專案
cd /path/to/your/project

# 如果 agents 目錄不存在則建立
mkdir -p .claude/agents

# 從此資料夾複製所有代理檔案
cp /path/to/04-subagents/*.md .claude/agents/

# 移除 README（在 .claude/agents 中不需要）
rm .claude/agents/README.md

方法 3：複製至使用者目錄 (Method 3: Copy to User Directory) ​

針對要在所有專案中使用的代理：

bash
# 建立使用者 agents 目錄
mkdir -p ~/.claude/agents

# 複製代理
cp /path/to/04-subagents/code-reviewer.md ~/.claude/agents/
cp /path/to/04-subagents/debugger.md ~/.claude/agents/
# ... 根據需要複製其他檔案

驗證 (Verification) ​

安裝後，透過列出目錄來驗證代理是否被辨識：

bash
ls .claude/agents/

您也可以詢問 Claude 在目前工作階段中有哪些子代理可用，它會報告它可以委派給的內建與自訂代理。

檔案結構 (File Structure) ​

project/
├── .claude/
│   └── agents/
│       ├── code-reviewer.md
│       ├── test-engineer.md
│       ├── documentation-writer.md
│       ├── secure-reviewer.md
│       ├── implementation-agent.md
│       ├── debugger.md
│       ├── data-scientist.md
│       ├── clean-code-reviewer.md
│       └── performance-optimizer.md
└── ...

與其他功能比較 (Comparison with Other Features) ​

功能 (Feature)使用者呼叫 (User-Invoked)自動呼叫 (Auto-Invoked)持久化 (Persistent)外部存取 (External Access)隔離脈絡 (Isolated Context)
斜線指令 (Slash Commands)是否否否否
子代理 (Subagents)是是否否是
記憶體 (Memory)自動自動是否否
MCP自動是否是否
技能 (Skills)是是否否否

整合模式 (Integration Pattern) ​

mermaid
graph TD
    User["使用者請求 (User Request)"] --> Main["主代理 (Main Agent)"]
    Main -->|使用| Memory["記憶體 (Memory)<br/>（脈絡）"]
    Main -->|查詢| MCP["MCP<br/>（即時資料）"]
    Main -->|呼叫| Skills["技能 (Skills)<br/>（自動工具）"]
    Main -->|委派| Subagents["子代理 (Subagents)<br/>（專家）"]

    Subagents -->|使用| Memory
    Subagents -->|查詢| MCP
    Subagents -->|隔離| Context["全新脈絡視窗<br/>(Clean Context Window)"]

可觀測性 (Observability) ​

新增於 v2.1.139。

源自子代理的 API 請求帶有兩個額外的 HTTP 標頭 (HTTP Headers)，以便追蹤與日誌可以關聯回分派工作階段：

標頭 (Header)說明 (Description)
x-claude-code-agent-id發出請求之子代理的 UUID。
x-claude-code-parent-agent-id分派此子代理之代理的 UUID（主代理，或鏈接中較高層級的子代理）。

相同的識別碼會在 claude_code.llm_request OpenTelemetry Span 上公開為屬性 claude.code.agent.id 與 claude.code.agent.parent_id。使用它們可以：

  • 將 API 花費歸因於特定的子代理類型，而非父工作階段
  • 事後重建代理呼叫鏈 (Invocation Chain)（parent_id 形成樹狀結構）
  • 針對失控的子代理發出警報（例如單一 agent.id 佔工作階段花費 >50%）

請參閱 進階功能 → 遙測 中的 OpenTelemetry 章節以了解端到端 Exporters 設定。

其他資源 (Additional Resources) ​

最後更新 (Last Updated)：2026 年 9 月 6 日 Claude Code 版本 (Claude Code Version)：2.1.263 來源 (Sources)：

Released under the MIT License.

Copyright © 2026 Claude Code HowTo Guide