如何在 Claude Code 中建立和使用子代理程式——實用指南

子代理程式是 Claude Code / Claude Agent 生態系統中最實用的新增功能之一：它們能夠將複雜的工作流程分解成更小、更專業的 AI“隊友”，保留主線程上下文，並安全地限制工具存取。本文將解釋 什麼是子代理, 如何創建和調用它們 （CLI、檔案系統和 SDK）， 設計原則 你在建造它們時應該遵循，並且 具體範例程式碼 你可以複製並改編。

什麼是子代理？

A 子代理 是一個預先配置的、功能有限的 AI 助手，Claude Code（或 Claude Agent SDK）可以委託其執行任務。每個子代理可以：

具有獨特的名稱和清晰的用途描述。
在其運行 自己的上下文窗口 與主要對話分開（因此長串的細節不會污染協調者的上下文）。
可以配置一組有限的工具（文件讀取/寫入、bash、grep、MCP 工具等），並具有特定的模型選擇。
包含指導行為和約束的系統提示（子代理的個性和指示）。

這些屬性使得子代理程式非常適合那些令牌密集型任務（研究、搜尋大日誌）、安全敏感任務（掃描或潛在破壞性工具）或重複且明確指定的任務（樣式檢查、測試運行）。

Anthropic 一直在快速迭代：Claude Code CLI 和 Agent SDK 已經重構並擴展到 Claude 代理 SDK，引入了對捆綁代理和相關自定義（斜線命令、MCP 伺服器、鉤子）的插件支持，以及技能提供一種打包領域工作流程的方法，以便在 Claude.ai、Claude Code 和 Agent SDK 之間重複使用。這些更新使 共用、安裝和版本 跨團隊和專案的子代理程式。如果您打算建立生產工作流程，則應評估外掛程式/技能打包以及基於 SDK 的部署模式。

為什麼子代理很重要

它們立即有用的三個原因：

上下文保存 ——冗長或吵雜的搜尋、測試運行或掃描都集中在子代理程式中，而不是淹沒在主上下文中。這減少了令牌浪費，並使結果更易於推理。
專業知識 — 您可以將領域知識和行為編碼到針對任務客製化的系統提示中（例如， security-auditor 專注於秘密、依賴問題和不安全的 shell 使用）。
更安全的權限 — 限制每個子代理程式的工具數量可以減少影響半徑（文件審閱者可能有唯讀工具；測試運行者可能有 Bash 但不是 Edit).
並行化： 您可以啟動多個子代理並發運行（例如： style-checker, security-scanner, test-runner)，然後收集他們的簡要結果——這對於昂貴的獨立檢查來說是一個巨大的勝利。

在 Claude 程式碼中使用子代理程式的先決條件

在開始建立子代理之前，請確保已做好以下準備：

1）安裝並驗證Claude程式碼

安裝 Claude Code CLI 或使用 web/IDE 整合。 CometAPI 的快速入門和設定文檔列出支援的安裝方法（npm 全域套件或本機安裝程式）並展示如何使用下列方法驗證您的安裝 claude --version / claude doctor. 你還需要一個彗星API 帳戶（使用 CometAPI 的金鑰存取 Claude 程式碼比官方模型更便宜、更方便。）如快速入門所述。

2）節點/環境（適用於某些安裝路徑）和基本 shell 工具

如果您透過 npm 套件安裝，則需要安裝 Node.js（範例中通常使用 Node 18 及以上版本）。如果您打算使用 Agent SDK（JavaScript/TypeScript 或 Python），則需要已安裝 SDK 相依性的專案。許多教學都假設您已安裝標準開發工具（git、bash、可選 gh 用於 GitHub 工作流程的 CLI)。

3）項目佈局和CLAUDE.md

最佳做法是保留 repo 等級的說明文件（CLAUDE.md）並將專案範圍的代理放入 .claude/agents/ 以便隊友繼承它們。 CLAUDE.md 檔案會自動拉入 Claude 的上下文，並協助引導跨會話的一致行為。每個子代理程式都是一個帶有 YAML 前置內容的 Markdown 檔案。最小範例：

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, probable false positives, and suggested fixes.
4. Provide a short, prioritized action list.

Return results in JSON with fields: summary, issues.

name 是小寫標識符。
description 引導自動呼叫和匹配。
tools 限制工具存取（省略繼承一切）。
model 可以 sonnet, opus, haiku，或者 inherit.

4）權限和 MCP 伺服器（可選但常見）

如果您的工作流程使用模型上下文協定 (MCP) 伺服器或外部工具（例如 Puppeteer、Sentry 和自訂 REST 工具），請確保您的 MCP 伺服器已設定並可存取。對於敏感操作（例如 write、bash、git commit），請仔細考慮允許清單和每個代理的權限。 tools 範圍界定。

如何在 Claude Code 中建立子代理

您可以透過三種主要方式建立子代理程式：透過互動式 CLI (/agents)，或透過 Agent SDK 以程式方式導入。以下是逐步選項：

Claude Code 支援三種建立子代理程式的實用方法：

互動式 CLI /agents UI — 在會話內進行迭代建立的速度最快。
基於檔案系統 — 使用 YAML 前置內容建立 Markdown 文件 .claude/agents/ （專案級）或 ~/.claude/agents/ （用戶級）。專案代理具有更高的優先權。
程式化（代理 SDK） — 透過以下方式在程式碼中定義子代理 agents 調用時的參數 query();推薦用於 SDK 驅動的應用。當子代理程式必須動態建立或嵌入到應用程式中時，此方法是理想的選擇。

快速互動流程（推薦第一步）

在終端機中啟動 Claude Code 或在 VS Code 中開啟命令面板。
使用斜線命令運行子代理程式介面：

/agents

選擇 建立新代理，選擇項目級或使用者級範圍，填寫名稱/描述/工具/系統提示，然後儲存。您可以使用 Claude 產生草稿，然後進行完善。保存後，代理將在 /agents 並且可以明確或自動調用。

基於檔案系統的子代理程式（Markdown + YAML 前言）

子代理程式儲存為 Markdown 文件，並使用 YAML 格式。請將它們放置在：

項目範圍： .claude/agents/*.md （最高優先權）
用戶範圍： ~/.claude/agents/*.md

基本文件結構：

---
name: code-reviewer
description: "Review recent code changes for security and style."
tools: Read, Grep, Glob, Bash  # optional; omit to inherit

model: sonnet  # optional; or 'inherit'

---
You are a senior code reviewer with expertise in security, performance, and best practices.
When reviewing:
- Identify security vulnerabilities
- Prioritize clarity and maintainability
- Always provide concise examples and suggested fixes
- If unsure, ask for the minimal reproducible snippet

一些實施說明：

name 必須小寫並帶有連字符。
省略 tools 將讓子代理繼承主執行緒的所有工具；明確列出工具可強制執行最小權限模型。
使用 model: 'inherit' 為了與主執行緒保持一致的行為，或指定模型別名（例如， sonnet, opus, haiku).

CLI JSON 定義（臨時/會話使用）

您可以在啟動會話時內聯定義臨時子代理程式：

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer.",
    "prompt": "You are a senior code reviewer. Focus on security and best practices.",
    "tools": ,
    "model": "sonnet"
  }
}'

CLI 定義的代理對於腳本運行或實驗很有用；它們的優先順序低於專案代理，但高於使用者代理。

程式化定義（Agent SDK－推薦用於應用程式）

如果您正在建立應用程式或自動化，請透過 Agent SDK 以程式設計方式定義子代理 agents 參數（這是最整合的選項）。範例（TypeScript）：

import { query } from '@anthropic-ai/claude-agent-sdk';

async function runReview() {
  const result = await query({
    prompt: "Assess the authentication module for security issues",
    options: {
      agents: {
        "code-reviewer": {
          description: "Expert code review specialist",
          prompt: `You are a code review specialist...`,
          tools: ,
          model: "sonnet"
        },
        "test-runner": {
          description: "Runs the test suite and analyzes failures",
          prompt: `You run tests and summarize failures...`,
          tools: ,
          model: "sonnet"
        }
      }
    }
  });

  console.log(result);
}

SDK 也接受基於檔案系統的代理程式（它將加載 .claude/agents/ 如果您更喜歡這種模式，可以使用文件。程序化代理對於動態工作流程和 CI 整合非常有效。

對於 Python， claude-agent-sdk 套件支援類似的模式：您可以使用 query() or ClaudeSDKClient 並以程式設計方式配置選項、工具和 MCP 伺服器。請參閱 Python SDK 倉庫以取得快速入門範例。

如何呼叫子代理

自動委派

克勞德·科德可以自動當使用者提示與子代理的目的相符時，選擇子代理。這對於後台編排非常有用，主代理會自動將任務分配給合適的專家。清晰的子代理描述和重點突出的系統提示可以提高自動選擇的準確性。

顯式呼叫（為了清晰起見建議這樣做）

您可以在對話中明確調用代理：

> Use the code-reviewer subagent to check my recent changes

顯式呼叫是確定性的，建議用於想要避免意外委派的生產流程。

SDK 協調器模式

SDK 應用中常見模式：

叉子+收集：並行啟動多個子代理，收集每個代理的簡潔答案，然後在主代理中匯總/合併結果。
主管循環：協調器將任務分配給子代理，檢查結果，並接受它們或要求重新計算/澄清。
沙盒執行：將潛在危險的功能（部署、運行腳本）賦予嚴格約束的代理，並在執行前要求明確的人工批准。

這些模式會對應到使用 Agent SDK 的會話管理、鉤子和 MCP 工具的實際實作。

如何製作實用、安全且可組合的子代理

1）職責單一，提示明確

每個子代理程式都應具有明確的用途，並應提供系統提示，其中應指定邊界、成功標準和輸出格式。如果所需的輸出是結構化的（JSON、項目符號清單、程式碼補丁），則應精確地指示子代理，以減少解析錯誤。

2）工具的最小權限

僅授予子代理所需的工具。例如，文件審閱者不需要 Write or Bash盡可能預設為唯讀，並在需要時明確提升工具權限。這可以降低風險並簡化審計。

3）返回緊湊、結構化的輸出

子代理應該返回 簡潔的最終答案 而不是長時間運行的思維軌跡。常見的模式是：在子代理程式的上下文中完成繁重的工作，然後傳回帶有附件（補丁、檔案參考、JSON）的簡短摘要。這最大限度地提高了編排器的上下文效率。

4）可測試性和版本控制

將子代理檔案儲存在版本控制中，建立針對小型輸入進行實際運行的持續整合測試，並固定模型/工具集。如果您依賴技能和插件，請採用插件市場/版本控制模式來管理升級和回滾。

5）審計鉤子和人工介入檢查點

使用 SDK 鉤子攔截工具呼叫（PreToolUse 鉤子），並要求破壞性操作需要手動批准。記錄所有工具調用，以便進行可重現的審計。 SDK 提供了鉤子和權限機制來支援此模式。

應用程式範例—一個小型的、類似生產的管道

以下是一個緊湊的範例，展示了典型的部分：一個檔案系統代理程式、一個使用兩個代理程式（一個用於審查，一個用於測試）的 SDK 呼叫以及一個簡單的編排。

1）檔案系統代理： `.claude/agents/code-reviewer.md`

---
name: code-reviewer
description: Use PROACTIVELY after code changes. Perform security, style, and maintainability review on modified files.
tools: Read, Grep, Glob
model: inherit
---
You are a meticulous senior code reviewer. When invoked:
1. Run `git diff --name-only` to find modified files.
2. For each modified file, read and look for security issues, suspicious patterns, or maintainability problems.
3. Return JSON:
{
  "summary": "one-line summary",
  "issues": ,
  "recommended_changes": 
}

2）程式化編排（Node.js）

import { query } from '@anthropic-ai/claude-agent-sdk';
import fs from 'fs';

async function runPipeline() {
  const result = query({
    prompt: 'Run PR checks: security review then unit tests.',
    options: {
      agents: {
        'code-reviewer': {
          description: 'Use PROACTIVELY after code changes; output JSON with issues.',
          prompt: fs.readFileSync('./.claude/agents/code-reviewer.md', 'utf8'),
          tools: ,
          model: 'sonnet'
        },
        'test-runner': {
          description: 'Run test suite and summarize failing tests.',
          prompt: `You are a test-runner. Execute tests and return JSON { summary, failing_tests[] }`,
          tools: 
        }
      }
    }
  });

  for await (const message of result) {
    // Implement streaming logic: messages may include subagent outputs
    console.log(message);
  }
}

runPipeline().catch(console.error);

注意： code-reviewer 儲存在 repo 中，供團隊重複使用；SDK 呼叫演示了程式代理的優先性，以及 tools 範圍界定可防止意外寫入。

高級主題和模式

動態代理配置

建立參數化代理工廠，根據環境（開發與生產）或嚴重程度選擇模型和工具集（例如， strict vs balanced 安全模式）。 SDK 範例展示如何在執行時間產生代理定義。

並行化

並行啟動多個唯讀分析代理程式（包括樣式、安全性、測試覆蓋率），並在主執行緒中聚合它們的 JSON 輸出。這大大縮短了大型程式碼庫的運行時間。

插件提供的代理

插件可以提供與插件清單一起打包的子代理；它們出現在 /agents 與自訂代理一起使用，並且可以明確呼叫。使用此功能可以在團隊之間分發標準化代理。

哪些地方最推薦使用Claude Code CLI

很高興地宣布 CometAPI 現在完全支援強大的 Claude Code cli。 您只需安裝Claude Code並使用取得的Comet API金鑰和基底位址進行驗證，即可在Claude Code上使用Comet API模型。

為什麼要透過 CometAPI 使用 claude 程式碼？

頂級人工智慧功能：使用專為開發人員構建的模型輕鬆生成、調試和優化程式碼。

靈活的模型選擇：我們全面的模型系列使您能夠更無縫地進行開發。
無縫整合：API 始終可用。只需幾分鐘即可將 Claude Code 直接整合到您現有的工作流程中。
透過 CometAPI 使用 Claude 程式碼將節省更多成本CometAPI提供的Claude API比官方價格優惠20%，並由官方更新最新型號。

準備好使用 Claude Code cli 了嗎？請諮詢 API指南有關詳細說明。

如果您想了解更多有關 AI 的提示、指南和新聞，請關注我們 VK, X 不和!

參見如何透過 CometAPI 安裝和運行 Claude 程式碼？

最後的思考

將子代理視為 可重複使用、版本化的微角色. 從小事做起：做一個 doc-reviewer 和 test-runner 對於 repo，請將其簽入 .claude/agents/並使用無頭 claude -p。迭代您的提示，新增結構化輸出，並加強工具權限。

最有幫助的思考模式：想像 Claude 是專案經理，而下屬則是團隊中的專家。經理負責委派措辭清晰的任務，彙總專家的可交付成果，並撰寫最終報告。隨著時間的推移，您將看到可靠性、可測試性以及自動化大量開發人員工作流程的能力的提升。

什麼是子代理？

為什麼子代理很重要

在 Claude 程式碼中使用子代理程式的先決條件

1）安裝並驗證Claude程式碼

2）節點/環境（適用於某些安裝路徑）和基本 shell 工具

3）項目佈局和CLAUDE.md

4）權限和 MCP 伺服器（可選但常見）

如何在 Claude Code 中建立子代理

快速互動流程（推薦第一步）

基於檔案系統的子代理程式（Markdown + YAML 前言）

CLI JSON 定義（臨時/會話使用）

程式化定義（Agent SDK－推薦用於應用程式）

如何呼叫子代理

自動委派

顯式呼叫（為了清晰起見建議這樣做）

SDK 協調器模式

如何製作實用、安全且可組合的子代理

1）職責單一，提示明確

2）工具的最小權限

3）返回緊湊、結構化的輸出

4）可測試性和版本控制

5）審計鉤子和人工介入檢查點

應用程式範例—一個小型的、類似生產的管道

1）檔案系統代理： `.claude/agents/code-reviewer.md`

2）程式化編排（Node.js）

高級主題和模式

動態代理配置

並行化

插件提供的代理

哪些地方最推薦使用Claude Code CLI

為什麼要透過 CometAPI 使用 claude 程式碼？

最後的思考

閱讀更多

一個 API 中超過 500 個模型

如何在 Claude Code 中建立和使用子代理程式——實用指南

什麼是子代理？

為什麼子代理很重要

在 Claude 程式碼中使用子代理程式的先決條件

1）安裝並驗證Claude程式碼

2）節點/環境（適用於某些安裝路徑）和基本 shell 工具

3）項目佈局和CLAUDE.md

4）權限和 MCP 伺服器（可選但常見）

如何在 Claude Code 中建立子代理

快速互動流程（推薦第一步）

基於檔案系統的子代理程式（Markdown + YAML 前言）

CLI JSON 定義（臨時/會話使用）

程式化定義（Agent SDK－推薦用於應用程式）

如何呼叫子代理

自動委派

顯式呼叫（為了清晰起見建議這樣做）

SDK 協調器模式

如何製作實用、安全且可組合的子代理

1）職責單一，提示明確

2）工具的最小權限

3）返回緊湊、結構化的輸出

4）可測試性和版本控制

5）審計鉤子和人工介入檢查點

應用程式範例—一個小型的、類似生產的管道

1）檔案系統代理： .claude/agents/code-reviewer.md

2）程式化編排（Node.js）

高級主題和模式

動態代理配置

並行化

插件提供的代理

哪些地方最推薦使用Claude Code CLI

為什麼要透過 CometAPI 使用 claude 程式碼？

最後的思考

閱讀更多

一個 API 中超過 500 個模型

1）檔案系統代理： `.claude/agents/code-reviewer.md`