Claude Code workflowの使い方：Claudeの代わりにスクリプトが指揮する仕組みとコスト

Claude Code workflowの使い方を、このサイトの翻訳チェックを例に説明します。記事はすべて5つの言語で公開していて、公開前にはロケールごとに翻訳の正確さ、機械的な言い回し、隠し文字を別々に確認します。1本の記事で15回のチェックです。これまでClaude Codeはそれを順番にこなし、途中のレポートを全部1つのセッションのコンテキストに積み上げていました。Claude Code workflowが片付けるのは、まさにこの問題です。ClaudeがJavaScriptのスクリプトを書き、ランタイムがそれに沿ってサブエージェントをバックグラウンドで起動し、会話に戻ってくるのは最終結果だけです。

以下ではClaude Codeのドキュメントをもとに、このモードが何なのか、サブエージェント、スキル、エージェントチーム（agent teams）とどう違うのか、どう起動するのか、どこから元が取れなくなるのかを書きます。内容はすべて2026年11月3日時点のドキュメントで確認しました。手元のClaude Codeは2.1.316です。Workflowはすべての有料プランに加え、Anthropic API、Amazon Bedrock、Google Cloud Agent Platform、Microsoft Foundryで使えます。Proでは /config の Dynamic workflows の行で有効にする必要があります。

Claude Code workflowとは：計画がコードに移る#

サブエージェント、スキル、エージェントチームは、以前からClaude Codeで起動できました。違うのは、計画を誰が握っているかです。従来の3つでは、オーケストレーターはClaude自身です。会話の流れの中で次に誰を起動するかを決め、結果は一つ残らずClaudeのコンテキストに入ります。workflowでは、ループも分岐も途中のデータも、スクリプトの変数の中に置かれます。

workflowとスキルは何が違うのか、というよくある質問の答えもここから出てきます。スキルは、Claudeが読んで自分で実行するテキストです。workflowを実行するのはランタイムで、Claudeが目にするのは答えだけです。

規模は、ここでは本題ではありません。作業の順序がコードに書かれている以上、品質チェックをそこに組み込めます。一部のエージェントが問題を探し、別のエージェントが独立にそれを反証しようとして、反証に耐えたものだけがレポートに残る。あるいは計画を3つの立場から書かせて、4体目のエージェントが案を比べる、という形もとれます。

Claude Code workflowの使い方：3つの起動方法#

組み込みの /deep-research。 このモードが動くところを見るなら、いちばん手っ取り早い方法です。コマンドはWeb検索を複数の方向に振り分け、見つけた情報源同士を突き合わせ、主張ごとに投票して、リンク付きのレポートを返します。照合を通らなかった主張はレポートから外されます。上限やAPIエラーのせいで確認できなかった主張には、反証済みではなく未検証の印が付きます。

/deep-research What changed in the Node.js permission model between v20 and v22?

プロンプトで頼む。 プロンプトの先頭に ultracode と書くか、自分の言葉でそのまま頼めば（「use a workflow」）、Claudeは一歩ずつ作業を進めるのをやめ、このタスク用のスクリプトを書きます。ハイライトされた単語は、そのプロンプトに限って取り消せます。macOSなら Option+W、WindowsとLinuxなら Alt+W です。

この単語が効くのは、人間が入力したプロンプトだけです。claude -p から渡したプロンプト、スケジュール実行のタスク、Webhook、pull requestのコメントは、ultracode が入っていてもworkflowを起動しません。

セッション全体で有効にする。 これが3つ目の方法で、次の節で別に扱います。

Claude Codeのultracodeとは何か、いつオフにするか#

/effort ultracode はセッションの設定で、effortレベルには手を付けません。これを有効にすると、どのタスクにworkflowが要るかをClaudeが自分で判断します。1つの依頼が、コードを調べる、変更を入れる、それを確認する、という3回の連続実行になることもあります。claude --effort ultracode で起動した場合は、さらにレベルが xhigh になります。オフにするコマンドは /effort ultracode off です。

ultracodeを有効にすると、安全装置が3つ外れます。Large workflow の警告、Agent toolで同時に動かせるサブエージェント数の上限、それにautoモードでの初回実行の確認です。サブスクリプションだとこういうセッションは日次や週次の上限に早く届く、とドキュメントにははっきり書いてあります。修正、1ファイルのレビュー、メール書きのような普段の作業なら、私はオンにしません。

スクリプトの中身#

スクリプトは普通Claudeが書きますが、目を通しておくと役に立ちます。Claude Codeは実行前にフェーズを表示し、コードを開かせてくれます（View raw script または Ctrl+G）。以下は私のロケールチェック用の下書きです。ドキュメントを見ながら組んだもので、実際の記事ではまだ回していません。

export const meta = {
  name: 'article-locale-review',
  description: 'Review every locale of an article against the Russian source',
  phases: [{ title: 'Review' }, { title: 'Verify' }],
}
 
const FINDINGS = {
  type: 'object',
  required: ['findings'],
  properties: {
    findings: {
      type: 'array',
      items: {
        type: 'object',
        required: ['locale', 'quote', 'problem'],
        properties: {
          locale: { type: 'string' },
          quote: { type: 'string' },
          problem: { type: 'string' },
        },
      },
    },
  },
}
const VERDICT = {
  type: 'object',
  required: ['isReal', 'reason'],
  properties: { isReal: { type: 'boolean' }, reason: { type: 'string' } },
}
 
const LOCALES = ['en', 'es', 'ja', 'zh-CN']
 
phase('Review')
const reviews = await pipeline(LOCALES, locale =>
  agent(
    `Compare content/articles/ru/general/${args.slug}.mdx with ` +
      `content/articles/${locale}/general/${args.slug}.mdx. ` +
      `List omissions, additions and mistranslations. Do not edit files.`,
    { label: locale, schema: FINDINGS },
  ),
)
 
phase('Verify')
const findings = reviews.filter(Boolean).flatMap(r => r.findings)
const verdicts = await parallel(
  findings.map(f => () =>
    agent(`Try to refute this translation issue: ${JSON.stringify(f)}`, {
      label: `verify:${f.locale}`,
      schema: VERDICT,
    }).then(v => (v ? { ...f, ...v } : null)),
  ),
)
 
return verdicts.filter(v => v?.isReal)

agent() はサブエージェントを1体起動します。pipeline() はリストの要素ごとに1体ずつ、parallel() はタスクの集合をまとめて並列実行し、全部が終わるのを待ちます。phase() は進捗ウィンドウでエージェントをグループにまとめ、args は保存したコマンドを起動するときに渡す入力です（「Run /article-locale-review on slug claude-code-workflows」）。

filter(Boolean) に注目してください。止められたエージェントや、回復できないAPIエラーで落ちたエージェントは null を返し、pipeline() はその null を配列に残したままにします。schema のほうは、サブエージェントに決まった形のJSONを返させるためのものです。5回続けて失敗すると、呼び出しは最後のバリデーションエラーで落ちます。

うまくいった実行は、コマンドとして保存できます。/workflows で実行を選び、s を押すだけです。ファイルはプロジェクトの .claude/workflows/（リポジトリをクローンした人全員に見える）か、~/.claude/workflows/（自分だけですが、どのプロジェクトでも使える）に置かれます。

最初に実行する前に知っておきたい制限#

• 途中で口を挟めない。 workflowが自分から一時停止するのは、エージェントの権限リクエストと、上限のリセット待ちのときだけです。段階の合間に承認を挟みたいなら、段階ごとに別々の実行にしてください。
• スクリプト自体は何にも触れない。 ファイルを読んで書き換えるのはエージェントで、スクリプトはその調整役です。import() は使えず、Date.now()、Math.random()、引数なしの new Date() はエラーを投げます。再実行のときに、エージェントを同じ順序で呼び出す必要があるからです。時刻は args で渡します。
• 上限値。 並列で動くサブエージェントは16体（CLAUDE_CODE_WORKFLOW_MAX_CONCURRENT_AGENTS、1〜256）、1回の parallel() や pipeline() に渡せる要素は4,096、1回の実行で使えるエージェントは1,000体までです。
• 障害後の再実行は、思ったより高くつく。 完了済みのエージェントは、再実行時に保存された結果を返します。ところが、スクリプトがA、B、C、Dを起動してBが落ちた場合、再実行でキャッシュから取り出されるのはAだけです。CとDが終わっていても、B、C、Dはもう一度走ります。
• 応答が止まった（ハングした）エージェントは自動で再起動されます。回数は最大5回です。時間のかかるタスクには、agent() の stallMs で猶予を延ばせます。
• サブスクリプションの上限に達したとき。 実行はリセットを待って自分で再開しますが、それには条件があります。対話セッションであること、autoContinueAtUsageLimit が有効なこと、リセットが24時間以内に来ること。しかも2回までです。claude -p やバックグラウンドセッションでは、エージェントはそのまま落ちます。

タスクを停止してセッションを閉じると、実行も一緒に止まります。保存された結果は残るので、claude --resume で戻り、Claudeにworkflowの再実行を頼めば続けられます。

workflowはいくらかかるか#

1回の実行は、同じ作業を会話の中でやるより明らかに多くのトークンを使い、その全部がプランの上限から引かれます。エージェントが25体を超えるか、見積もりが150万トークンを超えると、Claude Codeはその実行に Large workflow の印を付けます。ただの警告なので、実行は止まりません。

Claudeが何体のエージェントを計画するかの目安は、workflowSizeGuideline で決まります。

デフォルトは medium で、Proではバージョン2.1.271から small になっています。変えるには /config workflowSizeGuideline=small を使います。あくまでモデルへの助言なので、プロンプトで明示的にもっと多くのエージェントを頼めば、Claudeはプロンプトのほうに従います。

見落としやすい節約もあります。同じ実行の中で、モデル、effortレベル、ツール、スキーマ、作業フォルダがそろっているエージェントはプロンプトキャッシュを共有します。そのためClaude Codeは、最初の1体の応答が始まるまで、ほかを最大5秒待たせます。キャッシュの寿命は5分です。subagentPromptCacheTtl: "1h" を指定すると1時間まで延びますが、書き込みの料金は高くなります。

ドキュメントの助言で私も同意しているのが、まず小さく切り出した範囲でworkflowを回すことです。リポジトリ全体ではなくフォルダ1つ、広い質問ではなく狭い質問1つ。/workflows ではエージェントごとのトークン消費が見られ、実行はいつでも止められます。終わった分は失われません。

workflowで元が取れる作業#

見分け方は単純で、同じ操作を多くの対象に繰り返し、その結果をクロスチェックする作業かどうかです。すべてのルートハンドラーで認可の抜けを監査する、分離したコピーの中で500ファイルを移行する、新しいラウンドで何も見つからなくなるまでフレーキーテストを探し続ける、といった作業です。こういう作業でエージェントが共有ファイルに書き込むなら、人間と同じ規律が必要になります。分離するか、黙って上書きせずに書き込みのclaimを取るかです。

私にとっては、これが2つの手順にあたります。1つは各記事の5ロケールのチェックで、上に書いたものです。もう1つは、自分のサイト全部に対するセキュリティパッチの確認で、リポジトリごとに1体のエージェントがバージョンとDockerfileを照合し、2体目がその結果を確かめ直します。どちらも繰り返しの作業で、どちらも今はセッションのコンテキストを食っています。

逆に、カバーレター、関数1つの修正、記事1本はworkflowの出番ではありません。1回で済ませたほうが安く、出来も変わりません。どのエージェントにも必要なプロジェクトの知識についても、workflowは何も変えません。それは相変わらずどこかに置いておく必要があり、置き場所はたとえばMCPでClaude Codeにつないだwikiです。エージェントが増えて本格的にコードを書くようになれば、git自体がボトルネックになるかもしれません。gitを自社のシステムに置き換えたAnthropicがそうでした。

始めるなら、私はこう勧めます。/config workflowSizeGuideline=small にしてから、どうせ30分かけてググるつもりだった質問を /deep-research に投げ、それがいくらかかったかを /workflows で確かめてみてください。