How and when to use subagents in Claude Code¶

チェック¶

[ ] 本文を確認した
[ ] 概要を確認した
[ ] タグを確認した
[ ] inbox/ 直下へ移行した

概要¶

Claude Codeのsubagentsを、いつ使うべきか、どう指示すべきか、どのようにチームで標準化するかを説明する記事。 Research-heavyな調査、独立した複数タスク、会話履歴に影響されないレビューには有効。一方で、逐次依存が強い作業、同一ファイル編集、小さな修正ではオーバーヘッドが勝つ。

本文¶

Claude Codeは複雑な複数ステップの作業を扱えるが、長いセッションではコンテキストが重くなる。読んだファイル、探索した寄り道、途中の考えが会話に残り、応答速度やトークンコストに影響する。

大きなTypeScript monorepoで機能追加をする場面を考える。主作業は実装だが、横で必要になる調査が多い。

既存サービスが認証をどう扱っているか
日付フォーマットの共通utilがどこにあるか
デザインシステムに近いコンポーネントがあるか

これらは主セッションの全コンテキストを必要としない。subagentに分ければ、主会話を汚さず並列に調査できる。

Claude Codeには、一般目的のagent、実装前にコードベースを調査するplan agent、高速なread-only探索向けのexplore agentなどがある。Claude Code自身が自動的にsubagentを起動することもあるが、人間が明示的に指示したり、再利用可能な専門subagentを定義したりできる。

使うべき場面¶

調査が重いタスク¶

変更前にコードベース理解が必要な場合、subagentに探索させて要約を返させるとよい。

Signal:
  コンテキスト収集に大量のファイル読み取りが必要

Benefit:
  主会話はきれいなまま、raw fileではなく統合された発見だけが返る

独立した複数タスク¶

複数ファイルのエラー修正、複数コンポーネントへの同種変更、依存関係のない更新は並列化しやすい。

Signal:
  サブタスク同士に依存がない

Benefit:
  3つのsubagentが同時に動けば、直列より短時間で終わる

新鮮な視点が必要なレビュー¶

実装者の会話履歴や仮定に影響されない検証が必要なとき、別コンテキストのsubagentが有効。

Signal:
  会話履歴に引きずられないレビューが必要

Benefit:
  より客観的なフィードバックが得やすい

明示的に指示する¶

subagentは明示的に依頼した方が安定する。scope、並列実行の有無、期待する出力を指定する。

例。

Use subagents to explore this codebase in parallel:

1. Find all API endpoints and summarize their purposes
2. Identify the database schema and relationships
3. Map out the authentication flow

Return a summary of each, not the full file contents.

このプロンプトがよい理由は、3つの独立タスクを定義し、並列実行を明示し、返す形式も指定しているため。

使える依頼文の例。

Use a subagent to explore how authentication works in this codebase.
Have a separate agent review this code for security issues.
Research this in parallel. Check the API routes, database models, and frontend components simultaneously.
Spin up subagents to fix these TypeScript errors across the different packages.

Custom subagents¶

繰り返し使う専門家はCustom subagentにできる。例えばsecurity reviewer。

---
name: security-reviewer
description: Reviews code for security issues before commits and pull requests.
tools:
  - Read
  - Grep
  - Glob
---

You are a security-focused code reviewer. Analyze the provided
changes for:

- SQL injection, XSS, and command injection risks
- Authentication and authorization gaps
- Sensitive data in logs, errors, or responses
- Insecure dependencies or configurations

Return a prioritized list of findings with file:line references
and a recommended fix for each. Be critical. If you find nothing,
say so explicitly rather than inventing issues.

Custom subagentsが向くのは次の条件。

Claudeが自動委譲できる専門家を用意したい
狭いsystem promptと制限されたtoolsが効く
チームや複数プロジェクトで再利用したい

description は委譲判断に使われるため、単に「security expert」よりも「commits前にsecurity issuesをreviewする」のようにトリガー条件を書く方がよい。

CLAUDE.md¶

Custom subagentsは「専門家が誰か」を定義する。CLAUDE.md は「いつ使うか」のポリシーを定義する。

例えば、すべてのコードレビューではread-only subagentを使う、アーキテクチャ質問の前にはresearch passを走らせる、といったルールは CLAUDE.md に置く。Claudeは会話開始時に読むため、チームメンバーが毎回覚えていなくても挙動を揃えられる。

Skills¶

Skillsは、subagentsだけではなく、テンプレート、出力例、スクリプトなどを含められるディレクトリ。深いコードレビューskillの例。

# .claude/skills/deep-review/SKILL.md

---
name: deep-review
description: Comprehensive code review that checks security,
  performance, and style in parallel. Use when reviewing staged
  changes before a commit or PR.
---

Run three parallel subagent reviews on the staged changes:

1. Security review - check for vulnerabilities, injection risks,
   authentication issues, and sensitive data exposure
2. Performance review - check for N+1 queries, unnecessary iterations,
   memory leaks, and blocking operations
3. Style review - check for consistency with project patterns
   documented in /docs/style-guide.md

Synthesize findings into a single summary with priority-ranked issues.
Each issue should include the file, line number, and recommended fix.

legacyな .claude/commands/ は単一ファイルなので、すべてをprompt内に書く必要があった。Skillはディレクトリなので、テンプレートやスクリプトも同梱できる。

Hooks¶

Hooksは、Claude Codeのライフサイクル上の特定タイミングで自動実行されるshell command、HTTP endpoint、LLM prompt。subagent workflowをイベントベースで自動化できる。

向く場面。

commit前に毎回レビューを走らせたい
security checkを誰かが頼むのを待たずに実行したい
CI的なquality gateをローカル開発プロセスに入れたい

Stop hookでテスト通過までClaudeの終了を止める例。

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-tests.sh"
          }
        ]
      }
    ]
  }
}

スクリプト側では、Stop hookがすでに有効な再実行かどうかを見て無限ループを避ける。

#!/bin/bash
INPUT=$(cat)
STOP_HOOK_ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active // false')

if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
  exit 0
fi

if ! npm test; then
  cat <<JSON
{
  "decision": "block",
  "reason": "Tests failed. Fix the failing tests before ending the turn."
}
JSON
fi

Hooksは最も自動化度が高い。最初は会話で明示的にsubagentを呼ぶか、CLAUDE.md に方針を書くところから始め、成熟したらHooksにするのがよい。

実践パターン¶

実装前に調査する¶

Before I implement user notifications, use a subagent to research:
- How are emails currently sent in this codebase?
- What notification patterns already exist?
- Where should new notification logic live based on the current architecture?

調査を先に分けることで、実装会話が探索ではなく判断から始まる。

レビューを別コンテキストで行う¶

実装者が持っている仮定に引きずられず、security、performance、styleなどを別の観点で見る。

使わない方がよい場面¶

subagentにはオーバーヘッドがある。小さい作業や強く依存した手順は主会話で進めた方がよい。

step 2がstep 1の完全な出力に依存する逐次作業
同じファイルを複数subagentが並列編集する作業
すぐ終わる小さな修正
人間が密に判断し続ける必要がある作業

要点¶

subagentsは、コンテキスト分離、並列性、新鮮な視点が効くときに使う。
scope、並列実行、返してほしい形式を明示する。
繰り返す専門作業はCustom subagentやSkillにする。
チーム方針は CLAUDE.md、成熟した自動化はHooksに寄せる。
同一ファイル編集や逐次依存作業ではsubagentを使わない方がよい。

タグ¶

claude-code #subagents #ai-coding #agent-workflow #hooks #skills¶