第7章サブエージェントとバックグラウンド実行

はじめに

大規模なコードベースの調査をメインの会話でやり続けると、検索結果やファイル内容でコンテキストが埋まってしまいます。
ハーネスはこの問題を、サブエージェント ——独立したコンテキストウィンドウを持つ子エージェント——への委譲で解決します。

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

メインのエージェント（親）は、Task（Agent）ツールでサブエージェントを起動できます。

flowchart TD
    P["親エージェント<br/>（メイン会話のコンテキスト）"]
    P -->|"プロンプトを渡して起動"| S1["サブエージェント A<br/>（独立コンテキスト）"]
    P -->|"並列起動も可能"| S2["サブエージェント B<br/>（独立コンテキスト）"]
    S1 -->|"最終レポートのみ返す"| P
    S2 -->|"最終レポートのみ返す"| P

重要な特性は次の3点です。

コンテキストが独立 — サブエージェントが何百ファイル読んでも、親のコンテキストは消費されない。
親に返るのは 最終報告のテキストだけ
ステートレスな起動 — サブエージェントは親の会話履歴を引き継がない。
必要な情報はすべて起動時のプロンプトに書く必要がある
並列実行が可能 — 複数のサブエージェントを同時に走らせ、調査を分担させられる

7.2 組み込みエージェントタイプ

ハーネスには汎用のエージェントタイプがあらかじめ用意されています。

タイプ	特徴
general-purpose	全ツールが使える汎用型。複雑な多段タスク向け
Explore（探索型）	読み取り専用の高速検索型。コードの所在調査に特化
Plan（計画型）	実装計画の立案に特化。読み取り専用

7.3 カスタムエージェントの定義

プロジェクト固有のエージェントは、Markdown ファイルで定義できます。

---
name: code-reviewer
description: コード変更をレビューし、バグ・セキュリティ問題を指摘する。コードレビューを求められたら積極的に使用する。
tools: Read, Grep, Glob, Bash
model: sonnet
---

あなたはシニアエンジニアとしてコードレビューを行います。

レビュー観点:
1. バグ・ロジックエラー
2. セキュリティ上の問題（インジェクション、認証漏れ）
3. パフォーマンス上の懸念

指摘は「重大度・該当箇所・修正案」のセットで報告してください。

配置場所	スコープ
`.claude/agents/`	プロジェクト（チーム共有）
`~/.claude/agents/`	ユーザー全体

定義のポイント：

description — 親エージェントが「いつこのサブエージェントに委譲するか」を判断する材料。
具体的に書く
tools — 許可するツールを絞れる。
レビュー用なら読み取り系のみ、が安全
model — サブエージェントごとにモデルを変えられる。
大量の単純作業は haiku、精密なレビューは opus など、コスト最適化に有効
本文 — サブエージェントのシステムプロンプトになる

/agents コマンドで対話的に作成・管理することもできます。

7.4 バックグラウンド実行と分離

サブエージェントの実行形態にはいくつかのオプションがあります。

バックグラウンド実行 — 親は結果を待たずに他の作業を継続し、完了時に通知を受け取る
worktree 分離 — サブエージェントに専用の git worktree を与え、親の作業ツリーを汚さずに変更を試させる
リモート実行 — クラウドのサンドボックス環境でサブエージェントを走らせる

例: 「この3つのモジュールをそれぞれサブエージェントで
     並列にリファクタリングして、worktree で分離して」
→ 3つのサブエージェントが独立した worktree で同時に作業
→ 親が結果を確認してマージ

7.5 マルチエージェント設計のコツ

プロンプトに文脈を全部入れる — サブエージェントは親の会話を知りません。
「さっきの件」は通じないため、対象ファイル・目的・期待する出力形式を明示します
出力形式を指定する — 「ファイルパスと行番号のリストで報告」のように指定すると、親が結果を使いやすくなります
書き込みの競合に注意 — 並列エージェントに同じファイルを編集させると競合します。
分担は疎結合な単位（ディレクトリ・モジュール）で切ります
起動コストを意識する — サブエージェントは毎回ゼロから環境を把握します。
親が数回のツール呼び出しで済むことは親が直接やる方が速くて安上がりです

まとめ

サブエージェントは独立コンテキストを持つ子エージェント。
大量調査を委譲して親のコンテキストを守る
.claude/agents/*.md でカスタムエージェントを定義でき、ツール・モデルを個別に制限できる
並列実行・worktree 分離・バックグラウンド実行で大規模タスクをスケールさせられる
ステートレスであることを前提に、起動プロンプトへ文脈を全部詰め込むのが成功の鍵