Claude Codeでサブエージェントをfan outし、戻ってきた結果を確かめる

Googleで「claude fan out subagents」と検索する人は多く、末尾に「command」を付ける人も少なくありません。まるで切り替えるスイッチがあるかのようです。実際には手法があり、コマンドもあります。私たちは2026年10月16日に、Claude Code 2.1.301とAnthropicのドキュメントで両方を確認しました。

そして、ドキュメントがあまり触れていない部分があります。この記事を書いた理由でもある、結果をどう扱うかという問題です。私たちは毎晩fan outを実行しています。6つのサブエージェントがこのブログの新しい記事を17の言語に翻訳し、メインのセッションがその成果をマージします。どのサブエージェントもルールを守ったと報告します。それでも、起動前に書いておいたチェックは問題を見つけます。

短い答え

fan outとは、1つのセッションが作業を互いに依存しないスライスに分け、各スライスをサブエージェントに渡し、同時に実行させ、戻ってきたものをマージすることです。Claude Codeでは3つの方法があります。

このページの残りでは、それぞれの方法を順に見たあと、私たち自身のfan outで実行しているチェックを紹介します。

サブエージェントに見えるもの、見えないもの

作業の分け方を決めるのは、ドキュメントにある3つの事実です。

各サブエージェントは白紙から始まります。 独自のコンテキストウィンドウで、独自のシステムプロンプト、ツール、権限を持って動きます。あなたの会話も、すでに使ったスキルも、Claudeがすでに読んだファイルも見えません。知っておくべきことは、すべてブリーフに書いておく必要があります。

結果はメインの会話に戻ります。 サブエージェントの作業の細かい部分はそのサブエージェントのコンテキストに残り、結果だけが戻ります。それでも、多くのサブエージェントが長いレポートを返せばメインのコンテキストは埋まりますし、各サブエージェントは実行中に自分のトークンを使います。

上限があります。 デフォルトでは、1つのセッションで同時に動けるサブエージェントは20個です。21個目はConcurrent subagent limit reachedで失敗し、エラーはClaudeに再試行しないよう伝えます。上限はCLAUDE_CODE_MAX_CONCURRENT_SUBAGENTSで上げることも下げることもできます。サブエージェントは自分のサブエージェントを起動でき、メインの会話から3階層下まで重ねられます。1つのセッションでの総数に上限はありません。

方法1：普通の言葉で頼む

いちばん簡単なfan outは1文で済みます。Anthropicのドキュメントにある例です：

Research the authentication, database, and API modules in parallel using separate subagents

各サブエージェントが自分の領域を調べ、そのあとClaudeが1つのまとめを書きます。ドキュメントは大事な条件も添えています：調査の筋道が互いに依存しないときに最もうまくいく、という条件です。データベースについての問いがauthについての答えを必要とするなら、それは3つのスライスではなく、1つの連続した手順です。

普通の言葉で頼むと、判断はClaudeに任されます。.claude/agents/にカスタムサブエージェントを定義しているなら、@で指名すればそのタスクで確実に動きます。これらのファイルの仕組みは、Claude Codeのサブエージェントのページで説明しています。

方法2：/batch、fan outのコマンドに最も近いもの

/batchはClaude Codeに同梱されたスキルです。指示を渡します：

/batch migrate src/ from JavaScript to TypeScript

コードベースを調べ、作業を5〜30の独立した単位に分割し、計画を示します。承認すると、単位ごとにバックグラウンドのサブエージェントを1つずつ起動し、それぞれを独立したgit worktreeで動かします。各サブエージェントは自分の単位を実装し、テストを実行し、変更を公開します。gitリポジトリが必要で、別のバージョン管理システムを使うなら、worktreeを作成するWorktreeCreateフックが必要です。

立ち止まるべきなのは計画の段階です。分割はそこで決まり、分割こそがすべてです。同じファイルに触れる2つの単位や、別の単位の出力を必要とする単位は、各サブエージェントがどれほど優秀でもきれいにマージできません。単位のリストは、同僚が書いた移行計画を読むときのように読んでください。

方法3：claude -pのループ

作業がファイルのリストで、呼び出しを1回ずつ管理したいときのために、Anthropicのベストプラクティスはループを紹介しています。まずClaudeにリストを書かせます（list all 2,000 Python files that need migrating and save the list to files.txt）。次に：

for file in $(cat files.txt); do
  claude -p "Migrate $file from Python 2 to Python 3. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" \
    --permission-mode dontAsk
done

この例には、真似する価値のある細部が3つあります。

• 答えを機械が読めます。 「Return OK or FAIL」とあるので、スクリプトは文章を読まずに失敗を数えられます。
• 権限は事前に決めておきます。 --allowedToolsは移行に必要なものだけを許可し、--permission-mode dontAskはそれ以外をすべて拒否します。その場にいない人を待ち続けることはありません。
• 最初は2〜3ファイルから始めます。 ドキュメントははっきり書いています：最初のファイルでうまくいかなかった点をもとにプロンプトを直し、それからリスト全体を実行します。

書かれたとおりなら、ループはファイルを1つずつ順に処理します。複数の呼び出しを同時に走らせるのは普通のシェルの作業ですが、呼び出しのたびに、あなたのマシンとクォータを使う完全なセッションが1つ動きます。複数のエージェントが同じ重いコマンドを同じ分に起動すると何が起きるかをこの記事で測定しましたが、ここでも同じことが言えます：並列の呼び出しは少ない数から始めましょう。

CIでは、ドキュメントは--bareを付けることを勧めています。フック、スキル、MCPサーバー、CLAUDE.mdを読み飛ばすので、どのマシンでも同じ実行になります。bareモードはサブスクリプションのログインを使いません：ANTHROPIC_API_KEYが必要です。

私たちが毎晩fan outする方法

これが、私たちが実際に動かしているfan outです。夜間のSEOチームは、新しい記事を英語とフランス語で手書きします。そのあと2つ目のエージェントが、Claude Codeのサブエージェントを使ってさらに17の言語に翻訳し、繁体字中国語は翻訳せずに簡体字中国語からスクリプトで生成します。2026年9月13日以降、11本の記事がこの流れを通り、それぞれ20個のファイルとして届いています。

スライス

6つのサブエージェントが、それぞれ3言語（最後だけ2言語）を担当します：スペイン語・ポルトガル語・イタリア語、ドイツ語・オランダ語・ポーランド語、ロシア語・ウクライナ語・トルコ語、日本語・韓国語・中国語、タイ語・ベトナム語・インドネシア語、アラビア語・ヒンディー語。ある言語が別の言語に依存することはなく、だからこそきれいなfan outになります。

各ブリーフには同じ5つのものが入っています。サブエージェントにはそれ以外何も見えないからです：

• 英語の原文と、トーンと製品用語の参考にするフランス語版
• 各言語について、その言語ですでにサイトに公開されている文。サブエージェントが新しい言葉を作らず、サイトがすでに使っている言葉を使うためです
• 厳格なルール：ブランド名と製品名はそのまま、コードは1バイトも変えない、emダッシュは使わない
• チェックスクリプトと、OKが出るまで実行し続けるという指示
• スライスの内外を問わず、気になったことは何でも報告するという依頼

チェックは起動前に書く

チェックはスクリプトであって、サブエージェントの意見ではありません。言語ごとに、ファイルを英語の原文と比べます：

• 同じslugと日付、タイトルはH1と同じ
• セクション、サブセクション、画像、リンク、表の行の数が同じで、本文のFAQの回答数がメタデータの質問数と同じ
• リンクは1バイト単位で同じ、コードの断片も1バイト単位で同じ
• ブランド名を数え、英語より少ないことは決してない
• 長さが言語ごとに調整した範囲に収まっていること。中国語は英語に必要な文字数のおよそ36%で同じことを言い、日本語はおよそ半分だからです
• その言語にアクセント記号があるなら、それが入っていること（ポーランド語、トルコ語、ベトナム語）

どのサブエージェントも、最後は「完了、すべてのチェックに合格」のような言葉で締めくくります。私たちが判断に使うのは1つだけ、同じスクリプトをメインのセッションがすべてのファイルに対して一度に再実行した結果です。

中央のチェックが見つけ、自己報告が見逃したもの

表の中で翻訳されたコード。 9月13日、サブエージェントの約半数が、表の中でコマンドと同じバッククォート内に続く言葉を翻訳しました。どれも自分が理解したとおりにブリーフに従っていました。修正したのはサブエージェントではなくブリーフです：コードの断片にはコマンドだけを入れ、そのあとの言葉はバッククォートの外に置きます。

私たち自身のチェックが間違っていました。 9月6日、置き換え前の古い文で調整した長さチェックが、17のサブエージェントのうち11に警告を出しました。11とも正しかったのです：新しい文は長くなるはずでした。修正済みのフランス語で調整し直すと、警告はゼロになりました。中央のチェックも間違えることがあります。それを見抜くには、良いとわかっている納品物でまず実行してみることです。

スライス間の一貫性。 10月15日、同じ方法で翻訳した新しい機能ページで、マージのチェックは90個のファイルで想定した文だけが変わったことを確認しました。ところが日本語、韓国語、中国語のサブエージェントはそれぞれ、「You may also like」に、その言語が隣のページですでに使っていたものとは違うタイトルを選んでいました。どの選択も正しい翻訳でした。どれもサイトとは一致していませんでした。スライスの内側からそれに気づけるサブエージェントはいません：気づけるのは、マージ後の結果を通して確認する工程だけです。

誤った単語は構造チェックをすべて通過します。 サイトのある言語では、かつてAIエージェントを自動車販売店と呼んでいて、それが何か月もオンラインに残っていました。長さも句読点も同じで、ブランド名もある：どのカウントも緑でした。それを捕まえられる唯一のものは、既知の誤訳を名指しで並べたリストです。このリストはすべてのデプロイをブロックし、新しい誤訳を見つけるたびに1行ずつ増えていきます。

スライスの外についての報告。 10月15日、トルコ語を担当していたサブエージェントが、サイトの既存の97の文で「agent」が「ajans」、つまり代理店と書かれていると報告しました。ブリーフで禁じられていたので、そのサブエージェントは手を加えませんでした。私たちはチケットを作成し、修正は翌日に公開されました。何をしたかだけでなく何を見たかをサブエージェントに尋ねるのは、手間が少なく、見返りがあります。

マージは1か所で行う

サブエージェントはリポジトリに直接書き込みません。それぞれが自分のファイルを返し、スクリプトがそれらをマージしてから、結果を前のバージョンと文単位で比べます：変わってよいのは依頼した文だけです。そのあと、リポジトリのチェックとサイトのビルドが、マージ後の結果に対して1回だけ実行されます。サブエージェントごとにビルドを走らせると時間がかかるうえ、決して公開されない中途半端なマージ状態をテストすることになります。

fan outすべきでないとき

• スライスが互いに依存している。 スライスBがスライスAの出力を必要とするなら、順番に実行します。
• 作業が小さい。 各サブエージェントは白紙から始まり、必要なものを読み直します。10分のタスクでは、始め直すコストが節約分を上回ります。
• チェックを書けない。 全部を自分で読まずに良いスライスと悪いスライスを見分ける方法がないなら、時間はマージに消えていきます。
• クォータに余裕がない。 各サブエージェントは自分のトークンを使います。fan outで得られるのは時間と整理されたメインのコンテキストで、請求額の削減ではありません。

AgentsRoomの位置づけ

サブエージェントは1つのClaude Codeセッションの中で動きます。見えるのは結果だけで作業そのものは見えず、途中で1つだけ軌道修正することもできません。各スライスを、個別に見守り、返答し、レビューできるエージェントにしたいなら、代わりに別々のセッションを動かしましょう：チケットごとに専用のgit worktreeを使い、スライス同士が作業を受け渡すときはAgent Teamsを使います。チームのステップにはチェックコマンドを持たせることができ、実行を先に進めるかどうかを決めるのは、エージェント自身の主張ではなくそのコマンドの終了コードです。上と同じルールを、ランナーが強制するわけです。Claude Code、Codex、そしてAgentsRoomが対応するその他のエージェントCLIで動きます。

サブエージェントとAgent Teamsのどちらにするかまだ迷っているなら、この比較でそれぞれの用途を説明しています。