エージェントをグラフとして設計する｜Claude Code動的ワークフローで多段処理を並列化する考え方

多段のAIエージェントを組むと、多くの人が同じ形に行き着く。「まず情報を集めさせて、その次に分析させて、その次に検証させて、最後に要約させる」——step1が終わってからstep2、それが終わってからstep3、という直線だ。素直で読みやすい。だが、この直線には代償がある。各段が前段の完了をひたすら待つため待ち時間が積み上がり、1体が全部の中間結果を抱えてコンテキストが膨らみ、途中の1段がこけると全体が止まる。

問題は、その仕事の本当の”形”が直線ではないことだ。情報収集を3つの角度から同時に走らせてよいなら、それは1本道ではなく扇形に開いた形をしている。検証が独立した複数の観点で並行できるなら、そこにも枝がある。仕事の形は、たいていの場合グラフだ。ノード（各ジョブ）とエッジ（ノード間を流れるデータ）でできた有向グラフである。直線は、そのグラフをたまたま一列に潰した特殊形にすぎない。

この「エージェント設計をグラフとして捉える」という見方を、Codez（@0xCodez）が2026年7月20日のXスレッド「Graph Engineering with Claude」で体系的に提示して話題になった。ただし「グラフエンジニアリング」は公式の機能名ではなく、あくまで設計のレンズだ。その土台になる実体は、Claude Codeの公式機能である動的ワークフロー（dynamic workflows）とサブエージェントである。本記事は、このレンズを使って「自分のエージェント設計をどうグラフとして組み直すか」の判断基準を、公式ドキュメントの仕組みに紐づけて整理する。

Claude Code全体の使い方・設定・アーキテクチャは Claude Code｜2026年版・インストールからCLAUDE.md・Hooks・本番運用までの実装手引き にまとめている。本記事はその中の「多段処理をどう設計するか」に絞った応用編にあたる。

1. なぜ多段エージェントは「直線」で詰まるのか

直線チェーンが生まれるのは、私たちが手順書を書くときの自然な語り口だからだ。「Aして、それからBして、それからC」——この「それから（and then）」を、そのままエージェントの依存関係に写してしまう。だが「それから」は本来2つの意味を混ぜている。ひとつは因果の依存（Bの入力はAの出力そのもの）、もうひとつは単に書いた順序（Aの話を先に書いただけで、BはAの結果を読まない）。前者は本物のエッジだが、後者はエッジではない。直線化の罪は、この後者まで直列にしてしまうことにある。

直線には3つのコストがある。第一にレイテンシ。各段が前段の完了を待つので、総所要時間は各段の所要時間の単純な和になる。3つの独立した検索を直列に回せば、3回分の待ち時間が積み上がる。第二にコンテキストの肥大。1体のエージェントが全段の中間結果を自分の文脈に抱え続けると、後半になるほど文脈が飽和し、判断の質が落ちる。第三に脆さ。1本道は途中のどこか1段が失敗しただけで、その先が全部止まる。冗長性がない。

グラフとして設計すると、この3つが同時に緩む。独立ノードを並列化すればレイテンシは「最も遅い1本の経路」に縮む。中間結果をオーケストレーター（Claude）ではなくスクリプトの変数に置けば文脈は膨らまない。枝が複数あれば、1本がこけても他の枝は生き残る。つまり「グラフで設計する」とは、絵を綺麗にすることではなく、待ち時間・文脈・堅牢性を同時に設計変数として扱うことだ。

Claude Codeの動的ワークフローは、この設計をそのままコードにできる場を提供する。あなたがタスクを記述すると、Claudeがオーケストレーションのスクリプト（JavaScript）を書き、専用ランタイムがバックグラウンドで実行する。スクリプトが走る間もセッションは応答可能なままだ。重要なのは、このスクリプトこそが「グラフの絵を、実行できる形にしたもの」だという点である。ノードはagent()呼び出し、エッジはあるagent()の戻り値を次のagent()の入力に渡す線、並列の枝はparallel()やpipeline()——グラフの各要素に、対応するコードの部品がある。

2. 仕事の”形”はグラフだ——ノード＝ジョブ、エッジ＝データ契約

グラフとして設計する第一歩は、2つのプリミティブをはっきり分けることだ。ノードは1つのジョブ（1体のサブエージェントが担う仕事の単位）。エッジはノード間を流れるデータ（あるノードの出力が、別のノードの入力になる関係）である。コードで言えば、ノードは1回のagent()呼び出し、エッジは「戻り値を次の呼び出しに渡す」という一本の線だ。図にすると、箱（ノード）と、その間を結ぶラベル付きの矢印（エッジ）になる。

矢印そのものより、矢印に載る「何が流れるか」が設計の本体だ。エッジは単なる順序ではなく、上流が下流に渡すデータの契約——だからこそ、次に見るように「型」を与えられる。

この分け方が効くのは、設計判断が「ノードの切り方」と「エッジの引き方」という2つの独立した問いに分解されるからだ。ノードの切り方は「この仕事を1体に任せるか、複数に割るか」。エッジの引き方は「どのノードの出力が、どのノードに必要か」。そして最も重要な問いがここから出てくる——「この”and then”は本当にエッジか？」。次のステップが前のステップの出力を実際に読むなら、それはエッジで、順序に意味がある。読まないなら、それはエッジではなく、ただ時間順に並べて書いただけだ。エッジでないなら、並列にできる。この一問を各「それから」に当てるだけで、直線の多くは自然にほどけていく。

具体的に考えてみる。「①READMEを読む→②Issue一覧を読む→③テストコードを読む→④全体を要約する」という4段を直線で書いたとする。ここに問いを当てる。②は①の出力（READMEの内容）を読むか？——読まない。③は②を読むか？——読まない。①②③はどれも「対象を独立に読む」だけで、互いの出力に依存していない。つまり①→②、②→③はエッジではなく、ただ書いた順序だ。本物のエッジは①②③のそれぞれ→④（要約は3つの読解結果を全部使う）だけ。すると正しい形は「①②③を並列に扇形展開し、④で集約する」——直線ではなくdiamondになる。4段の待ち時間が積み上がっていた設計が、「最も遅い読解1本＋要約」の待ち時間に縮む。エッジと順序を見分けるだけで、形とレイテンシが同時に決まるのが分かる。

エッジには”型”がある——データ契約としてのschema

エッジは単なる矢印ではない。上流ノードが下流ノードに「どんな形のデータを渡すか」という契約でもある。人間同士の引き継ぎでも「箇条書きで欲しい」「ファイル名だけくれ」と形を決めるのと同じで、ノード間のエッジにも型を決められると設計が安定する。

動的ワークフローでは、agent()にJSON schemaを渡すと、そのサブエージェントは構造化出力ツールの呼び出しを強制され、返り値が検証される。検証はモデルの外側、ツール呼び出しの層で行われ、スキーマに合わなければモデルにリトライさせる。つまりエッジの型がコードレベルで保証される。「次のノードが期待する形と違うデータが流れてくる」という多段処理で最も厄介な事故を、境界で止められるわけだ。schemaを付けたエッジは、ただの矢印から「破れない契約」に変わる。

なぜ文脈が膨らまないのか——トークンの話を正確に

「グラフにすると節約になる」という言い方は、半分正しく半分間違いだ。正確に言い分ける必要がある。

正しい半分：オーケストレーション——ループ・分岐・中間結果の保持——は、Claudeが書いた素のJavaScriptをランタイムが実行する。だからエッジ上を流れる中間結果はスクリプトの変数に載るのであって、オーケストレーター（Claude）のコンテキストには積み上がらない。公式ドキュメントの表現では「スクリプトがループ・分岐・中間結果を持つので、Claudeのコンテキストには最終回答だけが残る」。数百ノード分の探索をしても、束ねる側の文脈はクリーンに保たれる。これが直線チェーンで1体が全部抱える設計との決定的な違いだ。

間違いの半分：だからといって「安い」わけではない。各ノード（サブエージェント）はトークンを消費する。公式のコスト説明は「1回の実行は、同じタスクを会話で進めるより明確に多くのトークンを消費しうる」と明言している。節約されるのは”制御フローと中間結果を運ぶ分”であって、”仕事そのものの分”ではない。グラフ化は文脈の飽和を防ぎ品質を保つための設計であって、コスト削減策ではない——ここを取り違えると、大きなグラフを気軽に回して請求に驚くことになる。

3. 直線は”退化したグラフ”——pipeline と parallel でレイテンシを設計する

直線チェーンをグラフ理論の言葉で言えば「すべてのノードが一列に並んだパス（path）」だ。枝分かれがゼロ、つまり並列の余地を自分でゼロにした退化形である。ここから設計を回復する最初のレバーが、バリアの置き方——すなわちparallel()とpipeline()の使い分けだ。

parallel()は、関数（thunk）の配列を受け取り、それらを並列に走らせて全部の完了を待ってから結果の配列を返す。これはバリアだ。どれか1つが例外を投げても呼び出し自体は失敗せず、その要素はnullに解決されるので、使う前に.filter(Boolean)で落とす。バリアが正しいのは、次の段が「全結果が揃っていること」を本当に必要とするとき——全件を横断して重複排除する、全体を集計する、0件なら以降を丸ごと省く早期脱出をする、といった場合だけだ。

pipeline()は、各アイテムを全ステージに独立して通す。ステージ間にバリアが無いのが核心で、アイテムAがステージ3にいる間、アイテムBはまだステージ1でよい。だから壁時計時間は「各ステージの最遅を足した和」ではなく「最も遅い1本のチェーン」に縮む。5つのファインダーが走り、最速と最遅で3倍差があるとき、バリアを置くと速い4つは最遅を待って遊ぶ。pipeline()ならその待ちが消える。多段処理を最速化する主要レバーは、実はこの「バリアを不用意に置かない」ことに尽きる。

判断のコツはシンプルだ。「途中で全部を一度に見る必要があるか？」——無ければpipeline()。フラット化やフィルタのような加工が挟まるだけなら、それはバリアの理由にならない（加工はステージの中でやればよい）。バリアを1つ置くたびに、そのグラフには「最速ノードが最遅ノードを待つ」区切りが1つ増える。だから既定はpipeline()で、parallel()は「全部が揃わないと次に進めない」と言い切れる箇所にだけ置く。

4. トポロジの型——diamond・router・verifier

グラフには、繰り返し現れる「型（パターン）」がある。型を知っておくと、目の前の仕事を「これはdiamondだ」「ここはrouterだ」と当てはめて素早く設計できる。ここでは3つの基本型を、Claude Codeの機能に紐づけて見る。

diamond——扇形展開して、畳む（fan-out → reduce → synthesize）

最も使う型がdiamond（ひし形）だ。1つの入力をN個のノードに扇形展開（fan-out）し、それぞれの結果を1つの集約ノードに集めて（reduce）、統合する（synthesize）。入口と出口が1点、中間が広がる——描くとひし形になる。

典型例は「変更ファイルごとにレビュアーを立て、全レビューを1体に渡して重複排除し、1本のランク付きサマリに畳む」。ファンアウトは並列、集約は全結果を要するのでバリア。この「広げて→畳む」は、コードベース監査・多観点リサーチ・複数案の比較検討など、探索の幅が要る仕事のほぼ全部に現れる。

このdiamondを、PRレビューを例に手順で追ってみる。まず変更ファイルの一覧を返す1ノードを置く（ここは機械的なので下位モデルでよい）。次にその一覧をpipeline()に渡し、ファイルごとに1体のレビュアーノードを走らせる——各レビュアーは自分の担当ファイルだけを見て、指摘を構造化出力（schemaで型付け）で返す。ここまでがファンアウトだ。最後に、全レビュー結果を1体の集約ノードに渡し、重複を排除してランク付けした1本のサマリに畳む。集約は全ファイルのレビューが出そろって初めて意味を持つので、ここだけがバリアになる。公式ドキュメントも「PRの変更ファイルを1ファイル1レビュアーで見て、指摘を1本のランク付きサマリに統合する」形をワークフローの代表例として挙げている。抽象的なdiamondが、そのまま日々のレビューフローに対応しているわけだ。ファンアウトの各枝は独立なので、遅いファイルのレビューが1本あっても、他のファイルのレビューはそれを待たずに集約待ち行列へ進める。

router——分類して、分岐する

router（ルーター）は、入口の1ノードが入力を分類し、その結果に応じて別々の下流に振り分ける型だ。「この課題はバグか、機能要望か、質問か」をまず判定し、種類ごとに違う処理へ流す。全部を同じパイプに通すより、各種類に最適なノードへ送れる。

ここは正確さが要る箇所だ。routerは「エージェントが自分で別のエージェントを次々と生む」自己増殖ではない。動的ワークフローでは、分類ノードの構造化出力（schemaで型付けした戻り値）を、スクリプトがifで読んで分岐先を選ぶ——ルーティングの判断はコード側にある。ネストは1段までで、あるワークフローの中でさらに別のワークフローを呼ぶと例外になる。つまり「賢い分類ノード＋素直な分岐コード」の組み合わせがrouterの実体で、制御は常にスクリプトが握る。

verifier——敵対的に検証する（実例：/deep-research）

グラフに信頼性を足す型がverifier（検証ノード）だ。verifierの唯一の仕事は、あるノードの結論を反証しようと試みること。多数が反証できれば、その結論を落とす。単発で「それらしい」出力を鵜呑みにせず、いったん疑う工程を挟む。verifierには実務でよく使う3つのパターンがある。

・敵対的検証（adversarial verify）：同じfindingに独立したスケプティックをN体立て、それぞれに反証を試みさせる。確信が持てなければ棄却側に倒し、過半が反証したら落とす
・観点分散検証（perspective-diverse verify）：失敗の仕方が違う観点（正しさ・再現性・セキュリティ…）を1体ずつ割り当てる。冗長な多数決では拾えない失敗モードを、観点の多様性が拾う
・審判パネル（judge panel）：複数の独立した案を生成し、並列の審判ノードが採点、勝者を軸に統合する（次点の良い部分も接ぎ木する）。検証というより「複数案から最良を選ぶ」場面で効く

findingが1通りの壊れ方しかしないなら同一検証（敵対的）でよいが、複数の壊れ方があるなら観点を分ける。下図は観点分散検証を多数決でまとめる形だ。

この型の出荷済みの実例が、Claude Code組み込みの/deep-researchワークフローだ。動きを分解すると、まさに「fan-out → verifier → reduce」になっている——複数の角度からWeb検索を扇形展開し、見つけたソースを取得して相互検証（各主張に投票）し、相互検証を生き残らなかった主張はフィルタして、出典付きの1本のレポートに畳む。抽象的なdiamondとverifierを、実際に使える1コマンドとして体験できる。

なお公式によれば、レート制限やAPIエラーで検証できなかった主張は、v2.1.196以降「反証された」ではなく「未検証」として扱われる——検証ノードが動けなかったことと、反証されたことを区別する精度改善だ。

5. cycle・model tiering・worktree——収束・コスト・安全性をノードに割り当てる

diamondやrouterは入口から出口へ一方向に進む有向非巡回グラフ（DAG）だ。だが現実には、DAGでは表せない設計も要る。ここでは残る3つの設計軸——サイクル（収束）・モデル階層化（コスト）・worktree隔離（安全性）——を見る。

cycle——「尽きるまで」回して収束させる

出力のサイズが事前に分からない仕事がある。「このリポジトリのバグを全部見つけて」——何個あるかは、探してみないと分からない。こうした仕事をdiamond（固定回数のfan-out）で設計すると、多すぎれば取りこぼし、少なすぎれば空振りする。ここで要るのがcycle（巡回）、つまりループだ。

収束条件の設計が肝になる。代表的なのは3つ。loop-until-dry（K回連続で新規ゼロになったら停止）、loop-until-count（目標数に達したら停止）、loop-until-budget（トークン予算を使い切ったら停止）。コードとしては単純なwhile文だが、「いつ止めるか」を明示的に設計するのがサイクルの本質だ。単純な「N回回す」では、探索の尻尾（最後の数個）を取りこぼす。下図はloop-until-dryの収束イメージである。

具体例として、公式ドキュメントは「不安定なテスト（flaky test）を見つける」ワークフローを挙げている——テストスイートを繰り返し実行し、断続的に落ちるテストを記録し、2ラウンド連続で新規の発見がゼロになったら止める。これがloop-until-dryそのものだ。flakyなテストは「1回実行して落ちたもの」ではなく「たまに落ちるもの」なので、固定回数では取りこぼす。「新規が尽きるまで」という収束条件があって初めて、尻尾まで拾える。ここで注意したいのは、重複排除の基準を「これまで見た全部（seen集合）」に取ること。「確定済みだけ」と突き合わせると、検証で棄却された発見が毎ラウンド蘇ってループが収束しなくなる。サイクルの設計では、この「何と照合して新規判定するか」がバグの温床になりやすい。

model tiering——ノードごとに難易度でモデルを割り当てる

エッジ（データ契約）が同じでも、ノードごとに難易度は違う。ファイル一覧を返すだけの機械的なノードと、複数の結論を突き合わせて最終判定する最難関のノードを、同じ最強モデルで回すのはコストの無駄だ。動的ワークフローでは、agent()のmodelオプションでノード単位にモデルを割り当てられる。既定ではセッションのモデルを継承するが、機械的な段は下位モデル、判定・統合の段は上位モデル、と段ごとに変えられる。

これはreasoning effort（low〜xhigh）でも同様で、安価な機械的ステージは低effort、最難関の検証・審判ステージだけ高effortに寄せる。グラフの各ノードに「知性の予算」を配分する感覚だ。下図のように、同じグラフでもノードの役割ごとにモデル層を割り当てると、品質を落とさずコストを抑えられる。

worktree隔離——並列ノードがファイルを書くとき

並列ノードがファイルを書き換えるとき、同じ作業ツリーを共有していると編集が衝突する。ノードAが書いた行を、ノードBが上書きしてしまう。ここで使うのがworktree隔離だ。isolation: 'worktree'を指定すると、そのノードは新しいgit worktree（隔離コピー）で走り、他ノードの編集とぶつからない。大規模マイグレーションや並列リファクタで、各ファイルを独立コピーで変換するときに要る。

ただしworktreeにはセットアップのコスト（作成時間とディスク）がある。だから常時使うものではなく、「並列ノードが実際に同じファイルへ書き込み、放っておくと衝突する」ときだけに絞る。読むだけのノードや、書き込みが競合しないノードには不要だ。安全性という設計軸を、ノード単位でオン・オフする——これもグラフ設計の一部である。並列ワークツリーを含むClaude Code全般の使いこなしは Claude Codeベストプラクティス2026｜Boris直伝25 Tips・並列ワークツリー・–bare最適化 が詳しい。

6. 自分のエージェント設計をグラフとして見直すチェックリスト

ここまでの型を、実際の設計に落とすための問いにまとめる。既存の（あるいは頭の中の）多段エージェントを、次の6問に通してみてほしい。直線で組んでいた部分の多くが、グラフとして組み直せるはずだ。

そして、設計したグラフを実際に動かす方法は薄く押さえておけば足りる。プロンプトにultracodeと書く、あるいは「use a workflow（ワークフローで）」と自分の言葉で頼むと、Claudeがその場でスクリプトを書く。/effort ultracodeにすると、実質的なタスクごとにClaudeが自動でワークフローを組む。組み込みの/deep-researchはすぐ試せる出来合いのグラフだ。気に入った実行は/workflowsで選んでsを押すと.claude/workflows/（リポジトリ共有）か~/.claude/workflows/（自分専用）に保存でき、以後/<name>で同じグラフを再実行できる。起動方法・承認フロー・実行モデルそのものの詳細は Claude Code Dynamic Workflows解説：1,000サブエージェント並列とOpus 4.8 に譲る。本記事はあくまで「どんなグラフを描くか」の設計に焦点を絞った。

前提だけ確認しておく。動的ワークフローはClaude Code v2.1.154以降で、各有料プランと主要クラウドで動く。同時実行は最大16エージェント、1回の実行で合計1,000エージェントが上限だ。1,000は暴走ループを防ぐ安全弁であり、目標値ではない。まずは小さなグラフ（1ディレクトリ、狭い問い）で回してコストと挙動を確かめ、形が固まってから幅を広げるのが堅実な入り方になる。

まとめ

「グラフエンジニアリング」という言葉自体は設計のレンズにすぎない。だが、このレンズを一度手にすると、多段エージェントの見え方が変わる。「まずこれ、それからこれ」と直線で書きかけたその瞬間に、「この”それから”は本当にエッジか？」と立ち止まれるようになる。並列にできる枝、畳める集約、疑うべき結論、尽きるまで回すべき探索——仕事の本当の形が、少しずつ図として見えてくる。Claude Codeの動的ワークフローは、その図を実行できるコードに変える場だ。まずは/deep-researchで1枚のグラフを体感し、自分の仕事の形を描き直すところから始めたい。プロンプトを書く人は「問い」を投げる。設計する人は「グラフ」を描く——多段エージェントの時代に効くのは、後者の視点だ。

参照ソース

• Orchestrate subagents at scale with dynamic workflows — Claude Code公式ドキュメント
• Create custom subagents — Claude Code公式ドキュメント
• Introducing dynamic workflows in Claude Code — Anthropic公式ブログ
• Codez（@0xCodez）「Graph Engineering with Claude: 14-Step roadmap from 0 to graph architect」X スレッド（2026-07-20・本記事の”グラフ”という枠組みの着想元／二次資料）
• Claude Graph Engineering Roadmap — YouMind（日本語まとめ）（同題材の日本語での見せ方を構成・図解の参考にした二次資料。機能・挙動の事実は公式ドキュメントを優先）