Claude Codeで始めるグラフエンジニアリング入門｜複数のエージェントを「点と線」で組み立てる方法

序章：1体のエージェントに全部やらせていませんか

前回の記事では、Claude Codeで「作業→確認→やり直し→終わったら止まる」を自動で回すループエンジニアリングを紹介しました。作る係と確認係を分け、1つの仕事を終わるまで確かめながら進める仕組みです。

ループに慣れると、次の壁にぶつかります。

50個のファイルを1つずつ順番に調べていて、終わるまで何時間もかかる
調査、修正、確認を1つの流れにまとめて頼むと、途中で何をしていたか分からなくなる
確認役が、作業役と同じ思い込みで「問題なし」と言ってしまう

これらを解決する考え方がグラフエンジニアリングです。

先に結論を示します。

グラフエンジニアリングとは、仕事を「点（ノード）」に分け、点どうしのつながりを「線（エッジ）」で設計すること。点はエージェントの作業や人間の承認などの作業単位、線は「この仕事の結果を、あの仕事が使う」「この承認が済むまで次へ進まない」といった依存関係を表す
ループは1つの仕事を良くし続けるモーター、グラフは仕事の進む道筋を決めるレール。どちらか一方ではなく、組み合わせて使う
いちばん大事なのは偽の矢印を見つけること。「AしてからB」と書いていても、BがAの結果を使わず、同じファイルの編集や承認待ちといった別の順番の理由もなければ、AとBは同時に進められる
Claude Codeでは、サブエージェントの並列実行で小さく試し、慣れたらdynamic workflowsで、1回の実行で数十〜数百のエージェントを使う規模へ広げられる
確認役は、作業役とは別の文脈で、実際の証拠を見て判定させる

Claude Codeの仕様は、2026年10月5日時点の公式ドキュメントで確認した内容です。記事中のプロンプト例は公式ドキュメントの例をもとに作成しました。2026年10月10日に、編集部で架空のTODO管理API（Node.js。src/routes/に5ファイル、認証漏れを2か所入れたもの）と認証要件の資料を用意し、Part 4の手順を記事どおりに試しました。各Stepの「試した結果」は、Windows 11、Claude Code v2.1.296、モデルはOpus 5.5、Proプラン、手動で確認するモード（claude --permission-mode defaultで起動）、ユーザー単位の設定やMCPを読み込まない起動オプションを付けた環境で確かめたものです。会話の記録は編集部で保存しています。

本記事は、Coding Agent連載の第3回です。第1回ではAIが働く作業場と権限を整える「ハーネスエンジニアリング」、第2回では作業と確認を繰り返す「ループエンジニアリング」を扱いました。

Part 1：グラフエンジニアリングとは何か

点と線で仕事を描く

グラフという言葉は、ここでは折れ線グラフではなく、点と線でできた図のことです。駅（点）と線路（線）でできた路線図を思い浮かべると分かりやすいでしょう。

要素	意味	例
ノード（点）	1つのことだけをする作業単位	「このファイルを調べる」エージェント、「結果をまとめる」エージェント、人間の承認
エッジ（線）	点と点の約束。何を、どんな形で渡すか、何を待つか	「調べた結果をJSONで渡す」「不合格なら差し戻す」「承認後に次へ進む」
状態	全体の進み具合の記録	どの点が終わり、どの点が失敗したか

資料作りでたとえるなら、執筆者とチェック担当がそれぞれ点です。「誤字を直してから渡す」「内容が薄ければ差し戻す」という取り決めが線、全員が見られる進捗表が状態にあたります。

ループとグラフの違い：モーターとレール

	ループエンジニアリング	グラフエンジニアリング
対象	作業・確認・やり直し・停止を繰り返す仕組み（複数の担当を含むこともある）	作業・確認・承認などのつながりと、その依存関係
たとえ	モーター（前に進める力）	レール（どこを通り、どこで待ち、どこで止まるか）
問い	どう確かめ、いつ止めるか	何を同時に進め、誰に何を渡し、どこで待つか

前回のループにも、作る係と確認係がいました。グラフエンジニアリングで考えるのは、担当の人数を増やすことそのものではありません。担当どうしに何を渡し、どこを並列にし、どこで待つかを設計することです。

使い分けの目安は単純です。仕事を繰り返し良くしたいなら、まずループを作る。仕事を分けて並列に進めたいときや、引き継ぎ・承認が必要な工程が出てきたら、グラフとして段取りを描く。強いエージェントには両方が必要です。

なぜ1つのループでは足りないことがあるのか

1つのループは、与えられた指標に向かって進みます。指標の選び方を誤ると、ループはその指標だけを追いかけます。

たとえば、問い合わせ対応のエージェントを「解決済みにした件数」だけで評価すると、本当に問題を解決するより、早く閉じる判断が増えるおそれがあります。指標そのものが目的になると、指標が本来の役に立たなくなる現象はグッドハートの法則と呼ばれます。

対策の第一は、指標や合格の条件そのものを見直すことです。そのうえで、作る担当と監査する担当を分け、異なる観点で確かめるつながりを設計する方法があります。この「担当どうしのつながり」を設計するのがグラフエンジニアリングです。

言葉の由来と、冷静な見方

サーバーワークスの解説記事では、開発者のPeter Steinberger氏による「ループからグラフへ移ったのではないか」という趣旨の投稿が、この言葉が話題になったきっかけとして紹介されています。本記事では、この紹介をもとに経緯を説明しています。

一方で、ノードとエッジで処理の流れを設計する考え方自体は、ワークフローエンジンなどで以前からあるものです。「新しい製品ではなく、複数の作業・チェック・判断をつなぐ考え方」という冷静な見方もあります。この記事では流行語としてではなく、AIエージェントの仕事を分けて、つなぎ、確かめるための考え方として扱います。

Part 2：「本物の矢印」と「偽の矢印」を見分ける

グラフエンジニアリングで最初に身に付けたいのが、この見分け方です。

私たちはつい、仕事を「AしてからB、それからC」と一列に並べて頼みます。しかし、その「してから」の中には、本当は順番が要らない偽の矢印が混じっています。最初に確かめる質問はこれです。

次の仕事は、前の仕事の結果を実際に使っているか？

使っていなければ、並列にできる候補です。ただし、結果を使わなくても順番が必要な場合があります。同じファイルを編集する、同じGitの操作をする、人間の承認を待つ、といった制約です。そこで、次の表で判断します。

確認すること	当てはまる場合	どうするか
前の結果を使うか	使う	本物の矢印。順番を守る
同じファイルの編集、Git操作、承認待ちなどがあるか	ある	結果を使わなくても順番が必要。作業場所を分けるか、順番を守る
前の結果への依存も、ほかの順番の理由もないか	どちらもない	偽の矢印。同時に進めてよい

例で確かめましょう。「src/routes/の20個のAPIファイルに認証漏れがないか調べて、最後に報告書にまとめて」という仕事です。調べるだけでファイルは変更しません。

偽の矢印だらけの一列：
ファイル1を調べる → ファイル2を調べる → … → ファイル20を調べる → 報告書を作る

本物の矢印だけのグラフ：
ファイル1を調べる ─┐
ファイル2を調べる ─┤
     …            ├─→ 報告書を作る
ファイル20を調べる ─┘

ファイル2の調査は、ファイル1の調査結果を使いません。どちらも読むだけなので、同じファイルを書き換える心配もありません。だから20個の調査は並列に進められます。全員の結果を待つ必要があるのは、最後の「報告書を作る」だけです。

一列のつなぎ方には、遅いこと以外にも弱点があります。途中のファイル7で止まると、ファイル8以降の調査も報告書も始まりません。

Part 3：Claude Codeでグラフを作る道具

Claude Codeには、複数のエージェントを動かす方法がいくつかあります。初心者が押さえておきたいのは次の4つです。

道具	何をするか	向く場面
サブエージェント	1つの会話の中で、別の文脈を持つ作業者に仕事を任せ、要約を受け取る	数個の仕事を並べて任せる、小さなグラフ
worktree	エージェントごとに別のgit作業コピーを用意し、同じファイルを同時に書き換える事故を防ぐ	複数のエージェントが並列でファイルを編集するとき
`/batch`	1つの大きな変更を、worktreeで分けた5〜30個のサブエージェントに分割して進める	大きな変更を手早く分けたいとき
dynamic workflows	Claudeが書いたJavaScriptの台本で、多数のサブエージェントをまとめて動かす	リポジトリ全体の監査、数百ファイルの移行、相互チェック付きの調査

サブエージェントとdynamic workflowsの違いは、誰が次の手を決めるかです。サブエージェントでは、Claudeが会話のたびに「次は誰に何を頼むか」を判断し、結果はClaudeの文脈に入ります。dynamic workflowsでは、段取りが台本（スクリプト）として書かれ、途中の結果は台本の変数に入ります。Claudeの会話に戻るのは最終結果だけです。

規模の数字は、1回の実行で使う総数と同時に動く数を分けて考えます。dynamic workflowsは1回の実行で最大1,000のエージェントを使えますが、同時に動くのは標準で最大16です（CPUが少ない環境ではさらに少なくなります）。並列にできる仕事でも、全員が一度に起動するとは限りません。

公式ドキュメントでは、dynamic workflowsは有料プランで使え、Proプランでは/configの「Dynamic workflows」の項目でオンにすると説明されています。編集部のProプランの環境（2026年10月10日、Claude Code v2.1.296）でも、この項目は最初falseでした。オンにすると、ユーザー設定ファイル（~/.claude/settings.json）に"enableWorkflows": trueが書き込まれました。

Part 4：実際にグラフを作る5ステップ

ここからは、APIファイルの認証漏れを、ファイルごとに並列で調べ、独立した確認役で裏を取ってから報告するグラフを作ります。調べて報告するだけでコードは変更しないため、最初の題材として安全です。

始める前に、次を用意します。

src/routes/のようなAPIのファイルがある、練習用のリポジトリ
認証が必要なAPIと、公開してよいAPIの一覧（設計資料やREADMEなど）。認証は個別のファイルではなく、ルートの登録処理や共通の認証処理で行われていることも多いため、その場所も分かっていると判定が正確になる
手動で確認するモード（Manual）で始める。2026年10月5日時点の公式情報では、Claude Code v2.1.283以降の対話型のターミナルとVS Codeでは、起動時の既定のモードがautoと説明されているので（設定や利用条件によって変わる。今回の試験では起動時にモードを指定したため、既定のモードは確かめていない）、起動時にclaude --permission-mode defaultと指定するか、Shift+Tabで画面下の表示を⏸ manual mode onにする。プロンプトに「変更しない」と書いても、それは権限を技術的に制限するものではないため、変更を伴う操作が求められたら承認しない

認証の要件が分からないAPIは、漏れと断定せず「未確認」として記録します。また、この例はコードを読んで確かめる静的な確認です。テストを実行して認証が効くことを実証した結果とは区別してください。

Step 1：仕事を箱に分けて、矢印を引く

いきなりプロンプトを書かず、まず紙やメモに箱と矢印を描きます。

[一覧を作る] → [ファイルごとに調べる] × N → [指摘を確かめる] × N → [報告書にまとめる]

各箱について、受け取るものと渡すものを書き出します。

箱	受け取るもの	渡すもの
一覧を作る	フォルダ名	ファイル名のリスト
調べる	1つのファイル名、認証要件の資料	指摘のリスト（場所、理由）。調べられなかった場合はその理由
確かめる	1件の指摘、認証要件の資料	確定／誤検知／未確認と、その根拠
まとめる	すべての判定	確定した指摘と未確認の項目を分けた報告書、調べた件数

「渡すもの」をはっきり書けない箱は、まだ分け方が粗いサインです。

Step 2：偽の矢印を消して、同時に進める箱を見つける

Part 2の表を、矢印ごとに当てはめます。

「一覧を作る → 調べる」：調べる箱はファイル名を使う。本物
「ファイル1を調べる → ファイル2を調べる」：互いの結果を使わず、どちらも読むだけ。偽物なので並列
「調べる → 確かめる」：確かめる箱は指摘を使う。本物
「確かめる → まとめる」：まとめる箱はすべての判定を使う。本物

この結果、「調べる」と「確かめる」はファイルごとに並列で進められることが分かります。

Step 3：サブエージェントで小さく試す

最初から全ファイルに広げず、3ファイル程度で試します。Claude Codeに次のように頼みます。<資料のパス>は、自分の認証要件の資料の場所（たとえばdocs/auth-requirements.md）に置き換えてください。src/routes/も、自分のAPIファイルがあるフォルダに合わせます。Step 5の例でも同じように置き換えます。


src/routes/ の中から3ファイルだけ選び、ファイルごとに別のサブエージェントを並列で起動して、
認証チェックの漏れを調べてください。コードや設定は変更しないでください。
認証要件の資料（<資料のパス>）と、ルートの登録処理・共通の認証処理も読み、
別の場所で認証している可能性と、公開APIとして意図された可能性を確認してください。
各サブエージェントは「ファイル名・該当行・問題だと考える理由・確認できなかったこと」の形式で報告してください。
調べられなかったファイルも、その理由とともに報告してください。

ここで確かめたいのは、次の3点です。

報告の形式がそろっているか（後でまとめやすいか）
1ファイルあたりどのくらいの時間と使用量がかかるか
明らかな誤検知が多くないか

試した結果：<資料のパス>をdocs/auth-requirements.mdに置き換えたほかは、このプロンプトをそのまま送りました。練習用リポジトリのsrc/routes/には5ファイルがあり、認証漏れを2か所（PATCH /todos/:id、GET /users）入れ、admin.jsはファイルの中ではなくルートの登録処理で認証する作りにしておきました。編集部の環境（2026年10月10日、Windows 11、Claude Code v2.1.296、Opus 5.5、手動で確認するモード）では、次のとおりでした。

Claudeは先に要件の資料とルートの登録処理（src/app.js）を読み、todos.js、users.js、admin.jsの3ファイルを選んで、1つの応答の中で3つのサブエージェントをバックグラウンドで起動した。3つは起動から終了まで約45秒で、時間が重なって動いていた
各サブエージェントの報告は、「ファイル名」「該当行」「問題だと考える理由」「確認できなかったこと」の見出しでそろっていた
認証漏れの2か所はどちらも見つかった。admin.jsは「ルートの登録処理で認証されている」として問題なしと判断し、誤検知にはならなかった
3つとも、頼んでいない指摘（環境変数がないと既定のトークンdev-tokenで通ってしまう）も挙げた
選ばなかったhealth.jsとstats.jsは、「3ファイルに絞るために外した」と理由付きで報告された
手動で確認するモードでも、読み取りだけの操作だったため、確認の画面は一度も出なかった

1ファイルあたりの使用量は、この方法では画面に出ませんでした。Step 5の/workflowsでは、エージェントごとの使用トークンが見えます。

Step 4：確認役を「別の文脈」で独立させる

グラフでよく起きる失敗が、グラフが自分自身に同意してしまうことです。確認役に作業役と同じ会話や同じ思い込みを渡すと、それは確認ではなく、言い方を変えた自己採点になります。

確認役の条件は2つです。

新しく起動した、forkでないサブエージェントにする：通常の新しいサブエージェントは、主会話の履歴を引き継がず、渡された依頼とプロジェクトのルールなどをもとに動きます。一方、会話を引き継ぐforkや、以前の作業者を再開したものは、過去の文脈を持っています。確認役にはこれらを使わず、判断に必要な資料と指摘だけを渡します
「完了しました」という報告ではなく、実際の証拠を見る：該当行のコード、共通の認証処理、認証要件の資料

文脈を分けても、判断が必ず独立するわけではありません。だからこそ、証拠を読ませて判定させることが欠かせません。

Step 3のプロンプトに、次を足します。


各指摘は、調べたエージェントとは別の、新しく起動するサブエージェントに渡して検証してください。
forkは使わず、調べたエージェントを再開しないでください。調査役の会話履歴は渡さず、
対象ファイル、指摘、認証要件の資料だけを渡してください。
検証役は該当ファイルと共通の認証処理を自分で読み、「確定／誤検知／未確認」で判定し、
根拠となるファイルと行、要件との対応、確認できなかったことを示してください。
最終報告では、確定した指摘と未確認の項目を分け、調べたファイルの件数も示してください。
調査や検証に失敗した対象も消さず、未確認として残してください。

公式ドキュメントでは、独立したエージェントどうしが互いの指摘を厳しく検証する形を、dynamic workflowsで使える品質向上の型として紹介しています。

試した結果：新しいセッションで、Step 3のプロンプトの後ろにこの文を続けて送りました（2026年10月10日、同じ環境）。会話の記録で確かめると、次のように動いていました。

調査役は3つ（今回はusers.js、todos.js、stats.jsを選んだ）を並列で起動した。stats.jsは「指摘なし」
指摘が出た2件について、調査役の報告が届くたびに、検証役を新しいサブエージェントとして1つずつ起動した。fork（会話を引き継ぐ起動）は使われず、調査役を再開する操作もなかった
検証役の会話の記録は、渡された依頼文（約900字）から始まっていた。依頼文には対象ファイル、要件の資料、調査役の指摘だけが入っていて、主会話の履歴は含まれていなかった
検証役は自分で該当ファイルと共通の認証処理を読み、2件とも「確定」と判定し、根拠の行と要件の行を示した
最終報告は、確定した指摘、未確認の項目、調べたファイルの件数（5ファイル中3件）に分かれていた

git statusでも、コードや設定に変更はありませんでした。

Step 5：dynamic workflowsで規模を広げる

小さく試した形がうまく動いたら、dynamic workflowsで全ファイルに広げます。プロンプトで「ワークフローを使って」のように自分の言葉で頼むか、ultracodeというキーワードを含めると、Claudeが台本を書いて実行します。公式ドキュメントでは、自分の言葉での直接の依頼も、キーワードと同じ扱いになると説明されています。


ワークフローを使って、src/routes/ の中のすべてのAPIファイルに認証チェックの漏れがないか調べてください。
認証要件の資料（<資料のパス>）を基準にし、ルートの登録処理と共通の認証処理も確認してください。
各指摘は、報告する前に、forkではない新しく起動したエージェントに厳しく検証させてください。
コードや設定の変更、commit、push、外部への送信はしないでください。
最終報告では、確定した指摘と未確認の項目を分け、調べられなかったファイルも含めてください。

この例は調査と会話への報告だけです。前述のとおり、プロンプトの禁止事項は権限の制限そのものではないため、手動で確認するモード（Manual）で試します。

公式ドキュメントによると、実行の流れは次のとおりです。

計画を確認して承認する：手動で確認するモード（Manual）なら、実行前に予定しているフェーズの一覧が表示され、「View raw script」で台本そのものも読めます。対象と制約が意図どおりかを確かめてから承認します。なお、承認画面が出るかどうかは、権限モードや過去の許可によって変わります
進み具合を見る：/workflowsで実行中のワークフローを選ぶと、フェーズごとのエージェント数、使用トークン数、経過時間が見える
止める・一時停止する：/workflowsの画面で、実行全体を選んでxを押すと全体が止まり、エージェントを選んでいる場合はそのエージェントだけが止まる。pで一時停止と再開ができる
1つの報告を受け取る：会話には、エージェントごとのやり取りではなく、まとめた結果だけが返る
気に入ったら保存する：/workflowsで実行を選んでsを押すと、プロジェクト用の.claude/workflows/か、個人用の~/.claude/workflows/に保存でき、次回から/<名前>で同じ段取りを呼び出せる

試した結果：<資料のパス>をdocs/auth-requirements.mdに置き換えて、このプロンプトを送りました（2026年10月10日、Windows 11、Claude Code v2.1.296、Opus 5.5、Proプラン、手動で確認するモード）。

まず、「Dynamic workflows」がオフのまま送ると、エラーにはならず、Claudeは通常のサブエージェントで調査と検証を進めました。確認の画面も/workflowsの表示もなく、最終報告も返りました。ワークフローが動いたかどうかは、承認画面が出たかで見分けてください。

次にオンにして新しいセッションで送ると、dynamic workflowsが起動しました。

計画の確認画面：「Run a dynamic workflow?」という画面に、2つのフェーズ（ファイルごとの調査「Review」と、指摘ごとの検証「Verify」）が表示され、「Yes, run it」「View raw script」「No」から選ぶ形でした。「View raw script」で台本を表示すると、検証役をagentType: 'general-purpose'で、指摘ごとに新しく起動する書き方になっていました。確かめてから「Yes, run it」を選びました
/workflowsの画面：実行中に開くと、フェーズごとの進み具合（Review 5/5、Verify 0/3など）、エージェントごとのモデル・使用トークン・経過時間が表示されました。画面下にはx stop workflow · p pause · esc back · s saveの操作が出ていました。xとpは試していません
規模：5ファイルの調査役5つと、指摘3件の検証役3つで、合計8エージェント、約1分、トークンの合計は約19万でした。Claudeは開始を知らせる報告の中で、検証役の数によっては「Dynamic workflow size」の目安（smallは5未満）を超えるかもしれないと説明しました。「Large workflow」の警告は出ませんでした
報告：会話に返ったのは、確定3件（GET /users、PATCH /todos/:id、既定のトークンdev-token）、未確認の項目、調べられなかったファイルに分けた最終報告だけでした。admin.jsは問題なしと判断されました
保存：終わったあと/workflowsでsを押すと、「Project scope · .claude/workflows/auth-gap-audit.js」として保存する画面が出て（Tabで個人用に切り替えられる表示）、Enterでプロジェクトの.claude/workflows/に保存されました。保存した段取りを/<名前>で呼び出すことは試していません
変更の有無：git statusで増えていたのは、保存したワークフローのファイルだけでした。コードや設定の変更はありませんでした

試して分かった注意点が3つあります。

オンにした設定がすぐ効かないことがある：編集部は試験のため、ユーザー単位の設定を読み込まない起動オプションでClaude Codeを動かしていました。この状態では、/configでオンにしても、同じセッションでも新しいセッションでもワークフローは使えず、Claudeは「この環境には専用のワークフロー実行ツールが見当たらない」として通常のサブエージェントで進めました。プロジェクトの.claude/settings.local.jsonに"enableWorkflows": trueと書いて新しいセッションを始めると使えました。普段どおりに起動している場合は、/configで切り替えたあと、承認画面が出るかで確かめてください
「変更しない」と頼んでも、検証役が動かして確かめようとする：ワークフローが使えず通常のサブエージェントで進んだ3回の実行では、検証役が一時フォルダにスクリプトを書いてローカルでサーバーを起動したり、テストを実行したりしようとしました。手動で確認するモードなので確認の画面が出て、編集部は大半を「No」で止めましたが、2件は許可しました（どちらも手元のPCの中だけの動作確認でした）
読み取りだけの操作は確認なしで動く：オフのときの実行では、Claudeが.envに対してAPI_TOKENの行の数を数える検索を、確認なしで実行していました（中身の表示ではなく件数だけ）。.envのような秘密のファイルを読ませたくない場合は、プロンプトではなく、ハーネスの回で扱ったdenyルールで止めてください

ファイルを並列で編集させる場合は、衝突を防ぐ工夫が必要です。複数のエージェントが同じ作業フォルダで同時にファイルを書き換えると、変更がぶつかります。作業場所を分けるか、担当するファイルとGit操作の順番を決めて防ぎます。初心者には、エージェントごとにworktree（別の作業コピー）を用意する方法がおすすめです。

参考までに、公式ドキュメントにある編集を伴う移行の例では、「各ファイルをそれぞれ分離したコピーで作業する」と指示に含めています。これは調査ではなく編集の例なので、試すときは練習用のリポジトリで、分離・検証・変更の統合のしかたを計画の段階で確認してください。次は、その例を日本語にしたものです。


ワークフローを使って、src/components/ の中のすべてのコンポーネントをJavaScriptからTypeScriptに移行してください。
各ファイルは、それぞれ分離したコピーの中で作業してください。

Part 5：初心者がつまずく4つの落とし穴

落とし穴	何が起きるか	防ぎ方
グラフが自分に同意する	作業役と同じ文脈の確認役が「問題なし」と言う	確認役を新しい非forkのサブエージェントにし、実際の証拠で判定させる
エージェントどうしが踏みつけ合う	同じファイルやgitの操作がぶつかる	編集するなら作業場所を分けるか、担当と順番を決める。始める前に「どこで作業するか」「どう統合するか」「食い違ったらどうするか」を決める
使用量が一気に増える	多数のエージェントが動き、普段の会話より明らかに多くのトークンを使う	1フォルダや3ファイルなど小さく試してから広げる。`/workflows`でエージェントごとの使用量を確認する
偽の矢印を残す	本当は並列でよい仕事を一列に並べ、遅く、途中で詰まる	矢印ごとに「前の結果を使うか」「ほかに順番の理由があるか」を確かめる

今回の試験（2026年10月10日）では、どの実行でもコードは変更されず、「踏みつけ合う」ことは起きませんでした。「グラフが自分に同意する」も、検証役を新しく起動したことで避けられていました。いちばん実感したのは使用量で、5ファイルという小さな題材でも、dynamic workflowsの1回の実行で合計約19万トークンを使いました。

使用量については、公式ドキュメントにも目安があります。標準の設定では、1回の実行でエージェントが25を超える予定か、見込みのトークン総数が150万を超えると、「Large workflow」という警告が表示されます。ただし、自分で規模の目安を選んだ場合は人数のしきい値が変わり、セッション全体で/effort ultracodeを有効にしている場合は警告が出ません。警告は止めるものではなく、知らせるだけです。

/configの「Dynamic workflow size」では、Claudeが目指すエージェント数の目安（smallは5未満、mediumは10未満、largeは50未満）を選べます。これは目安であり、強制的な上限ではありません。

規模が本物である一方、費用も本物です。Bun（JavaScriptの実行環境）をZigからRustへ書き直した事例では、11日で100万行以上のRustコードが追加されましたが、API料金換算で約16万5千ドルかかったと報告されています。人間による監視や確認も伴った事例で、この取り組みが成り立った理由の一つは、TypeScriptで書かれた既存のテスト一式を、正しく動くかの判定基準として使えたことでした。大きなグラフほど、信頼できる確認役が欠かせません。

Part 6：グラフにしない方がよい場面

グラフで段取りを管理するのは、いつも得とは限りません。次の場面では、1つのループや普通の会話のままの方がうまくいきます。

場面	理由
仕事が小さい（1つの関数の追加、1つのバグ修正）	分ける手間と調整の費用の方が大きくなる
工程の間で人間が1つずつ判断したい	dynamic workflowsでは、実行の途中に人間の判断を挟めない。ツールの権限確認による待機はあるが、工程ごとに判断したいなら、工程ごとに別のワークフローとして実行する
何を探しているか、自分でもまだ分からない	箱と矢印を描けない段階では、段取りを決められない
すべての工程が前の結果を使う	並列にできる部分がなく、調整の費用だけが増える

すべてが順番どおりに進む仕事も、グラフとして描くことはできます。ただし、小さな一本道の作業なら、グラフとして段取りを管理する手間を増やさず、普通の会話やループで十分な場合が多いでしょう。

結論：最初の一歩は「調べるだけ」の小さなグラフ

グラフエンジニアリングは、大量のエージェントを動かす派手な技術に見えます。しかし、出発点は地味です。仕事を箱に分け、矢印を引き、偽の矢印を消すこと。そして、確認役を作業役から切り離すことです。

今日から試すなら、次の順番がおすすめです。

同じ作業をたくさんのファイルに行う、コードを変更しない調査を1つ選び、判定に必要な資料を用意する
紙に箱と矢印を描き、「前の結果を使うか」「ほかに順番の理由があるか」で偽の矢印を消す
3ファイルだけ、サブエージェントの並列実行で試す
確認役を新しい非forkのサブエージェントにし、証拠を示して「確定／誤検知／未確認」で判定させる
うまくいったら、dynamic workflowsで範囲を広げ、気に入った段取りを保存する

ループが1つの仕事を前に進めるモーターなら、グラフはたくさんのモーターをぶつからせずに走らせるレールです。仕事をどう分け、どこで待ち、どこで確かめるかを描けることが、AIエージェントを使いこなす次の一歩になります。

参考資料

Claude Code Docs「Orchestrate subagents at scale with dynamic workflows」 https://code.claude.com/docs/en/workflows
Claude Code Docs「Run agents in parallel」 https://code.claude.com/docs/en/agents
Claude Code Docs「Create custom subagents」 https://code.claude.com/docs/en/sub-agents
Claude Code Docs「Run parallel sessions with worktrees」 https://code.claude.com/docs/en/worktrees
Simon Willison「Rewriting Bun in Rust」 https://simonwillison.net/2026/Jul/8/rewriting-bun-in-rust/
サーバーワークスエンジニアブログ「『グラフエンジニアリング』とは何か？」 https://blog.serverworks.co.jp/what-is-graph-engineering
tatsuki「グラフエンジニアリングってなに？」 https://note.com/nobel/n/n4c8353703f1b （無料公開部分を確認）