Claude Code Subagent使い方｜並列・分離処理の実践ガイド

Claude Codeを使い込んでいくと、ある壁にぶつかります。会話が長くなるにつれてコンテキストが肥大化し、精度が落ちる。複数のタスクを同時に進めたいのに、1つの会話では処理が混線する。この問題を根本的に解決するのがSub-agents（サブエージェント）です。

私はClaude Codeを2025年10月から業務全般で使用しており、Sub-agentsは記事生成・リサーチ・コードレビューなど多くの場面で活用しています。この記事では、Sub-agentsの全フロントマターフィールドの解説から、実務での活用パターンまで具体的に解説します。

Sub-agentsとは何か

Sub-agentsは、.claude/agents/ディレクトリにMarkdownファイルを置くことで作成できる独立したコンテキストウィンドウで動作する自律エージェントです。

CommandやSkillとの最大の違いは、メインの会話コンテキストを汚さずに独立して処理を実行する点です。これにより、以下のことが可能になります。

• メイン会話の精度を保ちながら、別タスクを並列で処理
• 大量のデータ処理をメイン会話から切り離して実行
• セッション間で学習結果を永続化

Thariq氏は「use subagentsでコンピュート（計算資源）を投入する」という考え方を提唱しています。サブエージェントを使うことで、コンテキストの制約を受けずに計算資源を効率的に投入できるという発想です。これはTest Time Compute（推論時にどれだけの計算を投入するか）の実践的な応用と言えます。

フロントマター全解説（16フィールド）

Sub-agentsのMarkdownファイルにはYAMLフロントマターで設定を記述します。16個のフィールドがありますが、重要度の高い順に解説します。

必須・推奨フィールド

• name（必須）：一意の識別子。小文字＋ハイフンで命名します
• description（必須）：エージェントの説明。ここにPROACTIVELYを含めると、Claudeが文脈に応じて自動的にこのエージェントを呼び出すようになります
• tools（推奨）：許可するツールの一覧。省略すると全ツールを継承しますが、必要最小限に絞ることで暴走を防ぐのがベストプラクティスです
• maxTurns（推奨）：最大ターン数。設定しないと無制限に動作する可能性があるため、必ず設定すべきです

重要フィールド

• model：使用モデル（haiku/sonnet/opus/inherit）。タスクの複雑さに応じて選択
• permissionMode：権限モード。acceptEditsでファイル編集を自動承認、dontAskで全操作を自動承認
• memory：永続メモリのスコープ。projectでプロジェクト単位の学習結果を保持
• skills：プリロードするSkill名のリスト。エージェント起動時にSkillの全文がコンテキストに注入されます

高度なフィールド

• disallowedTools：使用を禁止するツール
• mcpServers：エージェント固有のMCPサーバー設定
• hooks：ライフサイクルフック
• background：trueでバックグラウンドタスクとして実行
• effort：思考レベル（low/medium/high/max）
• isolation：worktreeでGit Worktreeによる完全分離実行
• initialPrompt：メインエージェントとして使用する場合の初期プロンプト
• color：CLI出力の色設定

memory: projectで学習を永続化する

memory: projectは、Sub-agentsの中でも特に強力な機能です。エージェントがセッション間でプロジェクト単位の永続メモリを持つことができます。

これにより、例えば以下のような使い方が可能です。

• コードレビューAgentが、過去のレビュー指摘パターンを記憶して次回に活かす
• リサーチAgentが、過去に調べた内容を記憶して重複調査を避ける
• 記事生成Agentが、執筆スタイルの改善点を記憶して品質を向上させる

memoryスコープは3種類あります。

• user：ユーザー単位（全プロジェクト共通）
• project：プロジェクト単位
• local：ローカル単位

業務での使用にはprojectが最も実用的です。

Git Worktreeによる完全分離実行

isolation: worktreeを設定すると、エージェントはGit Worktreeで完全に分離された作業ツリーで実行されます。これにより、メインブランチの作業を一切邪魔することなく、独立した環境でコード変更を行えます。

CLIからは--worktreeフラグでも同じことが可能です。

Worktree分離が有効な場面は以下の通りです。

• 大規模なリファクタリング：メインの作業に影響を与えずに実行
• 実験的な変更：失敗してもメインブランチに影響なし
• 並列開発：複数のエージェントが異なるブランチで同時に作業

Skillプリロードでドメイン知識を注入する

skills:フィールドでSkill名を指定すると、エージェント起動時にそのSkillの全文がコンテキストに注入されます。これが「Agent Skill（プリロードSkill）」パターンです。

例えば、API呼び出しの手順をSkillとして定義し、それをデータ取得Agentにプリロードすれば、エージェントはAPI呼び出しの詳細手順を最初から把握した状態で動作します。

プリロードSkillを作成する際のポイントは以下の通りです。

• user-invocable: falseを設定して/メニューから非表示にする（直接呼び出す必要がないため）
• Skill本文にはドメイン知識・手順・制約事項を詳細に記載する
• 1つのAgentに複数のSkillをプリロードすることも可能

公式ビルトインAgent

Claude Codeには6個のビルトインAgentが用意されています。

• general-purpose：複雑なマルチステップタスク（デフォルト）
• Explore：haikuモデルで高速コードベース探索（Read-only）
• Plan：計画モードでの事前調査（Read-only）
• Bash：ターミナルコマンド実行に特化

特にExploreは、大規模コードベースの調査を高速に行いたい場面で有用です。haikuモデルで動作するため、opusのコンテキストを消費せずに探索できます。

Sub-agent設計の原則

実務でSub-agentsを設計する際に、私が守っている原則を共有します。

原則1：toolsは必要最小限に絞る

全ツールを許可すると、エージェントが想定外の操作を行うリスクがあります。例えば、リサーチ専用のAgentにはRead系ツールのみを許可し、ファイル編集は禁止するといった設計が安全です。

原則2：maxTurnsは必ず設定する

未設定だとエージェントが延々と動作し続ける可能性があります。タスクの複雑さに応じて適切なターン数を設定してください。単純な調査なら5ターン、複雑な実装なら10〜15ターンが目安です。

原則3：descriptionは具体的に書く

Claudeがエージェントを自動呼び出しするかどうかは、descriptionの内容で判断されます。「何をするエージェントなのか」「どういう場面で使うのか」を具体的に記載してください。自動呼び出しを積極的に促したい場合はPROACTIVELYを含めます。

Test Time Computeの実践的応用

Sub-agentsを理解するうえで重要な概念がTest Time Computeです。これは「推論時にどれだけの計算資源を投入するか」という考え方で、Sub-agentsはまさにこの概念の実践的な応用です。

メインの会話で1つのモデルが処理するのではなく、複数のサブエージェントに計算資源を分散投入することで、以下の効果が得られます。

• 各エージェントが専門領域に集中できる
• コンテキストの肥大化を防げる
• 並列処理で全体の処理時間が短縮される

ただし、並列実行には注意が必要です。私の経験では、コンテキスト量が大きい状態での並列実行はトークン消費が急増します。単純作業の繰り返しに限定して並列実行するのが効率的です。

まとめ

Claude Code Sub-agentsの要点を整理します。

• Sub-agentsは独立コンテキストで動作する自律エージェント
• 16個のフロントマターフィールドで細かく制御可能
• memory: projectでセッション間の学習を永続化
• isolation: worktreeでGit Worktree完全分離実行
• skills:フィールドでドメイン知識をプリロード
• maxTurnsとtoolsの制限は暴走防止の必須設定
• Test Time Computeの発想で計算資源を分散投入

Sub-agentsはClaude Codeの機能の中でもTier 3（応用）に位置づけられます。まずはTier 1のCLAUDE.md、Tier 2のSkills・Commandsを使いこなしたうえで、コンテキスト分離や並列処理が必要になった段階で導入するのが最も効果的です。