Claude Code Agents：專用子代理完整指南

Claude Code 的 agent 系統 是其最強大的功能之一。透過 Task tool，你可以啟動專用的子代理並行工作，每個都針對特定任務進行優化。本指南涵蓋每種 agent 類型、何時使用它們，以及如何有效地組合使用。

理解 Claude Code Agents

什麼是 Agent？

根據官方文件，Claude Code 中的 agent 是一個專門的子流程，具有以下特點：

以自己的 context 自主運行
可存取特定的工具和功能
可以與其他 agents 並行工作
將結果回傳到主對話

Task Tool

Task tool 是你啟動 agents 的方式：

Task({
  subagent_type: "Explore",           // Required: Agent type
  model: "haiku",                      // Optional: haiku, sonnet, opus
  prompt: "Your task description",     // Required: What to do
  run_in_background: false             // Optional: Async execution
})

Agent 類型概覽

Agent 類型	用途	預設模型	最適合
`Explore`	快速程式碼庫導航	Haiku 4.5	檔案搜尋、模式匹配
`general-purpose`	複雜的多步驟任務	Sonnet 4.5	實作、分析
`code-reviewer`	程式碼品質分析	Sonnet 4.5	PR 審查、模式檢查
`security-auditor`	漏洞偵測	Sonnet 4.5	認證、付款程式碼
`test-runner`	測試執行	Haiku 4.5	運行、分析測試
`debugger`	根本原因分析	Sonnet 4.5	Bug 調查
`refactor-assistant`	程式碼改進	Sonnet 4.5	清理、重構
`doc-writer`	文件撰寫	Haiku/Sonnet	README、API 文件

Explore Agent

概述

Explore agent（在 v2.1.0 引入）是 Claude Code 最快速的程式碼庫導航 agent。由 Haiku 4.5 驅動，它將多個搜尋工具整合成單一高效的操作。

語法

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: `
    Explore [target] (thoroughness: [level]).
    [Specific goals]
  `
})

徹底程度等級

等級	時間	使用情境
`quick`	10-30 秒	尋找特定檔案或函式
`medium`	30-60 秒	映射模組結構和模式
`very thorough`	60-120 秒	完整流程分析

範例

快速搜尋：

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Explore authentication (thoroughness: quick). Find the login handler."
})

中等探索：

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: `
    Explore payment module (thoroughness: medium).
    Find all Stripe integration points and webhook handlers.
  `
})

徹底分析：

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: `
    Explore user authentication (thoroughness: very thorough).
    Map complete auth flow from login to session management.
    Include JWT handling, refresh tokens, and logout.
  `
})

為什麼 Explore 更快

舊方法（5 個手動步驟）：

Agent 1: Glob find *auth*.ts       → 15s
Agent 2: Grep search "JWT"         → 15s
Agent 3: Read auth/index.ts        → 10s
Agent 4: Grep find middleware      → 15s
Agent 5: Read test files           → 10s
Total: 65 seconds

新方法（1 個 Explore agent）：

Task({
  subagent_type: "Explore",
  model: "haiku",
  prompt: "Explore auth (thoroughness: medium). Map JWT, middleware, tests."
})
// Total: 30-45 seconds

general-purpose Agent

概述

general-purpose agent 處理需要深度推理的複雜多步驟任務。預設使用 Sonnet 4.5 以獲得平衡的效能。

語法

Task({
  subagent_type: "general-purpose",
  model: "sonnet",  // or "opus" for critical tasks
  prompt: "Your complex task description"
})

範例

實作：

Task({
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: `
    Implement user profile editing feature.
    - Add API endpoint for profile updates
    - Create form component with validation
    - Include image upload support
    - Follow existing patterns in src/api/
  `
})

分析：

Task({
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: `
    Analyze the current state management architecture.
    - Identify patterns and anti-patterns
    - Assess scalability
    - Recommend improvements
  `
})

重構：

Task({
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: `
    Refactor the order processing module.
    - Extract shared logic to utilities
    - Improve error handling
    - Maintain backward compatibility
  `
})

code-reviewer Agent

概述

code-reviewer agent 專精於程式碼品質分析、模式偵測和最佳實踐執行。

語法

Task({
  subagent_type: "code-reviewer",
  model: "sonnet",
  prompt: "Review [target] for [aspects]"
})

範例

PR 審查：

Task({
  subagent_type: "code-reviewer",
  model: "sonnet",
  prompt: `
    Review changes in the authentication module.
    Check for:
    - Code quality and patterns
    - Error handling
    - Test coverage
    - Documentation

    Provide findings with severity levels.
  `
})

模式檢查：

Task({
  subagent_type: "code-reviewer",
  model: "sonnet",
  prompt: `
    Review src/components/ for React best practices.
    Check:
    - Proper hook usage
    - Component structure
    - Prop validation
    - Performance optimizations
  `
})

security-auditor Agent

概述

security-auditor agent 專門用於漏洞偵測和安全最佳實踐。對於認證、付款和資料處理程式碼至關重要。

語法

Task({
  subagent_type: "security-auditor",
  model: "sonnet",  // or "opus" for critical code
  prompt: "Audit [target] for security vulnerabilities"
})

範例

認證審計：

Task({
  subagent_type: "security-auditor",
  model: "sonnet",
  prompt: `
    Audit the authentication module.
    Check for OWASP Top 10:
    - Injection vulnerabilities
    - Broken authentication
    - Sensitive data exposure
    - Broken access control

    Report findings with severity.
  `
})

付款安全：

Task({
  subagent_type: "security-auditor",
  model: "opus",  // Critical code deserves best model
  prompt: `
    Comprehensive security audit of payment processing.
    Check:
    - PCI DSS compliance
    - Data encryption
    - Token handling
    - Webhook security
    - Error message safety
  `
})

何時使用 security-auditor

情境	優先級
Auth/登入變更	高
付款程式碼	關鍵
用戶資料處理	高
API endpoints	中
檔案上傳	高
外部整合	中

test-runner Agent

概述

test-runner agent 處理測試執行、覆蓋率分析和測試結果解讀。

語法

Task({
  subagent_type: "test-runner",
  model: "haiku",
  prompt: "Run tests for [target] and analyze results"
})

範例

執行測試：

Task({
  subagent_type: "test-runner",
  model: "haiku",
  prompt: `
    Run all tests related to user authentication.
    Report:
    - Pass/fail status
    - Coverage percentage
    - Failed test details
  `
})

覆蓋率分析：

Task({
  subagent_type: "test-runner",
  model: "haiku",
  prompt: `
    Analyze test coverage for the checkout module.
    Identify:
    - Uncovered code paths
    - Edge cases missing tests
    - Integration test gaps
  `
})

debugger Agent

概述

debugger agent 專精於根本原因分析和系統性 bug 調查。

語法

Task({
  subagent_type: "debugger",
  model: "sonnet",
  prompt: "Investigate [error/issue] and find root cause"
})

範例

錯誤調查：

Task({
  subagent_type: "debugger",
  model: "sonnet",
  prompt: `
    Investigate: TypeError: Cannot read 'id' of undefined
    at CheckoutForm.handleSubmit (checkout.tsx:45)

    Context: Error occurs when submitting with empty cart.

    Find root cause and suggest fix.
  `
})

效能問題：

Task({
  subagent_type: "debugger",
  model: "sonnet",
  prompt: `
    Debug slow dashboard load (8s, should be <2s).
    Investigate:
    - Data fetching patterns
    - Render cycles
    - Database queries
    - Network waterfall
  `
})

refactor-assistant Agent

概述

refactor-assistant agent 協助進行程式碼重構、清理和改進，同時不改變功能。

語法

Task({
  subagent_type: "refactor-assistant",
  model: "sonnet",
  prompt: "Refactor [target] to improve [aspect]"
})

範例

程式碼清理：

Task({
  subagent_type: "refactor-assistant",
  model: "sonnet",
  prompt: `
    Refactor utils/helpers.ts:
    - Split into focused modules
    - Remove dead code
    - Improve naming
    - Add TypeScript types
  `
})

模式提取：

Task({
  subagent_type: "refactor-assistant",
  model: "sonnet",
  prompt: `
    Extract common patterns from API handlers.
    Create:
    - Shared error handling middleware
    - Response helpers
    - Validation utilities
  `
})

doc-writer Agent

概述

doc-writer agent 專精於創建和更新文件。

語法

Task({
  subagent_type: "doc-writer",
  model: "sonnet",  // or "haiku" for simple docs
  prompt: "Document [target]"
})

範例

API 文件：

Task({
  subagent_type: "doc-writer",
  model: "sonnet",
  prompt: `
    Document the user API endpoints.
    Include:
    - Endpoint descriptions
    - Request/response formats
    - Authentication requirements
    - Error codes
    - Examples
  `
})

README 更新：

Task({
  subagent_type: "doc-writer",
  model: "haiku",
  prompt: `
    Update README.md with:
    - New authentication flow
    - Environment variables
    - Setup instructions
  `
})

並行 Agent 模式

模式 1：分析群集

啟動多個 Explore agents 進行全面分析：

// 5 parallel Explore agents
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Map auth file structure (thoroughness: quick)" })
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Find JWT patterns (thoroughness: quick)" })
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Analyze middleware (thoroughness: medium)" })
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Check auth tests (thoroughness: quick)" })
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Review recent changes (thoroughness: quick)" })

模式 2：實作與審查

同時建構和驗證：

// Phase 1: Implementation
Task({
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: "Implement user profile feature"
})

// Phase 2: Parallel review (after Phase 1)
Task({ subagent_type: "code-reviewer", model: "sonnet",
  prompt: "Review code quality" })
Task({ subagent_type: "security-auditor", model: "sonnet",
  prompt: "Security review" })
Task({ subagent_type: "test-runner", model: "haiku",
  prompt: "Run and analyze tests" })

模式 3：多檔案重構

將工作分配給並行 agents：

// Each agent handles one file
Task({ subagent_type: "general-purpose", model: "sonnet",
  prompt: "Refactor payment/checkout.ts to new pattern" })
Task({ subagent_type: "general-purpose", model: "sonnet",
  prompt: "Refactor payment/subscription.ts to new pattern" })
Task({ subagent_type: "general-purpose", model: "sonnet",
  prompt: "Refactor payment/refund.ts to new pattern" })
Task({ subagent_type: "general-purpose", model: "sonnet",
  prompt: "Update payment/types.ts for new pattern" })
Task({ subagent_type: "test-runner", model: "haiku",
  prompt: "Update payment tests for new pattern" })

模式 4：Bug 調查

並行假設測試：

// Investigate multiple theories simultaneously
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Search for session handling changes (thoroughness: quick)" })
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Check for race conditions (thoroughness: medium)" })
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Review error logs (thoroughness: quick)" })
Task({ subagent_type: "Explore", model: "haiku",
  prompt: "Find timeout configurations (thoroughness: quick)" })
Task({ subagent_type: "debugger", model: "sonnet",
  prompt: "Analyze most likely root cause from exploration" })

模型選擇指南

任務類型	模型	成本	速度
快速搜尋	Haiku 4.5	$	⚡⚡⚡
模式匹配	Haiku 4.5	$	⚡⚡⚡
測試運行	Haiku 4.5	$	⚡⚡⚡
簡單文件	Haiku 4.5	$	⚡⚡⚡
程式碼審查	Sonnet 4.5	$$	⚡⚡
實作	Sonnet 4.5	$$	⚡⚡
除錯	Sonnet 4.5	$$	⚡⚡
安全審計	Sonnet/Opus	$$-$$$	⚡-⚡⚡
架構	Opus 4.5	$$$	⚡

成本/速度權衡：

Haiku 4.5：比 Sonnet 快 2 倍，成本為 1/3
Sonnet 4.5：最佳程式碼效能
Opus 4.5：最高智力，預設 Thinking Mode

背景 Agents

對於長時間運行的任務，使用 run_in_background：

Task({
  subagent_type: "security-auditor",
  model: "opus",
  prompt: "Comprehensive security audit of entire codebase",
  run_in_background: true
})

檢查背景任務：

TaskOutput({ task_id: "...", block: false })

最佳實踐

1. 選擇正確的 Agent

檔案搜尋 → Explore (haiku)
實作 → general-purpose (sonnet)
程式碼品質 → code-reviewer (sonnet)
安全 → security-auditor (sonnet/opus)
測試 → test-runner (haiku)
Bug → debugger (sonnet)
清理 → refactor-assistant (sonnet)
文件 → doc-writer (haiku/sonnet)

2. 保持提示聚焦

太廣泛：

"Analyze everything about the codebase"

聚焦：

"Explore authentication module (thoroughness: medium). Find JWT handling and session management."

3. 提供上下文

Task({
  subagent_type: "general-purpose",
  model: "sonnet",
  prompt: `
    Context: Migrating from REST to GraphQL.
    Pattern: Use new ApiClient from src/lib/api.ts

    Task: Refactor user service to use GraphQL.
  `
})

4. 盡可能使用並行

獨立任務應同時運行：

// These are independent - run in parallel
Task({ ..., prompt: "Analyze file A" })
Task({ ..., prompt: "Analyze file B" })
Task({ ..., prompt: "Analyze file C" })

5. 串聯相依任務

順序任務應分階段進行：

Phase 1: Explore (gather context)
Phase 2: Implement (with context from Phase 1)
Phase 3: Review (verify Phase 2)

開始使用

今天：

嘗試一個 thoroughness: medium 的 Explore agent
對最近的變更使用 code-reviewer
在下一次實作後運行 test-runner

本週：

實作分析群集模式
對敏感程式碼使用 security-auditor
嘗試並行實作與審查

本月：

為你的工作流程開發 agent 組合
優化模型選擇以平衡成本/效能
為常見模式創建模板

Claude Code agents 改變了你的工作方式——從順序提示轉變為並行編排。精通它們可解鎖 5-10 倍的效率提升。

來源：Claude Code Documentation、Claude Code GitHub、CHANGELOG