Claude Codeのエージェント機能完全解説【2026年最新】：サブエージェント・Agent Teamsの使い方・設定・ベストプラクティスまで

Claude Codeのエージェント機能とは？サブエージェント・Agent Teamsを完全解説【2026年最新】

室谷

今回はClaude Codeのエージェント機能の話をしましょう。「claude code agent」「claude code agents」「claude code エージェント」って検索している人が増えているんですよね。

それだけ使い始めた人が増えてきたってことで・・・

テキトー教師

.AI（ドットエーアイ）のコミュニティでも、エージェント機能の質問は今年一番増えているトピックですよ。「サブエージェントって何ですか？」と「Agent Teamsってどう使うんですか？」が毎週飛んできます。

室谷

実はこの2つ、全然別物なんですよね。サブエージェントは「1つのClaudeの中で、特化した専門家を呼び出す」イメージ。

Agent Teamsは「複数のClaudeが並列で動くチーム」。混乱している人が多いので、今回はこの違いを中心に整理していきます。

テキトー教師

そうですね。まずエージェント機能全体の文脈を整理してから、それぞれの使い方に入りましょうか。

Claude Codeのエージェント機能は、大きく3つの層に分かれています。

1つ目は自動委任（Automatic delegation）。Claude自身がタスクに応じてサブエージェントを自動で呼び出す仕組みです。 2つ目はカスタムサブエージェント。自分でエージェントを定義して、特定のタスク専門のアシスタントを作れます。 3つ目はAgent Teams。複数のClaude Codeインスタンスが協調して動く実験的な機能です。

室谷

この階層を頭に入れておくと、「これどっちで解決すればいいんだろう」という迷いがなくなるんですよ。MYUUUでもそうで、最初は全部サブエージェントで解決しようとして、「あれ、これはAgent Teamsが向いてる」って気づくのに時間がかかりましたw

テキトー教師

講座でも「とりあえずAgent Teamsを使えばいい」と思い込んでいる受講生さんが多くて。でも実際はサブエージェントの方が軽くて速くて、ほとんどのユースケースをカバーできるんですよね。

室谷

この記事を読むと、サブエージェントとAgent Teamsの仕組みを理解して、自分のワークフローに合った使い方ができるようになります。Claude Codeを「ただコードを書くツール」から「複数の専門家チームを率いるプロデューサー」として使えるようになるので、ぜひ最後まで読んでみてください。

サブエージェントの仕組みと組み込みエージェント

Claude Code サブエージェントの公式ドキュメント（Claude Code Docs公式サイトより）

テキトー教師

まずサブエージェントの基本から入りましょう。公式ドキュメントの定義によると、サブエージェントは「特定のタスクを専門に扱う特化型AIアシスタント」です。

それぞれが独自のコンテキストウィンドウ・カスタムシステムプロンプト・特定のツールアクセス・独立したパーミッションを持って動きます。

室谷

「独自のコンテキストウィンドウ」ってのがポイントですよね。メインの会話のコンテキストを汚染せずに作業できる。

コードベースを探索させても、その結果がメインの会話に詰め込まれないわけです。

テキトー教師

そうです。たとえばコードベース全体を調査するとき、サブエージェントに任せれば、メインの会話のコンテキストはスリムなまま保てます。

これ、長時間のセッションでは本当に効いてきますよ。

室谷

実際、MYUUUのエンジニアが「なんかClaude Codeが途中で的外れなことを言い始めた」って言ってきたことがあって。原因はコンテキストが肥大化してたことだったんですよ。

サブエージェントをうまく使えば、この問題がかなり軽減される・・・

テキトー教師

コンテキスト管理は教える上でも難しいポイントですね。目に見えないリソースなので。

でも「専門家に外注して、結果だけ受け取る」という感覚で考えると、コミュニティのメンバーさんにも伝わりやすいです。

組み込みサブエージェント（Built-in subagents）

室谷

Claude Codeにはデフォルトで組み込まれているサブエージェントがあります。これ、ユーザーが設定しなくても勝手に呼び出されているやつです。

テキトー教師

受講生さんも知らずに使ってることが多いですよね。4種類あります。

エージェント名	使用モデル	用途	自動呼び出しのトリガー
Explore	Haiku（高速・低レイテンシ）	コードベースの検索・分析（読み取り専用）	コードベースを調査する必要があるとき
Plan	メイン会話と同じ	プラン作成前のコード調査（読み取り専用）	planモードで調査が必要なとき
General-purpose	メイン会話と同じ	複雑な多段階タスク（全ツール使用可）	探索と実装の両方が必要な複雑なタスク
Claude Code Guide	Haiku	Claude Codeの機能についての質問に回答	Claude Codeの使い方を聞かれたとき

室谷

Exploreは特に意識しておくといいですよ。Haikuを使っているので速い＆安い。

コードベースを読むだけの作業はどんどん委任してくれているんですよね。

テキトー教師

planモードのPlanエージェントも重要です。プラン作成前に必要な調査だけをPlanエージェントが担当して、メインコンテキストをきれいに保ちます。

「無限ループを防ぐために、サブエージェントからさらにサブエージェントは呼べない」というルールもここで効いてきます。

室谷

サブエージェントのネストを防ぐ設計ですね。安全弁として機能している・・・

エージェントの自動委任はどう決まる？

テキトー教師

Claude Codeがどのサブエージェントに委任するかは、各サブエージェントの「description」フィールドで決まります。Claudeはこの説明文を読んで、「このタスクはこのエージェントに任せよう」と判断します。

室谷

だからカスタムエージェントを作るときにdescriptionをちゃんと書くのが大事なんですよね。曖昧に書くと委任されないし、広すぎると意図しないタイミングで呼ばれる。

テキトー教師

そうです。あと、最新バージョンからは「never delegate understanding」という重要なルールが追加されました。

エージェントが理解していないタスクをサブエージェントに丸投げするのを禁止するルールです。

室谷

これ、室谷がツイートで解説しましたね。委任前に「本当に理解しているか」を検証する仕組みが入ったという話・・・

テキトー教師

よくあった失敗パターン——「エージェントが文脈を理解せずに委任→サブエージェントも的外れ→手戻り」——を根本から防ごうというアプローチですね。こういう改善が入ってくると、自動委任の信頼性がどんどん上がっていくんですよ。

カスタムサブエージェントの作り方

室谷

ここからが実践的な話です。組み込みエージェントだけじゃなく、自分でカスタムエージェントを作れます。

これが強い。MYUUUでも複数のカスタムエージェントを運用していますね。

テキトー教師

作り方は2通りあります。「/agentsコマンド」を使う方法と、Markdownファイルを手動で作る方法です。

まず/agentsコマンドから見ましょう。

/agentsコマンドでの作成

テキトー教師

Claude Codeを開いて /agents と打つと、サブエージェントを管理するインタラクティブな画面が出てきます。ここから「Create new agent」を選んで作れます。

室谷

UIで全部設定できるのは直感的ですよね。「Generate with Claude」を選ぶと、作りたいエージェントの説明文を入力するだけで、識別子・description・システムプロンプトをClaude自身が生成してくれます。

テキトー教師

これが便利で。受講生さんでも「コードを改善するエージェントが欲しい」と日本語で書くだけで、適切な設定を生成してくれます。

作成時に設定する項目は次の5つです。

保存場所（スコープ）: プロジェクト（.claude/agents/）か個人全体（~/.claude/agents/）か
ツールアクセス: 読み取り専用にするか、全ツールを使わせるか
モデル: Sonnet / Opus / Haiku から選択
色: タスク一覧での識別色
メモリ: セッションをまたいで学習を蓄積するか

室谷

スコープの選択が重要なんですよね。プロジェクト固有のエージェントは .claude/agents/ に保存してGitにコミットする。

チームで共有できます。個人的に全プロジェクトで使いたいエージェントは ~/.claude/agents/ に。

テキトー教師

この区別、最初は混乱する人が多いですよ。「なんでこのエージェントが使えないんだろう」という問い合わせが来たとき、だいたいスコープの設定ミスです（笑）

Markdownファイルで手動作成

室谷

より細かい制御がしたいときはMarkdownファイルを直接書きます。構造はシンプルです——YAMLフロントマターで設定を書いて、本文がシステムプロンプトになります。

---
name: code-reviewer
description: コード変更後に自動でコードレビューを実行する。品質・セキュリティ・ベストプラクティスを確認する
tools: Read, Glob, Grep
model: sonnet
---

あなたはシニアコードレビュアーです。コードが変更されたとき、以下の観点でレビューしてください。
- 可読性と保守性
- セキュリティの脆弱性
- パフォーマンスの問題
- ベストプラクティスへの準拠

各問題について、現在のコードと改善案を具体的に示してください。

テキトー教師

name と description が必須フィールドで、あとはオプションです。tools を指定しないと親会話のツールを全部継承します。

読み取り専用のレビュアーなら tools: Read, Glob, Grep みたいに制限するのが安全ですね。

室谷

model: sonnet を指定するとそのエージェント専用でSonnetを使います。Haikuにすると速くて安い代わりに少し精度が落ちる。

タスクの複雑さに応じて使い分けるのがコツです。

テキトー教師

コミュニティのメンバーさんでよくあるのが「全部Opusにすればいい」という考え方なんですが、探索系のタスクはHaikuで十分ですし、そうするとコストが全然違ってきます。

CLIフラグでその場限りのエージェントを定義

室谷

/agentsコマンドやファイルで作る以外に、コマンドラインから一時的なエージェントを定義する方法もあります。テスト・自動化スクリプト向けですね。

claude --agents '{
  "code-reviewer": {
    "description": "コード変更後にコード品質をレビューする専門家",
    "prompt": "あなたはシニアコードレビュアーです。コード品質・セキュリティ・ベストプラクティスに注力してください。",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  }
}'

テキトー教師

セッション中だけ有効で、終わったら消えます。CI/CDで「このパイプラインではこのエージェントを使う」という使い方ができますね。

室谷

自動化パイプラインでの活用が増えてきています。MYUUUでも「コードが書かれたら即レビュー」みたいなフローを組んでいますよ。

サブエージェントのスコープ（優先度順）

テキトー教師

同名のサブエージェントが複数の場所に定義されていた場合、優先度の高い方が使われます。優先度はこの順です。

保存場所	スコープ	優先度
マネージド設定	組織全体	1（最高）
`--agents` CLIフラグ	現在のセッションのみ	2
`.claude/agents/`	現在のプロジェクト	3
`~/.claude/agents/`	個人の全プロジェクト	4
プラグインの `agents/`	プラグインが有効な場所	5（最低）

室谷

チームで使う場合はプロジェクトの .claude/agents/ が基本になりますね。Gitにコミットしてチーム全員で同じエージェントを使える。

テキトー教師

企業やチームの管理者がマネージド設定でエージェントを配布することもできます。「この組織では全員このエージェントを使う」という制御ができますね。

サブエージェントの設定項目完全解説

テキトー教師

サブエージェントのフロントマターには、必須の name description 以外にも豊富な設定項目があります。全項目を把握しておくと、かなり細かい制御ができますよ。

室谷

カスタムエージェントを作り込んでいくと、これ全部使うことになりますよね。整理するとこうなります。

フィールド	必須	説明
name	必須	エージェントの識別子（英小文字とハイフン）
description	必須	いつこのエージェントに委任するかの説明
tools	任意	使用可能なツールのリスト（省略時は全ツール継承）
disallowedTools	任意	禁止するツールのリスト（継承ツールから削除）
model	任意	sonnet / opus / haiku / フルモデルID / inherit
permissionMode	任意	default / acceptEdits / auto / dontAsk / bypassPermissions / plan
maxTurns	任意	エージェントが停止するまでの最大ターン数
skills	任意	起動時にコンテキストに読み込むスキル
mcpServers	任意	このエージェントが使えるMCPサーバー
hooks	任意	このエージェントに固有のライフサイクルフック
memory	任意	セッションをまたいだ学習の有効化（user/project/local）
background	任意	trueにすると常にバックグラウンドタスクとして実行
effort	任意	作業量（low/medium/high/max）。maxはOpus 4.6のみ
isolation	任意	worktreeにするとgit worktreeで分離された環境で動く
color	任意	タスク一覧での表示色
initialPrompt	任意	--agentフラグで起動時に最初のターンとして自動送信

室谷

isolation: worktree が実はかなり便利なんですよ。エージェントを一時的なgit worktreeで動かすので、メインのコードを汚さずにリスクのある作業をさせられる。

変更なしで終わったらworktreeは自動削除されます。

テキトー教師

大幅なリファクタリングを試したいとき、コードを壊しながら試行錯誤させたいときに使うパターンですね。

室谷

MYUUUでも使っています。「このAPIの移行を試してみて」みたいなタスクを isolation: worktree のエージェントに投げると、本番コードは絶対安全なままで試せる。

この安心感が大きいですよ。

modelの解決優先順位

テキトー教師

model フィールドには優先順位があります。同じエージェントでも、どこで指定されたモデルが使われるかが変わります。

室谷

環境変数が最優先です。優先度はこの順です。

環境変数 CLAUDE_CODE_SUBAGENT_MODEL（最優先）
呼び出し時の model パラメーター（Claudeが委任するとき指定）
エージェント定義の model フロントマター
メイン会話のモデル（デフォルト）

テキトー教師

環境変数でまとめてサブエージェントのモデルを制御できるのは、コスト管理の観点で役立ちますね。「サブエージェントは全部Haikuにする」という環境変数を設定すれば、個別に指定しなくていい。

室谷

チームで運用するときに便利ですね。.env ファイルに CLAUDE_CODE_SUBAGENT_MODEL=claude-haiku-4-5 みたいに書いておけば、エンジニア全員が同じコスト設定で動く・・・

パーミッションモードとセキュリティ

テキトー教師

permissionMode の設定も重要です。これはエージェントがどの程度の権限で動くかを制御します。

室谷

plan モードは読み取り専用で始まって、リードがプランを承認するまで実装に進まない。リスクの高い作業をさせるときに有効です。

テキトー教師

bypassPermissions は全確認をスキップして全自動で動く。CI環境や、すでに十分テストしたパイプラインでないと危険ですよね。

室谷

基本は default か acceptEdits で運用して、確認済みの自動化フローにだけ auto や bypassPermissions を使う——これが安全な使い方です。MYUUUでもそのルールを徹底しています。

Agent Teams（エージェントチーム）入門

Claude Code Agent Teamsの公式ドキュメント概要（Claude Code Docs公式サイトより）

室谷

ここからAgent Teamsの話に入ります。これ、サブエージェントとは根本的に違う仕組みです。

サブエージェントは「1つのClaude Codeセッションの中で動く専門家」ですが、Agent Teamsは「複数のClaude Codeインスタンスが並列で協調する」仕組みです。

テキトー教師

.AIコミュニティの勉強会でも「Agent Teamsってどういう仕組みで動いているの？」という質問がよく出ます。Agent Teamsは3つのコンポーネントで構成されています。

コンポーネント	役割
チームリード	メインのClaude Codeセッション。チームを作成し、チームメートを生成し、作業を調整する
チームメート	独立したClaude Codeインスタンス。それぞれがタスクを受け取って独立して作業する
タスクリスト	全エージェントが共有する作業項目リスト。チームメートが自律的にクレームして消化する

室谷

「チームメート同士が直接メッセージをやり取りできる」というのがサブエージェントとの最大の違いです。サブエージェントは結果をメインに返すだけですが、チームメートは他のチームメートに「おい、この部分どうなった？」と聞ける。

テキトー教師

これがどういう場面で価値を発揮するかというと、「対立する仮説を立てて互いに検証し合う」という作業ですよね。並列で独立した思考ができるエージェントが必要なわけで。

Agent Teamsの有効化と前提条件

室谷

重要なのが、Agent TeamsはデフォルトでOFFになっていることです。実験的機能なので。

使うには settings.json に設定を追加します。

{
  "env": {
    "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1"
  }
}

テキトー教師

バージョンも確認が必要です。Claude Code v2.1.32以降が必要で、claude --version で確認できます。

室谷

この「実験的機能」というステータスは意識しておいた方がいいですよ。セッションの再開、タスクの調整、シャットダウン周りにまだ既知の制限があります。

本番クリティカルな処理には、まだ慎重に使った方がいい・・・

テキトー教師

受講生さんには「Agent Teamsで壊れたら、シングルセッションやサブエージェントで代替できるか」を考えてから使ってもらうようにアドバイスしています。実験段階だからこそ、試してみる価値はありますが。

表示モード：in-processとsplit-panes

テキトー教師

Agent Teamsには2つの表示モードがあります。

室谷

in-process モードはメインのターミナル内に全チームメートが同居します。Shift+Down で切り替えながら操作できる。

tmuxが不要なので、どの環境でも動きます。

テキトー教師

split-panes モードはチームメートごとに別ペインが開く。全員の作業を同時に見られるのが強みですが、tmuxかiTerm2が必要です。

室谷

デフォルトは「auto」で、tmuxセッション内にいれば split-panes、そうでなければ in-process を使います。~/.claude.json でグローバルに変更できます。

{
  "teammateMode": "in-process"
}

テキトー教師

iTerm2ユーザーなら it2 CLI をインストールするとsplit-panesモードが使えます。視覚的にチームの状態を把握できるので、最初の試し方としてはiTerm2のsplit-panesがおすすめですよ。

Agent Teamsの使い方・操作方法

室谷

実際のAgent Teamsの使い方に入りましょう。基本は「チームリードに自然言語で指示を出す」だけです。

Claudeがチームを作って、タスクを分割して、チームメートに割り振ってくれます。

テキトー教師

チームを起動するときは、こんな感じで指示を出します。

CLIツールのリファクタリングを、3人のチームメートで並列で進めてほしい。
- 1人はセキュリティの観点でコードをレビュー
- 1人はパフォーマンス改善を担当
- 1人はテストカバレッジを確認

それぞれが独立した作業でOKなので、parallel workで進めてください。

室谷

「並列で独立して動ける仕事」がポイントです。互いに依存しない作業なら、3人が同時に進んでくれます。

タスクの管理と自律的な作業割り当て

テキトー教師

Agent Teamsの強みは「タスクリスト」にあります。チームリードがタスクを作成すると、チームメートが自律的にタスクをクレームして作業を始めます。

室谷

タスクには3つのステータスがあります——pending（未着手）、in progress（進行中）、completed（完了）。依存関係も設定できて、前のタスクが完了するまで次のタスクはクレームできない。

テキトー教師

ファイルロックで「複数のチームメートが同じタスクを同時にクレームする」競合を防いでいます。この設計は丁寧ですよね。

室谷

チームリードが「このタスクはAさんに」と明示的に割り当てることもできるし、チームメートが自分で次のタスクを選ぶこともできる。フレキシブルですよ。

チームメートとの直接コミュニケーション

テキトー教師

Agent Teamsの面白い機能が「チームメートへの直接メッセージ」です。リードを通さずに直接指示を出せます。

室谷

in-processモードなら Shift+Down でチームメートを切り替えて、直接入力できます。「このアプローチは変えてほしい」とか「この部分を優先して」とか。

テキトー教師

これが実際の開発チームっぽいですよね。マネージャー（リード）と直接話せる、という感覚で。

室谷

ただ、「チームメートにブロードキャストする」機能はトークンコストがチームメンバー数分かかるので、必要なときだけ使う方がいいですよ。

チームの終了とクリーンアップ

テキトー教師

Agent Teamsを終了するときは、必ずリードからクリーンアップするのが重要です。

室谷

チームメートからクリーンアップをすると、チームコンテキストが正しく解決されなくて、リソースが中途半端な状態になることがある。必ずリードに「clean up the team」と伝えてから終了する。

テキトー教師

チームメートをシャットダウンするときも同じで、リードに「researcher teammates should shut down」と指示を出すと、リードがチームメートに shutdown request を送ります。チームメートは承認か拒否かを選べる仕組みです。

室谷

「チームメートが何かやり残しているから、もう少し待って」という状況でシャットダウンを拒否できるのは、実務的に助かりますよね。

サブエージェント vs Agent Teams：使い分けの判断基準

サブエージェントとAgent Teamsのアーキテクチャ構造の違いを示した図解

テキトー教師

前回はサブエージェントとAgent Teamsそれぞれの仕組みを見てきました。ここで「どっちを使うべきか」の判断基準を整理しましょう。

室谷

これ、本質的な違いは「コミュニケーションが必要かどうか」なんですよね。整理するとこうなります。

比較項目	サブエージェント	Agent Teams
コンテキスト	独自コンテキストウィンドウ、結果をメインに返す	独自コンテキストウィンドウ、完全に独立
コミュニケーション	メインエージェントへの報告のみ	チームメート同士が直接メッセージ
調整方法	メインエージェントが全作業を管理	共有タスクリストで自律的に調整
向いているケース	結果だけ欲しい集中型タスク	議論・コラボが必要な複雑な作業
トークンコスト	低め（結果をサマリーして返す）	高め（各チームメートが独立したインスタンス）
安定性	安定している	実験的機能（既知の制限あり）

テキトー教師

受講生さんへのアドバイスとしては、「まずサブエージェントで解決できるか試す。それで足りないときにAgent Teamsを検討する」ですね。

室谷

Agent Teamsは「並列探索に本当に価値がある場合」に限定するのが正しい使い方です。海外でも「チームが対立する仮説を立てて検証し合う」みたいな使い方が評価されているんですよ・・・

サブエージェントが向いているケース

テキトー教師

具体的にどんな場面でサブエージェントを使うか、まとめてみます。

コードベースを探索して結果だけ欲しいとき（Exploreエージェント）
単独で完結するコードレビューや品質チェック
APIを叩いてデータを取得するような「外注できる」タスク
メインのコンテキストを汚染したくないリサーチ作業
コスト重視で、Haikuモデルを使えばいい軽量タスク

室谷

「明確なインプットと明確なアウトプット」があるタスクはサブエージェントに向いていますよ。「この関数のセキュリティを調べて」みたいな。

Agent Teamsが向いているケース

テキトー教師

Agent Teamsが真に力を発揮するのは、こういうケースです。

複数の視点から同時に問題を調査するとき（並列リサーチ）
競合する仮説を立てて互いに検証し合う（バグ調査など）
フロントエンド・バックエンド・テストを同時に進む新機能開発
チームメートが「同意・反論・修正」をやり取りして品質を上げるコードレビュー

室谷

室谷がツイートで取り上げていた「Code Review」機能もまさにこれですよね。PRが出た瞬間に複数のエージェントが独立してバグを探し、相互検証して誤検知を潰す。

テキトー教師

エージェント同士が「こっちは違う」と反論することで、誤検知率が1%未満になった——という結果は、まさにAgent Teamsの本質を表していますよね。

実践パターン：Agent Teamsの活用例

室谷

ここで具体的な活用パターンを3つ見ていきましょう。公式ドキュメントにも載っているやつですが、それぞれのポイントを解説していきます。

パターン1：並列コードレビュー

テキトー教師

1人のレビュアーだと、どうしても1種類の問題に集中しがちです。セキュリティを見始めると、パフォーマンスが見えなくなる。

室谷

Agent Teamsで「セキュリティ専門家・パフォーマンス専門家・テストカバレッジ専門家」の3人を同時に走らせると、独立した視点が同時に動いて、後で統合できます。プロンプトはこんな感じです。

PR #142をAgent Teamでレビューしてほしい。3人のレビュアーを生成して：
- 1人はセキュリティの脆弱性に集中
- 1人はパフォーマンスへの影響を確認
- 1人はテストカバレッジを検証

それぞれのレビュー結果を報告してください。

テキトー教師

ポイントは「それぞれのレビュアーに明確なレンズを与える」こと。「とりあえずレビューして」だと、3人が同じことを見る可能性があります。

パターン2：競合仮説での並列デバッグ

室谷

バグ調査でも効果的です。根本原因が不明なとき、シングルエージェントだと1つの仮説を見つけたら「これだ！」と止まりやすい。

テキトー教師

Agent Teamsなら「各チームメートが異なる仮説を立てて、互いに反証し合う」設計ができます。こんなプロンプトです。

アプリが最初のメッセージの後に切断される問題を調査してほしい。
5人のチームメートを生成して、それぞれ異なる仮説を立てて調査してください。
チームメート同士で互いの仮説を検証し合い、最も有力な根本原因について
consensus（合意）を見つけてください。結果をfindings.mdに記録してください。

室谷

「互いに反証し合う」という設計が鍵です。1つの仮説に全員が飛びつかないように。

テキトー教師

科学的な論争みたいなイメージですよね。生き残った仮説が本物の根本原因である可能性が高い。

パターン3：サブエージェント定義をチームメートとして使う

室谷

Agent Teamsで便利なのが、あらかじめ定義したサブエージェントをチームメートとして使える点です。

テキトー教師

.claude/agents/ に security-reviewer.md を定義しておけば、「security-reviewer エージェントタイプのチームメートを生成して」と指示できます。

室谷

この設計が面白くて、「サブエージェントとして使う場合とAgent Teamsのチームメートとして使う場合」を同じ定義でカバーできるんですよ。一度定義すれば両方に使い回せる。

ベストプラクティスとよくある失敗

テキトー教師

ここでベストプラクティスと、コミュニティのメンバーさんがよくハマるパターンをまとめましょう。

室谷

まずAgent Teamsのチームサイズについて。公式ドキュメントでは「3〜5人が適切な出発点」とされています。

テキトー教師

これ、本当にその通りで。「多ければ多いほどいい」と思って10人のチームを作ると、調整オーバーヘッドで効率が落ちるんですよ。

室谷

トークンコストもチームメンバー数に比例するので。3人で十分なところに6人を投入してもROIが合わないケースが多い。

よくある失敗パターン

テキトー教師

受講生さんでよくあるのがこの3パターンです。

失敗1: チームメートに十分なコンテキストを渡さない

室谷

チームメートはCLAUDE.md・MCPサーバー・スキルを自動で読み込みますが、「リードの会話履歴」は引き継ぎません。だからスポーンプロンプトに「このモジュールはJWT認証を使っている」みたいな前提情報を含める必要があります。

テキトー教師

「なんでチームメートが的外れなことをしているんだろう」という問い合わせの原因は、だいたいここですよ。コンテキスト不足。

失敗2: チームメートが終わるのを待たずにリードが進む

室谷

たまにチームリードがチームメートのタスクが終わる前に自分で実装を始めることがある。そのときは「Wait for your teammates to complete their tasks before proceeding」と明示的に指示する必要があります。

テキトー教師

これは仕様上の制限というより、プロンプトの問題ですね。チームを使うなら「待つ」という概念を指示に含めると安全です。

失敗3: 同じファイルを複数のチームメートが編集する

室谷

これ、致命的な競合になります。チームメートが同じファイルを同時に編集すると、一方が上書きされる。

タスク設計の段階で「各チームメートが担当するファイルを分ける」のが鉄則です。

テキトー教師

大きなリファクタリングをAgent Teamsで実施するときは、「誰がどのディレクトリを担当するか」を最初に決めてもらうようにしています。

コスト意識：Agent Teamsはトークンが重い

テキトー教師

Agent Teamsのトークンコストは、シングルセッションと比べてかなり重いです。各チームメートが独立したコンテキストウィンドウを持つので、チームメンバー数分のトークンが消費されます。

室谷

経営者視点でいうと、「このタスクはAgent Teamsでなければ解決できないか？」を必ず問うべきですね。サブエージェントで解決できるなら、コストは大幅に下がる。

テキトー教師

目安として「研究・レビュー・新機能開発」はAgent Teamsの費用対効果が出やすい。「ルーティンタスク」はシングルセッションかサブエージェントの方がコスパいいですよ。

claude code agent mdについて

室谷

「claude code agents md」というキーワードで検索している人も多いようで。エージェントのMarkdownファイルのことですね。

テキトー教師

エージェントの定義ファイルは .md 拡張子で保存します。YAMLフロントマター + システムプロンプトの構成です。

.claude/agents/ か ~/.claude/agents/ に置けば使えます。

室谷

プロジェクト固有のエージェントは .claude/agents/ に、Gitにコミットして使う。このあたりを探している人は「スコープの管理方法を理解したい」のかなと。

claude code multi agentの活用

テキトー教師

「claude code multi agent」で検索している人も、Agent Teamsを調べているケースが多いです。マルチエージェントの使い方について言うと——

室谷

①サブエージェント（シングルセッション内でのマルチエージェント）と②Agent Teams（独立したインスタンス間のマルチエージェント）の2層構造、という理解が正確です。

テキトー教師

サブエージェントはsingle sessionのマルチエージェント。Agent Teamsはmulti sessionのマルチエージェント。

この区別を頭に入れておくと、公式ドキュメントの読み方がわかりやすくなりますよ。

Agent Teams料金とコスト最適化

室谷

「claude code agent teams 料金」で調べている人も多いですね。Agent Teams自体に追加料金はなくて、使用するモデルのトークン量に応じた従量課金です。

テキトー教師

ただ、前述の通りチームメンバー数分のトークンが消費されます。3人チームなら、シングルセッションの概算3倍の消費量になる。

室谷

コスト最適化のポイントは「チームメートにHaikuを使う」か「チームサイズを最小化する」です。探索系のチームメートはHaikuで十分なケースも多い。

テキトー教師

CLAUDE_CODE_SUBAGENT_MODELは「サブエージェント」限定の環境変数なので、Agent Teamsのチームメートには適用されません。チームメートのモデルはスポーンプロンプトで指示するか、サブエージェント定義の model フィールドで設定します。

室谷

「チームメートにSonnetを使いたい」なら「Spawn 3 teammates using Sonnet for each」と明示するのが確実ですよ。

サブエージェントを明示的に呼び出す方法

室谷

前のセクションまでは「Claudeが自動的に委任する」という話でしたが、自分で明示的にエージェントを指定して呼び出す方法もあります。

テキトー教師

3つのパターンがあります。自然言語指定・@メンション・--agentフラグです。

自然言語で指定する

テキトー教師

最もシンプルな方法です。プロンプトの中でエージェント名を書けば、Claudeがそのエージェントを使うか判断します。

code-reviewerサブエージェントを使って最近の変更をレビューして
debuggerエージェントにテストの失敗を調査させて

室谷

「Claude が判断する」というのがポイントで、必ずそのエージェントが使われるわけじゃない。確実に特定のエージェントを呼びたいときは@メンションを使います。

@メンションで確実に指定する

テキトー教師

@ を入力するとエージェントの候補が出てきます。タイプアヘッドから選ぶか、手動で @agent-code-reviewer のように書きます。

室谷

これは確実にそのエージェントが使われます。プロンプト全体はClaudeに渡って、Claudeが指定したエージェントへのタスクプロンプトを作ります。

テキトー教師

プラグイン経由で入ったエージェントは @agent-<plugin-name>:<agent-name> という形式になります。

セッション全体をエージェントモードで起動

室谷

--agent フラグを使うと、セッション全体がそのエージェントのシステムプロンプトで動きます。

claude --agent code-reviewer

テキトー教師

デフォルトのClaude Codeシステムプロンプトが、指定したエージェントのシステムプロンプトに完全に置き換わります。「このプロジェクトでは常にコードレビュアーとして動く」という使い方ですね。

室谷

プロジェクトの .claude/settings.json に書いておくと、そのプロジェクトを開くたびに自動でそのエージェントモードになります。

{
  "agent": "code-reviewer"
}

テキトー教師

チームで「このリポジトリはコードレビューエージェントとして動かす」という設定にしたいときに使えますね。

フォアグラウンドとバックグラウンド実行

テキトー教師

サブエージェントはフォアグラウンド（同期）とバックグラウンド（非同期）の2つのモードで動かせます。

室谷

これ、生産性に大きく影響する機能なんですよ。「重いタスクをバックグラウンドで動かしながら、別の作業を進める」という並列作業ができます。

フォアグラウンド実行

テキトー教師

デフォルトはフォアグラウンドです。サブエージェントが完了するまで、メインの会話がブロックされます。

パーミッションのリクエストや質問もそのまま渡されてきます。

室谷

インタラクティブな確認が必要なタスクはフォアグラウンドが安全ですよ。「この変更を本当にする？」という確認が来たときにちゃんと応答できる。

バックグラウンド実行

テキトー教師

バックグラウンドで動かすには「バックグラウンドで実行して」と頼むか、Ctrl+B を押します。

室谷

バックグラウンドエージェントは、起動前に必要なパーミッションをまとめて確認してから走ります。走り始めたら、事前に許可されたツールだけ使える。

未許可のアクションは自動拒否されます。

テキトー教師

これ、設計が丁寧ですよね。バックグラウンドで勝手に何でもやられると困るので、起動時に「これとこれのパーミッションを使います」と宣言させる仕組みです。

室谷

バックグラウンドエージェントが「パーミッション不足で失敗した」場合は、同じタスクをフォアグラウンドで再実行してインタラクティブに確認しながら進める——というリカバリーパターンが公式ドキュメントに載っています。

テキトー教師

background: true をフロントマターに書くと、そのエージェントは常にバックグラウンドで起動します。継続的に動かしておくモニタリングエージェントなどに使えますね。

バックグラウンドタスクを無効にする

室谷

バックグラウンド機能を完全に無効にしたい場合は、環境変数 CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 を設定します。

テキトー教師

CI/CD環境や「確認なしに自動実行したくない」という厳格な環境に向けた設定ですね。

サブエージェントのコンテキスト管理と再開

室谷

長時間動くサブエージェントの管理についても触れておきましょう。サブエージェントの「再開」機能があります。

テキトー教師

デフォルトではサブエージェントを呼び出すたびに新鮮なコンテキストで始まります。でも「前回の続きから」再開させることもできます。

室谷

再開の仕組みはちょっと特殊で——Claudeがサブエージェント完了時にエージェントIDを受け取ります。「前のコードレビューを続けて」と言うと、ClaudeはそのIDでSubagentにメッセージを送って再開させます。

テキトー教師

CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 が有効な環境でないと SendMessage ツールが使えないので、再開機能を使うにはAgent Teamsを有効にする必要があります。

室谷

サブエージェントのトランスクリプトは ~/.claude/projects/{project}/{sessionId}/subagents/ に保存されます。30日でデフォルト削除されます。

コンテキスト上限に達したときの自動圧縮

テキトー教師

サブエージェントもメインの会話と同じ自動圧縮（auto-compaction）をサポートしています。デフォルトでコンテキストが95%になると発動します。

室谷

長時間動かすサブエージェントでは重要な機能ですね。圧縮が発動する閾値を変えたい場合は CLAUDE_AUTOCOMPACT_PCT_OVERRIDE 環境変数で設定できます。

サブエージェントとスキルの選択基準

テキトー教師

「サブエージェント」と「スキル」の使い分けも、よく聞かれる質問です。

室谷

似ていて混乱しやすいんですよね。端的に言うと——スキルは「メインの会話のコンテキスト内で動くプロンプト・ワークフロー」、サブエージェントは「独立したコンテキストウィンドウで動くAI」です。

テキトー教師

使い分けの基準として、公式ドキュメントにはこう書かれています。

スキルを使う: 再利用可能なプロンプトやワークフローをメインの会話のコンテキスト内で動かしたい場合
サブエージェントを使う: タスクが多量の出力を生成する場合・特定のツール制限やパーミッションを強制したい場合・独立して完結できて要約を返せばいい場合

室谷

「コンテキストを汚染したくない」かどうか、ですね。大量のログを解析させる・コードベース全体をスキャンするといった作業はサブエージェント向きです。

テキトー教師

逆に「会話の流れを保ちながら、決まった手順で作業を進める」ならスキルの方が自然です。コンテキストを引き継ぎながら使えるので。

室谷

/btw コマンドも選択肢の一つですね。会話の中で「ちょっとこれを調べて」というような一回限りの確認にはサブエージェントを立ち上げるまでもなく、/btw を使うと軽くて速い。

ただし結果は会話に残らないので、記録を残したいときはサブエージェントを使う。

スキル＋サブエージェントの組み合わせパターン

テキトー教師

スキルとサブエージェントを組み合わせると、かなり強力なワークフローが作れます。

室谷

例えば「コードレビューのスキル」が定義されていたとして、それを skills フィールドでサブエージェントに注入する。すると「スキルの知識を持ったサブエージェント」が生まれます。

テキトー教師

.claude/skills/code-review-standards.md にレビュー基準を書いておいて、コードレビューエージェントの skills: [code-review-standards] に設定する——こういう設計が実務的ですよね。

室谷

MYUUUでも採用しているパターンです。「プロジェクト固有のコーディング規約ドキュメント」をスキルにして、コードレビューエージェントに注入しています。

これで毎回「この規約では〜」と説明しなくていい。

テキトー教師

ポイントは「スキルの更新がエージェントに自動で反映される」こと。スキルのMarkdownを更新すれば、そのスキルを使う全エージェントが最新の知識で動きます。

サブエージェントの高度な設定：スキル・メモリ・フック

サブエージェントへのスキルプリロードの設定方法（Claude Code Docs公式サイトより）

室谷

ここからはサブエージェントのより高度な設定を見ていきましょう。サブエージェントを「自己学習するアシスタント」にしたり、「条件付きのルールで動かす」仕組みが揃っています。

テキトー教師

基本の設定ができたら、次はここを押さえておくと、カスタムエージェントが格段に使いやすくなりますよ。

スキルをサブエージェントに注入する

テキトー教師

skills フィールドを使うと、スタートアップ時にスキルの内容をサブエージェントのコンテキストに注入できます。

室谷

「スキルをサブエージェントに注入」と「通常のスキル呼び出し」の違いが最初わかりにくいんですが、注入するとサブエージェントのシステムプロンプトにスキルの全内容が入ります。見つけてロードするのを待たずに、最初から使える状態になる。

---
name: api-developer
description: APIエンドポイントをチームの規約に従って実装する
skills:
  - api-conventions
  - error-handling-patterns
---

APIエンドポイントを実装してください。プリロードされたスキルの規約とパターンに従ってください。

テキトー教師

スキルはClaude Code Skillsの仕組みと同じです。.claude/skills/ か ~/.claude/skills/ のMarkdownファイルを参照します。

室谷

重要な注意点として、サブエージェントは親会話のスキルを継承しません。必要なスキルは skills フィールドに明示的に列挙する必要があります。

これを見落として「サブエージェントがプロジェクトの規約に従わない」という問い合わせが来ることがあります。

メモリ：セッションをまたいで学習を蓄積

テキトー教師

memory フィールドを有効にすると、サブエージェントが永続的なメモリディレクトリを持てます。セッションをまたいで知識を積み上げる仕組みです。

室谷

これ、面白い機能ですよね。コードレビューエージェントに memory: project を設定すると、レビューをするたびに「このプロジェクトでよく見つかる問題パターン」「コーディング規約の特徴」を記憶していって、次回のレビューに活かせます。

---
name: code-reviewer
description: コード品質とベストプラクティスについてレビューする
memory: user
---

あなたはコードレビュアーです。コードをレビューしながら、発見したパターン・規約・繰り返し出る問題をエージェントメモリに記録してください。

テキトー教師

メモリのスコープは3種類あります。

スコープ	保存場所	使うケース
user	`~/.claude/agent-memory/<エージェント名>/`	複数プロジェクトをまたいで使う知識
project	`.claude/agent-memory/<エージェント名>/`	プロジェクト固有でチームと共有する知識
local	`.claude/agent-memory-local/<エージェント名>/`	プロジェクト固有だがGitに入れたくない知識

室谷

project がデフォルト推奨です。Gitにコミットしてチームで共有できるので、「エージェントが積み上げた知識」をチーム全体で使えます。

これ、長期的に使えば使うほど賢くなるエージェントになる・・・

テキトー教師

メモリの使い方として、公式ドキュメントにある実践的なアドバイスが2つあります。1つは「作業前にメモリを確認して」と伝えること。

もう1つは「作業後にメモリを更新して」と伝えること。この習慣をつけると効果が出やすいです。

フックでサブエージェントの動作を制御

テキトー教師

hooks フィールドを使うと、サブエージェントがツールを使う前後に独自のスクリプトを走らせられます。

室谷

「データベースに書き込むコマンドを実行しようとしたらブロックする」みたいなことができますよ。公式ドキュメントにある例が面白くて、read-onlyデータベースクエリのみを許可するサブエージェントです。

---
name: db-reader
description: データベースの読み取り専用クエリを実行する
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

テキトー教師

PreToolUse はツール実行前に発火するフックです。検証スクリプトが「exit 2」を返すとツールの実行がブロックされる。

これでINSERT/UPDATE/DELETE/DROPを含むコマンドをエージェントが実行できなくします。

室谷

セキュリティガードレールとして使えますよね。「このエージェントは絶対にこれをやらせない」というルールをコードで定義できる。

MYUUUでも本番環境に近い作業をするエージェントには、このフック設計を使っています。

サブエージェントを無効化する

テキトー教師

「特定のサブエージェントを使わせたくない」場合は、settings.jsonの permissions.deny に追加します。

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

室谷

組み込みのExploreエージェントが重いと感じるときに無効化する使い方が多いですよ。コスト削減目的で。

テキトー教師

あるいはCIパイプラインで「このエージェントは使わせない」という制限をかけるのにも使えます。

MCPサーバーをサブエージェントにスコープする

室谷

これ、地味に便利な設定があって——MCPサーバーをサブエージェント専用に設定できます。メインの会話には見えず、そのサブエージェントだけが使えるMCPツールを持てます。

---
name: browser-tester
description: Playwrightを使ってブラウザでフィーチャーをテストする
mcpServers:
  # インライン定義：このサブエージェント専用
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # 名前参照：セッションで設定済みのサーバーを再利用
  - github
---

テキトー教師

この設計の何がいいかというと、「Playwrightのツールの説明文がメインのコンテキストを消費しない」点です。ブラウザ操作が必要なときだけ、そのサブエージェントを呼び出せばいい。

室谷

MCPサーバーのツール説明文って、結構コンテキストを取るんですよ。全部メインに入れると、どんどんコンテキストが埋まっていく。

サブエージェントにスコープすることでコンテキスト効率が上がります・・・

Agent Teamsの詳細アーキテクチャ

テキトー教師

Agent Teamsの仕組みをもう少し深く見ていきましょう。内部的にどうデータが管理されているかを知っておくと、トラブルシューティングが楽になります。

室谷

チームの設定とタスクは、ローカルに保存されます。

チーム設定: ~/.claude/teams/{チーム名}/config.json
タスクリスト: ~/.claude/tasks/{チーム名}/

テキトー教師

config.json にはセッションID・tmuxペインID等のランタイム情報が入っています。これは自動生成・自動更新されるので、手動で編集してはいけません。

室谷

チームメートが他のメンバーを知りたい場合は config.json の members 配列を参照できます。自律的な調整に使われる仕組みです。

タスクのライフサイクル

テキトー教師

タスクには3つのステータスがあって、依存関係も設定できます。

室谷

pending → in progress → completed のフローです。タスクAが完了するまでタスクBはクレームできない、という依存関係を作れます。

これが「チームメートが実行順序を自律的に管理する」仕組みの核になっています。

テキトー教師

タスクのクレームはファイルロックで競合を防いでいます。複数のチームメートが同じタスクをクレームしようとしても、ロックを取った1つしか成功しません。

室谷

この設計、実装が綺麗ですよね。分散システムの定石——共有状態を使い、競合はロックで解決。

でもClaude Codeという文脈で自然に実現している。

Agent Teamsのトークン消費を理解する

テキトー教師

コスト最適化の観点から、Agent Teamsのトークン消費を正確に理解しておきましょう。

室谷

各チームメートが独立したClaude Codeインスタンスを持ちます。つまり、3人チームなら：

チームリード: 通常のClaude Codeセッション分
チームメートA: 独立したセッション分
チームメートB: 独立したセッション分
チームメートC: 独立したセッション分

合計で4インスタンス分のトークンが消費される計算です。

テキトー教師

ブロードキャスト（全チームメートへの同時メッセージ）はさらにコストが乗ります。全員に同じメッセージを送ると、チームメンバー数分のインプットトークンが消費されます。

室谷

コスト管理の観点では「最初は3人から始める」がおすすめです。5人・7人と増やすのは、3人では並列化の恩恵が明確に出ると確認できてからにする。

claude code best practices for agentic coding

テキトー教師

エージェント機能全般で押さえておきたいベストプラクティスをまとめましょう。

室谷

まず大原則として——「エージェントに渡すコンテキストは、人間のエンジニアに渡すコンテキストと同じように設計する」という考え方が重要です。曖昧な指示をAIに渡しても、期待通りの結果は出ない。

テキトー教師

具体的なチェックリストはこうです。

descriptionは具体的に書く: 「いつ・どのような状況でこのエージェントを使うか」をトリガー条件込みで書く
ツールは最小限に絞る: 書き込みが不要なエージェントは読み取りツールのみに制限する
モデルはタスクに合わせる: 探索系はHaiku、実装系はSonnet、複雑な判断はOpusを選択する
スコープは目的に合わせる: チーム共有なら .claude/agents/、個人使用なら ~/.claude/agents/
メモリは長期運用するエージェントに: 短期的なタスクにはメモリ不要
フックでガードレールを張る: セキュリティに敏感な操作はPreToolUseフックで検証する

室谷

あと「isolation: worktree」の活用を忘れないでほしいですね。リスクのある操作をするエージェントには、デフォルトでworktreeを設定しておくと安全です。

テキトー教師

Agent Teamsに関しては追加のポイントがあります。「チームメートへの指示は具体的に、役割分担は明確に」——これが最重要です。

室谷

「なんかチームメートが同じことをしている」「チームメートが的外れな作業をしている」という問題は、だいたいスポーンプロンプトの曖昧さから来ています。

claude code agent sdkとの関係

テキトー教師

「claude code agent sdk」で調べている人もいますね。Claude Agent SDKは、Claude Codeの基盤となるSDKです。

室谷

Claude CodeはこのAgent SDK上に構築されています。だから「Claude CodeのエージェントとしてXcodeや他のIDEと連携できる」という話が出てきているんですよね。

テキトー教師

AppleのXcodeがClaude Agent SDKに対応した事例ですね。Claude Codeと同じ基盤——サブエージェント・バックグラウンドタスク・プラグイン——がXcode内で使えるようになった。

室谷

Agent SDKを直接使って開発するケースは今のところ少ないですが、「Claude CodeのエージェントモデルはAgent SDKがベース」という理解を持っておくと、今後の拡張の文脈がつかみやすくなりますよ。

claude code vs copilot agentの比較

テキトー教師

「claude code vs copilot agent」で比較している人も多いですね。ざっくり比較するとこうなります。

室谷

GitHub Copilot AgentはVSCodeやGitHubのエコシステムとの深い統合が強みです。PRの自動化、GitHub Actionsとの連携など。

テキトー教師

Claude Codeのエージェント機能は「ローカルでのエージェント協調」「カスタムエージェントの柔軟な定義」「Agent Teamsによる並列探索」が強みです。

室谷

競合するツールというより、用途が少し違うんですよね。GitHub ActionsやCI/CDとの統合が主眼なら Copilot Agent、ローカルでの開発作業の自律化・チーム協調が主眼なら Claude Codeのエージェント機能——という棲み分けのイメージです。

テキトー教師

実際MYUUUではどう使い分けてますか？

室谷

うちはClaude Code一択ですね。カスタムエージェントの柔軟性と、Agent Teamsの並列作業が他では代替できない。

GitHub連携もClaude CodeからGitHub MCPを使えばできますし・・・

実践的なカスタムエージェント例

テキトー教師

具体的なカスタムエージェントの例を見ていきましょう。公式ドキュメントにある3つのサンプルが参考になります。

コードレビュアーエージェント

---
name: code-reviewer
description: コード変更後に自動でレビューを実行する。品質・セキュリティ・ベストプラクティスを確認するとき
tools: Read, Glob, Grep
model: sonnet
memory: project
---

あなたはシニアコードレビュアーです。コードをレビューするとき：
1. 可読性と保守性を確認する
2. セキュリティの脆弱性を探す
3. パフォーマンスの問題を特定する
4. ベストプラクティスへの準拠を確認する

各問題について、現在のコードと改善案を具体的に示してください。
エージェントメモリを参照し、過去に発見したプロジェクト固有のパターンを活用してください。

室谷

memory: project が入っているのがポイントです。レビューをするたびに、プロジェクト固有のパターンを学習していきます。

デバッガーエージェント

---
name: debugger
description: エラーやテストの失敗をデバッグするとき。根本原因を特定して修正案を提供する
tools: Read, Glob, Grep, Bash
model: sonnet
isolation: worktree
---

あなたは専門のデバッガーです。問題を診断するとき：
1. エラーメッセージと スタックトレースを分析する
2. 関連するコードを調査する
3. 根本原因を特定する
4. 修正案を提供し、その理由を説明する

複数の原因が考えられる場合は、最も可能性が高い順に示してください。

テキトー教師

isolation: worktree が入っています。デバッグ中に試行錯誤でコードを変更しても、メインブランチに影響しない設計です。

データサイエンティストエージェント

---
name: data-scientist
description: データ分析やPythonスクリプトが必要なとき。データの探索・可視化・統計分析を実行する
tools: Read, Write, Bash
model: opus
mcpServers:
  - jupyter
---

あなたはデータサイエンティストです。データを分析するとき：
1. データを探索し、基本統計を確認する
2. 分布とパターンを可視化する
3. 統計的な洞察を提供する
4. Python/Pandasで実行可能なコードを書く

室谷

OpusモデルとJupyter MCPを使うデータサイエンス特化のエージェントです。複雑な分析はモデルの強さが必要なのでOpusを選択している。

テキトー教師

MCPサーバーをエージェントにスコープしているので、Jupyterのツールはメインの会話には見えません。必要なときだけデータサイエンティストエージェントを呼び出す設計です。

今後の展望：エージェント機能の進化

室谷

Claude Codeのエージェント機能は、今もどんどん進化しています。Agent Teamsはまだ「実験的」ですが、安定化していくのは時間の問題だと思いますよ。

テキトー教師

教育者として感じるのは、「エージェントをどう設計するか」という能力の重要性が急速に上がっているということです。

室谷

そうなんですよね。室谷がツイートしたKarpathyのautoresearch的な話——「AIが自律的に研究・改善を繰り返す」という流れの中で、Claude Codeのエージェント設計はその入り口になっていると思う・・・

テキトー教師

個々のツールの使い方より「エージェントシステムをどう組み合わせるか」「タスクをどう分割して委任するか」のアーキテクチャ設計力が、差を生む時代になってきていますよね。

室谷

海外でも「誰でも使えるツールはコモディティ化する、差がつくのは設計力」という話が増えてきています。Claude Codeのエージェント機能を使いこなすには、この設計力が必要なんですよ。

テキトー教師

.AIコミュニティでは、こういう設計パターンの勉強会も定期的にやっています。ぜひ参加してみてください。

FAQよくある質問

テキトー教師

ここで、.AIコミュニティでよく出る質問にまとめて答えましょう。

Q. サブエージェントのファイルを手動で作ったのに反映されません

室谷

セッション起動時にエージェント定義が読み込まれます。手動で .claude/agents/ にファイルを追加した場合は、/agents コマンドを使うと再起動なしで即座にロードできます。

Q. agent.mdファイルに書いてもClaude Codeに呼び出されません

テキトー教師

descriptionが適切でないケースが多いです。「いつこのエージェントを使うべきか」が明確に書かれていないと、Claudeが委任判断できません。

「コード変更後にコード品質をレビューするとき」のように、具体的なトリガーを書きましょう。

Q. Agent Teamsでチームメートが現れません

室谷

in-processモードの場合、Shift+Down を押してチームメートがいるか確認してください。もしくは、タスクが1人でこなせるほど単純と判断されると、チームが生成されないことがあります。

明示的に「Create a team with 3 teammates」と指定するのが確実です。

Q. サブエージェントとAgent Teamsを同時に使えますか？

テキトー教師

使えます。Agent Teamsのチームメートもサブエージェントを呼び出せます。

ただし、サブエージェントのネストは禁止されているので、「サブエージェントがさらにサブエージェントを呼ぶ」ことはできません。

Q. GitHub Actionsで使えますか？

室谷

Claude Codeのヘッドレスモードでは使えます。--agents CLIフラグでセッション限定エージェントを定義するアプローチが自動化と相性がいいです。

まとめ

室谷

今回はClaude Codeのエージェント機能について、サブエージェントからAgent Teamsまで全部解説してきました。

テキトー教師

まとめると、Claude Codeのエージェント機能は「サブエージェント（シングルセッション内の専門化）」と「Agent Teams（マルチインスタンスの協調）」の2層で構成されています。

室谷

ほとんどのケースはサブエージェントで解決できます。Agent Teamsは「並列探索・競合仮説の検証・チームメート間のコミュニケーションが必要な場合」に使う——この判断基準を持っていると、コスト効率よく使えます。

テキトー教師

Claude Codeは今もどんどん進化しています。エージェント機能も実験的機能が着々と安定化していくフェーズにいるので、定期的に公式ドキュメントをチェックするのをおすすめします。

室谷

.AIコミュニティでも定期的にエージェント機能の勉強会を開いています。「実際に使ってみたけど、うまくいかない」という話もぜひ持ってきてください。

詳しくはをご確認ください。

出典

Claude Code Agents - Create custom subagents（Anthropic公式ドキュメント）
Claude Code - Run agent teams（Anthropic公式ドキュメント）