Claude Code SDK×サブエージェント完全攻略ガイド

⚡ 3秒でわかる！この記事のポイント

Claude Code SDKでサブエージェントを起動し、並列処理で開発速度を大幅向上
コンテキスト分離により、安全で効率的なマルチタスク処理が実現
Skills 2.0で再利用可能なエージェントワークフローを構築可能

「Claude Codeのサブエージェントって何ができるの？」「SDKを使えば自動化の幅がどこまで広がる？」——マルチエージェント開発に興味を持つエンジニアが急増しています。

結論から言えば、Claude Code SDKのサブエージェント機能を活用すれば、1つのタスクを複数のエージェントに分割して並列処理でき、大規模開発の生産性が飛躍的に向上します。特にコードレビューの並列化、大規模リファクタリングの分割戦略は、すぐに実践できるユースケースです。

この記事では、SDKの基本概念から実践的なサブエージェント活用パターン、Skills 2.0によるプログラマブルエージェント構築まで、実コード例とともに解説します。

Claude Code SDK×サブエージェントの仕組み

Claude Code SDKとサブエージェントの基本概念

SDKアーキテクチャ概要

Claude Code SDKは、Claude Codeのコア機能をプログラムから利用するためのインターフェースです。TypeScriptまたはPythonから、以下のような操作をプログラマティックに実行できます。

ファイルの読み書き・編集
シェルコマンドの実行
エージェントの起動・管理
コンテキストの注入と管理

SDKの基本的な使い方は、CLIから claude コマンドをパイプラインに組み込む方法と、ライブラリとしてインポートする方法の2通りがあります。

# CLIパイプライン方式
echo "このリポジトリの構造を分析してください" | claude --output-format json

# SDK方式（TypeScript）
import { Claude } from '@anthropic-ai/claude-code';
const claude = new Claude();
const result = await claude.run('このリポジトリの構造を分析してください');

Claude Codeの基本操作については「Claude Code使い方入門」で解説しています。

サブエージェントとは — コンテキスト分離の仕組み

サブエージェントは、メインのClaude Codeセッションから独立したコンテキストを持つ子プロセスとして起動されるエージェントです。

コンテキスト分離のメリット:

メインセッションのトークンを消費しない
サブエージェントの失敗がメインに影響しない
並列実行が可能
専門的なタスクに特化した指示を渡せる

Anthropicの公式ドキュメントによると、サブエージェントはメインセッションの約1/3のコンテキストサイズで動作し、トークンコスト面でも有利です。

マルチエージェント並列処理の実装パターン

コードレビューの並列化（スタイル・セキュリティ・テスト）

一つのPRに対して複数の観点でレビューを行う場合、サブエージェントの並列起動が効果的です。

// 3つのレビュー観点で並列実行
const reviews = await Promise.all([
  claude.subagent({
    task: 'コードスタイルとベストプラクティスの観点でレビューしてください',
    context: diffContent,
    tools: ['read', 'grep'],
  }),
  claude.subagent({
    task: 'セキュリティ脆弱性の観点でレビューしてください（OWASP Top 10準拠）',
    context: diffContent,
    tools: ['read', 'grep'],
  }),
  claude.subagent({
    task: 'テストカバレッジの観点で不足しているテストケースを特定してください',
    context: diffContent,
    tools: ['read', 'exec'],
  }),
]);

この方法により、通常15〜20分かかるレビューが5〜7分に短縮されます。

大規模リファクタリングの分割戦略

数百ファイルに及ぶリファクタリングでは、ファイル群をグループに分割し、各サブエージェントに担当範囲を割り当てます。

const fileGroups = chunkFiles(targetFiles, 20); // 20ファイルずつ分割

const results = await Promise.all(
  fileGroups.map((files, i) =>
    claude.subagent({
      task: `以下のファイル群のimport文をES Modules形式に統一してください`,
      context: files.map(f => f.path).join('\n'),
      tools: ['read', 'edit'],
    })
  )
);

エージェントチームの活用方法は「Claude Code エージェントチームガイド」で詳しく解説しています。

Skills 2.0 — プログラマブルエージェントプラットフォーム

スキルからサブエージェントを起動する

Skills 2.0では、CLAUDE.mdやスキルファイルからプログラマティックにサブエージェントを起動するフックが利用可能です。

<!-- .claude/skills/pr-review.md -->
# PR Review Skill

## Trigger
PRレビューの依頼を受けた場合

## Workflow
1. diffを取得する
2. 以下のサブエージェントを並列起動する:
   - スタイルチェッカー
   - セキュリティスキャナー
   - テストアドバイザー
3. 各結果を統合してレビューコメントを生成する

ライフサイクルフックとフォークコンテキスト

Skills 2.0のライフサイクルフックにより、特定のイベント発生時にサブエージェントを自動起動できます。

PreCommit: コミット前にコードスキャンを実行
PostPush: プッシュ後にCIの結果を監視
OnError: エラー発生時に自動デバッグを起動

フォークコンテキストは、現在のセッションの一部のコンテキストをサブエージェントに引き継ぐ機能です。全コンテキストを渡すのではなく、必要な情報だけを選択的に共有できるため、トークン効率が向上します。

Hooksの基本については「Claude Code Hooks完全ガイド」で解説しています。

Opus 4.6のエージェント性能と100万トークンコンテキスト

2026年にリリースされたClaude Opus 4.6は、エージェント的なタスクに最適化されたモデルです。

主な特徴:

100万トークンコンテキスト: 大規模コードベースを一度に把握可能
長時間タスクへの耐性: 数時間にわたる連続作業でもパフォーマンス維持
ツール使用の精度向上: ファイル操作・コマンド実行のエラー率が大幅低下
自己修正能力: エラー発生時に自動的にアプローチを変更

サブエージェントにはSonnet 4モデルを使用し、メインセッションにOpus 4.6を使うという階層的なモデル配置がコスト効率の面でも推奨されます。

Claude Code Security — マルチエージェントセキュリティスキャン

複数のサブエージェントによるセキュリティスキャンは、Claude Codeの最も実用的なユースケースの一つです。

const securityScan = await Promise.all([
  claude.subagent({ task: 'SQLインジェクション脆弱性をスキャン', tools: ['read', 'grep'] }),
  claude.subagent({ task: 'XSS脆弱性をスキャン', tools: ['read', 'grep'] }),
  claude.subagent({ task: 'ハードコードされた秘密情報をスキャン', tools: ['read', 'grep'] }),
  claude.subagent({ task: '依存関係の脆弱性をチェック', tools: ['exec'] }),
]);

セキュリティ全般については「Claude Code セキュリティガイド」を参照してください。

実践チュートリアル — サブエージェントでPR分析を自動化

セットアップ手順

Claude Codeの最新版をインストール:

npm install -g @anthropic-ai/claude-code

プロジェクトにスキルファイルを作成:

mkdir -p .claude/skills
touch .claude/skills/pr-analyzer.md

GitHub CLIとの連携を設定:

gh auth login
claude config set github.enabled true

コード例と実行結果

以下は、PRの変更内容を取得し、3つの観点で並列分析するスクリプトの例です。

#!/usr/bin/env npx tsx
import { Claude } from '@anthropic-ai/claude-code';

const claude = new Claude();
const prNumber = process.argv[2];

// PR情報の取得
const prInfo = await claude.run(`gh pr view ${prNumber} --json diff`);

// 並列分析
const [summary, risks, suggestions] = await Promise.all([
  claude.subagent({
    task: '変更内容の要約を日本語で作成してください（200字以内）',
    context: prInfo,
  }),
  claude.subagent({
    task: 'リスクの高い変更箇所を特定し、理由とともにリストアップしてください',
    context: prInfo,
  }),
  claude.subagent({
    task: '改善提案を3つ以内で具体的に提示してください',
    context: prInfo,
  }),
]);

// 結果をPRコメントとして投稿
const comment = `## 🤖 AI PR分析レポート\n\n### 📝 変更概要\n${summary}\n\n### ⚠️ リスク分析\n${risks}\n\n### 💡 改善提案\n${suggestions}`;
await claude.run(`gh pr comment ${prNumber} --body "${comment}"`);