Claude Codeのサブエージェントとは何か、/agentsやフックを使った繰り返し作業の自動化を非エンジニア目線で解説。.claude/agents/への定義方法、ツール権限やモデルの使い分け、そして「丸投げしない」ための注意点まで、公式ドキュメントに沿って整理しました。
サブエージェントは「役割特化の小さなAI」に作業を委譲する仕組みで、独立したコンテキスト・ツール権限を持ちます。フックや繰り返し作業の自動化と組み合わせると、手間の多い定型作業を任せられます。ただし、指示の設計と成果物の確認は人の仕事。丸投げは禁物です。
この記事は、コードを書けない私が実際にClaude Codeでサイトやツールを作ってきた経験をふまえ、「委譲と自動化」を非エンジニアでも分かる言葉で整理したものです。
「サブエージェント」と聞くと高度に思えますが、要は得意分野を絞った“分身”に、面倒な作業を任せる仕組みです。この一点を押さえると、一気に分かりやすくなります。
この記事の要点
- サブエージェントは、独立したコンテキスト・システムプロンプト・ツール権限を持つ役割特化のAI。Claudeが役割説明を見て委譲する。
- 定義は
.claude/agents/（チーム共有）か~/.claude/agents/（全プロジェクト）にMarkdownで置くだけ。toolsやmodelで権限・コストを調整できる。 - 自動化は便利だが丸投げは禁物。権限を絞り、差分を承認しながら進めるのが安全。
実体験メモ
正直、最初は「エージェントを分ける意味が分からない」と思っていました。ですが、本題の会話が探索ログでぐちゃぐちゃになって困った時に、「調べ物専用の分身に任せて、結果だけ受け取る」という発想が腑に落ちました。非エンジニアの私でも、やることは .claude/agents/ にテキストファイルを1枚置くだけ。難しさの大半は「言葉のいかつさ」で、実作業はメモを書く程度だった、というのが率直な感想です。逆に、権限を絞らず何でも任せた時ほど、想定外の変更が増えて手戻りしました。
サブエージェントとは？（役割特化の“分身”）
サブエージェントは、特定の役割に特化したAIアシスタントです。ふつうの会話は1つのClaudeと進めますが、サブエージェントはそこから切り出した別働隊のようなもの。それぞれが次の3つを独立して持ちます。
- コンテキストウィンドウ（作業メモリ）：本会話とは別の作業領域。ログや探索の大量出力を本会話に持ち込まない。
- システムプロンプト：その役割に特化した指示（例：「コードレビューだけをする」）。
- ツール権限：使える道具を絞れる（例：読み取り系だけ許可）。
Claudeは、各サブエージェントの description（役割説明）を見て、「この作業はあの分身に任せよう」と委譲の判断をします。探索・ログ処理など出力が膨らむ作業を隔離し、要約だけを本会話に返すのが大きな利点です。結果として、本題の文脈が散らからずに済みます。
💡 ポイントは「専門の担当者に一部を任せ、報告だけ受け取る」イメージ。会社で調べ物を部下に頼み、要点だけ聞くのと同じ感覚です。
サブエージェントを使うと何が良いのか
イメージしやすいよう、代表的なメリットを整理します。
| 良い点 | 中身 |
|---|---|
| 文脈が散らからない | 大量出力を隔離し、本会話には要約だけ返る |
| 役割ごとに最適化できる | レビュー用・調査用など、専用の指示を持たせられる |
| 権限を絞れる | 使えるツールを限定し、想定外の操作を防ぎやすい |
| コストを調整できる | 単純な作業は低コストなモデルに任せられる |
※対応や仕様は変わっていきます。最新の挙動は公式ドキュメントで確認してください。
サブエージェントの作り方（.claude/agents/ と /agents）
作り方はシンプルで、Markdownファイルを決まった場所に置くだけです。置き場所は2つあります。
- プロジェクト：
.claude/agents/（そのリポジトリのメンバーで共有） - ユーザー：
~/.claude/agents/（自分の全プロジェクトで使える）
ファイルの先頭にfrontmatter（設定欄）を書きます。公式ドキュメントの例に沿うと、次のような形です。
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---各項目の意味は次のとおりです。必須なのは name と description の2つだけで、あとは任意です。
| 項目 | 役割 |
|---|---|
name | サブエージェントの名前（必須） |
description | 役割の説明。Claudeが委譲を判断する手がかりになる（必須） |
tools | 使わせるツールの許可リスト（絞ると安全）。mcp__<サーバー名> でMCPサーバー単位の指定も可 |
disallowedTools | 逆に、使わせないツールの拒否リスト |
model | 使うモデル。省略すると本会話のモデルを引き継ぐ（inherit）。単純用途は低コストなモデルに寄せられる |
permissionMode | 権限確認のモード |
maxTurns | やり取りの最大ターン数 |
memory | サブエージェント自身にauto memory（学習ノート）を持たせる。user/project/localから選び、公式推奨はproject |
frontmatterの下に、そのサブエージェント専用の指示（システムプロンプト）を本文として書きます。「何をする担当か」「してはいけないこと」を具体的に書くほど、委譲の精度が上がります。
なお、同じ名前のサブエージェントが複数の場所にある場合の優先順位は、管理設定 → --agents フラグ → プロジェクトの .claude/agents/ → ユーザーの ~/.claude/agents/ → プラグインの順です。
組み込みのサブエージェントもある
自作しなくても、最初から使える組み込みサブエージェントがあります。
- Explore：読み取り専用の調査担当。コードベースの探索などに使われる
- Plan：プランモードでの計画づくり担当
- general-purpose：汎用の作業担当
注意点として、ExploreとPlanはCLAUDE.mdを読み込みません。プロジェクト固有のルールを前提にした作業を任せたい場合は、自作のサブエージェントに役割として持たせるか、本会話で進めるのが安全です。
/agents コマンドの今の挙動
セッション内で /agents と打つと、サブエージェントの作成・管理を促してくれます。ただし挙動には注意点があります。
- v2.1.198以降、対話ウィザードは廃止されました。現在の公式手順は「Claudeに作成を依頼するか、
.claude/agents/のファイルを直接編集する」の2択で、/agentsはその案内を表示します。 - ファイルの追加・編集は数秒で自動検知され、基本的に再起動は不要です。
- ただし、起動時に
~/.claude/agents/が存在しなかった場合は、再起動が必要になることがあります。
慣れないうちは、「こういう役割のサブエージェントを作って」とClaudeに日本語で頼むのが手軽です。私も最初はそうしました。
フックと繰り返し作業の自動化
サブエージェントと相性が良いのが、繰り返し作業の自動化です。Claude Codeは公式ドキュメント上、次のような反復作業を自然言語の指示でこなせるとされています。
- テストの作成、lint（文法・書式チェック）の修正
- 依存関係の更新、マージ競合の解決
- リリースノートの作成
- Git操作（変更のステージング、コミットメッセージ作成、ブランチ作成、PR作成）
こうした定型作業は、専用のサブエージェントに役割として持たせておくと、毎回ゼロから指示しなくて済みます。さらに、フック（特定のタイミングで自分の決めた処理を差し込む仕組み）と組み合わせると、作業の前後に自動チェックを挟むといった運用も可能です。
ただし、フックやMCP・設定が思ったとおりに効かないこともあります。その場合の切り分け手順は公式で案内されています。
- 状態確認は
/mcp（MCP関連）や、設定のデバッグ手順を参照 - カスタマイズをいったん全部オフにして切り分けるなら
claude —safe-mode
フックや自動化の設定は強力な反面、意図しない処理を挟むと原因追跡が難しくなります。まず1つ、小さく試すのが安全です。
「丸投げしない」自動化の考え方
ここが本記事でいちばん伝えたいところです。委譲や自動化は便利ですが、丸投げ（全部お任せ）は禁物です。理由はシンプルで、AIは指示に沿って動くほど、指示の設計が甘いと“甘いまま”進んでしまうからです。
私自身、権限を絞らずに何でも任せた時ほど、想定外のファイル変更が増えて手戻りしました。逆に、次のように「人が握る部分」を残すと、安定して使えます。
- 役割と範囲を明確にする：サブエージェントの
descriptionと本文に「何をする担当か／してはいけないこと」を具体的に書く。 - ツール権限を絞る：
toolsで必要な道具だけ許可する。調査用なら読み取り系だけ、など。 - 差分を承認しながら進める：ファイル編集は差分を確認してから反映する。いきなり全承認にしない。
- 委譲を止められるようにしておく：不要なら権限設定の
permissions.denyでAgentツールを拒否し、委譲自体を止められる。Agent(名前)の形式なら、特定のサブエージェントだけを無効化できる。 - 成果物は人が確認する：最終的な良し悪しの判断と責任は、あくまで自分の側に残す。
要は、「作業は任せる。判断と確認は手放さない」という線引きです。これは、そもそもAIにコードを書かせる前の準備とも地続きの話です。あわせて AIにコードを書かせる前に決めること も読んでおくと、迷いが減ります。
つまずきやすいところ
-
/agentsがウィザードを開かない：v2.1.198以降は仕様（ウィザード廃止）。Claudeに頼むか、.claude/agents/を直接編集する。 - 作ったのに認識されない：多くは数秒で自動検知されるが、起動時に
~/.claude/agents/が無かった場合は再起動が要ることも。 - 委譲が多すぎて把握できない：まず1つの役割から。慣れてから増やす。
- 文脈が重い・auto-compactのエラー：大きなファイルの読み込みは、サブエージェントに逃がす／
/compactで対象を絞る／/clearで仕切り直す、が定石。 - 仕様は変わる：コマンドや挙動は更新される。最新は公式ドキュメントで確認する。
委譲や自動化まわりの不具合は、Claude Codeのエラー・不具合の対処 もあわせてどうぞ。
なお、モデルの使い分けについては、単純なサブエージェント用途には低コストなモデル、複雑な設計には上位モデル、という「考え方」が公式に示されています。具体的なモデル名やIDは更新が早いため、最新のClaudeモデルの一覧や選び方は /model コマンドや公式ドキュメントで確認してください。
まとめ
- サブエージェントは、独立したコンテキスト・システムプロンプト・ツール権限を持つ役割特化のAI。Claudeが役割説明を見て作業を委譲する。
- 作り方は
.claude/agents/か~/.claude/agents/にMarkdownを置くだけ。必須はnameとdescriptionのみで、toolsやmodelで権限・コストを調整できる。 - v2.1.198以降、
/agentsの対話ウィザードは廃止。Claudeに依頼するか、ファイルを直接編集するのが公式手順。 - 組み込みのExplore・Plan・general-purposeも使えるが、ExploreとPlanはCLAUDE.mdを読まない点に注意。
- フックや繰り返し作業の自動化と組み合わせると、テスト作成やGit操作などの定型作業を任せられる。
- ただし丸投げは禁物。役割と権限を絞り、差分を承認し、成果物は人が確認する。最新の仕様は公式ドキュメントで確認を。
公式情報は Claude Code公式ドキュメント（サブエージェント） を参照してください（公式ドキュメントは code.claude.com に移転しています）。
関連記事：Claude Codeの全体像は Claude Codeとは？、AIへの指示をまとめるファイルは CLAUDE.mdの書き方、外部サービス連携は MCP連携とは？、任せる前の準備は AIにコードを書かせる前に決めること をどうぞ。カテゴリ一覧は AI活用・ノウハウ へ。
よくある質問（FAQ）
サブエージェントとは何ですか？
サブエージェントは、特定の役割に特化した小さなAIアシスタントです。独立したコンテキスト（作業メモリ）・システムプロンプト・ツール権限を持ち、Claudeが役割説明を見て作業を委譲します。探索やログ処理など大量出力を本会話から切り離し、要約だけ返せるのが利点です。
サブエージェントはどうやって作りますか？
プロジェクトの .claude/agents/ かユーザーの ~/.claude/agents/ にMarkdownファイルを置き、frontmatterで name・description・tools・model などを設定します。Claudeに頼んで作ってもらうこともできます。ファイルは数秒で自動検知され、再起動は基本的に不要です。
自動化すると全部お任せにできますか？
できません。委譲や自動化はあくまで作業の一部を任せる仕組みで、指示の設計・成果物の確認・責任は人の側に残ります。ツール権限を絞り、差分を承認しながら進めるのが安全です。丸投げは想定外の変更や手戻りを招きやすいので避けましょう。
サブエージェントへの委譲を止めることはできますか？
できます。権限設定の permissions.deny で Agent ツールを拒否すると委譲そのものを止められ、Agent(名前) の形式なら特定のサブエージェントだけを無効化できます。まずは委譲される作業や範囲を把握したうえで、必要に応じて制限するのがおすすめです。最新の設定方法は公式ドキュメントで確認してください。
自分で作らなくても使える組み込みサブエージェントはありますか？
あります。読み取り専用で調査を行うExplore、プランモードで計画づくりを担うPlan、汎用のgeneral-purposeが組み込まれています。注意点として、ExploreとPlanはCLAUDE.mdを読み込みません。プロジェクト固有のルールを前提にした作業は、自作のサブエージェントか本会話で行うのが安全です。