結論:Anthropic の Claude Code のサブエージェント(subagent)は、横の仕事(本題の脇で要る調べ物・テスト・ログの読み込みなど)を別の文脈(コンテキスト=作業の記憶)で任せる係です。検索結果・ログ・ファイルの中身で親の会話があふれそうな時に使い、係は自分の文脈で作業して、要約だけを親の会話に返します。組み込みの係(Explore・Plan・general-purpose など)は何も作らなくても使え、同じ指示の係を何度も頼むなら、Markdown のファイル 1 つで自分の係を作れます。この記事は2026年10月29日時点で確認した公式の資料をもとに整理したものです。
- 要点1:係ごとに、自分の文脈・システムプロンプト・使える道具・権限を持つ。係が使う量も、親の会話と同じ利用の上限に数えられる
- 要点2:組み込みは、読むだけで速く探す Explore、計画モードで調べる Plan、調べて直す general-purpose など。説明に合う仕事は Claude が自動で任せる
- 要点3:作り方は、
.claude/agents/(そのプロジェクト)か~/.claude/agents/(自分の全プロジェクト)に YAML の前置き(ファイルの先頭に---で挟んで書く設定)付きの Markdown を置くか、Claude に頼んで書いてもらう。必須の項目は name と description の 2 つ - 要点4:おすすめは、まず組み込みの係をそのまま使い、自分で作るなら公式の例(コードレビューの code-reviewer・デバッガーの debugger・データ分析の data-scientist・読み取り専用の DB の確認の db-reader)を元に、道具を絞った係を 1 つ作ること
- 要点5:何も設定していなければ、Claude が親の会話から起動する係は裏で(バックグラウンドで)動く。会話をまるごと引き継ぐフォークは
/subtaskで始められる。入れ子は既定で 3 層まで。Claude が新しく起動できるのは、動いている係が 20 より少ない間(既定)
Claude Code の基本はClaude Codeとは、日本語での始め方はクロードコードとは、毎日の使い方はClaude Code 使い方で整理しています。仕事で使う頼み方の例はClaude Code Subagentの業務活用プロンプトにまとめています。
Claude Code サブエージェントとは|横の仕事を別の文脈で任せる係
サブエージェントは、決まった種類の仕事を受け持つ専門の AI の係です。公式の資料は、あとで見返さない検索結果・ログ・ファイルの中身で親の会話があふれそうな横の仕事に使う、としています。係はその仕事を自分の文脈で進め、要約だけを返します。同じ指示の係を何度も起動しているなら、自分の係を定義する時です。
係はそれぞれ自分の文脈の窓で動き、自分のシステムプロンプト(係への最初の指示)・使える道具・権限を持ちます。係が出す依頼も、親の会話と同じ利用の上限に数えられます。Claude は、仕事が係の説明(description)に合うとその係に任せ、係は独立して作業して結果を返します。

公式の資料が挙げる、サブエージェントでできることは次の 5 つです。
| できること | 中身(2026年10月29日時点の公式の説明) |
|---|---|
| 文脈を守る | 調べ物や実装の途中の記録を、親の会話の外に置く |
| 制約をかける | 係が使える道具を絞る |
| 設定を使い回す | 自分用(ユーザー)の係は、どのプロジェクトでも使える |
| 振る舞いを専門にする | その分野に絞ったシステムプロンプトを持たせる |
| 費用を抑える | 速くて安いモデルに仕事を回す |
Claude は係の description を見て、いつ任せるかを決めます。description は文脈に入るので短く書きます。組み込み以外の係の description の合計が 15,000 トークンを超えると、Claude Code は起動の時にトークンの合計とともに注意を出します。詳しい指示は、その係が動く時にだけ読み込まれるシステムプロンプトの側へ移します。
フォーク以外のサブエージェントが、始まる時に持っている物は次のとおりです。
| 持っている物 | 中身(2026年10月29日時点の公式の説明) |
|---|---|
| システムプロンプト | 係の定義の本文(組み込みの係は決まった物)に、Claude Code が作業フォルダなどの情報を足した物。Claude Code 自身のシステムプロンプトは入らない |
| 依頼文 | Claude が仕事を渡す時に書く、仕事の要約 |
| CLAUDE.md | メインの会話が読む全部の段(~/.claude/CLAUDE.md・プロジェクトの決まり・CLAUDE.local.md・管理のポリシーのファイルなど)。組み込みの Explore と Plan は読まない |
| git の状態 | 係が始まる時にリポジトリから読む写し。Explore と Plan は読まない |
| 先に読み込むスキル | 前置きの skills に書いたスキルの中身 |
反対に、それまでの会話の履歴・すでに使ったスキル・Claude がすでに読んだファイルは見えません。出力スタイルとメインの会話の自動のメモも届きません。メインの会話の決まりのうち、係にも必ず守らせたい物(たとえば「vendor/ のフォルダは見ない」)は、任せる時の依頼に書き直します。
サブエージェントは 1 つのセッションの中で動く仕組みです。別々のセッションを並べて動かす方法(agent view・agent teams など)との違いは、後の「ほかの並列の仕組みとの違い」の節で比べます。
組み込みのサブエージェント|Explore・Plan・general-purposeほか
Claude Code には、最初から入っている係があり、Claude が合う時に自動で使います。どれも親の会話の許可の規則を引き継ぎ、多くは使える道具が絞られています。Explore と Plan は、調べ物を速く安く進めるため、CLAUDE.md と git の状態の写しを読み込まずに始まります。ほかの組み込みと自分の係は、どちらも読み込みます。
| 係 | 使える道具 | 何に使うか |
|---|---|---|
| Explore | 読むための道具だけ(Write と Edit は使えない) | ファイルを探す・コードを検索する・コードの全体を調べる。変えずに調べたい時に任される |
| Plan | 読むための道具だけ(Write と Edit は使えない) | 計画モードで、計画を出す前にコードを調べる |
| general-purpose | 係が使えるすべての道具 | 調べることと直すことの両方が要る仕事・結果の読み解きが難しい仕事・手順が続く仕事 |
| claude | 係が使えるすべての道具 | ほかのどの係にも合わない仕事の受け皿。agent view から出したバックグラウンドのセッションの既定の係でもある |

このほかに、/statusline でステータスラインを設定する時の statusline-setup と、Claude Code の機能について質問した時に答える claude-code-guide があります。公式の資料の表では、どちらも決まったモデルで動き、ふつうは自動で使われるので、自分で呼ばなくてよいとされています。
- Explore のモデル:基本はメインの会話と同じモデル。例外は、メインの会話が
fable系のモデルで動いている時で、つなぎ方によって変わる(Claude のサブスクリプション・Anthropic Console のアカウント・ANTHROPIC_BASE_URLで通す LLM ゲートウェイならopusの別名が指すモデル、Amazon Bedrock・Google Cloud の Agent Platform・Microsoft Foundry などではメインと同じモデル) - Explore の深さ:Claude が任せる時に、quick(狙いを絞った検索)・medium(つり合いを取った調べ方)・very thorough(くまなく調べる)のどれかを指定する
- Explore を安いモデルで:自分用かプロジェクト用に Explore という名前の係を作ると、組み込みの代わりに使われ、その係の model の値が効く(例:
model: haiku) - general-purpose のモデル:ほかの方法でモデルが決まらず、環境変数
CLAUDE_CODE_SUBAGENT_MODELを決めていればそのモデル。決めていなければメインの会話のモデル
組み込みの係は、対話のセッションでは最初から登録されています。止めたい時は、次の方法があります。
- 決まった係だけ止める:設定の
permissions.denyにAgent(Explore)のように書く(後の「特定の係を止める」の書き方) - どの係にも任せさせない:
Agentのツールそのものをpermissions.denyで止める - Explore と Plan だけ外す:環境変数
CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1(v2.1.198 以降。Claude は自分でファイルを読んで調べる) - 非対話のモードと Agent SDK:
CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1で組み込みを全部外し、自分の係だけを渡す
なお、どの係かを指定しない呼び出しは、セッションに general-purpose が無いと subagent_type is required のエラーで失敗します。
サブエージェントの作り方|Claudeに頼むか、Markdownのファイルを置く
サブエージェントの正体は、YAML の前置き(frontmatter)が付いた Markdown のファイルです。作るには、Claude に頼んで書いてもらうか、自分でファイルを書きます。公式の資料の手順は、読みやすさや速さの改善案を出す自分用の係(code-improver)を作る、次の 3 つです。
- Claude に頼む:Claude Code で、どんな係をどこに置くかを書いて頼む(下の例)。Claude が name・description・tools・model とシステムプロンプトを書いたファイルを作る
- ファイルを見る:
~/.claude/agents/code-improver.mdを開き、前置きが頼んだとおりかを確かめる - 使ってみる:「Use the code-improver agent to suggest improvements in this project」のように頼む。会話の記録には
code-improver(Suggest code improvements)のように、係の名前と短い仕事の説明の行が出る
Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.日本語で頼んでもかまいません(例:「~/.claude/agents/ に、ファイルを読むだけで改善案を出す code-improver の係を作って」)。できあがるファイルは、次のような形です。
---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---
You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.~/.claude/agents/ に置いた係は、その PC のどのプロジェクトでも使えます。1 つのプロジェクトだけで使うなら、そのプロジェクトの .claude/agents/ へ移します。この手順で Claude が新しい係を見つけられないのは、セッションを始めた時に ~/.claude/agents/ のフォルダが無かった場合で、その時は Claude Code を起動し直します(動いているセッションは、新しくできた agents のフォルダに気づかない。起動し直しが要る場合の全体は、後の「ファイルの書き方」の項)。
以前の /agents の対話式の画面は、今はありません。今の /agents は、Claude に頼むか .claude/agents/ と ~/.claude/agents/ を直接編集するよう、案内を出すだけです(v2.1.197 までは、動いている係の Running のタブと、作る・直す・消す Library のタブがあった)。名前の似た 3 つは、次のように別の物です。
| 名前 | 何か |
|---|---|
/agents(会話の中で打つコマンド) | 係のファイルの置き場所を案内する(v2.1.197 までは、係を作る・直す・消す対話式の画面) |
claude agents(シェルで打つコマンド) | 裏で動くセッションを 1 つの画面で見張る agent view を開く |
.claude/agents/・~/.claude/agents/ | 係のファイルを置くフォルダ(そのプロジェクト用・自分の全プロジェクト用) |
置き場所と優先の順|同じ名前ならどれが使われるか
係のファイルの置き場所で、誰が使えるかが決まります。同じ名前の係が複数あると、優先の順が上の物が使われます。
| 置き場所 | 使える範囲 | 優先の順 | 作り方 |
|---|---|---|---|
| 管理の設定(managed settings) | 組織の全体 | 1(いちばん上) | 管理者が管理の設定で届ける |
--agents の CLI のフラグ | そのセッションだけ | 2 | 起動の時に JSON で渡す |
.claude/agents/ | そのプロジェクト | 3 | Claude に頼むか、自分でファイルを作る |
~/.claude/agents/ | 自分の全プロジェクト | 4 | Claude に頼むか、自分でファイルを作る |
プラグインの agents/ のフォルダ | そのプラグインを有効にした所 | 5(いちばん下) | プラグインと一緒に入る |
- プロジェクトの係:そのコードに合わせた係に向き、バージョン管理に入れればチームで使って直していける。今いるフォルダからリポジトリの一番上までの
.claude/agents/を全部読み、同じ name があれば今いるフォルダに近い方が使われる - フォルダ分け:
.claude/agents/と~/.claude/agents/は下のフォルダまで読むので、agents/review/のように分けてよい。係を見分けるのは name の値だけで、フォルダの場所は関係ない - name は重ねない:同じ
.claude/agents/の中(下のフォルダを含む)で同じ name のファイルが 2 つあると、片方しか読み込まれず、どちらになるかはファイルを読む順で決まる(公式に決まった優先の順は無い)。/doctorの点検が、同じフォルダの中で名前が重なるファイルを知らせる - プラグインの係:入れたプラグインの係は自分の係と一緒に読み込まれ、@ の候補にプラグインの名前付き(
my-plugin:code-reviewerなど)で出る。安全のため、プラグインの係では hooks・mcpServers・permissionMode の項目は効かない - 管理の設定の係:組織の管理者が、管理の設定のフォルダの中の
.claude/agents/に置く。同じ名前のプロジェクトや自分の係より先に使われる
プラグインで係を共有する方法はClaude Code Plugin開発ガイドで扱っています。
ファイルの書き方|本文が係のシステムプロンプトになる
ファイルの先頭の --- と --- の間に前置きで設定を書き、その後ろに Markdown でシステムプロンプトを書きます。公式の資料の例は、読むだけの道具でコードを見る係です。
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.ファイルの本文が係のシステムプロンプトになり、Claude Code が作業フォルダなどの基本の情報を足します。Claude Code 自身のシステムプロンプトは入りません(係が始まる時に持つ物の全体は、最初の節の表)。係は親の会話と同じ作業フォルダで始まり、係の中の cd は次の Bash の呼び出しに持ち越されません。リポジトリの別の写しで作業させたい時は、後の項目の isolation: worktree を使います。
Claude Code は ~/.claude/agents/ と .claude/agents/ を見張っていて、ファイルを足したり直したりすると数秒で気づき、次に任せる時から新しい定義を使います(起動し直さなくてよい)。起動し直しが要るのは、セッションを始めた時に無かった agents のフォルダに最初の係を作った時・--add-dir か /add-dir で足したフォルダの係を足すか直した時・--disable-slash-commands で始めたセッションの 3 つだけです。
CLIのフラグで、そのセッションだけの係を作る
起動の時に --agents へ JSON を渡すと、そのセッションの中だけの係を作れます。ファイルには残らないので、試しや自動化のスクリプトに向きます。1 回の --agents で複数の係を渡せます。
claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
},
"debugger": {
"description": "Debugging specialist for errors and test failures.",
"prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
}
}'JSON の一番外のキーが係の名前で、値が定義です(名前を - で始めない)。
- 使える項目:
promptがファイルの本文にあたるシステムプロンプトで、ほかに description・tools・model など前置きと同じ項目を使える。color と experimental はここでは使えず、無視される - Windows:PowerShell では、公式の資料に
@'と'@で囲む書き方がある - ファイルで渡す:非対話のモード(
claude -p)では、同じ中身を書いた JSON のファイルの場所も渡せる(例:claude -p --agents ./agents.json "Review my changes"。v2.1.281 以降。対話のセッションではファイルの場所は受け付けない)
おすすめのサブエージェント|公式の例4つから始める
おすすめは、まず組み込みの Explore・Plan・general-purpose をそのまま使うことです。自分で作るなら、最初の 1 つは公式の資料の例を元にします。例はどれも、1 つの仕事に絞り、要る道具だけを渡しています。まとめると次の 4 つと、手順の節で作った code-improver です。
| 係(name) | する仕事 | 道具(tools)とモデル |
|---|---|---|
code-reviewer | コードを変えずに見て、直すべき点・注意・提案を優先の順に返す | Read, Grep, Glob, Bash・model: inherit(Edit と Write を渡さない) |
debugger | エラーの内容と再現の手順をつかみ、原因を探して、最小の修正を入れて確かめる | Read, Edit, Bash, Grep, Glob(直すので Edit を渡す) |
data-scientist | SQL と BigQuery で分析し、結果を要約する。コードの外の仕事の例 | Bash, Read, Write・model: sonnet |
db-reader | 読み取りのクエリ(SELECT)だけで、データについての質問に答える | Bash と、書き込みを止める PreToolUse のフック(確かめるスクリプトも置く) |
code-improver | 読みやすさ・速さ・よい書き方の点から、ファイルの改善案を出す | Read, Grep, Glob・model: sonnet |

公式の資料の code-reviewer の例は、次のとおりです。呼ばれたら git diff で最近の変更を見て、変わったファイルに絞ってすぐに見始めるよう、システムプロンプトに書いています。
---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer ensuring high standards of code quality and security.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately
Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed
Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)
Include specific examples of how to fix issues.debugger は、調べるだけでなく直す係です。code-reviewer と違い、バグを直すにはコードを変える必要があるので、Edit を渡しています。システムプロンプトには、エラーをつかむ所から、直した後に確かめる所までの流れを書いています。
---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---
You are an expert debugger specializing in root cause analysis.
When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works
Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states
For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations
Focus on fixing the underlying issue, not the symptoms.data-scientist は、ふつうのコードの仕事の外で、データの分析を受け持つ係の例です。分析の力を上げるため、前置きで model: sonnet をはっきり決めています。
---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---
You are a data scientist specializing in SQL and BigQuery analysis.
When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly
Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations
For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data
Always ensure queries are efficient and cost-effective.db-reader は、Bash を使わせながら、読み取りの SQL だけを通す係です。tools の項目より細かく止めたい時に、道具を使う前に動くフック(PreToolUse)で確かめる例です。
---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---
You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.
When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context
You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.フックが呼ぶ確かめるスクリプトは、プロジェクトの中のどこに置いてもよく、場所はフックの command の値と合わせます。スクリプトは、Claude Code から受け取った JSON の中の Bash のコマンドを取り出し、書き込みの SQL があれば終了コード 2 で止めて、エラーの文を Claude に返します。
#!/bin/bash
# Blocks SQL write operations, allows SELECT queries
# Read JSON input from stdin
INPUT=$(cat)
# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')
if [ -z "$COMMAND" ]; then
exit 0
fi
# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
exit 2
fi
exit 0- 実行の権限:macOS と Linux では
chmod +x ./scripts/validate-readonly-query.shで実行できるようにする。付けておかないと、フックは止めずに失敗する - Windows:確かめるスクリプトを PowerShell で書き、フックの項目に
shell: powershellを足す - 守りの順:書き込みを断るのは、まずシステムプロンプトの指示で、フックは予備の守り。それでも係が書き込もうとすると、Claude Code がコマンドを止め、係には
Blocked: Write operations not allowed. Use SELECT queries only.が返る - フックが動かない時:プロジェクトの
.claude/agents/に置いた係の前置きのフックは、その係のファイルがあるフォルダを信頼するまで飛ばされる(係そのものは動く)。claude -pのセッションは信頼したことにならない(後の「フックで条件を付ける」の項)
公式の資料が挙げる、係を作る時のこつは 4 つです。
- 1 つの仕事に絞る:係ごとに、1 つの決まった仕事が得意になるように作る
- 説明で 1 つの係を指す:Claude は description で任せる先を決めるので、正しい係に行くくらい具体的に書き、全部の係の説明の合計を 15,000 トークンの枠に収める
- 道具を絞る:安全と集中のため、要る権限だけを渡す
- バージョン管理に入れる:プロジェクトの係をチームで共有する
公式の資料には、項目ごとの短い例もあります。safe-researcher・browser-tester・api-developer は、後の節でそれぞれの項目の例として出てきます。
- safe-researcher:読むための道具と Bash だけを渡した調べ役(「使える道具を絞る」の項)
- browser-tester:Playwright の MCP サーバーをこの係のためだけにつなぎ、実際のブラウザで機能を試す係(「係にMCPサーバーを渡す」の項)
- api-developer:チームの決まりを書いたスキルを先に読み込んで、API を作る係(「スキルを先に読み込む」の項)
- log-reader:長いログを読んでエラーを報告する係。前置きの
autoCompactWindow: 200000で、自動の圧縮を早める(値は200kでなく数字で書く)
Claude に自分から任せてほしい係は、description に「use proactively」のような言葉を入れます。どの係を作るかに迷ったら、組み込みの Explore・Plan・general-purpose で足りない仕事(毎回同じ指示を書いている仕事)から作ります。
サブエージェントの使い方|自動で任せる・名前で頼む・@で指名する
Claude は、依頼の内容・係の description・今の文脈を見て、自動で係に任せます。自分で係を指定する方法は、軽い順に 3 つあります。
| 頼み方 | 決まり方 | 例 |
|---|---|---|
| 名前を出して頼む | 任せるかどうかは Claude が決める(多くは任せる) | 「Use the test-runner subagent to fix failing tests」 |
| @ で指名する | その 1 つの仕事は、必ずその係で動く | @"code-reviewer (agent)" look at the auth changes |
| セッションごと係にする | メインの会話そのものが、その係の道具の制限とモデルで動く | claude --agent code-reviewer |
名前で頼む時に、決まった書き方はありません。日本語でも、係の名前を出して頼めば、Claude はたいていその係に任せます(例:「code-reviewer の係に、最近の変更を見てもらって」)。
@ を打つと、ファイルと同じように候補から係を選べます。手で打つ時は、自分の係は @agent-<名前>、プラグインの係は @agent-my-plugin:code-reviewer のように書きます。@ で決まるのはどの係を呼ぶかで、係への依頼文は、あなたの依頼を元に Claude が書きます。動いている名前付きの裏の係も、状態と一緒に候補に出ます。
--agent で始めたセッションでは、その係のシステムプロンプトが Claude Code の既定のシステムプロンプトの代わりになります(係のプロンプトが空の時を除く)。CLAUDE.md とプロジェクトのメモは、ふだんどおり読み込まれます。起動の見出しに @<名前> が出れば、その係で動いています。プロジェクトのどのセッションでも使うなら、.claude/settings.json に "agent": "code-reviewer" と書きます(CLI のフラグの方が先に効く)。
コマンドの使い方の全体はClaude Code コマンド一覧にまとめています。
この記事の内容を社内で使うなら
要点と手順をまとめた資料を無料で受け取れます。研修6,000名以上・支援100社以上の実績をもとに、自社の業務に当てはめる相談も30分から受け付けています。
前置き(frontmatter)で決められる項目|必須はnameとdescriptionだけ
前置きで決められる主な項目は、次のとおりです。必須は name と description の 2 つだけです。2 語以上の項目の名前は maxTurns・disallowedTools のように表の綴りどおりに書きます。知らない項目は、エラーを出さずに無視されるので、綴りの間違いに気づきにくくなります。
| 項目 | 決めること(2026年10月29日時点の公式の説明) |
|---|---|
name(必須) | 係を見分ける名前(256 字まで。: は使えない)。ファイル名と同じでなくてよい |
description(必須) | Claude がいつこの係に任せるか |
tools | 使える道具(Read, Grep, Bash のような書き方か YAML のリスト)。書かなければ、係が使えるすべての道具を引き継ぐ |
disallowedTools | 使わせない道具。引き継ぐ道具か tools の中から外す |
model | 使うモデル(sonnet・opus・haiku・fable の別名か、モデルの ID か、inherit) |
permissionMode | 権限のモード(default・acceptEdits・auto・dontAsk・bypassPermissions・plan) |
maxTurns | 止まるまでのターン(やり取りの 1 往復)の上限。上限で止まると、出力は途中の物という印付きで返り(v2.1.246 以降)、続きを頼める |
skills | 起動の時に係の文脈へ読み込んでおくスキル(説明だけでなく中身まで入る) |
mcpServers | この係で使う MCP サーバー(その場で書いた定義は、この係が動く間だけつながる) |
hooks | この係が動いている間だけ働くフック |
memory | 会話をまたいで残すメモの範囲(user・project・local) |
background | true にすると、Claude が結果を待とうとしても裏で動かし続ける |
omitClaudeMd | true にすると、自分・プロジェクト・ローカルの CLAUDE.md を読まずに始める(v2.1.271 以降)。管理のポリシーのファイルは読む(管理の設定の係を除く)。--agent か設定の agent でセッションの主役にした時は効かない |
effort | この係の推論の深さ(low・medium・high・xhigh・max。選べる段はモデルによる)。環境変数 CLAUDE_CODE_EFFORT_LEVEL を決めていると、そちらが先に効く |
isolation | worktree にすると、一時的な git の worktree(リポジトリの別の写し)で動く。何も変えなければ自動で片づく |
color | タスクの一覧と会話の記録での色 |
initialPrompt | この係をセッションの主役として動かした時(--agent か設定の agent)に、最初の依頼として自動で送る文(プラグインの係では効かない) |
このほか、係ごとに自動の圧縮(会話の要約)を早める autoCompactWindow(v2.1.296 以降)と、試しの設定の experimental があります。isolation の worktree は、親のセッションの今の位置でなく、既定ではリポジトリの既定のブランチから分かれます。
次の場合、Claude Code はそのファイルを、セッションの中で何も知らせずに飛ばします。係が見当たらない時は、まずここを確かめます。
- name が無い:係の横に置いた説明の文書として扱われる
- 始めの
---がファイルの 1 行目でない:前置きの無いファイルとして読まれ、説明の文書として扱われる - name が
-で始まる・:を含む・256 字より長い:飛ばして、--debugの記録にエラーを書く - name はあるが description が無い:飛ばして、
--debugの記録に理由を書く - YAML として読めない:項目を何も読まずに飛ばし、
--debugの記録に読めなかったわけを書く
記録を見るには、claude --debug で起動します。セッションの前に、claude plugin validate .claude/agents のようにフォルダを指定して、前置きが読めないファイルを探すこともできます(v2.1.233 以降。name が無いだけのファイルは知らせない)。
モデルの決まり方|呼び出し・前置き・環境変数・メインの順
係のモデルは、次の順で先に決まった物が使われます(v2.1.251 以降の順。それより前は、環境変数がいちばん先だった)。
- Claude が呼び出しの時に渡したモデル(
sonnet・opus・haiku・fableの別名だけで、モデルの ID やinheritは渡せない) - 係の前置きの model(
inheritならメインの会話のモデル) - 環境変数
CLAUDE_CODE_SUBAGENT_MODELに別名かモデルの ID を決めていれば、そのモデル - メインの会話のモデル
呼び出しか前置きの model で、メインの会話のモデルと同じ系統の別名(たとえばメインが opus 系の時の opus)を指定すると、係はメインとまったく同じモデルで動き、同じ大きさの文脈の窓を使えます。環境変数 CLAUDE_CODE_SUBAGENT_MODEL の別名は、いつもその別名が指す版になります。また、環境変数だけでは、組み込みの Explore と Plan のモデルは変わりません。すべての係を 1 つのモデルにそろえたい時は、CLAUDE_CODE_SUBAGENT_MODEL に加えて CLAUDE_CODE_SUBAGENT_MODEL_FORCE を 1 にします(v2.1.257 以降)。係がどのモデルで動いているかは、/tasks の一覧の行で見られます(v2.1.242 以降)。
{
"env": {
"CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
"CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
}
}係は、メインの会話の拡張思考(extended thinking)の設定も引き継ぎます(v2.1.198 以降)。係ごとに思考を切り替える設定はありません。推論の深さは、前置きの effort で係ごとに決められます。
使える道具を絞る|toolsとdisallowedTools
係は、メインの会話で使える組み込みの道具と MCP の道具を引き継ぎます。ただし、質問を出す AskUserQuestion や計画モードに入る EnterPlanMode などは、フォーク以外の係から外れます(tools に書いても外れる。フォークはメインの会話と同じ道具を持つ)。裏で動く係(既定)は、使える組み込みの道具がさらに絞られ、Read・Grep・Glob・Bash・Edit・Write・WebFetch・WebSearch などの決まった物だけになります(MCP の道具は残る)。同じ定義でも、手前で動く時と裏で動く時で、使える道具が変わることがあります。
道具を絞るには、tools で使ってよい道具を並べるか、disallowedTools で使わせない道具を並べます。両方を書くと、先に disallowedTools で外してから、残りから tools を選びます。
---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---この例の係は、ファイルの編集・書き込みと MCP の道具を使えません。反対に、書き込みだけを外して残りを全部引き継ぐなら disallowedTools: Write, Edit と書きます。MCP のサーバー単位でも指定できます。
| したいこと | 項目 | 書き方の例 |
|---|---|---|
| 1 つのサーバーの道具を全部渡す | tools | mcp__github__* |
| 1 つのサーバーの道具を外す | disallowedTools | mcp__github か mcp__github__* |
| どのサーバーの MCP の道具も外す | disallowedTools | mcp__* |
disallowedTools に Bash(git push *) のような条件付きの書き方をしても、その道具ごと外れます。Bash を残して決まったコマンドだけ止めたい時は、設定の permissions.deny に Bash の拒否の規則を書きます(規則はメインの会話と係の両方に効く)。なお、仕事を任せる道具は v2.1.63 で Task から Agent に名前が変わりました。設定や定義に残る Task(...) の書き方も、そのまま使えます。
係にMCPサーバーを渡す|mcpServers
mcpServers を書くと、メインの会話には無い MCP サーバーを、その係にだけ使わせられます。1 つずつ、その場でサーバーの定義を書くか、すでに設定してあるサーバーの名前を書きます。その場で書いたサーバーは係が始まる時につながり、終わると切れます。名前で書いたサーバーは、親のセッションのつながりを共有します。
---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
# Inline definition: scoped to this subagent only
- playwright:
type: stdio
command: npx
args: ["-y", "@playwright/mcp@latest"]
# Reference by name: reuses an already-configured server
- github
---
Use the Playwright tools to navigate, screenshot, and interact with pages.MCP サーバーをメインの会話に入れず、その道具の説明でメインの文脈を使わせたくない時は、.mcp.json でなく、ここにその場の定義で書きます。プロジェクトの .claude/agents/ の係に書いたその場のサーバーは、その係のファイルがあるフォルダを信頼した後にだけ読み込まれます(v2.1.238 以降)。管理の設定の MCP の制限は、係の前置きのサーバーにも効きます。MCP の仕組みはMCP の実装ガイド、サーバーの作り方はMCP Server構築ガイドで扱っています。
権限のモード|書かなければ親の会話のモードを引き継ぐ
permissionMode を書かなければ、係はメインの会話の権限のモードを引き継ぎます。書いた値が効くかどうかは、メインの会話のモードで決まります。
- メインが bypassPermissions・acceptEdits・auto の時:係もそのモードで動き、書いた permissionMode は無視される
- メインが plan の時:係は、permissionMode に何を書いても plan のまま動く(agent teams の仲間として動く時を除く)。dontAsk を書くと、plan のモードで承認を聞くはずの操作は、聞かずに断られる
- メインが default・dontAsk の時:係は書いたモードで動く。ただし bypassPermissions を書いた時(v2.1.267 以降)と、係に auto が使えない時(設定で auto を止めている・係のモデルが auto に対応していない)は、メインのモードのまま
v2.1.267 以降では、bypassPermissions の係は、メインの会話が bypassPermissions の時にだけ、そのモードで動きます。auto のモードはClaude Code Auto Modeの記事で紹介しています。Claude Code の事故を防ぐ設定の全体はClaude Code の危険性と事故を防ぐ5つの対策で整理しています。
スキルを先に読み込む・会話をまたいで覚えさせる
skills に並べたスキルは、起動の時に中身ごと係の文脈に入ります(リストの最初の 32 個まで)。これは読み込んでおくスキルを決めるだけで、使えるスキルを決める物ではありません。書かなくても、係は Skill の道具でプロジェクト・自分・プラグインのスキルを使えます。スキルを使わせたくない時は、tools から Skill を外すか、disallowedTools に入れます。スキルそのものはClaude Code Skillsとは、社内での使い方はClaude Skillsエンタープライズ社内展開で紹介しています。
---
name: api-developer
description: Implement API endpoints following team conventions
skills:
- api-conventions
- error-handling-patterns
---
Implement API endpoints. Follow the conventions and patterns from the preloaded skills.memory を書くと、係に会話をまたいで残るフォルダができ、コードの型や不具合の手がかりなどを書きためられます。範囲は 3 つで、公式の資料はバージョン管理で共有できる project を既定のおすすめとしています。
| 範囲 | 置き場所 | 向く時 |
|---|---|---|
user | ~/.claude/agent-memory/<係の名前>/ | 全プロジェクトで覚えておく |
project | .claude/agent-memory/<係の名前>/ | そのプロジェクトの知識をバージョン管理で共有する |
local | .claude/agent-memory-local/<係の名前>/ | そのプロジェクトの知識だが、バージョン管理には入れない |
memory を有効にすると、係のシステムプロンプトに、そのフォルダの MEMORY.md の最初の 200 行か 25KB(先に届く方)が入り、メモを書くための Read・Write・Edit の道具も使えるようになります。自動のメモ(auto memory)を切っていると、memory の項目は効きません。
フックで条件を付ける・特定の係を止める
道具の一部だけを許したい時は、道具を使う前に動くフック(PreToolUse)で確かめます。例は「おすすめ」の節の db-reader です。前置きのフックについて、知っておくことは次のとおりです。
- 働く間:その係が動いている間だけ働き、終わると片づく。前置きの Stop のフックは、係として動く時は SubagentStop に置き換わる
- 信頼の確認:プロジェクトの係の前置きのフックを動かすには、その係のファイルがあるフォルダを信頼する確認に答えておく。信頼する前は、係は動くがフックだけ飛ばされ、どう信頼するかが
--debugの記録に出る。親のフォルダを信頼しただけでは足りず、claude -pのセッションは信頼したことにならない - 確認が要らない係:
~/.claude/agents/の係と、--agentsで渡した定義のフックは、この確認なしに動く
設定の settings.json には、係が始まった時(SubagentStart)と終わった時(SubagentStop)に動くフックも書けます。フックの書き方はClaude Code Hooksガイドで詳しく扱っています。
決まった係を使わせたくない時は、設定の permissions.deny に Agent(係の名前) の形で書きます。組み込みの係にも自分の係にも効き、CLI では --disallowedTools のフラグでも同じ指定ができます。
{
"permissions": {
"deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
}
}並列で任せる・順に任せる|向く仕事と向かない仕事
公式の資料は、よく使う形を 3 つ挙げています。
- 量の多い作業を切り離す:テストを流す・資料を取ってくる・ログを読むような、出力の多い作業を係に任せ、要る要約だけを親に戻す(例:「Use a subagent to run the test suite and report only the failing tests with their error messages」)
- 並列で調べる:互いに関係しない調べ物を、複数の係に同時に任せる(例:「Research the authentication, database, and API modules in parallel using separate subagents」)。調べる道が互いに頼らない時にいちばん効く
- 順につなぐ:手順が続く仕事は、係を順に使う。係が結果を返すと、Claude が要る文脈を次の係へ渡す(例:code-reviewer で速さの問題を見つけ、optimizer で直す)
並列には注意もあります。係が終わると結果はメインの会話に戻るので、細かい結果を返す係をたくさん動かすと、メインの文脈を大きく使います。係はそれぞれ動いている間も自分のトークンを使います。ずっと並べて動かし続ける仕事や、1 つの文脈の窓に収まらない仕事は、別々のセッションで動かします。
サブエージェントでなく、メインの会話で進めた方がよいのは、次のような時です。
| メインの会話が向く時 | サブエージェントが向く時 |
|---|---|
| 何度もやり取りして詰める仕事 | メインの文脈に要らない、出力の多い仕事 |
| 計画・実装・テストのように、段階をまたいで多くの文脈を共有する仕事 | 道具の制限や権限を、仕事ごとに決めたい時 |
| 小さく狙いの決まった直し | それだけで完結し、要約を返せる仕事 |
待ち時間を短くしたい時も、メインの会話が向きます。フォーク以外の係は白紙から始まるので、文脈を集める時間がかかることがあります。

メインの会話の文脈の中で繰り返し使う指示や手順なら、サブエージェントでなくスキルも考えます(スキルはサブエージェントの中で動かすこともできる)。今の会話にある物についての質問は、係でなく /btw で聞きます(会話を全部見て答えるが、道具は使わず、答えは会話の履歴に加わらない)。
裏で動くサブエージェント|既定ではバックグラウンド・待たせる方法
係は、手前(フォアグラウンド)か裏(バックグラウンド)で動きます。手前の係は終わるまでメインの会話を止め、許可の確認はそのつどあなたに出ます。裏の係はあなたの作業と並んで動き、許可が要る道具を使う時は、どの係が聞いているかを付けてメインのセッションに確認が出ます。認めれば係は続き、Esc を押すと、係を止めずにその 1 回の呼び出しだけを断れます。
何も設定していなければ、Claude がメインの会話から起動する係は裏で始まります。結果を待たせたい時の扱いは、使い方で違います。
claude -pと Agent SDK:Claude は、自分の判断か、あなたに頼まれた時に、係を待てる(Agent SDK の全体はClaude Agent SDK の解説)- 手元の PC の対話のターミナル・VS Code・デスクトップアプリ:Claude に係を待たせるには、既定でオンのフォークの仕組み(fork mode)を切る
フォークの仕組みを切って、待たせる手順は次のとおりです。
- 設定の
settings.jsonなどで、環境変数CLAUDE_CODE_FORK_SUBAGENTを0にする(下の例) - シェルから
claudeを起動し直すか、VS Code で新しい会話を開く - 先に結果が要る時に、「run the reviewer subagent and wait for its report」のように待つよう頼む
{
"env": {
"CLAUDE_CODE_FORK_SUBAGENT": "0"
}
}Claude が待っている間も作業を続けたい時は、ターミナルで Ctrl+B を押すか、VS Code で「Run in background」を押します。フォークの仕組みを切る代わりに環境変数 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS を 1 にすると、Claude は係が終わるのを待ってから先に進みます。裏で動くコマンドも止まり、Ctrl+B でも裏に回せなくなります。
裏の係について、知っておくことは次のとおりです。
- 道具:手前の係より、使える組み込みの道具が少ない(会話のフォークと、手前で動いていて続きを頼まれた係を除く)
- 許可:裏の係の許可の確認は、すべてメインのセッションに出る。「このセッションの間ずっと」のように 1 回より長く効く答えを選ぶと、メインの会話を含めたセッション全体に効く
- 結果:係の結果は、後の番に、終わったことを知らせるメッセージで Claude に届く。Claude はそれを待ってから結果を伝え、先に進み具合を聞くと「まだ動いている」と答える
- 終わった後:うまく終わった係の行は、プロンプトの下の一覧からすぐ消え、30 秒の間
/tasksで中身を開ける。失敗した係と止めた係の行は 30 秒残る
フォークとは|会話をまるごと引き継ぐサブエージェント
フォーク(fork)は、それまでの会話をまるごと引き継いで始まる係です。ふつうの係のように白紙から始まらず、メインのセッションと同じシステムプロンプト・道具・モデル・会話の履歴を見るので、状況を説明し直さずに横の仕事を任せられます。フォークの道具の呼び出しはメインの会話に入らず、最後の結果だけが戻るので、メインの文脈はきれいなままです。ほかの係では背景の説明が多すぎる時や、同じ出発点からいくつかのやり方を並べて試したい時に使います。
フォークの仕組み(fork mode)がオンの間は、Claude が自分からフォークを始めることがあり、オンが既定です(v2.1.302 から既定でオン、対話のターミナルでは v2.1.232 から)。自分で始めるなら、フォークの仕組みがオンでもオフでも、/subtask の後に仕事を書きます。フォークの名前は、仕事の最初の言葉から付きます。
/subtask draft unit tests for the parser changes so farフォークはプロンプトの下の一覧に出て、作業を続けている間も裏で動き、終わると結果がメインの会話にメッセージで届きます。一覧では ↑ と ↓ で行を選び、Enter でそのフォークの記録を開いて続けて頼めます。x で止める(動いていない行は消す)、Esc で入力欄に戻ります。agent view を切っている時は /subtask が無く、/fork がフォークを始めます(agent view がある時の /fork は、セッション全体を新しいバックグラウンドのセッションに写す)。
| 違い | フォーク | ふつうの係 |
|---|---|---|
| 文脈 | それまでの会話の履歴をすべて | 渡した依頼文で始まる新しい文脈(会話の履歴は引き継がない) |
| システムプロンプトと道具 | メインのセッションと同じ | 係の定義のファイルから(裏で動く時は絞られる) |
| モデル | メインのセッションと同じ | 係の model の項目から |
| プロンプトのキャッシュ | メインのセッションと共有 | 別のキャッシュ |

フォークは最初の依頼でメインのプロンプトのキャッシュを使い回すので、同じ文脈が要る仕事なら、新しい係より費用が少なくて済みます。Claude がフォークを始める時に isolation: "worktree" を渡すと、フォークのファイルの編集は、あなたの作業中のフォルダでなく別の git の worktree に書かれます。フォークは、さらにフォークを始められません。
Claude が自分でフォークを始めないようにするには、2 つの方法があります。フォークの仕組みがオンの間は、手元の対話のターミナル・VS Code・デスクトップアプリで、Claude は係を待てない点にも注意します。
- フォークだけ止める:設定の
permissions.denyに"Agent(fork)"を足す - フォークの仕組みを切る:
CLAUDE_CODE_FORK_SUBAGENTを0にする(前の節の「待たせる」手順と同じ)
入れ子と同時の数|既定で3層まで・同時に20まで
係は、自分の係を起動できます(入れ子)。既定では、メインの会話から下へ 3 層までです。上限の層では、フォーク以外の係から Agent の道具が外れ、係は任された仕事を自分で進めて、要約を 1 つ返します。入れ子は、レビューの係が指摘ごとに確かめの係を出すような、それ自体が並列の小さな仕事に分かれる仕事に向きます。
- 対話のターミナル:あなたに戻るのは、いちばん上の係の要約だけ。裏の係を起動した係は、その結果を待ってから終わる
claude -pと Agent SDK:フォークの仕組みがオンの間は、起動した係が待つ。切ると、入れ子の係は裏で始まり、起動した係より長く動いた分の報告はメインの会話に届く- 層の数を変える:環境変数
CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH(例:2で 2 層まで、1で入れ子をなしに) - 1 つの係だけ入れ子を止める:読むだけにしておきたいレビューの係などは、tools から Agent を外すか、disallowedTools に入れる
{
"env": {
"CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
}
}同時に動かせる数にも上限があります。既定では、1 つのセッションで 20 の係が動いている間は、Agent の道具で新しく起動すると Concurrent subagent limit reached のエラーで失敗し、動いている数が上限を下回ると、また起動できます。数は環境変数 CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で変えられます(v2.1.217 以降)。セッションで起動できる係の合計には上限がありません。
/subtaskで自分で始めたフォークは、動いている間は枠を 1 つ使うが、上限では止まらない- 終わった係の続きを頼むと、上限を確かめずに新しい枠を使う(上限を超えることがある)
- ultracode が有効なセッションでは、この上限は効かない
- 動的ワークフロー(dynamic workflows)のエージェントと agent teams の仲間は、それぞれ別の上限に従う
続きを頼む・失敗した時・報告の点検
係は、呼ぶたびに新しく起動し、前の続きにはなりません。前の係の続きをさせたい時は、Claude に続きを頼みます。続きを頼まれた係は、前の道具の呼び出し・結果・考えの流れをすべて持ったまま続けます。
- ID と名前:係が終わると、Claude は係の ID を受け取る。Claude は SendMessage の道具で、ID か名前を宛先にして続きを頼む。SendMessage は agent teams を有効にしていなくても使える。係に名前が付くのは、agent teams を有効にして始めたセッションで、Claude が起動の時に付けた場合
- 続けられない係:組み込みの Explore と Plan は 1 回きりで ID を返さないので、続きを頼めない。続きが要る仕事は general-purpose か自分の係に任せる
- ターンの上限で止まった時:maxTurns の上限で止まると、出力は途中の物として返り、Claude が続きを頼める
- あなたが止めた係:
/tasksの x などで止めた係は、自動では再開しない - 会話の記録:係の記録は
~/.claude/projects/{project}/{sessionId}/subagents/にagent-{agentId}.jsonlとして残り、メインの会話を圧縮しても消えない。既定では 30 日(cleanupPeriodDays)で自動で消える
利用の上限やサーバーのエラーで係が止まった時の動きは、次のとおりです。
- 手前の係:途中までの出力が「途中で切れた」という注記付きで返るか、
Agent terminated early due to an API errorのエラーになる - 裏の係:失敗の印が付き、エラーの内容と最後の出力が Claude に届く
- モデルの代わりの順(fallback model chain)を決めている時:係のモデルが使えない時などに、代わりの順の中で依頼を受け付けた最初のモデルへ切り替わって作業を続け、報告の先頭に切り替えた旨の 1 行が付く
エラーが解けたら、Claude にやり直しか続きを頼みます。
Claude Code は、係の最後の報告を Claude が読む前に点検します。係が読んだファイルや Web のページに、メインの会話に向けた指示が紛れ込んでいることがあるためです。点検は文を消したり書き換えたりせず、次の 2 つだけをします。
- バックスラッシュを入れる:Claude Code の出力に似せた部分(
<system-reminder>のタグや、Human:・Assistant:で始まる行)に入れて、ふつうの文として読まれるようにする - 印の行を足す:そうしたタグに似せた文や、
bypassPermissionsのような権限の設定に触れた文があると、報告の先頭に印の行を足す
点検は、中身が悪意のある物かどうかを判断しません。報告に従って Claude が道具を使う時も、ふだんの許可の確かめとサンドボックスは効きます。点検は、係が触れられる範囲を絞ることの代わりにはなりません。AI エージェントの安全の考え方の全体はAI エージェントのセキュリティの解説で整理しています。
ほかの並列の仕組みとの違い|agent view・agent teams・動的ワークフロー
Claude Code には、いくつもの仕事を同時に進める方法が 5 つあります。違いは、あなたがどれだけ関わるかと、仕事が手元の PC とクラウドのどちらで動くかです。どの方法でも、働き手は Claude のセッションです。
| 方法 | 何ができるか(2026年10月29日時点の公式の説明) | 向く時 |
|---|---|---|
| サブエージェント | 1 つのセッションの中の係が、横の仕事を自分の文脈で進めて要約を返す | 横の仕事の検索結果・ログ・ファイルの中身で、メインの会話があふれそうな時 |
| agent view | 裏で動くセッションを 1 つの画面から出して見張る(claude agents で開く・研究プレビュー) | 互いに関係しない仕事をいくつも任せ、状態をひと目で見て、要る時だけ入りたい時 |
| agent teams | リーダーが、共有のタスクの一覧とセッションどうしのメッセージで、複数のセッションを動かす(実験的で既定では無効) | Claude に仕事を分けて割り当てさせ、働き手の足並みをそろえたい時 |
| projects | claude.ai/code かデスクトップアプリの 1 つの会話から、Claude がスレッドと呼ぶ並列のセッションを始める(Pro と Max で公開ベータ) | 何日・何週間にわたる仕事を、PC を切っても動かし続けたい時 |
| 動的ワークフロー(dynamic workflows) | たくさんの係を動かし、結果を突き合わせる台本 | 数体の係では収まらない仕事や、結果を互いに確かめたい時(コード全体の監査・500 のファイルの移行など) |
このほか、セッションごとに別の git の写しを使う worktree、手元や別の PC・クラウドのセッションどうしでやり取りする機能、1 つの大きな変更を 5〜30 の係(それぞれ別の worktree)に分ける /batch のスキルがあります。いくつものセッションや係を同時に動かすと、トークンの使用量もその分増えます。
- 誰がまとめるか:1 つの会話の中で Claude が任せて集めるならサブエージェント、あなたが仕事を渡して後で見るなら agent view、Claude が計画して割り当てて見張るなら agent teams、Claude の判断でなく台本が計画を持つなら動的ワークフロー
- 同じファイルを触るか:触るなら worktree で分ける。サブエージェントも、自分で動かすセッションも、それぞれ別の worktree を使える。agent teams は仲間を worktree で分けないので、仲間ごとに受け持つファイルを分ける
- 動いている物の見方:今のセッションの裏で動く物は
/tasks、裏のセッションはclaude agents、動的ワークフローは/workflows。名前は似ているが、/agents(係のファイルの場所の案内)とclaude agents(agent view)は別物
agent teams の使い方はClaude Code Agent Teamsの使い方、AI エージェントを会社に入れる全体の流れはAI エージェント導入の進め方で紹介しています。
よくある質問
Claude Codeのサブエージェントとは何ですか?
サブエージェントは、横の仕事を別の文脈で任せる、専門の AI の係です。係は自分の文脈・システムプロンプト・使える道具・権限を持ち、作業して要約だけをメインの会話に返します。検索結果やログでメインの会話があふれそうな時に向きます。係が使う量も、メインの会話と同じ利用の上限に数えられます。
おすすめのサブエージェントはどれですか?
まずは組み込みの Explore(読むだけで速く探す)・Plan(計画モードで調べる)・general-purpose(調べて直す)を、何も作らずに使います。自分で作るなら、公式の資料の例の code-reviewer(Read, Grep, Glob, Bash で変更を見る)・debugger・data-scientist・db-reader(読み取りの SQL だけ)を元に、道具を絞った係を 1 つ作るのがおすすめです。4 つの例の定義は、本文の「おすすめ」の節にそのまま載せています。
サブエージェントの作り方は?
Claude に「~/.claude/agents/ に読むだけのレビューの係を作って」のように頼むか、.claude/agents/(そのプロジェクト)か ~/.claude/agents/(自分の全プロジェクト)に、YAML の前置き付きの Markdown のファイルを置きます。必須の項目は name と description の 2 つで、tools で道具を絞り、model でモデルを変えられます。ファイルを足したり直したりすると、数秒で使えるようになります(セッションを始めた時に無かった agents のフォルダに最初の係を作った時などは、起動し直す)。
general-purposeとは何ですか?
Claude Code に組み込みの係の 1 つで、調べることと直すことの両方が要る仕事・結果の読み解きが難しい仕事・手順が続く仕事を受け持ちます。係が使えるすべての道具を持ちます。モデルは、ほかで決まらず CLAUDE_CODE_SUBAGENT_MODEL を決めていればそのモデル、決めていなければメインの会話のモデルです。
/agentsコマンドはどうなりましたか?
今の /agents は、Claude に頼むか .claude/agents/ と ~/.claude/agents/ を直接編集するよう、案内を出すだけです。v2.1.197 までは、係を作る・直す・消す対話式の画面がありました。動いている係は /tasks で見られ、名前付きの裏の係は @ の候補にも状態と一緒に出ます。名前は似ていますが、claude agents は裏のセッションを見張る agent view を開く別のコマンドです。
サブエージェントはいくつ同時に動かせますか?
既定では、1 つのセッションで 20 の係が動いている間は、Claude が Agent の道具で新しく起動できません(数は CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS で変えられる)。/subtask のフォークと、終わった係の続きの依頼は、この上限で止まらないので、動いている数が 20 を超えることもあります。セッションの中で起動できる合計の数には上限がありません。係がさらに係を起動する入れ子は、既定でメインの会話から 3 層までです(CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH で変えられる)。
サブエージェントを使うと使用量は増えますか?
係はそれぞれ自分の依頼を出し、その分もメインの会話と同じ利用の上限に数えられます。いくつもの係を同時に動かすと、トークンの使用量はその分増えます。細かい結果を返す係をたくさん動かすと、メインの文脈も多く使います。安く済ませたい仕事は、係の model に速くて安いモデルを指定できます。プランごとの料金はClaude Code料金にまとめています。
スキルやAgent Teamsとの違いは何ですか?
スキルは、メインの会話の文脈の中で使い回す指示や手順です。サブエージェントは、別の文脈で横の仕事を進めて要約を返す係です。agent teams は、リーダーが共有のタスクの一覧とメッセージで複数のセッションを動かす仕組みで、実験的で既定では無効です。サブエージェントは、起動した会話に報告を返します。
最終確認日: 2026年10月29日
まとめ:まず組み込みを使い、同じ指示を繰り返す仕事から係を作る
- 何か:横の仕事を別の文脈で任せ、要約だけを受け取る係。係ごとに文脈・システムプロンプト・道具・権限を持つ
- 組み込み:Explore(読むだけで探す)・Plan(計画モードで調べる)・general-purpose(調べて直す)など。説明に合う仕事は Claude が自動で任せる
- 作る:
.claude/agents/か~/.claude/agents/に Markdown を置くか、Claude に頼む。必須は name と description。おすすめは公式の例を元に、道具を絞った係を 1 つ - 動き方:何も設定していなければ裏で動く。会話を引き継ぐフォークは
/subtask。入れ子は既定で 3 層まで、Claude が新しく起動できるのは動いている係が 20 より少ない間。たくさん動かすほどトークンも増える
Claude Code を社内で使いたい会社にはClaude Code 法人研修があります。1対1で教わりたい場合はClaude Code 個別指導があります。ご質問はお問い合わせフォームからどうぞ。
参考・出典
Claude Code の公式ドキュメント(2026年10月29日確認)
- サブエージェント: Create custom subagents
- 並列の方法の比べ方: Run agents in parallel
著者: 佐藤傑(さとう・すぐる)
株式会社Uravation代表取締役。X(@SuguruKun_ai)フォロワー約10万人。100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』『Claude仕事術』(SBクリエイティブ・シリーズ累計66,000部)、『AI推進担当になったら読む本』(大和書房)。SBクリエイティブ「ビジネス+IT」ほかで生成AI連載を執筆(NewsPicks最大1,125ピックス)。ご質問・ご相談はお問い合わせフォームからお気軽にどうぞ。
監修:株式会社Uravation(生成AI活用書籍シリーズ累計66,000部の著者チームが運営。自社7メディアの実運用でAI検索からの引用・流入を継続計測し、その知見に基づいて編集しています。仕様・料金が変わりやすい領域のため、重要な意思決定の前には各公式情報の最新版をご確認ください)
この記事の内容を社内展開する方へ: Claude Code × ビジネス活用 実践ガイド(無料・PDF 30ページ+Excel) をダウンロードできます。



