Claude Code でサブエージェントを作成して使用する方法 - 実践ガイド

CometAPI
AnnaOct 22, 2025
Claude Code でサブエージェントを作成して使用する方法 - 実践ガイド

サブエージェントは、Claude Code / Claude Agentエコシステムへの最も便利な追加機能の一つです。複雑なワークフローをより小規模で専門性の高いAI「チームメイト」に分割し、メインスレッドのコンテキストを維持しながら、ツールへのアクセスを安全に制限することができます。この記事では、 サブエージェントとは何か, 作成して呼び出す方法 （CLI、ファイルシステム、SDK） 設計原理 構築時に従うべきこと、そして 具体的なサンプルコード コピーして適応することができます。

サブエージェントとは何ですか?

A サブエージェント は、Claude Code（またはClaude Agent SDK）が作業を委任できる、事前設定された限定的なAIアシスタントです。各サブエージェントは以下の機能を提供します。

  • 一意の名前と明確な目的の説明があります。
  • 実行中 独自のコンテキストウィンドウ メインの会話とは分離します (長い詳細の連鎖がオーケストレーターのコンテキストを汚染しないようにするため)。
  • 限定されたセットで構成可能 豊富なツール群 (ファイルの読み取り/書き込み、bash、grep、MCP ツールなど)、および特定のモデルの選択が可能です。
  • 動作と制約をガイドするシステム プロンプト (サブエージェントのパーソナリティと指示) が含まれます。

これらの特性により、サブエージェントは、トークンを大量に使用するタスク (調査、大きなログの検索)、セキュリティを重視するタスク (スキャンや潜在的に破壊的なツール)、反復的で明確に指定されたタスク (スタイル チェック、テストの実行) に最適です。

アントロピックは迅速にイテレーションを行っており、クロードコードCLIとエージェントSDKはリファクタリングされ、 クロードエージェントSDKバンドルエージェントと関連するカスタマイズ（スラッシュコマンド、MCPサーバー、フック）用のプラグインサポートが導入されました。 性格 Claude.ai、Claude Code、Agent SDK間で再利用できるようにドメインワークフローをパッケージ化する方法を提供します。これらのアップデートにより、 共有、インストール、バージョン チームやプロジェクトをまたいでサブエージェントを構築します。本番環境のワークフローを構築する予定の場合は、プラグイン/スキルのパッケージングとSDKベースのデプロイメントパターンを評価する必要があります。

サブエージェントが重要な理由

すぐに役立つ 3 つの理由:

  1. コンテキストの保存 — 長時間またはノイズの多い検索、テスト実行、スキャンは、プライマリコンテキストを圧迫するのではなく、サブエージェント内で実行されます。これによりトークンの無駄が削減され、結果の推論が容易になります。
  2. 専門知識 — タスクに合わせたシステムプロンプトにドメイン知識と行動をエンコードすることができます（例： security-auditor 秘密、依存関係の問題、および安全でないシェルの使用に焦点を当てています。
  3. より安全な権限 — サブエージェントごとにツールを制限すると、影響範囲が狭まります（ドキュメントレビュー担当者は読み取り専用ツールを持つかもしれませんが、テストランナーは Bash でもない Edit).
  4. 並列化： 複数のサブエージェントを同時に実行することができます（例： style-checker, security-scanner, test-runner) を作成し、簡単な結果を収集します。これは、高額な独立したチェックにとって大きなメリットです。

Claude Codeでサブエージェントを使用するための前提条件

サブエージェントの構築を開始する前に、次のものが用意されていることを確認してください。

1) クロードコードがインストールされ認証されている

Claude Code CLI をインストールするか、Web/IDE 統合を使用します。 CometAPI のクイックスタートとセットアップドキュメント サポートされているインストール方法（npmグローバルパッケージまたはネイティブインストーラ）をリストし、インストールを検証する方法を示します。 claude --version / claude doctor. また、 コメットAPI アカウント (CometAPI のキーを使用して Claude コードにアクセスする方が、公式モデルよりも安価で便利です)。クイックスタートに記載されているとおりです。

2) ノード/環境（一部のインストールパス）と基本的なシェルツール

npmパッケージ経由でインストールする場合は、Node.js（Node.js 18以上が例としてよく使用されます）が必要です。Agent SDK（JavaScript/TypeScriptまたはPython）を使用する場合は、SDK依存関係がインストールされたプロジェクトが必要です。多くのチュートリアルでは、標準的な開発ツール（git、bash、オプション）が前提となっています。 gh GitHub ワークフロー用の CLI。

3) プロジェクトレイアウトとCLAUDE.md

ベストプラクティスとしては、リポジトリレベルのヘルパードキュメント（CLAUDE.md）とプロジェクトスコープのエージェントを配置する .claude/agents/ チームメイトがそれらを継承します。CLAUDE.mdファイルはClaudeのコンテキストに自動的に取り込まれ、セッション間で一貫した動作をガイドするのに役立ちます。各サブエージェントはYAMLフロントマターを含むMarkdownファイルです。最小限の例：

---
name: code-reviewer
description: Expert code review specialist. Use PROACTIVELY after code changes to check security, style, and maintainability.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. When invoked:
1. Run `git diff` to identify modified files.
2. Focus review on changed code paths.
3. List security issues, probable false positives, and suggested fixes.
4. Provide a short, prioritized action list.

Return results in JSON with fields: summary, issues.
  • name 小文字の識別子です。
  • description 自動呼び出しとマッチングをガイドします。
  • tools ツールのアクセスを制限します (すべてを継承しないようにします)。
  • model することができます sonnet, opus, haikuまたは inherit.

4) 権限と MCP サーバー (オプションだが一般的)

ワークフローでModel Context Protocol（MCP）サーバーまたは外部ツール（Puppeteer、Sentry、カスタムRESTツール）を使用している場合は、MCPサーバーが正しく構成され、アクセス可能であることを確認してください。機密性の高い操作（書き込み、bash、gitコミット）については、許可リストとエージェントごとの許可について慎重に検討してください。 tools スコープ設定。

Claude Codeでサブエージェントを作成する方法

サブエージェントは主に3つの方法で作成できます: 対話型CLI (/agents）、ファイルシステムのマークダウンファイルとして、またはAgent SDKを介してプログラム的に保存できます。手順は以下の通りです。

Claude Code は、サブエージェントを作成するための 3 つの実用的な方法をサポートしています。

  1. インタラクティブCLI /agents UI — セッション内での反復的な作成が最速です。
  2. ファイルシステムベース — YAMLフロントマターでMarkdownファイルを作成する .claude/agents/ （プロジェクトレベル）または ~/.claude/agents/ (ユーザーレベル) プロジェクトエージェントの優先度が高くなります。
  3. プログラム（エージェントSDK） — コード内でサブエージェントを定義するには、 agents 呼び出すときのパラメータ query(); SDK駆動型アプリに推奨されます。このアプローチは、サブエージェントを動的に作成したり、アプリケーションに埋め込んだりする必要がある場合に最適です。

クイックインタラクティブフロー（推奨される最初のステップ）

  1. ターミナルで Claude Code を起動するか、VS Code でコマンド パレットを開きます。
  2. スラッシュ コマンドを使用してサブエージェント インターフェイスを実行します。
/agents
  1. 選択する 新しいエージェントを作成するプロジェクトレベルまたはユーザーレベルのスコープを選択し、名前/説明/ツール/システムプロンプトを入力して保存します。Claudeでドラフトを作成し、その後修正することができます。保存すると、エージェントは /agents 明示的または自動で呼び出すことができます。

ファイルシステムベースのサブエージェント（Markdown + YAML フロントマター）

サブエージェントは、YAMLフロントマター付きのMarkdownファイルとして保存されます。以下の場所に配置してください。

  • プロジェクト範囲： .claude/agents/*.md （最優先）
  • ユーザースコープ: ~/.claude/agents/*.md

基本的なファイル構造:

---
name: code-reviewer
description: "Review recent code changes for security and style."
tools: Read, Grep, Glob, Bash  # optional; omit to inherit

model: sonnet  # optional; or 'inherit'

---
You are a senior code reviewer with expertise in security, performance, and best practices.
When reviewing:
- Identify security vulnerabilities
- Prioritize clarity and maintainability
- Always provide concise examples and suggested fixes
- If unsure, ask for the minimal reproducible snippet

実装に関する注意事項:

  • name ハイフン付きの小文字にする必要があります。
  • 省略 tools サブエージェントがメインスレッドのすべてのツールを継承できるようになります。ツールを明示的にリストすると、最小権限モデルが強制されます。
  • model: 'inherit' メインスレッドと一貫した動作をさせるために、またはモデルの別名（例： sonnet, opus, haiku).

CLI JSON定義（アドホック/セッション使用）

セッションを起動するときに、一時的なサブエージェントをインラインで定義できます。

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer.",
    "prompt": "You are a senior code reviewer. Focus on security and best practices.",
    "tools": ,
    "model": "sonnet"
  }
}'

CLI 定義のエージェントは、スクリプト実行や実験に役立ちます。優先度はプロジェクト エージェントよりも低いですが、ユーザー エージェントよりも高くなります。

プログラムによる定義（エージェント SDK - アプリに推奨）

アプリケーションや自動化を構築する場合は、エージェントSDKの agents パラメータ（これは最も統合されたオプションです）。例（TypeScript）:

import { query } from '@anthropic-ai/claude-agent-sdk';

async function runReview() {
  const result = await query({
    prompt: "Assess the authentication module for security issues",
    options: {
      agents: {
        "code-reviewer": {
          description: "Expert code review specialist",
          prompt: `You are a code review specialist...`,
          tools: ,
          model: "sonnet"
        },
        "test-runner": {
          description: "Runs the test suite and analyzes failures",
          prompt: `You run tests and summarize failures...`,
          tools: ,
          model: "sonnet"
        }
      }
    }
  });

  console.log(result);
}

SDKはファイルシステムベースのエージェントも受け入れます（ .claude/agents/ ファイルなど）を使用することもできます。プログラムによるエージェントは、動的なワークフローやCI統合に非常に役立ちます。

Pythonの場合、 claude-agent-sdk パッケージは同様のパターンをサポートしています。 query() or ClaudeSDKClient オプション、ツール、MCPサーバーをプログラムで設定できます。クイックスタートサンプルについては、Python SDKリポジトリをご覧ください。

サブエージェントの呼び出し方法

自動委任

クロード・コードは 自動的に ユーザープロンプトがサブエージェントの目的と一致する場合、サブエージェントを選択します。これは、メインエージェントがタスクを適切なスペシャリストに自動的にルーティングするバックグラウンドオーケストレーションに役立ちます。明確なサブエージェントの説明と、焦点を絞ったシステムプロンプトを活用することで、自動選択の精度が向上します。

明示的な呼び出し（わかりやすくするために推奨）

会話の中でエージェントを明示的に呼び出すことができます。

> Use the code-reviewer subagent to check my recent changes

明示的な呼び出しは決定論的であり、予期しない委任を回避する必要がある実稼働フローに推奨されます。

SDK オーケストレーター パターン

SDK アプリの一般的なパターン:

  • フォーク + ギャザー: 複数のサブエージェントを並行して起動し、各エージェントの簡潔な回答を収集し、メインエージェントで結果を要約/マージします。
  • スーパーバイザーループ: オーケストレーターはサブエージェントにタスクを割り当て、結果を検査し、それを受け入れるか、再計算/明確化を要求します。
  • サンドボックス実行: 潜在的に危険な機能 (デプロイ、スクリプトの実行) を厳しく制約されたエージェントに付与し、実行する前に明示的な人間の承認フックを要求します。

これらのパターンは、エージェント SDK のセッション管理、フック、および MCP ツールを使用した実際の実装にマッピングされます。

有用で安全、かつ構成可能なサブエージェントの作り方

1) 単一の責任と明確な指示

各サブエージェントには明確な目的が1つあり、境界、成功基準、出力形式を指定するシステムプロンプトが必要です。出力が構造化されている場合（JSON、箇条書き、コードパッチなど）、サブエージェントに正確な指示を与えることで、解析エラーを削減できます。

2) ツールに対する最小権限

サブエージェントに必要なツールのみを付与します。例えば、ドキュメントレビュー担当者には必要なツールはありません。 Write or Bash可能な限りデフォルトで読み取り専用に設定し、必要に応じてツールの権限を明示的に昇格します。これによりリスクが軽減され、監査が簡素化されます。

3) コンパクトで構造化された出力を返す

サブエージェントは戻るべきである 簡潔で最終的な回答 長時間実行される思考トレースではなく、サブエージェントのコンテキスト内で負荷の高い処理を行い、その後、添付ファイル（パッチ、ファイル参照、JSON）付きの短いサマリーを返すというパターンが一般的です。これにより、オーケストレーターのコンテキスト効率が最大化されます。

4) テスト可能性とバージョン管理

サブエージェントファイルをバージョン管理に保存し、小さな入力に対して実際の実行を行うCIテストを作成し、モデル／ツールセットをピン留めします。スキルやプラグインに依存している場合は、プラグインマーケットプレイス／バージョン管理パターンを採用して、アップグレードとロールバックを管理します。

5) 監査フックと人間参加型チェックポイント

SDKフックを使用してツール呼び出しをインターセプトし（PreToolUseフック）、破壊的なアクションには人間の承認を求めます。すべてのツール呼び出しをログに記録し、再生可能な監査を実現します。SDKは、このパターンをサポートするためのフックと権限の仕組みを提供します。

アプリケーションサンプル - 小規模で本番環境に近いパイプライン

以下は、ファイルシステム エージェント、2 つのエージェント (レビュー用とテスト用) を使用する SDK 呼び出し、および単純なオーケストレーションという典型的な部分を示すコンパクトな例です。

1) ファイルシステムエージェント: .claude/agents/code-reviewer.md

---
name: code-reviewer
description: Use PROACTIVELY after code changes. Perform security, style, and maintainability review on modified files.
tools: Read, Grep, Glob
model: inherit
---
You are a meticulous senior code reviewer. When invoked:
1. Run `git diff --name-only` to find modified files.
2. For each modified file, read and look for security issues, suspicious patterns, or maintainability problems.
3. Return JSON:
{
  "summary": "one-line summary",
  "issues": ,
  "recommended_changes": 
}

2) プログラムによるオーケストレーション（Node.js）

import { query } from '@anthropic-ai/claude-agent-sdk';
import fs from 'fs';

async function runPipeline() {
  const result = query({
    prompt: 'Run PR checks: security review then unit tests.',
    options: {
      agents: {
        'code-reviewer': {
          description: 'Use PROACTIVELY after code changes; output JSON with issues.',
          prompt: fs.readFileSync('./.claude/agents/code-reviewer.md', 'utf8'),
          tools: ,
          model: 'sonnet'
        },
        'test-runner': {
          description: 'Run test suite and summarize failing tests.',
          prompt: `You are a test-runner. Execute tests and return JSON { summary, failing_tests[] }`,
          tools: 
        }
      }
    }
  });

  for await (const message of result) {
    // Implement streaming logic: messages may include subagent outputs
    console.log(message);
  }
}

runPipeline().catch(console.error);

注意： 　 code-reviewer チームの再利用のためにリポジトリに保存されます。SDK呼び出しは、プログラムエージェントが優先され、 tools スコープを設定すると、誤った書き込みを防ぐことができます。

高度なトピックとパターン

動的エージェント構成

環境（開発と本番）や重大度レベル（例： strict vs balanced セキュリティ モード)。SDK の例では、実行時にエージェント定義を生成する方法を示しています。

並列化

複数の読み取り専用分析エージェント（スタイル、セキュリティ、テストカバレッジ）を並列に実行し、それらのJSON出力をメインスレッドに集約します。これにより、大規模リポジトリのウォールクロック時間が大幅に短縮されます。

プラグイン提供エージェント

プラグインは、プラグインマニフェストにパッケージ化されたサブエージェントを提供することができます。 /agents カスタムエージェントと並行して実行でき、明示的に呼び出すこともできます。これを使用して、標準化されたエージェントをチーム全体に配布できます。

Claude code cliを使用するのが最も推奨される場所

CometAPI が強力な Claude Code cli を完全にサポートするようになったことをお知らせします。 Claude Code で Comet API モデルを使用するには、Claude Code をインストールし、取得した Comet API キーとベース アドレスで認証するだけです。

CometAPI を通じて claude コードを使用するのはなぜですか?

主要な人工知能機能: 開発者向けに特別に構築されたモデルを使用して、コードを簡単に生成、デバッグ、最適化できます。

  • 柔軟なモデル選択: 当社の包括的なモデル範囲により、よりシームレスな開発が可能になります。
  • シームレスな統合：APIはいつでも利用可能です。Claude Codeを既存のワークフローにわずか数分で直接統合できます。
  • **CometAPI経由でClaude Codeを使用すると、コストをさらに節約できます。**CometAPIが提供するClaude APIは公式価格より20%オフで、公式による最新モデルにアップデートされています。

Claude Code cliを使用する準備はできましたか？ APIガイド 詳細な手順については、

AIに関するヒント、ガイド、ニュースをもっと知りたい方は、フォローしてください。 VK, X および Discord!

も参照してください CometAPI 経由で Claude コードをインストールして実行する方法

最終的な考え

サブエージェントを次のように扱う 再利用可能でバージョン管理されたマイクロペルソナ小さく始める： doc-reviewer フォルダーとその下に test-runner リポジトリの場合は、チェックインしてください .claude/agents/ヘッドレスを使用してCIで自動化します claude -pプロンプトを繰り返し、構造化された出力を追加し、ツールの権限を厳格化します。

最も役立つメンタルモデルは、クロードをプロジェクトマネージャー、サブエージェントをチームのスペシャリストとして想像することです。マネージャーは明確に定義されたタスクを委任し、スペシャリストの成果物を集約し、最終報告書を作成します。時間の経過とともに、信頼性、テスト可能性、そして開発ワークフローの大部分を自動化する能力が向上していくでしょう。

もっと読む

1つのAPIで500以上のモデル

最大20%オフ