何のためのものか
特定種類のタスクを専用のコンテキストウィンドウで処理する AI アシスタント。独自のシステムプロンプト、ツールアクセス、権限を持ち、結果の要約だけをメイン会話へ返す。
つまり subagent は「賢くする道具」である前に「メイン会話を汚さない道具」である。
触る
まず組み込みを使う。
| Agent | ツール | 用途 |
|---|---|---|
| Explore | read-only。Write と Edit は拒否 | ファイル探索、コード検索、コードベース調査 |
| Plan | read-only | plan mode 中の調査 |
| General-purpose | subagent が使えるすべてのツール | 探索と実行の両方を要する複雑・多段のタスク |
大きな調査を Explore に投げ、/tasks で走っているところを見る。Explore を呼ぶとき Claude は thoroughness（quick / medium / very thorough）を指定する。
Explore と Plan は CLAUDE.md と親セッションの git status を読み込まない。 他の組み込みとカスタム subagent は両方を読み込む。
入れる
自分用の subagent を .claude/agents/ に置く。YAML frontmatter + markdown のシステムプロンプトで、必須は name と description だけ。
descriptionは「どの場面で委譲すべきか」を書く。 Claude はこれで判断する- 絞りたいものだけ足す。
tools/disallowedTools（ツール）、model（既定はinherit）、maxTurns、effort、skills（起動時に全内容を preload） - 確実に呼びたいときは
@から typeahead で選ぶ。 手入力なら@agent-<name>。自然言語で名前を挙げるだけだと、委譲するかは Claude の判断になる - セッションごと乗っ取るなら
claude --agent <name>。既定のシステムプロンプトを完全に置き換える
ファイルの追加・編集は数秒以内に検出され次の委譲から反映される（agents ディレクトリを新規作成したときだけ再起動が要る）。
効かせる
思ったツールが使えない・権限が違う、はここで説明が付く。
- ツールは 2 段で絞られる。 第 1 フィルタで
AskUserQuestion/EndConversation/ExitPlanMode（permissionMode: planを除く）などがtoolsに書いても外れる。第 2 フィルタはバックグラウンド実行時で、組み込みツールがRead/Grep/Glob/Bash/Edit/Write/WebFetchなどに絞られる（MCP ツールは全部残る） - permission は親が強い。 親が
bypassPermissionsまたはacceptEditsならそれが優先され、frontmatter のpermissionModeでは上書きできない。親が auto mode なら継承してpermissionModeは無視される - 既定はバックグラウンド実行。 並行して動き、permission が必要になるとメインセッションにプロンプトが出る（
Escはその 1 回の呼び出しだけを拒否し、subagent は止まらない） - 続きをやらせたいなら resume。 完了時に Claude は agent ID を受け取り、
SendMessageで再開できる。Explore と Plan は one-shot で agent ID を返さないため resume できない - 独立して作業させたいなら
isolation: worktree。既定ブランチから分岐する（親のHEADではない）
落とし穴
- メイン会話の auto memory と output style は subagent に届かない（fork を除く）。コンテキストウィンドウも親ではなく自身のモデルで決まる
- ネストと同時実行に上限がある。 既定でメイン会話の 3 層下まで、同時実行は 20。超えると
Concurrent subagent limit reachedで失敗する - subagent の最終レポートはスキャンされてから Claude に渡る。
<system-reminder>を模した文字列にはバックスラッシュが挿入され、指示めいたパターンにはマーカー行が付く。内容の削除も判定もしないので、レポートを鵜呑みにする設計にしない - project レベルの subagent の frontmatter hooks は workspace trust の承認後にしか動かない（承認するまで subagent 自体は動く）
.claude/agents/は再帰的に走査され、identity はnamefrontmatter だけから決まる。同じディレクトリで名前が重複すると片方しか読み込まれない（/doctorが報告する）