Claude Code Agents: 専門サブエージェント完全ガイド

Claude Codeのエージェントシステムは、最も強力な機能の一つです。Task toolを通じて、特定のタスクに最適化された専門サブエージェントを並列で生成できます。本ガイドでは、すべてのエージェントタイプ、使用タイミング、効果的な組み合わせ方を解説します。

現在の名称（2026 年 7 月）： Claude Code は v2.1.63 で Task tool を Agent に改名しました。既存の Task(...) は互換エイリアスとして動作しますが、新しい permissions と agent 定義では Agent を使ってください。

2026年10月21日更新： Claude Code v2.1.305 に合わせ、組み込みの Explore と general-purpose がメイン会話のモデルを既定で使うこと、Anthropic API では haiku・sonnet・opus・fable がそれぞれ Haiku 5.5・Sonnet 5.5・Opus 5.5・Fable 5.1 を指すこと、以下の専門エージェントが組み込みではなくカスタム定義であること、削除された TaskOutput ツールに代わるバックグラウンド結果の確認方法を反映しました。

Claude Code Agentsの理解

エージェントとは？

公式ドキュメントによると、Claude Codeにおけるエージェントとは、以下の特徴を持つ専門サブプロセスです：

独自のコンテキストで自律的に動作
特定のツールと機能にアクセス可能
他のエージェントと並列実行可能
結果をメイン会話に返却

Task Tool

Task toolはエージェントを生成する方法です：

Task({
  subagent_type: "Explore",           // Optional: agent type (omit for general-purpose)
  description: "Map auth module",     // Required: short task label
  prompt: "Your task description",     // Required: What to do
  model: "haiku",                      // Optional: haiku, sonnet, opus, fable
  effort: "medium",                    // Optional: low–max, model permitting (v2.1.292+)
  run_in_background: true              // Optional: background is already the default
})

エージェントタイプ概要

エージェントタイプ	用途	モデル	最適な用途
`Explore`（組み込み）	高速コードベースナビゲーション	メイン会話のモデル	ファイル検索、パターン
`general-purpose`（組み込み）	複雑なマルチステップタスク	メイン会話のモデル	実装、分析
`code-reviewer`（カスタム）	コード品質分析	`sonnet`（Sonnet 5.5）	PRレビュー、パターン
`security-auditor`（カスタム）	脆弱性検出	`sonnet`（Sonnet 5.5）	認証、決済コード
`test-runner`（カスタム）	テスト実行	`haiku`（Haiku 5.5）	テスト実行、分析
`debugger`（カスタム）	根本原因分析	`sonnet`（Sonnet 5.5）	バグ調査
`refactor-assistant`（カスタム）	コード改善	`sonnet`（Sonnet 5.5）	クリーンアップ、再構築
`doc-writer`（カスタム）	ドキュメント作成	`haiku` / `sonnet`	README、API ドキュメント

Claude Code に組み込まれているのは Explore と general-purpose（ほかに Plan といくつかの補助エージェント）だけです。残りの6つはカスタムサブエージェントなので、.claude/agents/ または ~/.claude/agents/ にエージェントごとの Markdown ファイルを作成し（またはプラグインからインストールし）、frontmatter で model を指定します。表のエイリアスは Anthropic API ではそれぞれ Haiku 5.5・Sonnet 5.5・Opus 5.5 を指しますが、Amazon Bedrock、Google Cloud’s Agent Platform、Microsoft Foundry、Claude Platform on AWS では一部のエイリアスが Haiku 4.5 などの旧モデルを指します。

Explore Agent

概要

Explore agent（v2.0.17で導入）は、Claude Codeに組み込まれた読み取り専用のコードベースナビゲーションエージェントで、複数の検索ツールを単一の効率的な操作に統合します。当初は Haiku で動作していましたが、v2.1.198 以降はメイン会話のモデルを使います（Anthropic API または Claude サブスクリプションの Fable セッションでは代わりに Opus を使用）。以下の例では探索コストを抑えるために model: "haiku" を渡しており、これは現在 Anthropic API では Haiku 5.5 を意味します。これを既定にしたい場合は、model: haiku を指定した独自の Explore エージェントを定義すると組み込み版を上書きできます。

構文

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は、より深い推論が必要な複雑なマルチステップタスクを処理します。model を指定しない場合は、設定した CLAUDE_CODE_SUBAGENT_MODEL、未設定ならメイン会話のモデル（Pro、Max、Team、Enterprise、Anthropic API では既定で Opus 5.5）を使います。バランスの取れたパフォーマンスが必要なら model: "sonnet"（Sonnet 5.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: "fable",  // Critical code deserves the top tier
  prompt: `
    Comprehensive security audit of payment processing.
    Check:
    - PCI DSS compliance
    - Data encryption
    - Token handling
    - Webhook security
    - Error message safety
  `
})

security-auditorを使用するタイミング

シナリオ	優先度
認証/ログイン変更	高
決済コード	最重要
ユーザーデータ処理	高
APIエンドポイント	中
ファイルアップロード	高
外部連携	中

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は、根本原因分析と体系的なバグ調査に特化しています。

構文

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
  `
})

並列エージェントパターン

パターン1：分析スウォーム

包括的な分析のために複数のExplore agentを起動：

// 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：マルチファイルリファクタリング

並列エージェント間で作業を分割：

// 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：バグ調査

並列仮説テスト：

// 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 5.5	$	⚡⚡⚡
パターンマッチング	Haiku 5.5	$	⚡⚡⚡
テスト実行	Haiku 5.5	$	⚡⚡⚡
シンプルなドキュメント	Haiku 5.5	$	⚡⚡⚡
コードレビュー	Sonnet 5.5	$$	⚡⚡
実装	Sonnet 5.5	$$	⚡⚡
デバッグ	Sonnet 5.5	$$	⚡⚡
セキュリティ監査	Sonnet 5.5 / Opus 5.5	$$-$$$	⚡-⚡⚡
アーキテクチャ	Opus 5.5 / Fable 5.1	$$$	⚡

コスト/速度のトレードオフ：

Haiku 5.5: 最速・最安で、effort を調整できる初の Haiku（既定は medium）。検索や大規模なファンアウトタスクに最適
Sonnet 5.5: Opus 5.5 を補完する、より高速・低コストなモデル。日常的なコーディング向け
Opus 5.5: Pro、Max、Team、Enterprise、Anthropic API の既定モデルで、Anthropic が多くの作業の出発点として推奨。/fast モードで高速出力に対応
Fable 5.1: 一般提供モデルとして最高の知性。高度な推論や長期にわたるエージェント作業向けで、既定にはならないため model: "fable" で明示的に指定

v2.1.292 以降、Claude はサブエージェントの呼び出しごとに effort を渡せるようになり、カスタムエージェントは frontmatter で effort を設定できます。Amazon Bedrock、Google Cloud’s Agent Platform、Microsoft Foundry、Claude Platform on AWS では haiku は引き続き Haiku 4.5 を指し、Haiku 4.5 は effort に対応していません。

バックグラウンドエージェント

Claude がメイン会話から起動するサブエージェントは既定でバックグラウンド実行されます（対話型ターミナルセッションでは v2.1.232 以降）。そのため実行中も作業を続けられます。長時間実行タスクでは、引き続き run_in_background を明示的に指定することもできます：

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

バックグラウンドタスクの確認：TaskOutput ツールは v2.1.277 で削除されました。バックグラウンドのサブエージェントの結果は、後のターンで完了通知として Claude に届き、バックグラウンドコマンドの出力ファイルは Claude が Read で読み取ります。自分で進捗を確認するには /tasks（エイリアス /bashes）を実行すると、実行中および完了直後のサブエージェントと、それぞれが使っているモデルが一覧表示されます：

/tasks

ベストプラクティス

1. 適切なエージェントを選択

File search → Explore (haiku)
Implementation → general-purpose (sonnet)
Code quality → code-reviewer (sonnet)
Security → security-auditor (sonnet/opus)
Testing → test-runner (haiku)
Bugs → debugger (sonnet)
Cleanup → refactor-assistant (sonnet)
Docs → 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 で1つのExplore agentを試す
最近の変更にcode-reviewerを使用
次の実装後にtest-runnerを実行

今週：

分析スウォームパターンを実装
機密コードにsecurity-auditorを使用
レビュー付き並列実装を試す

今月：

ワークフロー用のエージェント組み合わせを開発
コスト/パフォーマンスのモデル選択を最適化
一般的なパターン用のテンプレートを作成

Claude Code agents は独立した作業をメインコンテキストから分離し、同時に進められます。得られるのは、より良いコンテキスト管理と、タスクが本当に独立している場合の待ち時間短縮であり、固定倍率の保証ではありません。

出典: Claude Code Documentation, Subagents, Claude Code GitHub, CHANGELOG