こんにちは、アサヒリンクスです。この記事は、代表コバが現場で蓄積してきた知見をもとに、AIを活用して構成・執筆し、弊社にて最終チェックを行ったものです。
社内の複雑な業務タスクを Claude Code で丸ごと自動化しようとすると、コンテキスト窓の圧迫、エラーの連鎖、役割の混在といった問題にぶつかることがあります。そこで注目されているのが Claude Code Subagents を使った役割分担の設計です。リサーチ・実装・レビュー担当を独立したサブエージェントに分け、それぞれが専門的な指示に従って動く仕組みを構築すると、複雑なタスクを安全かつ効率的に並列処理できます。本記事では、基本設定から実際の社内タスク自動化パターンまで、具体的な設定例とコードを交えて解説します。
Claude Code Subagents とは何か
サブエージェントの役割と仕組み
Claude Code Subagents は、メインエージェントから委譲を受けて専門的なタスクを実行する「専任担当者」です。通常の Claude Code セッションでは、1つのコンテキスト窓に調査結果・実装コード・レビュー指摘がすべて積み重なります。情報が混在すると判断の質が落ち、関係ない情報を参照するミスも増えていきます。
サブエージェントはこの問題を解決します。各サブエージェントは 独立したコンテキスト で起動し、メインエージェントからの委譲プロンプトだけを受け取って処理を行います。完了したらその結果だけがメインに返るため、メインの会話履歴は汚れません。複数のサブエージェントを並列起動することも可能で、独立したタスクは同時に走らせてスループットを上げられます。
仕組みとしては、.claude/agents/{name}.md にサブエージェントの定義ファイルを置き、メインエージェントが Task tool 経由でそのサブエージェントを呼び出すことで委譲が発生します。
サブエージェントの定義ファイル構成
.claude/agents/ ディレクトリの配置
サブエージェントは .claude/agents/ 配下に Markdown ファイルとして定義します。ファイル名がそのまま識別子になります。チーム共有する場合はリポジトリの .claude/agents/、個人専用なら ~/.claude/agents/ に置きます。
.claude/
├── settings.json # プロジェクト共通設定
├── settings.local.json # 個人設定（.gitignore対象）
└── agents/
├── researcher.md # リサーチ担当
├── implementer.md # 実装担当
└── reviewer.md # レビュー担当
各 Markdown ファイルは YAML frontmatter でメタ情報を宣言し、その下の本文がシステムプロンプトになります。リサーチ担当の定義例です。
---
name: researcher
description: コードベースやドキュメントを読み取り、調査レポートを作成する。コード編集は行わない。
model: claude-sonnet-4-6
tools:
- Read
- Bash
---
あなたはコードベース調査の専門家です。
与えられたタスクについて関連ファイルを読み取り、現状を正確に把握してレポートします。
コードの変更は一切行いません。調査結果は以下の形式でまとめてください。
## 調査結果
- 対象ファイル一覧
- 現状の実装概要
- 問題点・改善点のリスト
- 実装担当へのメモ（依存関係・注意事項）
実装担当とレビュー担当の定義
実装担当は調査結果を受け取ってコード変更だけに集中させます。Edit と Write のみを持たせ、余計な調査をさせない設計が重要です。
---
name: implementer
description: 調査レポートをもとにコードを実装・修正する。リサーチは行わない。
model: claude-sonnet-4-6
tools:
- Read
- Edit
- Write
- Bash
---
渡された調査レポートと実装仕様に基づき、コードの修正・追加を行います。
不明点があればメインエージェントに差し戻してください。
変更後は必ず変更内容の要約を出力してください。
レビュー担当は Read と Bash のみに絞り、コードを書き換えられない状態にしておくのが安全です。
---
name: reviewer
description: コードをレビューし、品質・セキュリティ観点で指摘をまとめる。コード修正は行わない。
model: claude-sonnet-4-6
tools:
- Read
- Bash
---
変更内容（diff）と実装要件を照らし合わせ、以下の観点でレビューします。
- 要件との整合性（実装漏れ・仕様逸脱）
- バグ・エラーハンドリングの欠如
- セキュリティリスク（認証バイパス等）
- パフォーマンス上の問題
出力は JSON 形式で返してください。
{
"result": "pass" or "needs_fix",
"critical": ["ブロッカーレベルの指摘"],
"summary": "全体評価コメント"
}
社内タスク分担の実装パターン
リサーチ → 実装 → レビューの直列パターン
もっとも基本的な構成です。CLAUDE.md でこのフローを定義しておくと、改修タスクを与えるだけで自動的に工程が進みます。
# CLAUDE.md（プロジェクトルート）
## タスク処理フロー
コードの改修・追加タスクを受け取ったら、次の順序で処理する。
1. researcher サブエージェントに委譲（対象ファイルとタスク概要を渡す）
2. implementer サブエージェントに委譲（researcher の調査レポートを添付）
3. reviewer サブエージェントに委譲（変更 diff と実装要件を渡す）
4. reviewer が needs_fix を返した場合は 2 に差し戻す（最大2回まで）
並列リサーチパターン
複数の調査項目が独立している場合、サブエージェントを並列起動して時間を短縮できます。Task tool を介した並列呼び出しのイメージです。
// Claude Code が内部で発行する Task tool 呼び出し（概念コード）
[
{
"tool": "Task",
"input": {
"agent": "researcher",
"prompt": "src/components/ 配下を調査。フォームコンポーネントの状態管理パターンを確認"
}
},
{
"tool": "Task",
"input": {
"agent": "researcher",
"prompt": "src/api/ 配下を調査。認証エンドポイントのレスポンス形式を確認"
}
}
]
両方の調査結果が揃ってから implementer に渡す、という制御もメインエージェントへの指示で実現します。
Claude Code Settings での権限分離設計
settings.json による基本設定
Claude Code Settings はプロジェクト全体の挙動を管理します。サブエージェントを使う構成では、settings.json でグローバルな許可・拒否を設定し、各サブエージェント定義ファイルでさらに絞り込みます。
// .claude/settings.json
{
"model": "claude-sonnet-4-6",
"permissions": {
"allow": [
"Read(*)",
"Bash(git diff*)",
"Bash(git log*)",
"Bash(git status)",
"Bash(npm run test*)",
"Bash(npm run lint*)"
],
"deny": [
"Bash(git push*)",
"Bash(rm *)",
"Bash(curl *)"
]
}
}
settings.json はリポジトリにコミットしてチームで共有し、API キーや個人設定は settings.local.json（.gitignore 対象）に書き分けるのが基本です。settings.json には秘匿情報を絶対に書かないことがルールです。
モデル使い分けでコストを最適化する
サブエージェントの定義ファイルでモデルを個別指定できるため、タスクの難易度に合わせて選択できます。これがコスト最適化の核心です。
- Claude Opus 4.7：複雑なアーキテクチャ設計、難易度の高いバグの根本原因分析など品質最優先のタスク
- Claude Sonnet 4.6：コードレビュー・実装・調査など一般的な開発タスクの本線。コスト・品質・速度のバランスが最良
- Claude Haiku 4.5：テスト実行の結果整理、ログ解析、構造化 JSON 生成など繰り返し・軽量タスク
# テスト実行専用（Haiku でコストを抑える）
---
name: tester
description: テストを実行し、結果をレポートする。コード変更は行わない。
model: claude-haiku-4-5
tools:
- Bash
---
テスト実行結果を以下の形式でまとめる。
- PASS / FAIL 件数
- 失敗したテストケース名とエラーメッセージ
- カバレッジサマリー
Slash Commands でフローを定型化する
カスタムコマンドとサブエージェントの組み合わせ
Claude Code Slash Commands を使うと、サブエージェント呼び出しのフローをコマンド1つに定型化できます。.claude/commands/ 配下に Markdown ファイルを置くだけで /コマンド名 として呼び出せます。
.claude/commands/
├── fix-bug.md # /fix-bug : バグ修正フル自動
├── add-feature.md # /add-feature : 機能追加フル自動
└── review-pr.md # /review-pr : レビューのみ
/fix-bug コマンドの定義例です。
---
description: バグ修正の完全フロー（調査→実装→テスト→レビュー）を自動実行する
---
# バグ修正フロー
対象バグ: $ARGUMENTS
1. researcher にバグの再現条件・原因ファイルの特定を委譲
2. implementer に調査結果を渡して修正を実行
3. tester に変更内容を渡してテスト実行（FAIL なら implementer に差し戻す）
4. reviewer に diff を渡してレビュー（needs_fix なら implementer に差し戻す、最大2回）
チーム運用でのルール設計
コマンドが増えすぎると逆に把握しづらくなります。10〜15個程度に絞り、CLAUDE.md に一覧と用途を明示する運用が現実的です。
# コマンド一覧（CLAUDE.md に記載）
| コマンド | 用途 | 主なサブエージェント |
|---|---|---|
| /fix-bug | バグ修正フル自動 | researcher→implementer→tester→reviewer |
| /add-feature | 機能追加 | researcher→implementer→reviewer |
| /review-pr | PR レビューのみ | reviewer |
| /investigate | 調査のみ | researcher |
運用上の注意点とよくある落とし穴
委譲プロンプトに前提情報を網羅する
サブエージェントは独立したコンテキストで動くため、メインの会話履歴を一切知りません。「さっき話した件をよろしく」のような委譲は完全に無視されます。委譲プロンプトには以下を必ず含めます。
- タスクの背景と目的
- 対象ファイルやモジュールの具体的なパス
- 成功条件（何ができたら完了か）
- 制約事項（変更してはいけない部分）
- 前工程の結果（調査レポートや実装サマリーをそのまま貼り付ける）
ループ暴走を防ぐ安全弁を必ず設ける
実装担当とレビュー担当が差し戻しを繰り返して終わらないループが発生することがあります。CLAUDE.md または Slash Command 定義に最大リトライ回数を明記しておきます。また Claude Code Hooks の Stop イベントを使うと、一定ターン数で強制終了する仕組みも設けられます。
# CLAUDE.md に書く安全弁
## サブエージェント実行ルール
- implementer → reviewer のサイクルは最大2回まで
- 2回目でも needs_fix の場合は人間にレビューを依頼してタスクを停止する
- researcher が同じファイルを3回以上参照している場合は調査を打ち切り、判明分を報告する
Claude Code Settings の permissions.deny にも危険コマンドを明示しておき、サブエージェントが意図せず本番データを変更したり、外部に通信したりしないように制限しておくことも重要です。
本記事は代表コバの現場知見をもとに AI で構成し、弊社にて最終確認を行っています。
まとめ
Claude Code Subagents を使った社内タスク分担自動化のポイントを振り返ります。
- サブエージェントは 独立したコンテキスト で動くため、メインの会話履歴が汚れず長時間タスクでも品質が安定する
.claude/agents/{name}.mdに 役割・モデル・許可ツール を宣言するだけで定義できる- リサーチ→実装→テスト→レビューの 直列パターン と、独立タスクの 並列パターン を使い分ける
- Claude Haiku 4.5 / Sonnet 4.6 / Opus 4.7 の モデル使い分け がコスト最適化の核心
- 委譲プロンプトには前提情報を網羅的に含め、最大リトライ回数を明記して ループ暴走を防ぐ
- Claude Code Slash Commands でフローを定型化すると、チーム全体で 再現性のある自動化 が構築できる
まずは2〜3役割のシンプルな構成から始め、実際の運用フィードバックをもとに役割を育てていくのが現実的です。Claude Code や Subagents を社内タスクの自動化に活用したい方、どこから始めればよいか迷っている方は、お気軽にご相談ください。費用感だけ知りたい方も歓迎しています。お問い合わせはこちらからどうぞ。
