Workflow ツール：スクリプトによるマルチエージェントオーケストレーション

学ぶこと

Dynamic workflow は subagents を協調させる JavaScript スクリプトです。専用 runtime が制御フローをバックグラウンドで実行します。ループ、分岐、fan-out をモデルの会話 context の中だけに置かず、読めて再利用できる形にしたいときに使います。

このセッションを終えると、次のことが分かります。

• Workflow、subagent、skill、agent team の使い分け
• Workflow の起動、確認、承認、保存、再実行
• meta、agent()、pipeline()、parallel()、phase()、args の文書化された形
• Runtime の実際の上限と同一セッション内 resume の境界
• スクリプトに持ち込むべきでない failure と budget の仮定

適切な協調レイヤーを選ぶ

仕組み	次の処理を決める主体	適した用途
Subagent	Claude がターンごとに判断	少数の委任タスク。結果は 1 つの context に戻る
Skill	保存された指示に従う Claude	再利用する手法やドメイン手順
Agent team	長時間動く peers を監督する lead	Tasks を共有し互いにメッセージする teammates
Workflow	Script runtime	大規模で反復可能なループ、fan-out、分岐、クロスチェック

Workflow が常に優れているわけではありません。単一の調査や密結合した編集なら、1 agent の方が低オーバーヘッドです。ブックキーピングをコードに任せる価値がある場合に使います。

Dynamic workflows には Claude Code 2.1.154 以降が必要です。有料プランと対応 API／クラウド provider surface で利用でき、Pro ユーザーは /config の Dynamic workflows 行で有効にします。

3 つの実行方法

組み込み workflow を試す

/deep-research Node.js v20 から v22 で permission model はどう変わった？

/deep-research は調査を fan-out し、claims をクロスチェックして、引用付きの 1 レポートを返します。

Workflow を直接依頼する

use a workflow to audit every route handler under src/routes/ for missing authentication checks, then adversarially verify each finding

ultracode キーワードも 1 タスクの明示的トリガーです。保存済みのセッション effort level は変えません。

Ultracode に判断させる

/effort ultracode

このセッション設定は、xhigh effort と、実質的なタスクに対する自動 workflow 計画を組み合わせます。提供範囲はセッション 26を参照してください。

保存されたスクリプトの形

通常、スクリプトは Claude が書きます。小さな保存済み workflow は次の文書化された形です。

export const meta = {
  name: 'audit-routes',
  description: 'Audit every route handler for missing auth checks',
}

const found = await agent('List every .ts file under src/routes/.', {
  schema: {
    type: 'object',
    required: ['files'],
    properties: {
      files: { type: 'array', items: { type: 'string' } },
    },
  },
})

const audits = await pipeline(found.files, file =>
  agent(`Audit ${file} for missing authentication checks.`, { label: file }),
)

return audits.filter(Boolean)

スクリプトは literal な meta export から始まり、top-level await を使える plain JavaScript で書きます。

• agent() は 1 subagent を起動します。
• pipeline() は項目リストに stages を適用します。
• parallel() は独立した functions を並行実行し、グループ全体を待ちます。
• meta.phases がある場合、phase() は進捗画面で作業をグループ化します。
• args は保存済み workflow に渡した structured input で、省略時は undefined です。

正確な input/output types は Agent SDK reference を正としてください。例から独自の return、exception、in-script budget contract を推測してはいけません。

承認と権限

インタラクティブな run の前に、Claude Code は計画した phases を表示し、次を選べます。

• 1 回だけ実行
• この project では常にその workflow を許可
• raw script を確認
• キャンセル

実際の prompt は permission mode に依存します。Workflow agents は acceptEdits mode で動き、セッションの tool allowlist を継承します。Allowlist 外の shell、web、MCP calls は実行中にも権限を求める場合があります。Workflow は途中で通常の業務質問をユーザーに聞けないため、人の承認点は別々の workflows に分けます。

監視、一時停止、保存

/workflows で実行中と完了済みの runs を確認できます。Phases、agents、経過時間、トークン使用量が表示され、一時停止、resume、停止、agent の再起動、スクリプト保存ができます。

保存先は slash command になります。

• .claude/workflows/：repository で共有する project workflow
• ~/.claude/workflows/：複数 project で使う personal workflow

保存済みスクリプトは args から呼び出し入力を受け取るので、ソースを変えずに異なる paths、issues、調査テーマを処理できます。

Runtime の境界

文書化された制約は具体的です。

境界	現在の動作
Script からのアクセス	Filesystem や shell に直接アクセス不可。Agents が tools を使う
実行途中の入力	通常の user input は不可。Agent permission prompts のみ一時停止できる
並行数	最大 16 agents。CPU が限られる場合は減る
Worker 総数	1 run あたり 1,000 agents
Session 終了	次の session では workflow を最初から実行

Pause と resume は同じ Claude Code session 内だけで機能します。完了済みの agent() calls は cached results を返せますが、一時停止時に実行中だった agent は再開時に最初から動きます。そのため、1 つの長大 worker より、小さく fan-out した方が進捗を保持しやすくなります。

コストと規模

Workflow は単一 conversation より大幅に多くのトークンを使う場合があります。大きな run の前に：

1. 1 directory や小さなサンプルでリハーサルする。
2. /workflows でトークン使用量を見る。
3. Evidence が改善しなくなったら停止する。
4. Claude に小さな workflow を書かせたい場合は /config で size guideline を設定する。

Size setting は Claude への助言で、強制上限ではありません。2.1.203 以降、25 scheduled agents 超または予測 150 万 tokens 超で Large workflow warning が出ます。これも助言であり、ultracode 有効時は大規模実行にすでに同意しているため表示されません。

実践的な設計ルール

• 本当に独立した作業だけを fan-out する。
• 項目間の重複排除やランキングは、必要な結果が揃った後に行う。
• Agents には transcript 全文ではなく、簡潔で構造化された evidence を求める。
• Passing check、2 dry rounds、no further progress などの stop condition をタスクに書く。
• Sampling、スキップした作業、unresolved claims を最終レポートに記録する。
• 人の判断が必要な箇所は別の stages/runs に分ける。

要点

Workflow は協調状態を conversation からコードへ移します。 各 agent 内の判断はモデルが担いますが、ループ、fan-out、中間値は検査・再利用可能になります。未文書化の内部動作を API 保証と誤認せずに、オーケストレーションを監査しやすくできます。

次のセッション

セッション 28 では、これらの仕組みをオーケストレーション品質パターンとして組み立てます。独立探索、敵対的検証、明示的な停止、監査可能な証拠を扱います。

公式情報源

• Dynamic workflows
• Agent 方式の選択
• Agent SDK Workflow tool types