Introduction to Subagentsコースで学ぶ委任ワークフロー設計

Introduction to Subagentsは、Anthropic Academyが無料で公開しているコースです。サブエージェントの仕組み、作り方、設計パターン、使いどころを4モジュールで扱います。ただしコース説明文の「/agentsコマンドで作る」という手順は、Claude Code v2.1.198以降では通用しません。

Introduction to Subagentsコースの概要

コースはSkilljar(anthropic.skilljar.com)上にあり、ページには「FREE」と表示されています。Skilljarは学習管理システムで、コースの進捗はSkilljar側に記録され、Anthropicアカウントのデータとは別扱いだと、ページのFAQが説明しています。

コース説明文は、サブエージェントを長いClaude Codeセッションから多くを引き出す最も実践的な手段の一つと位置付けています。別のコンテキストで作業を終えて必要な情報だけを返すので、メインのコンテキストウィンドウをきれいに保てるという狙いです。

Anthropic Academyには本コース以外にも複数のコースがあり、開発者向けには「Introduction to agent skills」や「Introduction to Model Context Protocol」も並びます。全体の一覧と有料の認定資格はAnthropic Academyの全コースと認定資格の学習ルートにあります。

到達点は2つです。複雑な作業を焦点の絞られた単位に分割し、時間内に完了して結果を明確に報告するサブエージェントを作れること。そして、委任する価値があるかを自分で判断できることです。

コース説明文の「/agents」は現行のClaude Codeで何が変わったか

コース説明文は第2モジュールを「/agentsコマンドでサブエージェントを作る」と案内しています。この手順は、Claude Codeのバージョンで挙動が分かれます。

名前が残っているclaude agentsも別物になっています。v2.1.289でclaude agents --helpを実行した出力は次のとおりです。

$ claude --version
2.1.289 (Claude Code)
$ claude agents --help
Usage: claude agents [options]
 
Manage background agents
 
Options:
  --cwd <path>   Show only background sessions started under <path>
  --json         Print active sessions (interactive and background) as a JSON array and exit
  ...

説明は「Manage background agents」で、サブエージェントの定義を編集するコマンドではありません。一覧の対象はclaude --bgで起動したバックグラウンドセッションで、サブエージェントの定義ファイルとは別の話です。

サブエージェントの定義を渡す手段は、claude --helpに載る--agentsです。ヘルプの例示は'{"reviewer": {"description": "Reviews code", "prompt": "You are a code reviewer"}}'で、ファイルを作らずJSONで1セッション分の定義を渡せます。--agent <agent>はセッション全体をそのエージェントとして動かすフラグです。

委任はいつ・どの形で起きるか

サブエージェントは、メインの会話とは別のコンテキストウィンドウで動きます。作業はそちらで完結し、メインの会話には結果の要約だけが返ります。

Claude Codeは、依頼内容とサブエージェントのdescriptionを照合して、委任先を自動で選びます。自動委任を後押ししたいときは、descriptionに「use proactively」のような一文を入れます。

自動に任せず確実に使わせる方法は、強さの違う3段階です。

実行の形はフォアグラウンドとバックグラウンドの2つです。フォアグラウンドは結果が出るまでメインの会話を止め、権限の確認もそのまま画面に出ます。バックグラウンドは並行して動き、権限の確認だけがメインセッションに戻ってきます。

どちらになるかは、先に当てはまる条件で決まります。

• 環境変数CLAUDE_CODE_DISABLE_BACKGROUND_TASKSが1なら、常にフォアグラウンドです
• フォークモードが有効なら、フォークでないサブエージェントも含めてバックグラウンドで、Claudeはフォアグラウンドを頼めません。フォークモードは、v2.1.232以降の対話セッションで既定で有効です
• フォークモードが無効(-pの非対話モードなど)なら、結果がすぐ要るときだけフォアグラウンドです

ここで、コース説明文の「別のコンテキストで動く」を修正しておく必要があります。フォークは例外で、それまでの会話をそのまま引き継ぎ、システムプロンプトとツールもメインと同じです。そのぶんプロンプトキャッシュを親と共有でき、再説明なしで脇の作業を任せられます。/subtaskで自分から起動でき、v2.1.161〜v2.1.211では同じ操作が/forkでした。

ファイルの作り方と、読み込まれないときの調べ方

サブエージェントの実体は、YAMLフロントマターとMarkdownのシステムプロンプトを持つ1ファイルです。.claude/agents/(プロジェクト)か~/.claude/agents/(ユーザー)に置き、必須なのはnameとdescriptionの2つだけです。

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
 
You are a code reviewer. Give specific, actionable feedback.

作成はClaudeに頼んでも手書きでも構いません。ファイルを追加・編集すると数秒で変更が検知され、次の委任から反映されます。例外は3つです。新しく作ったagentsディレクトリの最初のファイル、--add-dirで追加したディレクトリ内のファイル、--disable-slash-commandsで起動したセッションでは、再起動が要ります。

困るのは、書き間違えても何も表示されないことです。フロントマターにnameが無いファイルは、同じ場所に置いた資料として黙って読み飛ばされます。小文字で書いたdisallowedtoolsのような認識されないフィールド名は、後述のclaude plugin validateでも指摘されません。

事前に調べる手段がclaude plugin validateで、v2.1.233以降で使えます。一時ディレクトリに3種類のファイルを置いて、v2.1.289で試した結果が次のとおりです。

$ claude plugin validate .claude/agents
Validating agent: .claude/agents/broken.md
✘ Found 1 error:
  ❯ frontmatter: YAML frontmatter failed to parse: YAML Parse error: Unexpected token.
    At runtime this agent does not load at all ...
✘ Validation failed          # 終了コード 1

検出できたのはYAMLとして壊れたbroken.mdだけです。nameの抜けたファイルと、disallowedtoolsと小文字で書いたファイルは、--strictを付けても「Validation passed」(終了コード0)でした。公式ドキュメントも、nameが無いファイルはこの検査の対象外だと書いています。

validateが通っても、読み込まれた保証にはなりません。委任されないときは--debugで起動してログを見ます。

信頼性を高める3つのパターン

コース説明文が挙げる3つの設計パターンは、公式ドキュメントの例サブエージェントに当てはめると形が見えます。

構造化された出力形式は、返す項目を固定する書き方です。公式のコードレビュー担当は「Critical issues・Warnings・Suggestions」の優先度別で返します。デバッグ担当は「根本原因・裏付けとなる根拠・具体的な修正・テスト方法・再発防止策」の5項目です。項目が決まっていれば、メインの会話は要約を読むだけで判断できます。

障害の報告に関わる公式の仕様が、API起因の失敗がサブエージェントの中で握りつぶされない扱いです。v2.1.199より前は、APIエラーの文面がサブエージェントの成果であるかのようにClaudeへ返っていました。現在の挙動は、実行場所と出力の有無で分かれます。

ツールアクセスの制限は、toolsとdisallowedToolsが基本です。それだけでは足りない場面の実装例が、公式のデータベース分析担当db-readerです。toolsにBashを許しつつ、PreToolUseフックで中身を検査します。

tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"

検査スクリプトは標準入力のJSONからコマンドを取り出し、INSERTやDROPなどの書き込み系SQLを見つけたら終了コード2で止めます。止められたサブエージェントには「Blocked: Write operations not allowed. Use SELECT queries only.」というメッセージが返ります。システムプロンプトにも書き込み依頼は断るよう書いてあるので、フックはその取りこぼしを受け止める後ろ盾です。権限ルール側の設計はClaude Codeサブエージェント権限ルール設計で詳しく扱っています。

委任する場面と、しない場面

第4モジュールの「いつ使うか」は、公式ドキュメントにも同じ切り口があります。メインの会話が向くのは、頻繁なやり取りや反復的な調整が要る作業、計画・実装・テストのように文脈を共有し続ける作業、素早く的を絞った変更、レイテンシが重要な場面です。

サブエージェントが向くのは、出力が大量で本筋には要らない作業、ツール制限や権限を強制したい作業、自己完結して要約だけ返せばよい作業です。

よく使われる型は、テスト実行やログ処理の隔離、認証・データベース・APIのような独立した調査の並列実行、レビュー担当と修正担当の連鎖の3つです。並列調査の組み方はClaude Codeのサブエージェント完全活用にまとめています。

避けたいのは、詳細な結果を返すサブエージェントを多数同時に走らせる使い方です。結果はすべてメインの会話に戻るので、数を増やすほどコンテキストを圧迫します。しかも各サブエージェントは自分でもトークンを使い、同じ利用上限に数えられます。

既にメインの会話にある内容への質問は、サブエージェントではなく/btwが適しています。会話全体が見え、ツールは使えず、答えは履歴に残りません。

増えすぎを抑える上限は、コース説明文に出てきませんが、設計に関わります。

このコースの使いどころ

サブエージェントを日常的に使っている人にとって、コース説明文の内容は、公式ドキュメントのSub-agentsページと重なる項目が多くあります。説明文によると、コースは仕組み・作成・設計・使い分けの4段で構成されています。

初めて触る人は、コースで全体像をつかんでから実機で試す流れが合います。フロントマターの全フィールドや権限の細部まで確かめたい人は、Claude Code Sub-agents完全ガイドから入るほうが早く目的に着きます。

コースで作成手順を学ぶときは、/agentsをファイル作成の依頼に読み替えてください。作ったあとはclaude plugin validateで壊れたフロントマターだけは機械的に拾えます。