建立子代理

建立子代理

摘要逐字稿

Claude Code 內建了子代理，但您也可以建立自己的子代理。自訂子代理專精於特定任務——例如審查程式碼、撰寫測試或檢查文件。它們被定義為帶有 YAML frontmatter 的 markdown 檔案，用來告訴 Claude 何時使用該子代理以及該子代理應如何運作。

建立子代理最簡單的方法是請 Claude 為您撰寫。描述您想要的子代理以及要儲存的位置，Claude 就會寫出該檔案。本課程中的影片和前三張截圖展示的是 /agents 精靈，該精靈已在 Claude Code v2.1.198 中移除。子代理檔案及其欄位並未改變，因此您仍需選擇範圍、工具、模型和顏色。請在您的請求中包含這些選擇。

首先，選擇您子代理的範圍。.claude/agents/ 中的檔案屬於專案層級，而 ~/.claude/agents/ 中的檔案屬於使用者層級：

專案層級 —— 僅在目前專案中可用
使用者層級 —— 在您機器上的所有專案間共用

接下來，您可以選擇如何建立它。您可以手動撰寫設定，但建議的做法是讓 Claude 為您產生。只需描述您希望子代理執行的任務，Claude 就會根據您的輸入產生名稱、描述和系統提示。

Claude Code 中的 /agents create-new-agent 流程，建立方式包括「Generate with Claude (recommended)」和「Manual configuration」

自訂工具

在建立過程中，您有機會自訂子代理可以存取哪些工具。工具類別包括：

唯讀工具
編輯工具
執行工具
MCP 工具
其他工具

代理建立的「Select tools」步驟，顯示 All tools、Read-only tools、Edit tools、Execution tools、MCP tools 和 Other tools 的核取方塊

請思考您的子代理實際需要什麼。程式碼審查者可能不需要編輯工具——它應該讀取和分析程式碼，而不是修改它。不過，您可能想保留執行工具的啟用狀態，以便更容易識別待處理的變更。

選擇模型和顏色

設定完工具後，您要選擇哪個 Claude 模型來驅動該子代理。您的選項包括：

Haiku —— 最適合快速、輕量的任務
Sonnet —— 在速度與深度之間取得良好平衡
Opus —— 最適合複雜分析
Inherit —— 使用您主對話目前執行的任何模型

最後，您選擇一種顏色。這會顯示在 UI 中，讓您能快速分辨哪個子代理正在運作。這是個小細節，但在您同時執行多個子代理時會很有幫助。

代理建立的「Choose background color」步驟，顯示顏色清單以及以青色標示的 code-quality-reviewer 名稱預覽

設定檔

建立完成後，子代理設定檔會儲存在您所選範圍對應的資料夾中（對於專案層級的子代理，通常是 .claude/agents/your-agent-name.md）。以下是典型子代理設定的樣貌：

markdown

---
name: code-quality-reviewer
description: Use this agent when you need to review recently written or modified code for quality, security, and best practice compliance.
tools: Bash, Glob, Grep, Read, WebFetch, WebSearch
model: sonnet
color: purple
---

You are an expert code reviewer specializing in quality assurance, security best practices, and
adherence to project standards. Your role is to thoroughly examine recently written or modified code
and identify issues that could impact reliability, security, maintainability, or performance.

讓我們逐一說明每個欄位：

name —— 子代理的唯一識別碼。這是您引用它的方式，可以直接請 Claude 使用，或在訊息中輸入 @agent-code-quality-reviewer。
description —— 控制 Claude 何時決定使用該子代理。這必須是單行內容（如果需要換行，請使用跳脫的換行字元 \n）。您可以在此處包含範例對話，以幫助 Claude 理解何時適合委派任務。
tools —— 列出該子代理可以存取的工具。Claude 會根據您的請求填入此欄位，但您隨時可以在此編輯清單。
model —— 指定要使用哪個 Claude 模型：可以是別名（sonnet、opus、haiku 或 fable）、完整的模型 ID（例如 claude-sonnet-5），或 inherit。
color —— 用於識別該子代理的 UI 顏色。

系統提示

markdown 檔案的主體（YAML frontmatter 以下的所有內容）就是系統提示。這裡是您給予子代理指示的地方：它應該專注於什麼、應該如何分析事物，以及應該如何向主代理回報發現。

一個撰寫良好的系統提示，決定了子代理是有用的還是抓不到重點的。請具體說明子代理應該尋找什麼，以及應該如何組織其輸出。

讓 Claude 自動使用您的子代理

如果您希望 Claude 在您未明確要求的情況下就將任務委派給該子代理，請在描述欄位中加入「proactively」這個詞。例如：

yaml

description: Proactively suggest running this agent after major code changes...

您也可以在描述中加入範例對話，以幫助 Claude 理解應該使用該子代理的特定情境。您的範例越具體，Claude 就越能準確判斷何時該委派任務。

測試您的子代理

建立子代理後，透過進行一些程式碼變更並請 Claude 審查來測試它。如果在您的工作階段開始時 agents 資料夾尚不存在，請先重新啟動 Claude Code 以載入新的子代理。

一個開啟了 FastAPI 專案的程式碼編輯器，側邊面板中的 Claude Code 被要求使用 code-reviewer 子代理來審查最近的變更

如果該子代理在您預期應該被使用時卻沒有被使用，請回頭檢查描述內容。加入更具體的範例和觸發情境，有助於 Claude 理解何時該將工作委派給您的子代理。