Claude Code サブエージェントの作成・委譲・並列実行ガイド

【結論】サブエージェントは.claude/agentsで定義する

Claude Codeのサブエージェントは、独立したコンテキスト、専用プロンプト、利用可能なツールを持つ専門エージェントです。

単に複数作業を列挙するだけではなく、プロジェクト用は「.claude/agents/」、全プロジェクト共通は「~/.claude/agents/」へMarkdownファイルを配置します。

まず読み取り専用のレビュー担当を作り、親エージェントから明示的に委譲する構成が安全です。

mkdir -p .claude/agents
cat > .claude/agents/code-reviewer.md <<'EOF'
---
name: code-reviewer
description: 変更後のコードを品質・安全性・保守性の観点でレビューする
tools: Read, Grep, Glob
model: sonnet
---
問題を重要度順に整理し、必ずファイル名と行番号を示してください。
コードは変更せず、具体的な修正案だけを返してください。
EOF
claude

具体的な手順・設定方法

1. Claude Codeをプロジェクトルートで起動し、作成した定義を読み込ませます。

   既にセッションを開いている状態で初めてagentsディレクトリを作った場合は、一度終了して再起動すると確実です。

   claude

2. 親エージェントへ、どのサブエージェントを使うかと成果物を指定します。

   説明欄が曖昧だと自動委譲されにくいため、利用場面を具体的に記載します。

実践プロンプト / 活用テクニック

探索結果や長いログを親セッションへ持ち込まず、要約だけ返させるとコンテキストを節約できます。

code-reviewerサブエージェントを使い、src/配下の今回の差分をレビューしてください。
次の観点を独立して確認してください。
1. 認証・権限・入力検証の欠落。
2. 例外処理とログの不足。
3. 既存テストで検出できない回帰。
ファイルは変更せず、重要度、根拠、対象行、最小修正案を表形式で返してください。

注意点・よくあるエラーと対処法

• サブエージェントは別セッションではなく、親セッション内で委譲される専門コンテキストです。

  大量の独立セッションを管理したい場合は、背景セッションやagent viewと用途を分けます。

  claude agents --json

• ツール名の綴りを誤ると利用可能なツールがゼロになり、起動に失敗します。

  読み取り専用にしたい場合はWriteやEditを許可しないでください。

  claude doctor