この投稿は、私、伊東美沙貴（AISHA株式会社）がClaude認定資格（CCA）取得に向けて学習した記録です。
今日はIntroduction to subagentsを60分ほど学習します。
ここに書いていることは私が読んで理解したことのメモ書きです。
（翻訳や意図を間違えている場合があります）
参考URL： Introduction to subagents
結果：クイズなしで修了 (May 3, 2026)
サブエージェントとは？
Claude Codeがタスクを委任できる特別なアシスタントのこと。
各サブエージェントはカスタムプロンプトを実行し、中間処理を行い、メインのコンテキストウィンドウに要約を返す。
全てのツールと呼び出し結果は、メインのコンテキストウィンドウに保存される。
Claude Codeには、すぐに使用できるサブエージェントが3つある。
1. General purpose subagent （汎用サブエージェント）
探索＋アクションの両方が必要なマルチステップタスク向け。最も汎用的。
2. Explore （探索）
コードベースの高速検索とナビゲーション専用。
読むだけ・変更しないタスクに特化し、速くて軽い。
3. Plan (プラン)
実際に手を動かす前に「まずどう対応するか計画を立てる」ための専用エージェント。
プランを考えるが実行はしない。
サブエージェントを使うことで、メインコンテキストウィンドウを清潔に維持。
メインコンテキストのノイズが少ないほど、作業時間が長く、より効果的に作業できるようになる。
サブエージェントの作成
Claude Codeにはサブエージェントが含まれているが、特定のタスクに特化したサブエージェントを作ることができる。
サブエージェントの作成に最も簡単な方法は「/agents」コマンドを使用する。
サブエージェントの作成にはClaude Codeを使用することをおすすめする。
（コードレビュー担当や、品質向上、セキュリティ向上のエージェントなど）
subagentの作り方
- /agents コマンドを実行
- 新しいエージェントを作成を選択
- 現在のプロジェクト専用のサブエージェントを作る or
マシン上の全てのプロジェクトで共有するサブエージェントを作るか選択 - このサブエージェントがアクセスできるツールを選
- 次に、サブエージェントを動かすモデルを選択（Haiku, Sonnet, Opus）
- 色を選択（自動、赤、青、緑、黄色、紫、オレンジ、ピンク、シアン）
- .mdファイルの説明文は一行に収める（description, tools, model, color）
- エスケープされた改行文字が含まれていることに注意
- サブエージェントをより頻繁に自動的に使用させたい時は説明文に「proactively (積極的に)」という単語を入れる。
description: Proactively suggest running this agent after major code changes…
（コードの大幅な変更後、このエージェントの実行を積極的に提案する） - Claudeがサブエージェントを使用するタイミングを理解するのに役立つ会話を追加
モデルの違い
- Haiku：素早い作業
- Sonnet：HaikuとOpusの中間
- Opus：複雑な分析
- Inherit：メインのものを継承
サブエージェントをいくつか作ったら、Claude Codeにサブエージェントを使うように依頼すると面白い。
Designing effective subagents
サブエージェントがどう働くか。（config設定）
コンテキストウィンドエージェントにメッセージを送信すると、各サブエージェントの名前と説明がシステムプロンプトに表示される。サブエージェントをより細かく制御したい時は、名前と説明を調整すること。
サブエージェント起動させると、メインエージェントが入力プロンプトを表示する。
この際、Diescrioptionsを参照するので呼び出すタイミングなど指定しておく。
最も重要な点は、システムプロンプトで出力形式を定義すること。
出力形式が与えられると短い時間で解決する。
障害物報告
サブエージェントが作業中に回避策を発見した場合、問題を発見した場合、詳細をサマリーに返す必要があります。
この情報を取得する方法は、出力形式で明示的に求めることです。出力テンプレートに「Obstacles Encountered」セクションを追加すること。
- レビューの過程で遭遇した問題を報告してください
- 発見された回避策やセットアップの問題も含む
- 特別な設定がひつようだったコマンドや依存関係、インポートについても報告してください
これを形式を指定しておくことで報告をもらえる。
アクセス権限
必要なものだけ渡すこと。そうすることで、予期せぬ副作用を防ぐことができる。（読むだけのはずが書き換えてしまう、等）
また、こうすることで各サブエージェントの役割がより明確になる。
サブエージェントを使うか使わないかの判断
途中の作業がメインのコンテキストウィンドウに必要かどうか？
途中の作業が重要？ （Yes→サブエージェントに委任、No→メインスレッドで実行）
使わないほうがいいパターン（アンチパターン）
「Python専門家です」系のペルソナは不要。Claudeはすでに知っているので意味がない。
連鎖パイプライン（調査→デバッグ→修正）は、各ステップが前の結果に依存するので情報が途中で失われる。
（各ステップが前のステップの発見に依存すると失敗する）
テストランナーのサブエージェントは、失敗時の詳細ログを隠す傾向がある。
