Subagent の本質: Context Isolation¶
なぜ subagent なのか¶
subagent の最大価値は 「親の context を汚さない」 こと。並列実行は副次的な効果。
典型的な汚染源: - 巨大ファイルの全文 Read (1万行のログ・大きい JSON) - リポ全体の grep 結果 - 別 LLM の長文応答 - 試行錯誤の途中経過
これらを親で食うと、後の作業で参照すべき本筋の情報がキャッシュから押し出される。
委譲すべき作業の判断¶
| 作業 | 親でやる? subagent? |
|---|---|
| 既知ファイルの編集 | 親 |
| 1-3 ファイルの grep | 親 |
| 「このリポでXは何処?」の探索 | subagent (Explore) |
| 巨大ログ解析 | subagent |
| 別 LLM への hand-off | subagent |
| ライブラリ調査 (10ファイル超) | subagent |
| Plan の作成 | subagent (Plan) or plan mode |
context: fork パターン¶
Skill の frontmatter で context: fork + agent: Explore を指定すると、skill 本文が subagent として実行され、結果サマリだけが親に戻る。
---
description: 大規模リポの API エンドポイントを列挙する
context: fork
agent: Explore
---
src/ 配下を網羅して REST/GraphQL のエンドポイント定義を列挙し、
パス・メソッド・認証要否・ハンドラ関数名を表で返してください。
親への返し方¶
subagent の出力は 構造化 すること。親が次の意思決定に使うので。
良い例 (Markdown 表 + 末尾サマリ):
## Endpoints
| Path | Method | Auth | Handler |
|------|--------|------|---------|
| /users | GET | required | listUsers |
...
## Summary
合計 24 エンドポイント。認証なしは 3 件 (X, Y, Z) — 要確認。
悪い例: 5000語の地の文で報告 → 親が読みきれず、結局再 Read することになる。
親が verify する責務¶
subagent の summary は 「やったつもり」を語る。実際に意図通り動いたかは親が確認する責任がある。
- ファイル編集系: subagent 完了後に diff を読む
- 探索系: 重要箇所だけ親が再 Read して裏取り
- 別 LLM 系: テスト or grep で実在性確認
ありがちな失敗¶
- 「small task でも subagent」→ 起動オーバヘッドで遅くなる。3操作未満は親で
- subagent に全権限を与える → 想定外の編集が発生。
tools:で絞る - 親が subagent の summary を鵜呑み → 「verify but trust」の原則を忘れない
出典¶
- _research/claude-code-features/2026-05-11-claude-code-features.md
- _research/multi-llm/2026-05-11-subagent-other-llm.md (cache hand-off)
- https://code.claude.com/docs/en/sub-agents