sub-agent-patterns

Claude Code のサブエージェント

ステータス：本番環境対応 ✅ 最終更新日：2026-02-02 ソース：https://code.claude.com/docs/en/sub-agents

サブエージェントは、Claude Code がタスクを委任できる、専門性を備えた AI アシスタントです。各サブエージェントは独自のコンテキストウィンドウ、設定可能なツール、カスタムのシステムプロンプトを持ちます。

---

サブエージェントを使う理由：コンテキストの整理

サブエージェントの主な価値は、専門性ではなく、メインのコンテキストをクリーンに保つことです。

エージェントなし（コンテキストの肥大化）：

Main context accumulates:
├─ git status output (50 lines)
├─ npm run build output (200 lines)
├─ tsc --noEmit output (100 lines)
├─ wrangler deploy output (100 lines)
├─ curl health check responses
├─ All reasoning about what to do next
└─ Context: 📈 500+ lines consumed

エージェントあり（コンテキストの整理）：

Main context:
├─ "Deploy to cloudflare"
├─ [agent summary - 30 lines]
└─ Context: 📊 ~50 lines consumed

Agent context (isolated):
├─ All verbose tool outputs
├─ All intermediate reasoning
└─ Discarded after returning summary

計算例：デプロイのワークフローでは、ツール呼び出しが約10回発生します。エージェントを使わない場合、メインのコンテキストには500行以上が追加されますが、エージェントを使えば30行の要約で済みます。セッションを重ねると、この差は大幅に広がります。

特に効果を発揮する場面：

• 繰り返し実行するワークフロー（デプロイ、移行、監査、レビュー）
• 出力が長いツール（ビルドログ、テスト結果、API レスポンス）
• 最終結果だけが重要な複数ステップの操作
• コンテキストへの負荷が高まる長時間のセッション

重要なポイント：エージェントは専門化のためだけでなく、繰り返し実行するワークフローに使いましょう。コンテキストの節約効果は時間とともに積み重なります。

---

組み込みサブエージェント

Claude Code には、すぐに使える組み込みサブエージェントが3つ含まれています。

Explore エージェント

コードベースの読み取り専用の探索に特化した、高速で軽量なエージェントです。

プロパティ	値
モデル	Haiku（高速、低レイテンシ）
モード	厳密な読み取り専用
ツール	Glob、Grep、Read、Bash（読み取り専用：ls、git status、git log、git diff、find、cat、head、tail）

詳細度のレベル（呼び出し時に指定）：

• quick - 高速検索、対象を絞った検索
• medium - 速度と詳細度のバランスが取れた調査
• very thorough - 複数の場所を対象とした包括的な分析

Claude が使用する場面：コードベースを変更せずに検索・把握する場合です。調査結果によってメインの会話が肥大化することはありません。

User: Where are errors from the client handled?
Claude: [Invokes Explore with "medium" thoroughness]
       → Returns: src/services/process.ts:712

Plan エージェント

プランモードでの調査と情報収集に特化しています。

プロパティ	値
モデル	Sonnet
モード	読み取り専用の調査
ツール	Read、Glob、Grep、Bash
呼び出し	プランモードで自動的に呼び出されます

Claude が使用する場面：プランモードで、計画を作成するためにコードベースを調査する場合です。無限のネストを防ぎます（サブエージェントはサブエージェントを起動できません）。

汎用エージェント

探索と操作の両方が必要な、複雑で複数ステップにわたるタスクに対応できるエージェントです。

プロパティ	値
モデル	Sonnet
モード	読み取りおよび書き込み
ツール	すべてのツール
用途	複雑な調査、複数ステップの操作、コードの変更

Claude が使用する場面：

• タスクに調査と変更の両方が必要な場合
• 検索結果の解釈に複雑な推論が必要な場合
• 複数の方法を検討する必要がある場合
• タスクに依存関係のある複数のステップが含まれる場合

---

カスタムサブエージェントの作成

ファイルの場所

種類	場所	適用範囲	優先度
プロジェクト	.claude/agents/	現在のプロジェクトのみ	最も高い
ユーザー	~/.claude/agents/	すべてのプロジェクト	低い
CLI	--agents '{...}'	現在のセッション	中間

名前が競合する場合は、プロジェクトレベルのものが優先されます。

⚠️ 重要：セッションの再起動が必要です

エージェントはセッションの開始時にのみ読み込まれます。セッション中に新しいエージェントファイルを作成した場合：

1. /agents に表示されません
2. Claude はエージェントを呼び出せません
3. 解決方法：Claude Code のセッションを再起動して、新しいエージェントを読み込みます

カスタムエージェントが「動作しない」最も一般的な原因は、セッション開始後に作成されていることです。

ファイル形式

YAML フロントマターを含む Markdown ファイル：

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: inherit
permissionMode: default
skills: project-workflow
hooks:
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

Your sub-agent's system prompt goes here.

Include specific instructions, best practices, and constraints.

設定フィールド

フィールド	必須	説明
name	はい	一意の識別子（小文字、ハイフン）
description	はい	Claude がこのエージェントを使用する条件
tools	いいえ	カンマ区切りのリスト。完全に省略すると、MCP を含むすべてのツールを継承します
model	いいえ	sonnet、opus、haiku、または inherit。デフォルト：sonnet
permissionMode	いいえ	default、acceptEdits、dontAsk、bypassPermissions、plan、ignore
skills	いいえ	自動ロードするカンマ区切りのスキル（サブエージェントは親のスキルを継承しません）
hooks	いいえ	PreToolUse、PostToolUse、Stop のイベントハンドラー

MCP ツールの継承（重要）

サブエージェントから MCP ツールにアクセスするには、tools フィールドを必ず完全に省略してください。

tools フィールドにツールを1つでも指定すると、そのフィールドは許可リストになります。ワイルドカード構文はありません。

# ❌ WRONG - "*" is interpreted literally as a tool named "*", not a wildcard
tools: Read, Grep, Glob, "*"

# ❌ WRONG - this is an allowlist, agent cannot access MCP tools
tools: Read, Grep, Glob

# ✅ CORRECT - omit tools field entirely to inherit ALL tools including MCP
# tools field omitted
model: sonnet

重要なポイント："*" は有効なワイルドカード構文ではありません。解析時に、存在しないツール名の文字列として扱われます。

エージェントの再起動が必要です：エージェント設定ファイルの変更は、Claude Code のセッションを再起動して初めて有効になります。

利用可能なツールの一覧

サブエージェントに割り当てられるツールの完全な一覧です。

ツール	用途	種類
Read	ファイル（テキスト、画像、PDF、ノートブック）を読み取ります	読み取り専用
Write	ファイルを作成または上書きします	書き込み
Edit	ファイル内の文字列を完全一致で置換します	書き込み
MultiEdit	1つのファイルに対する一括編集を行います	書き込み
Glob	ファイルパターンで検索します（**/*.ts）	読み取り専用
Grep	正規表現でコンテンツを検索します（ripgrep）	読み取り専用
LS	ディレクトリの内容を一覧表示します	読み取り専用
Bash	シェルコマンドを実行します	実行
BashOutput	バックグラウンドシェルの出力を取得します	実行
KillShell	バックグラウンドシェルを終了します	実行
Task	サブエージェントを起動します	オーケストレーション
WebFetch	Web コンテンツを取得して分析します	Web
WebSearch	Web を検索します	Web
TodoWrite	タスクリストを作成・管理します	整理
TodoRead	現在のタスクリストを読み取ります	整理
NotebookRead	Jupyter ノートブックを読み取ります	ノートブック
NotebookEdit	Jupyter ノートブックのセルを編集します	ノートブック
AskUserQuestion	ユーザーに対話形式で質問します	UI
EnterPlanMode	計画モードに入ります	計画
ExitPlanMode	計画を提示して計画モードを終了します	計画
Skill	会話内でスキルを実行します	スキル
LSP	Language Server Protocol と連携します	高度
MCPSearch	MCP ツールを検索します	高度

エージェントの種類別ツールアクセスパターン：

エージェントの種類	推奨ツール	備考
読み取り専用のレビュアー	Read, Grep, Glob, LS	書き込み機能はありません
ファイル作成エージェント	Read, Write, Edit, Glob, Grep	⚠️ Bash は使用しません — 承認要求の連発を回避します
スクリプト実行エージェント	Read, Write, Edit, Glob, Grep, Bash	CLI の実行が必要な場合に使用します
リサーチエージェント	Read, Grep, Glob, WebFetch, WebSearch	外部へのアクセスは読み取り専用です
ドキュメント作成エージェント	Read, Write, Edit, Glob, Grep, WebFetch	ワークフローをすっきりさせるため Bash は使用しません
オーケストレーター	Read, Grep, Glob, Task	ツールを最小限にし、専門エージェントに委任します
フルアクセス	tools フィールドを省略（すべてを継承）	必要な場合に限って使用してください

⚠️ ツールアクセスの原則：エージェントに Bash が不要なら、Bash を付与しないでください。Bash コマンドを実行するたびに承認が必要となり、ワークフローが中断されます。詳しくは、以下の「Bash の承認要求の連発を避ける」を参照してください。

Bash の承認リクエストの連発を避ける（重要）

サブエージェントのツール一覧に Bash が含まれていると、ファイルの作成に Write ツールではなく、cat > file << 'EOF' のヒアドキュメントを使うことがよくあります。Bash コマンドは種類ごとにユーザーの承認が必要になるため、次の問題が発生します。

• エージェントの実行ごとに何十回も承認を求められる
• ワークフローが遅くなり、ストレスがたまる
• レビューしづらい（ヒアドキュメントは、内容が圧縮された長いテキストの塊になる）

根本原因：

1. モデルはファイル操作に Bash を使いがちです — 学習データがシェルコマンドに偏っているためです
2. ツール一覧に Bash があると Bash が使われます — Write ツールが使える場合でも同様です
3. 指示が埋もれてしまいます — 450 行のプロンプトの 300 行目にある「Bash を使わない」というルールは無視されがちです

解決策（推奨順）：

1. 必要ない場合は、ツール一覧から Bash を削除します：

   # Before - causes approval spam
   tools: Read, Write, Edit, Glob, Grep, Bash
   
   # After - clean file operations
   tools: Read, Write, Edit, Glob, Grep
   

   エージェントがファイルを作成するだけなら、Bash は必要ありません。必要なスクリプトはオーケストレーターが後から実行できます。

2. 重要な指示を最初に記載します（フロントマターの直後）：

   ---
   name: site-builder
   tools: Read, Write, Edit, Glob, Grep
   model: sonnet
   ---
   
   ## ⛔ CRITICAL: USE WRITE TOOL FOR ALL FILES
   
   **You do NOT have Bash access.** Create ALL files using the **Write tool**.
   
   ---
   
   [rest of prompt...]
   

   冒頭にある指示は守られます。300 行も下に埋もれた指示は無視されます。

3. 矛盾する指示を削除します：

   # BAD - contradictory
   Line 75: "Copy images with `cp -r intake/images/* build/images/`"
   Line 300: "NEVER use cp, mkdir, cat, or echo"
   
   # GOOD - consistent
   Only mention the pattern you want used. Remove all bash examples if you want Write tool.
   

Bash を残す場合：

• エージェントが外部 CLI（wrangler、npm、git）を実行する必要がある
• エージェントがスクリプトを実行する必要がある
• エージェントがコマンドの出力を確認する必要がある

テスト：Bash を削除する前と後の比較：

• 前（Bash あり）：ヒアドキュメントの承認リクエストが 11 回以上発生し、誤ったパターンが適用される
• 後（Bash なし）：ほとんどが Write ツールの使用になり、正しいパターンが適用され、承認リクエストは最小限になる

/agents コマンドの使用（推奨）

/agents

次の操作を行うためのインタラクティブメニューです。

• すべてのサブエージェント（組み込み、ユーザー、プロジェクト）を表示する
• ガイドに沿って新しいサブエージェントを作成する
• 既存のサブエージェントとツールへのアクセス権を編集する
• カスタムサブエージェントを削除する
• アクティブなサブエージェントを確認する

CLI の設定

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"
  }
}'

---

サブエージェントの使用

自動委任

Claude は次の内容に基づいて、積極的にタスクを委任します。

• リクエスト内のタスクの説明
• サブエージェント設定の description フィールド
• 現在のコンテキストと利用可能なツール

ヒント：自動的に呼び出されやすくするには、説明に「use PROACTIVELY」または「MUST BE USED」を含めてください。

明示的な呼び出し

> 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

再開可能なサブエージェント

サブエージェントを再開して、以前の会話を続けることができます。

# Initial invocation
> Use the code-analyzer agent to review the auth module
[Agent completes, returns agentId: "abc123"]

# Resume with full context
> Resume agent abc123 and now analyze the authorization logic

ユースケース：

• 複数のセッションにまたがる長期的な調査
• コンテキストを失わずに反復的に改善する
• コンテキストを維持した複数ステップのワークフロー

サブエージェントの無効化

settings.json の権限設定に追加します。

{
  "permissions": {
    "deny": ["Task(Explore)", "Task(Plan)"]
  }
}

または CLI から実行します。

claude --disallowedTools "Task(Explore)"

---

エージェントのオーケストレーション

サブエージェントはほかのサブエージェントを呼び出すことができ、高度なオーケストレーションパターンを実現できます。これを行うには、エージェントのツール一覧に Task ツールを含めます。

仕組み

サブエージェントが Task ツールを利用できる場合、次の操作を行えます。

• ほかのサブエージェント（組み込みまたはカスタム）を起動する
• 専門分野ごとに並行作業を調整する
• 複数フェーズのワークフローでエージェントを連鎖させる

---
name: orchestrator
description: Orchestrator agent that coordinates other specialized agents. Use for complex multi-phase tasks.
tools: Read, Grep, Glob, Task  # ← Task tool enables agent spawning
model: sonnet
---

オーケストレーターパターン

---
name: release-orchestrator
description: Coordinates release preparation by delegating to specialized agents. Use before releases.
tools: Read, Grep, Glob, Bash, Task
---

You are a release orchestrator. When invoked:

1. Use Task tool to spawn code-reviewer agent
   → Review all uncommitted changes

2. Use Task tool to spawn test-runner agent
   → Run full test suite

3. Use Task tool to spawn doc-validator agent
   → Check documentation is current

4. Collect all reports and synthesize:
   - Blockers (must fix before release)
   - Warnings (should address)
   - Ready to release: YES/NO

Spawn agents in parallel when tasks are independent.
Wait for all agents before synthesizing final report.

実践例

複数の専門家によるワークフロー：

User: "Prepare this codebase for production"

orchestrator agent:
  ├─ Task(code-reviewer) → Reviews code quality
  ├─ Task(security-auditor) → Checks for vulnerabilities
  ├─ Task(performance-analyzer) → Identifies bottlenecks
  └─ Synthesizes findings into actionable report

並行調査：

User: "Compare these 5 frameworks for our use case"

research-orchestrator:
  ├─ Task(general-purpose) → Research framework A
  ├─ Task(general-purpose) → Research framework B
  ├─ Task(general-purpose) → Research framework C
  ├─ Task(general-purpose) → Research framework D
  ├─ Task(general-purpose) → Research framework E
  └─ Synthesizes comparison matrix with recommendation

ネストの深さ

レベル	例	状態
1	Claude → オーケストレーター	✅ 動作します
2	オーケストレーター → code-reviewer	✅ 動作します
3	code-reviewer → サブタスク	⚠️ 動作しますが、コンテキストが不足します
4+	さらに深いネスト	❌ 推奨されません

ベストプラクティス：オーケストレーションは 2 階層までに抑えてください。それ以上深くすると、コンテキストウィンドウが小さくなり、連携が不安定になります。

オーケストレーションを使用する場合

オーケストレーションを使用	直接委任を使用
複雑な複数フェーズのワークフロー	単一の専門タスク
複数の情報源から統合する必要がある	簡単な監査やレビュー
並行実行が重要	順次実行で問題ない
異なる専門家が必要	同じ種類のエージェントでよい

オーケストレーターと直接委任の比較

直接委任（より簡単で、多くの場合これで十分です）：

User: "Review my code changes"
Claude: [Invokes code-reviewer agent directly]

オーケストレーション（調整が必要な場合）：

User: "Prepare release"
Claude: [Invokes release-orchestrator]
        orchestrator: [Spawns code-reviewer, test-runner, doc-validator]
        orchestrator: [Synthesizes all reports]
        [Returns comprehensive release readiness report]

設定に関する注意事項

1. ツールアクセスの伝播：Task を持つオーケストレーターは、セッションでアクセス可能な任意のエージェントを起動できます
2. モデルの継承：起動されたエージェントは、設定されたモデルを使用します（または inherit に設定されている場合は継承します）
3. コンテキストの分離：起動された各エージェントは、それぞれ独自のコンテキストウィンドウを持ちます
4. 結果の集約：オーケストレーターはエージェントの結果を受け取り、それらを統合できます

---

高度なパターン

バックグラウンドエージェント（非同期委任）

メインセッションで作業を続けながら、エージェントをバックグラウンドで実行します。

エージェントの実行中に Ctrl+B を押すと、バックグラウンドに移行します。

> Use the research-agent to analyze these 10 frameworks
[Agent starts working...]
[Press Ctrl+B]
→ Agent continues in background
→ Main session free for other work
→ Check results later with: "What did the research agent find?"

用途：

• 長時間かかる調査タスク
• ドキュメントの並列取得
• 作業を妨げないコードレビュー

モデル選択の戦略

品質優先のアプローチ：ほとんどのエージェントでは、デフォルトで Sonnet を使用します。Haiku によるコスト削減は、品質の低下に見合わないことがほとんどです。

モデル	最適な用途	速度	コスト	品質
sonnet	ほとんどのエージェントのデフォルト - コンテンツ生成、推論、ファイル作成	バランス型	標準	✅ 高
opus	クリエイティブな作業、複雑な推論、品質が重要な出力	遅め	プレミアム	✅ 最高
haiku	品質が重要でない単純なスクリプト実行のみ	2倍高速	3倍安価	⚠️ 変動あり
inherit	メインの会話に合わせる	変動	変動	親に準拠

Sonnet をデフォルトにする理由

テストでは、品質に大きな差が見られました。

• Haiku：スタイルシートのリンク間違い、CSS の欠落、値の誤り、パターンの間違い
• Sonnet：正しいパターン、適切な検証、エラーの減少

タスクの種類	推奨モデル	理由
コンテンツ生成	Sonnet	品質が重要です
ファイル作成	Sonnet	パターンが正確である必要があります
コード作成	Sonnet	バグは高くつきます
監査／レビュー	Sonnet	判断が必要です
クリエイティブな作業	Opus	最高の品質
デプロイスクリプト	Haiku（可）	コマンドを実行するだけです
単純な形式チェック	Haiku（可）	合否の判定のみです

パターン：デフォルトは Sonnet、クリエイティブな作業には Opus、品質が本当に重要でない場合に限って Haiku を使用します。

---
name: site-builder
model: sonnet  # Content quality matters - NOT haiku
tools: Read, Write, Edit, Glob, Grep
---

---
name: creative-director
model: opus  # Creative work needs maximum quality
tools: Read, Write, Edit, Glob, Grep
---

---
name: deploy-runner
model: haiku  # Just running wrangler commands - quality irrelevant
tools: Read, Bash
---

エージェントのコンテキストに関する考慮事項

エージェントのコンテキスト使用量は、タスクに大きく左右されます。

シナリオ	コンテキスト	ツール呼び出し	動作するか
詳細な調査エージェント	130k	90+	✅ はい
複数ファイルの監査	80k+	50+	✅ はい
単純な形式チェック	3k	5-10	✅ はい
連鎖的なオーケストレーション	変動	変動	✅ タスクによります

実際のところ：90 回以上のツール呼び出しと 130k のコンテキストを持つエージェントでも、意味のある作業を行っていれば問題なく動作します。制限要因はタスクの複雑さであり、恣意的なトークン制限ではありません。

実際に重要なこと：

• エージェントはツール呼び出しのたびに進捗していますか？
• コンテキストは実際の作業に使われていますか、それとも重複した指示に使われていますか？
• 最終的な結果に一貫性がありますか？

コンテキストが問題になる場合：

• エージェントが同じことを繰り返したり、状況を把握できなくなったりする
• 結果に一貫性がなくなったり、矛盾したりする
• 長いセッションでエージェントが以前の調査結果を「忘れる」

ペルソナベースのルーティング

明示的な制約を設けて、エージェントが隣接するドメインに逸脱するのを防ぎます。

---
name: frontend-specialist
description: Frontend code expert. NEVER writes backend logic.
tools: Read, Write, Edit, Glob, Grep
---

You are a frontend specialist.

BOUNDARIES:
- NEVER write backend logic, API routes, or database queries
- ALWAYS use React patterns consistent with the codebase
- If task requires backend work, STOP and report "Requires backend specialist"

FOCUS:
- React components, hooks, state management
- CSS/Tailwind styling
- Client-side routing
- Browser APIs

これにより、エージェントが不慣れなドメインに遭遇した際の幻覚を防止できます。

フックのパターン

フックを使うと、自動検証とフィードバックを有効にできます。

コミット時のブロック（品質ゲートを適用）：

hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: |
            if [[ "$BASH_COMMAND" == *"git commit"* ]]; then
              npm test || exit 1
            fi

ヒントフック（処理を妨げないフィードバック）：

hooks:
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/lint-check.sh"
          # Exits 0 to continue, non-zero to warn

ベストプラクティス：計画の途中ではなく、コミットの段階で検証します。エージェントが自由に作業できるようにし、永続的な変更が行われる前に問題を検出します。

ネストされた CLAUDE.md のコンテキスト

Claude は、対象のパスにアクセスする際、サブディレクトリ内の CLAUDE.md ファイルを自動的に読み込みます。

project/
├── CLAUDE.md              # Root context (always loaded)
├── src/
│   └── CLAUDE.md          # Loaded when editing src/**
├── tests/
│   └── CLAUDE.md          # Loaded when editing tests/**
└── docs/
    └── CLAUDE.md          # Loaded when editing docs/**

用途：ディレクトリ固有のコーディング規約、ローカルのパターン、モジュールのドキュメント。

これは遅延読み込みされるコンテキストです。メインのプロンプトを肥大化させることなく、サブエージェントに関連するコンテキストが提供されます。

マスター・クローンとカスタムサブエージェント

委任には2つの考え方があります。

カスタムサブエージェント（明示的な専門家）：

Main Claude → task-runner agent → result

• メリット：コンテキストが分離され、専門的なプロンプトを使え、再利用できます
• デメリット：ゲートキーパー効果（メインエージェントから見えなくなります）

マスター・クローン（動的な委任）：

Main Claude → Task(general-purpose) → result

• メリット：メインエージェントが状況を把握し続け、柔軟に振り分けられます
• デメリット：専門性が低く、より多くの指示が必要になる場合があります

推奨：明確に定義された反復タスクにはカスタムエージェントを使用してください。メインのコンテキストが重要な、その場限りの委任には Task(general-purpose) を使用してください。

---

委任パターン

最適な使いどころ

最適なユースケース：反復的でありながら、判断を必要とするタスクです。

✅ Good fit:
   - Audit 70 skills (repetitive) checking versions against docs (judgment)
   - Update 50 files (repetitive) deciding what needs changing (judgment)
   - Research 10 frameworks (repetitive) evaluating trade-offs (judgment)

❌ Poor fit:
   - Simple find-replace (no judgment needed, use sed/grep)
   - Single complex task (not repetitive, do it yourself)
   - Tasks with cross-item dependencies (agents work independently)

基本プロンプトのテンプレート

この5段階の構成は、一貫して機能します。

For each [item]:
1. Read [source file/data]
2. Verify with [external check - npm view, API, docs]
3. Check [authoritative source]
4. Evaluate/score
5. FIX issues found ← Critical: gives agent authority to act

重要な要素：

• 「見つかった問題を修正する」 - これがないと、エージェントは報告するだけです。指定すると、実際に対処します。
• 正確なファイルパス - 曖昧さや誤ったファイルの編集を防ぎます
• 出力形式のテンプレート - 一貫性があり、解析可能なレポートを作成できます
• 項目リスト - 処理対象を明示的に列挙します

バッチサイズ

バッチサイズ	使用する場面
3-5 項目	複雑なタスク（詳細な調査、複数段階の修正）
5-8 項目	標準的なタスク（監査、更新、検証）
8-12 項目	簡単なタスク（バージョン確認、形式の修正）

なぜ、もっと増やさないのでしょうか？

• エージェントのコンテキストが埋まります
• 1つの失敗でバッチ全体が台無しになることを防げます
• 小さな変更セットのほうがレビューしやすくなります

並列エージェント：それぞれに独自のバッチを割り当て、2～4個のエージェントを同時に起動します。

ワークフローパターン

┌─────────────────────────────────────────────────────────────┐
│  1. PLAN: Identify items, divide into batches               │
│     └─ "58 skills ÷ 10 per batch = 6 agents"                │
├─────────────────────────────────────────────────────────────┤
│  2. LAUNCH: Parallel Task tool calls with identical prompts │
│     └─ Same template, different item lists                  │
├─────────────────────────────────────────────────────────────┤
│  3. WAIT: Agents work in parallel                           │
│     └─ Read → Verify → Check → Edit → Report                │
├─────────────────────────────────────────────────────────────┤
│  4. REVIEW: Check agent reports and file changes            │
│     └─ git status, spot-check diffs                         │
├─────────────────────────────────────────────────────────────┤
│  5. COMMIT: Batch changes with meaningful changelog         │
│     └─ One commit per tier/category, not per agent          │
└─────────────────────────────────────────────────────────────┘

---

プロンプトのテンプレート

監査・検証パターン

Deep audit these [N] [items]. For each:

1. Read the [source file] from [path]
2. Verify [versions/data] with [command or API]
3. Check official [docs/source] for accuracy
4. Score 1-10 and note any issues
5. FIX issues found directly in the file

Items to audit:
- [item-1]
- [item-2]
- [item-3]

For each item, create a summary with:
- Score and status (PASS/NEEDS_UPDATE)
- Issues found
- Fixes applied
- Files modified

Working directory: [absolute path]

一括更新パターン

Update these [N] [items] to [new standard/format]. For each:

1. Read the current file at [path pattern]
2. Identify what needs changing
3. Apply the update following this pattern:
   [show example of correct format]
4. Verify the change is valid
5. Report what was changed

Items to update:
- [item-1]
- [item-2]
- [item-3]

Output format:
| Item | Status | Changes Made |
|------|--------|--------------|

Working directory: [absolute path]

調査・比較パターン

Research these [N] [options/frameworks/tools]. For each:

1. Check official documentation at [URL pattern or search]
2. Find current version and recent changes
3. Identify key features relevant to [use case]
4. Note any gotchas, limitations, or known issues
5. Rate suitability for [specific need] (1-10)

Options to research:
- [option-1]
- [option-2]
- [option-3]

Output format:
## [Option Name]
- **Version**: X.Y.Z
- **Key Features**: ...
- **Limitations**: ...
- **Suitability Score**: X/10
- **Recommendation**: ...

---

カスタムサブエージェントの例

コードレビュアー

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

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

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

デバッガー

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

データサイエンティスト

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

Always ensure queries are efficient and cost-effective.

---

コミット戦略

エージェントはコミットしません。ファイルを編集するだけです。これは意図的な設計です。

エージェントが行うこと	人間が行うこと
調査と検証	変更をレビューする
ファイルを編集する	差分を抜き取り確認する
採点して報告する	git add/commit
要約を作成する	変更履歴を記述する

その理由は？

• コミット前のレビューで、エージェントのミスを発見できます
• 複数のエージェントの作業を、意味のあるコミットにまとめられます
• すっきりしたコミット履歴になります（小さなコミットが50個並ぶことはありません）
• コミットメッセージとグループ分けは人間が決定します

コミットパターン：

git add [files] && git commit -m "$(cat <<'EOF'
[type]([scope]): [summary]

[Batch 1 changes]
[Batch 2 changes]
[Batch 3 changes]

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

---

エラー処理

いずれかのエージェントが失敗した場合

1. エラーメッセージを確認します
2. そのバッチを再試行するか、スキップして続行するかを決めます
3. 1つの失敗で処理全体が止まらないようにします

エージェントが誤った変更をした場合

1. git diff [file] で変更内容を確認します
2. git checkout -- [file] で元に戻します
3. より具体的な指示を出して再実行します

エージェント同士が競合した場合

まれに発生します（エージェントは異なる項目を処理します）が、発生した場合は次の手順に従います。

1. どちらのエージェントの変更が正しいかを確認します
2. 手動で解決するか、一方のエージェントを再実行します

---

ベストプラクティス

1. Claude で生成したエージェントから始める：/agents を使って初期設定を生成し、その後カスタマイズします
2. 役割を絞ったサブエージェントを設計する：各エージェントの責任を1つに明確化します
3. 詳細なプロンプトを書く：具体的な指示、例、制約を記載します
4. 必要がなければ Bash を許可しない：承認要求の連発を防ぎます（「Bash の承認要求を防ぐ」を参照）
5. 重要な指示を最初に置く：プロンプトの冒頭にある指示は守られやすく、埋もれた指示は無視されます
6. 矛盾する指示を取り除く：Write ツールを使いたい場合は、bash の例をすべて削除します
7. モデルは Sonnet をデフォルトにする：コスト削減より品質を重視します（「モデルの選択」を参照）
8. バージョン管理：チームで共有するため、.claude/agents/ を git にチェックインします
9. モデルの inherit は控えめに使う：予測可能な動作を得るには、モデルを明示的に設定するほうが適切です

---

パフォーマンスに関する考慮事項

考慮事項	影響
コンテキスト効率	エージェントはメインコンテキストを保持できるため、より長時間のセッションが可能になります
レイテンシ	サブエージェントは新たに起動し、コンテキストの収集に時間がかかる場合があります
徹底度	Explore エージェントの徹底度レベルでは、速度と網羅性の間でトレードオフが生じます

---

クイックリファレンス

Built-in agents:
  Explore  → Haiku, read-only, quick/medium/thorough
  Plan     → Sonnet, plan mode research
  General  → Sonnet, all tools, read/write

Custom agents:
  Project  → .claude/agents/*.md (highest priority)
  User     → ~/.claude/agents/*.md
  CLI      → --agents '{...}'

Config fields:
  name, description (required)
  tools, model, permissionMode, skills, hooks (optional)

Tool access principle:
  ⚠️ Don't give Bash unless agent needs CLI execution
  File creators: Read, Write, Edit, Glob, Grep (no Bash!)
  Script runners: Read, Write, Edit, Glob, Grep, Bash (only if needed)
  Research: Read, Grep, Glob, WebFetch, WebSearch

Model selection (quality-first):
  Default: sonnet (most agents - quality matters)
  Creative: opus (maximum quality)
  Scripts only: haiku (just running commands)
  ⚠️ Avoid Haiku for content generation - quality drops significantly

Instruction placement:
  ⛔ Critical instructions go FIRST (right after frontmatter)
  ⚠️ Instructions buried 300+ lines deep get ignored
  ✅ Remove contradictory instructions (pick one pattern)

Delegation:
  Batch size: 5-8 items per agent
  Parallel: 2-4 agents simultaneously
  Prompt: 5-step (read → verify → check → evaluate → FIX)

Orchestration:
  Enable: Add "Task" to agent's tools list
  Depth: Keep to 2 levels max
  Use: Multi-phase workflows, parallel specialists

Advanced:
  Background: Ctrl+B during agent execution
  Context: 130k+ and 90+ tool calls work fine for real work
  Hooks: PreToolUse, PostToolUse, Stop events

Resume agents:
  > Resume agent [agentId] and continue...

---

参考資料

公式ドキュメント

• サブエージェントのドキュメント
• プラグインのドキュメント
• ツールのドキュメント
• フックのドキュメント
• CLI リファレンス

コミュニティリソース

• Awesome Claude Code Subagents - 100 以上の専門エージェント
• Claude Code System Prompts - 内部プロンプトの分析
• Claude Code Built-in Tools Reference - 包括的なツールガイド
• Claude Code Frameworks Guide (Dec 2025) - 高度なパターン

---

最終更新日: 2026-02-02