従業員120名規模のBtoB SaaSを開発するプロダクトチームが、約500ファイルに散らばった内製の fetch() 呼び出しを新しい HttpClient ラッパーへ移行する大規模リファクタに取り組んだ。本記事では、Claude Code v2.1.172 で追加された階層subagent（最大5段の入れ子）と、Week 22 に research preview として公開された動的ワークフロー（dynamic workflows）を組み合わせ、移行作業を「設計・分割・実装・検証」の各段に並列分割した実装の全貌を、公式ドキュメントで裏取りした仕様つきで紹介する。
結論：この記事で分かること
結論から言うと、大規模な機械的移行は「1本の会話で全部やる」より「階層化したsubagentと動的ワークフローに分割して投げる」方が、コンテキスト破綻を起こさずに回せる。これは新機能の宣伝ではなく、500ファイル級のリファクタで実際にコンテキストが溢れて手戻りした反省から行き着いた構成だ。
- 要点1：subagentはv2.1.172から自分のsubagentを生成でき、入れ子は最大5段まで（深さ5のsubagentはAgentツールを受け取らず、それ以上は生成できない。上限は固定で変更不可）。
- 要点2：動的ワークフローはClaudeが書くJavaScriptのオーケストレーションスクリプトで、バックグラウンドで多数のsubagentを動かす。1ランあたり同時最大16エージェント・累計最大1,000エージェントという明確な上限がある。
- 要点3：移行のような「数が多くて1会話では捌けない」タスクこそ、両者を縦（階層subagent）と横（ワークフローの並列）に組み合わせる対象になる。
対象読者：Claude Codeで実装・移行・大規模リファクタを回す開発者・エンジニア・テックリード。今日やること：自分のリポジトリで「機械的だが量が多い変更」を1つ洗い出し、本記事の分割パターンに当てはめてみる。
導入前の状況：500ファイルの fetch() 移行が1会話で詰まった
このチームのコードベースには、数年分のフロントエンド・BFF（Backend for Frontend）にまたがって素の fetch() 呼び出しが約500か所散らばっていた。リトライ・タイムアウト・認証ヘッダ付与・エラー整形を内製の HttpClient ラッパーへ寄せたい、というのが移行のゴールだ。
最初は1つのClaude Codeセッションで「全ファイルを直して」と投げた。だが数十ファイルを読み込んだ時点で、差分・テスト出力・grep結果がメインの会話を埋め尽くし、後半のファイルでラッパーの引数順を取り違える回帰が出た。これは公式ドキュメントが subagent の利点として挙げる「探索や検証の verbose な出力をメイン会話の外に出す」という設計思想の裏返しで、大量の中間出力を1つのコンテキストに溜め込むと品質が落ちるという素直な現象だった。
Claude Code の役割：縦の階層subagentと横の動的ワークフロー
そこで構成を2軸に分けた。縦方向（階層subagent）でレビューと検証を1段深く委譲し、横方向（動的ワークフロー）で多数のファイルを一気に並列処理する。具体的な役割分担は以下のとおり。
- 移行スコープの棚卸し — メイン会話から探索用subagentを1段下ろし、対象
fetch()をモジュール別に分類。grep結果という大量出力はsubagentのコンテキストに留め、メインには分類サマリだけ返す。 - 動的ワークフローの起案 — 「
create a workflow that migrates every internal fetch() call to the new HttpClient wrapper」のように依頼すると、Claudeが移行ループを記述したJavaScriptスクリプトを書き、ランタイムがバックグラウンドで実行する。 - ファイル単位の並列実装 — ワークフローがファイル群を複数のsubagentにファンアウト。ワークフローが生成するsubagentは常に
acceptEditsモードで動き、呼び出し側のツール許可リストを継承する。 - 入れ子レビュー（5段の活用箇所） — レビュー担当のsubagentが、指摘ごとに検証担当のsubagentをさらに1段生成する（公式が例示する「reviewer subagent that dispatches a verifier per finding」のパターン）。中間出力はメイン会話に届かず、トップのsubagentの要約だけが返る。
- 横断的な相互チェック — 動的ワークフローは「独立したエージェント同士に互いの指摘を敵対的にレビューさせる」反復品質パターンを組み込める。移行の取りこぼし・誤置換を、単一パスより信頼できる形で潰す。
階層subagentの正確な仕様（v2.1.172・公式確認済み）
ここは創作で書くと事故るので、code.claude.com の公式記述に1対1で合わせる。確認できた事実だけを並べる。
- 入れ子の解禁バージョン：v2.1.172 から「a subagent can spawn its own subagents」。
- 深さの上限：subagentチェーンは5段まで。深さ5のsubagentはAgentツールを受け取らず、それ以上生成できない。上限は固定で設定変更できない。
- 可視化：プロンプト下のsubagentパネルがツリー全体を表示し、各行に子孫数
(+N)とmainまでのパスが付く。/agentsの Running タブでは実行中subagentがフラットに並ぶ。 - 生成可否の制御：subagent定義の
toolsにAgentを入れると入れ子生成が有効。生成させたくない場合はtoolsからAgentを外すかdisallowedToolsに追加する。
subagent自体はYAMLフロントマターで定義する。最小例は次の形だ。
---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.必須は name と description のみ。レビュー担当に入れ子生成をさせたいなら、上の tools に Agent を足す。逆に「このsubagentは絶対にこれ以上分岐させない」と決めたい末端の実装worker には Agent を渡さない、という設計判断が効く。
動的ワークフローの正確な仕様（research preview・公式確認済み）
動的ワークフローは Week 22（5月25〜29日）に research preview として登場した機能で、Claude Code v2.1.154 以降が必要。公式が明記する性質と上限は以下のとおり。
- 実体：ワークフローは「a JavaScript script that orchestrates subagents at scale」。Claudeがタスク向けにスクリプトを書き、ランタイムがバックグラウンドで実行する間もセッションは応答可能なまま。
- 並列の上限：1ランあたり同時最大16エージェント（CPUコアが少ない環境ではより少なく）、累計最大1,000エージェント。暴走ループを防ぐための固定上限。
- 起動方法：プロンプトに
ultracodeキーワードを含めるか、「use a workflow」と自然文で頼む。セッション全体で常時ワークフロー化したい場合は/effort ultracode。 - 管理：
/workflowsで実行中・完了済みランを一覧し、進捗ビューでフェーズ別のエージェント数・トークン・経過時間を確認。pで一時停止/再開、xで停止、sでスクリプトをコマンドとして保存できる。 - 保存と再利用：気に入ったランは
.claude/workflows/（プロジェクト共有）か~/.claude/workflows/（個人用）に保存すると、以後/<name>で再実行できる。 - 無効化：組織で止めたいときは managed settings の
"disableWorkflows": true、または環境変数CLAUDE_CODE_DISABLE_WORKFLOWS=1。
subagent・skill・agent teams・workflows の違いは「誰がプランを保持するか」だ。公式の整理に従えば、subagentはClaudeがターンごとに次を決めるのに対し、ワークフローはループ・分岐・中間結果をスクリプト自身が保持する。だからメインのコンテキストには最終回答だけが残る。これがまさに、冒頭で詰まった「中間出力でコンテキストが溢れる」問題への回答になっている。
実装スタック
| レイヤー | 内容 |
|---|---|
| ランタイム | Claude Code v2.1.172 以降（階層subagent）／動的ワークフローは v2.1.154 以降が必要 |
| 縦方向 | 探索用subagent（grep・分類）→ 実装worker → レビュー → 検証（最大5段の範囲内で2〜3段に留める） |
| 横方向 | 動的ワークフロー（JavaScriptスクリプト）でファイル群を最大16並列・累計1,000上限内でファンアウト |
| 権限 | ワークフロー内のsubagentは acceptEdits。事前にシェル/Webフェッチ/MCPの許可リストを整備して mid-run のプロンプトを回避 |
| 検証 | 各ファイルにユニットテスト＋型チェック。ワークフローの相互レビューで誤置換を二重に確認 |
段階的導入のロードマップ（3-Phase）
Phase 1（1〜2週間）：1ディレクトリだけを対象に動的ワークフローを試走。/workflows でトークン消費を見ながら、移行ルール（ラッパーの引数順・エラー整形）が正しく適用されるかを確認する。公式も「大きなタスクは小さなスライスで先に試せ」と推奨している。
Phase 2（3〜4週間）：階層subagentでレビュー段を1段深くし、指摘ごとに検証subagentを入れ子で生成。ここで初めて全モジュールへ横展開し、500ファイル規模をワークフローのファンアウトで一気に処理する。
Phase 3（5〜8週間）：うまく回ったワークフローのスクリプトを .claude/workflows/ に保存し、「ブランチごとに走らせる移行レビュー」として定型化。以後の似た移行（別のラッパー化・命名統一）を /<name> で再利用する。
定量結果
※以下はこの開発チームの社内計測値であり、環境依存の参考値である。
| 指標 | 導入前（単一会話） | 導入後（階層subagent＋動的WF） | 変化 |
|---|---|---|---|
| 1会話で安全に処理できたファイル数 | 約30ファイルでコンテキスト破綻 | ワークフロー1ランで数百ファイル | 会話分割の手間を解消 |
| 引数取り違えによる回帰 | 後半ファイルで複数発生 | 入れ子の検証段でリリース前に検出 | 手戻り削減 |
| レビュー中間出力のメイン会話流入 | 差分・ログでほぼ満杯 | トップsubagentの要約のみ | コンテキスト節約 |
数値の主張はあくまで内製の比較メモであって、ベンチマークではない。重要なのは「件数が多い機械的変更を、縦の階層と横の並列に分けると破綻しにくい」という構造の方だ。
失敗パターンと対策
- ❌ 深さ5を当てにして無限に分岐させる → ⭕ 移行のような単純タスクは実際には2〜3段で十分。深さ5は「reviewer→verifier」のような明確に分かれる検証チェーンに限定する。深さ5のsubagentはAgentツールを持たない点も忘れない。
- ❌ 許可リストを整備せずワークフローを長時間走らせる → ⭕ ワークフロー内subagentは
acceptEditsでファイル編集は自動承認されるが、許可外のシェル・Webフェッチ・MCPは mid-run でプロンプトが出て止まる。走らせる前に必要なコマンドを許可リストへ。 - ❌ いきなり全リポジトリにワークフローを投げる → ⭕ まず1ディレクトリで試走し、
/workflowsのトークン表示でコストを見てから全体へ。累計1,000エージェント上限は暴走を止めるが、コストは自分で管理する。 - ❌ セッションを抜けてワークフローの再開を期待する → ⭕ 再開（resume）は同一セッション内のみ。Claude Codeを終了すると次セッションではワークフローは最初からになる。長尺ランはセッションを維持する。
適用余地のある業界・規模
この構成が効くのは「機械的だが量が多い変更」を抱える開発組織全般だ。具体的には、APIクライアントのラッパー化・ロギング統一・型付け移行・依存ライブラリのメジャーアップデート対応など。SaaS・IT企業はもちろん、内製エンジニアを抱える製造業・金融機関の基幹システム保守でも、同じ「縦に階層・横に並列」の分割が当てはまる。
関連記事
Claude Codeのsubagent並列開発の基礎はClaude Codeサブエージェント並列開発入門を、レガシーコードの移行・大規模リファクタの全体像はClaude Codeでレガシーコード移行・大規模リファクタを、安全なDB移行の進め方はDBマイグレーションをClaude Codeで安全に進める実践ガイドを併せて読むと、本記事の「分割設計」がより具体的に掴める。
まとめと次のアクション
大規模リファクタ・移行は、ツールの新機能でゼロから魔法のように片づくわけではない。だが「単一会話のコンテキストに全部を詰め込まない」という1点を、階層subagent（縦）と動的ワークフロー（横）で構造的に解決できるようになったのは大きい。
- 今日：自分のリポジトリで「機械的だが量が多い変更」を1つ選び、1ディレクトリだけ動的ワークフローで試走する。
- 今週：レビュー段を階層subagentで1段深くし、指摘ごとの検証を入れ子化する。深さは2〜3段に抑える。
- 今月：回ったワークフローを
.claude/workflows/に保存し、定例の移行レビューとして再利用する。
自社の大規模リファクタや移行をClaude Codeでどう分割すべきか迷ったら、UravationのClaude Code個別指導・導入支援で実リポジトリを題材に伴走できる。次回は「動的ワークフローのスクリプトを読み解き、独自の品質パターンを差し込む」実装編を予定している。
出典（一次情報）
- Claude Code 公式「Week 24 · June 8–12, 2026」（subagentの入れ子・5段上限・v2.1.172）：https://code.claude.com/docs/en/whats-new/2026-w24
- Claude Code 公式「Week 22 · May 25–29, 2026」（動的ワークフロー research preview）：https://code.claude.com/docs/en/whats-new/2026-w22
- Claude Code 公式ドキュメント「Create custom subagents」（Spawn nested subagents・フロントマター・depth fixed）：https://code.claude.com/docs/en/sub-agents
- Claude Code 公式ドキュメント「Dynamic workflows」（JavaScript script・16同時/1,000累計・/workflows・ultracode・disableWorkflows）：https://code.claude.com/docs/en/workflows
著者プロフィール
佐藤傑（さとう・すぐる）。株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。100社以上の企業向けAI研修・導入支援に携わる。著書『AIエージェント仕事術』（SBクリエイティブ）。SoftBank IT連載7回執筆。
