Claude Codeのサブエージェント｜仕事を分けて同時に進める

Claude Codeのサブエージェントを調べ始めると、定義ファイルの置き場所とYAMLの書き方までは10分で分かります。詰まるのはその先です。分けたのに速くならない、指示が伝わっていない、途中で止まっているのに気づかない。原因のほとんどは機能の使い方ではなく、サブエージェントが「別の文脈で走る」という前提を作業の組み方に反映していないことにあります。ここでは置き場所と必須項目から始めて、文脈が引き継がれない範囲、同時に走らせられる数の上限、そして分業が空回りする型までを順に並べます。

サブエージェントは、別の文脈で走る作業者を定義する仕組み

サブエージェントは、Markdownファイル1つで「役割と道具を限定した作業者」を定義し、本体の会話から仕事を渡せるようにする仕組みです。ファイルの先頭にYAMLのフロントマターで設定を書き、その下の本文がそのまま作業者の指示書になります。

いちばん効いてくる性質は、渡した相手が本体の会話履歴を読めないことです。呼び出されたサブエージェントの手元にあるのは、自分の指示書と、本体から渡された依頼文と、CLAUDE.mdの階層と、リポジトリの状態だけです。それまでのやり取り、出力スタイル、自動で読み込まれる記憶、本体がすでに読み込んだスキルの中身は届きません。例外はfork型で、これだけは親の会話の文脈をそのまま引き継ぎます。

この仕様は最初は不便に見えます。ただ、設計の理由を知ると納得できるものです。

この仕様は初見では不便に感じますが、設計意図を知ると納得できます。もしサブエージェントがメインの会話をすべて読める設計だったとすると、次のような問題が起きます。 出典: qiita.com

本体の会話が長くなるほど、それを丸ごと読ませることの代償は大きくなります。読ませた分だけ処理する量が増え、関係のない過去のやり取りに引きずられる余地も増えます。文脈を切る設計は、長い作業を破綻させないための割り切りです。

裏を返せば、依頼文に書かなかったことは相手に届きません。「さっき決めた命名規則で」「先ほどのファイルに」という書き方は、本体との会話では通じてもサブエージェントには通じません。分業がうまくいかない原因の大半は、この1点に集まります。

置き場所は5層。プロジェクトと利用者で効く範囲が変わる

定義ファイルの置き場所は2つを覚えれば足ります。そのプロジェクトだけで使うなら .claude/agents/、どのプロジェクトでも使うなら ~/.claude/agents/ です。どちらのディレクトリも入れ子の中まで読まれるので、agents/review/ や agents/research/ のように用途で分けて整理できます。

同じ名前が複数の場所にあるときの優先順位は5段階で決まっています。組織の管理設定がもっとも強く、次に起動時に渡すCLIの指定、次にプロジェクト、次に利用者、最後にプラグインが持ち込むものです。名前が衝突すると意図しないほうが動くので、同じディレクトリの中では名前を重複させない前提で付けます。

置き場所の選び方は単純です。そのリポジトリの規約や構成に依存する作業なら、定義もリポジトリに入れて共有します。文章の推敲や調べもののように、どのプロジェクトでも同じ形で頼む作業なら利用者側に置きます。両方に置いてプロジェクト側で上書きする運用は可能ですが、どちらが効いているのかが分かりにくくなるため、最初は片方に寄せたほうが扱いやすくなります。

1つ注意点があります。新しく agents ディレクトリを作って最初のファイルを置いたときは、読み込まれるまでに再起動が要ります。--add-dir や /add-dir で後から足したディレクトリの中の定義も同じです。2本目以降の追加は監視されているのでそのまま反映されますが、最初の1本だけは「作ったのに出てこない」が起きます。

定義ファイルの必須は2つ。あとは絞り込みの指定

フロントマターで欠かせないのは name と description の2つだけです。name は識別子で、コロンを含めることと先頭をハイフンで始めることができません。description は「どういうときにこの作業者へ渡すか」を書く欄で、本体がここを読んで振り分けを判断します。

残りはすべて任意で、実務でよく使うのは絞り込み系です。tools に使わせる道具を並べれば許可制になり、disallowedTools に書けば禁止制になります。model には sonnet opus haiku fable のような系統名か、モデルIDそのもの、あるいは本体と同じものを使う inherit を指定します。maxTurns は何手で打ち切るかの上限、permissionMode は確認の取り方、skills は最初から読ませておくスキル、memory は記憶の範囲、effort は掛ける手間の段階です。

description の書き方には分量の制限があります。自作の作業者の description を合計した長さが15,000トークンを超えると、起動時に注意が出ます。1本ずつは短くても、数十本に増やせば届く数字です。似た役割を1本にまとめるか、使っていないものを片付けるかの判断が、ある時点で必要になります。

道具の絞り込みには、書かなくても効いている分があります。サブエージェントからは、利用者に質問する道具や、会話を終える道具、計画モードに入る道具などが最初から外されています。裏側で走る形の作業者では、読む・探す・書く・調べるといった基本の道具に絞られます。「聞いてから決めてほしい」という指示は、聞く手段が無いので成立しません。判断の材料は依頼文に入れておくか、判断そのものを本体に残す形にします。

メリットは文脈の節約と、道具の絞り込みと、同時進行

分けることで得られるものは3つに整理できます。

1つ目は本体の文脈を使い切らないことです。大量のファイルを読む調査、長いログの突き合わせ、テストの失敗の洗い出しは、読む量が多いのに最終的に必要なのは結論の数行です。これをサブエージェントに渡すと、読む作業は相手の文脈で消費され、本体には結論だけが戻ります。長い作業の途中で本体が詰まる回数を減らせるのは、この性質によるものです。

2つ目は道具を絞れることです。調べものだけを頼む相手に書き込みの道具を渡さなければ、意図しない変更が起きません。レビューを頼む相手を読み取りだけに限れば、指摘と修正が混ざりません。役割ごとに権限を切るという発想は、共同作業の設計としては目新しいものではありませんが、指示文だけで守らせようとするより機械的に確実です。

3つ目は同時に走らせられることです。既定では20体まで同時に動き、環境変数で変更できます。入れ子の深さは既定で3階層までで、こちらも設定で変えられます。20という数字は、5本のファイルを1体ずつに割り当てて4周させる、といった段取りを組むときの上限として使えます。

3つのうちどれを狙っているのかを先に決めると、設計がぶれません。文脈の節約が目的なら、戻ってくる形式を厳密に指定して出力を短く保ちます。同時進行が目的なら、担当範囲が重ならないように分け方を決めます。目的を混ぜたまま数を増やすと、速くはなったが結果が揃わない状態になります。

呼び出し方は3通り。頼むか、名指しするか、最初から起動する

呼び出し方は3つあります。1つ目は文章の中で名前を出して頼む形で、渡すかどうかは本体が判断します。2つ目は @ から候補を選ぶ明示的な指定で、これは確実にその作業者が走ります。3つ目はセッションそのものをその作業者として起動する形で、起動時の引数か設定ファイルで指定します。

使い分けの基準は、外してほしくないかどうかです。「レビューをかけたい」のように本体の判断で足りる場面は文章で頼めば済みます。「この定義で必ず走らせたい」という場面は明示的に指しておきます。日常的に同じ役割で使うなら、セッションごと切り替えてしまうほうが手数が減ります。

なお /agents の役割は途中で変わりました。以前は対話形式で作成を案内する画面が開きましたが、v2.1.198以降は「Claudeに頼むか、定義のディレクトリを直接編集するように」という案内を出すだけになっています。定義ファイルの形式も置き場所も変わっていないため、既存の定義はそのまま動きます。作り方の解説記事が対話画面を前提にしている場合は、その部分だけ読み替えます。

失敗しやすい3つの型と、その回避

分業がうまくいかない型は、おおむね3つに絞られます。

1つ目は依頼文の不足です。文脈が引き継がれないという前提が抜けていると、「前と同じ方針で」という書き方をしてしまいます。受け取った側には前が無いので、勝手な方針で進みます。回避策は、依頼文に対象のパス、守るべき規約、戻してほしい形式の3点を毎回書くことです。手間に見えますが、書けない依頼はそもそも分けられない依頼だという判定にも使えます。

2つ目は成果の形が揃わないことです。同じ指示書から出た作業者でも、戻ってくる文章の構成はばらつきます。10体に同じ形の作業を渡して、戻りをそのまま貼り合わせると、見出しの粒度や順番が合わないものが混ざります。回避策は、判定できるものを機械側に寄せることです。項目名と順番を指示書で固定し、数や形式の検査は本体ではなくスクリプトで通します。

3つ目は静かに止まることです。裏で走らせた作業者は、進捗を大きな声で知らせません。上限に当たった、途中で打ち切られた、依頼文の解釈を誤って何も書かずに終えた、といった終わり方は見分けが付きにくくなります。回避策は、結果の有無を数で確かめることです。保存された件数、書き出されたファイルの更新時刻、想定した担当の一覧との差分。この3つを見れば、報告を待たずに生死が分かります。

maxTurns を決めておくのも効きます。上限を決めずに走らせると、行き詰まった作業者が同じ試行を繰り返したまま長く残ります。何手で諦めてほしいかを先に決めておけば、失敗が早く表に出ます。

スキルとの違いは、文脈を分けるかどうか

似た仕組みとしてスキルがあります。違いは文脈を分けるかどうかの1点で考えると整理しやすくなります。

スキルは本体の文脈に手順や知識を読み込ませる仕組みです。読み込んだ内容はそのまま本体の会話の一部になり、本体が自分で作業します。文脈は増えますが、やり取りの流れは途切れません。

サブエージェントは作業そのものを別の文脈へ出す仕組みです。本体の文脈は増えませんが、渡した内容しか伝わりません。サブエージェント側で最初から読ませておきたい手順があるなら、skills に書いて持たせます。

選び方の基準は2つです。読ませたい内容が短く、本体がそのまま手を動かしたほうが早いならスキルです。読む量が多い、または同じ形の作業を同時に何本も回したいならサブエージェントです。両方を組み合わせる場合は、共通の手順をスキルに切り出し、それを読ませたサブエージェントを複数走らせる形になります。

分業を組んでも、窓をまたぐ工程は減らないまま残る

サブエージェントで減るのは、本体が読む量と、順番に待つ時間です。減らないものもあります。どのファイルを担当に割り当てるかを決める工程、戻ってきた成果を実際のファイルと突き合わせる工程、上限に当たって止まった分をやり直す工程です。

この3つは、どれもファイルの一覧を見ながらコマンドを打つ作業です。担当表を作るためにフォルダを開いて数え、分割したファイルをターミナルで渡し、書き出されたものを一覧で並べて更新時刻を見る。分業の設計をどれだけ丁寧に組んでも、ここは手作業として残ります。

工程を数えると、打つコマンドの数よりも、フォルダの画面とターミナルの画面を行き来する回数のほうが多くなります。AIへの依頼がもう1つの窓で行われているなら、切り替えの回数はさらに増えます。ここで効くのは短いコマンドを覚えることではなく、フォルダとターミナルとAIが同じ窓にある状態にして、一覧で選んだパスをそのまま依頼文に渡し、戻ってきた結果を同じ画面で数えられるようにすることです。

ターミナルを内側に持つファイル管理で何がどこまでできるのかはできることに一覧があり、文章向けの道具やコードエディタとの向き不向きは他のファイル管理との比較に9項目で整理されています。走らせたまま外出して、止まっている作業者に出先から返す使い方はiPhone・iPadから続きをが該当します。費用の考え方は料金にあり、Mac単体の機能は無料で、iPhoneとiPadから使う分だけ月額780円などの選択肢が置かれています。導入前に迷いやすい点はよくある質問にまとめられています。

サブエージェントは、作業を小さく切って同時に流すための道具です。切り方と渡し方が決まっていれば効きますし、決まっていなければ数を増やしただけになります。定義ファイルに書けるかどうかを先に確かめるのが、分けるべき仕事かどうかの判定として実用的です。