Claude Code subagent はどんなプロジェクトに向いているか：ユースケース、境界、落とし穴

Claude Code subagent を初めて見ると、「複数の AI を開いて一緒にコードを書かせるもの」と理解しがちです。それは半分だけ正しい理解です。

より正確には、subagent は三つの問題を解きます。コンテキストの分離、独立したサブタスクへの分割、特定の役割に固定ルールを持たせることです。すべてのプロジェクトに必要な加速装置ではありません。タスクが小さい、境界が曖昧、複数の Agent が同じファイルを取り合う場合は、むしろ結果が乱れます。

この記事では、プロジェクト視点で Claude Code subagent がどんな場面に向くのか、いつ使わないほうがよいのか、プロジェクトレベル subagent をどう設計するかを整理します。

Quick Answer

プロジェクト/タスク	適性	理由
大規模コードベースの初期調査	とても向く	API、DB、フロント、テストを分けて読める
複数モジュールの並列調査	とても向く	サブタスクが独立し、主会話を汚さない
PR や大きな diff のレビュー	とても向く	bug、安全、性能、テストの観点で分割できる
テスト失敗とログ分析	向く	ノイズの多いログを専門 role に任せられる
ドキュメント、移行、依存更新評価	向く	資料を読み、影響範囲を整理できる
単一ファイルの小さなバグ修正	あまり向かない	調整コストが大きい
要件が曖昧な探索	向かない	subagent には明確な境界が必要
複数 Agent が同じファイルを編集	高リスク	衝突や上書きが起きやすい

一言でいうと、subagent は「分割でき、独立して進められ、最後は結論や小さな成果として返せるタスク」に向いています。

価値は速度よりコンテキスト管理

Claude Code の公式ドキュメントでは、subagent は独立した agent インスタンスとして説明されています。主 agent は特定のタスクを委任し、subagent は自分のコンテキストで作業して結果を返します。

主な価値は単純な高速化ではありません。

コンテキスト分離：ログ、テスト出力、資料、ディレクトリ調査が主会話を圧迫しない。
役割固定：code-reviewer は常に読み取り専用レビュー、test-runner はテスト実行と失敗分析だけを行う。
ツール権限管理：一部の subagent を Read/Grep/Glob のみに制限できる。
並列調査：独立した方向を同時に調べ、最後に統合できる。
プロジェクト知識の蓄積：チームのレビュー基準を .claude/agents/ に残せる。

判断時は「速くなるか」より、「大量のコンテキストが出るか」「役割を明確に分けられるか」を先に見ます。

向く場面 1：大規模コードベースの把握

未知の大きなリポジトリを引き継ぐとき、最初の問題は「どこから見るか」です。

subagent で次のように分けられます。

api-reader：ルート、コントローラ、認証。
db-reader：schema、migration、ORM model。
frontend-reader：ページ構造、状態管理、コンポーネント入口。
test-reader：テストフレームワーク、カバレッジ、実行コマンド。

各 subagent は 5 から 10 件の結論だけを返します。主会話はリポジトリ全体を抱え込まず、構造化された地図を持てます。

monorepo、古い業務システム、前後端混在リポジトリ、ビルドやデプロイスクリプトが散らばったプロジェクト、技術的負債の評価に向いています。

Codex と Claude Code の引き継ぎを設計するなら、この「読む・構造を掴む」作業を Claude Code subagent 側に置き、結果を Codex に渡して長い変更を進める形も使えます。関連: /ja/2026/07/10/codex-claude-code-task-handoff-guide/。

向く場面 2：コードレビューを役割で分ける

レビューは観点ごとに分けやすいため、subagent と相性がよいです。

bug-reviewer：ロジックミス、null、境界条件、回帰。
security-reviewer：権限、入力検証、秘密情報、注入、越権。
performance-reviewer：ループ、クエリ、キャッシュ、描画、並行性。
test-reviewer：本当にリスクを覆うテストがあるか。

ただし、レビュー型 subagent は読み取り専用をデフォルトにするべきです。

安全な流れは次の通りです。

主会話が diff を集める。
複数の読み取り専用 subagent がレビューする。
主会話が結論を統合する。
明確な実装担当が小さく修正する。

Claude Code と Codex のレビュー閉ループは、こちらも参考になります: /ja/2026/07/10/claude-code-codex-code-review-workflow/。

向く場面 3：テスト失敗とログのノイズ

自動テストの失敗出力は長くなりがちです。E2E、統合テスト、CI ログでは、有用なエラーが数百行の中に埋もれます。

test-runner subagent は次を担当できます。

指定テストコマンドを実行する;
失敗ケースを抜き出す;
失敗理由を要約する;
関連しそうなファイルを示す;
直接コードを修正しない。

subagent	推奨ツール	タスク
`test-runner`	`Bash, Read, Grep`	テスト実行と失敗説明
`log-analyzer`	`Read, Grep, Glob`	ログとスタックトレース分析
`coverage-reviewer`	`Read, Grep, Glob`	不足テストと高リスク分岐の確認

Claude Code hooks でテストを自動実行している場合、hooks がトリガー、subagent が失敗を説明する役割にできます: /ja/2026/07/10/claude-code-hooks-auto-run-tests/。

向く場面 4：大規模リファクタ前の影響分析

大きなリファクタは、いきなり編集しないほうが安全です。subagent は読み取り専用の偵察に向いています。

たとえば認証モジュール置換、DB アクセス層更新、フロントエンド状態管理の変更では、次を調べます。

古い interface に依存するファイルはどれか;
どのテストが対象ロジックを覆っているか;
どの呼び出し経路が壊れやすいか;
ドキュメント、スクリプト、設定も更新が必要か;
先にテストを追加すべき場所はどこか。

重要なのは、subagent は影響範囲を出し、patch を急がないことです。

主会話がその結果を見て、一括変更、段階的変更、先にテスト追加のどれを選ぶか決めます。これは長時間タスクの復旧にも役立ちます: /ja/2026/07/10/ai-agent-long-task-resume-guide/。

向かない場面

subagent には追加コンテキスト、待ち時間、調整コストがあります。

通常は次の場面では使いません。

1. 直接直せる小さな問題

typo、import、CSS class、null チェック、設定値更新などは主会話で直すほうが速いです。

2. 境界が曖昧な要件

「このプロジェクトを最適化して」「このページを良くして」のような依頼は、先に目標と制約を明確にします。

3. 頻繁な相談が必要なタスク

subagent は独立作業向きで、設計を細かく往復相談する仕事には向きません。

4. 複数 Agent が同じファイルを編集する

先に読み取り専用レビューを行い、修正は一つの実行者に集約します。

5. 高リスクな外部操作

本番環境、実アカウント、有料 API、削除、権限変更、メール送信、メッセージ送信は、厳しいツール制限と確認なしに背景 subagent へ任せるべきではありません。

プロジェクトレベル subagent の設計

Claude Code では subagent を Markdown として書けます。プロジェクトレベルでは通常ここに置きます。

1

.claude/agents/

グローバルに再利用するものはここです。

1

~/.claude/agents/

プロジェクト用には、テストコマンド、ディレクトリ構造、レビュー観点、触ってはいけないファイル、出力形式を書きます。

最小の読み取り専用レビュー subagent 例：

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24


---
name: code-reviewer
description: Use when the task needs a read-only review of code changes for bugs, regressions, security risks, and missing tests.
tools: Read, Grep, Glob
---

# Code Reviewer

Only perform read-only review. Do not modify files.

Focus on:

- logic errors and edge cases
- regression risk
- security and permission issues
- missing tests
- inconsistency with project style

Output:

1. List high-risk issues first.
2. Include file paths and reasons.
3. If no issue is found, say so clearly.
4. Do not output long rewritten code.

特に重要なのは description です。Claude Code はこれを見て委任タイミングを判断します。

よく使う subagent 構成

最初から十数個作る必要はありません。まずは 3 から 5 個で十分です。

名前	ツール	役割
`code-reviewer`	`Read, Grep, Glob`	バグ、回帰、テスト不足の読み取り専用レビュー
`test-runner`	`Bash, Read, Grep`	テスト実行と失敗説明
`docs-researcher`	`Read, Grep, Glob`	ドキュメント、移行メモ、規約整理
`security-reviewer`	`Read, Grep, Glob`	権限、入力、秘密情報、注入リスク確認
`refactor-planner`	`Read, Grep, Glob`	大変更前の影響分析と段階計画

汎用的な助言ばかり返す subagent は、役割が広すぎます。範囲を狭めるか、プロジェクトルールを追加します。

呼び出し方

明示的に呼び出せます。

1

Use the code-reviewer subagent to review the current diff. Do not modify files.

@code-reviewer のように名前を指定したり、コマンドで起動することもできます。

1

claude --agent code-reviewer

重要な作業では自動委任だけに頼らず、「read-only」「do not modify files」「return conclusions only」と明示するのが安定します。

判断式

迷ったら次の 5 つを確認します。

モジュール、ディレクトリ、役割、観点で分割できるか。
サブタスク同士が十分独立しているか。
各サブタスクが明確な結論を返せるか。
異なるツール権限が必要か。
コンテキスト分離の利益が token と待ち時間のコストを上回るか。

3 つ以上が yes なら試す価値があります。1 つだけなら、分けないほうがよいでしょう。

落とし穴チェックリスト

helper、assistant、worker のような曖昧な名前を避ける。
description には起動場面を書く。
レビュー型 subagent は原則読み取り専用。
編集型 subagent は一度に小さな範囲だけ担当する。
大規模リファクタは先に影響分析をする。
テスト subagent はログ全文ではなく失敗要約を返す。
複数 subagent の出力は主会話が統合する。
高リスク操作はツールと範囲を制限する。
プロジェクトルールは .claude/agents/、個人習慣は ~/.claude/agents/ に置く。
低頻度、重複、品質の低い subagent は定期的に削除する。

まとめ

Claude Code subagent が最も向いているのは、明確なモジュール、役割、境界を持つ中〜大規模の開発タスクです。

コードベース調査、専門レビュー、テスト失敗分析、移行影響評価、プロジェクト固有 role の再利用には向きます。小さな編集、曖昧な要求、頻繁な相談、複数 Agent による同一ファイル編集には向きません。

良い subagent は数ではなく境界で決まります。主会話は目標、判断、最終反映を担当し、subagent は局所問題を深く正確に調べます。そう使うと、subagent は「AI が一つ増えた」ではなく、プロジェクトワークフローの信頼できる一部になります。