workflow-builder

Workflow Builder

Claude Code の Workflow ツール用に、実行可能なワークフロースクリプトを作成します。これは、単純な JavaScript の制御フローで、新しいコンテキストのサブエージェントに作業を振り分ける、決定論的なマルチエージェントオーケストレーションファイル（.js）です。トークンを消費するのは末端の agent() 呼び出しだけなので、メインセッションはクリーンなまま保たれ、実行全体を再開できます。

すべてのセッションは必ずインテークから開始してください（必須）

ワークフローを提案または作成する前に、インテークを実施してください。コードの作成に進む前に必ず行ってください。

1. どのようなワークフローを望んでいるか尋ねます。 次の質問から始めてください。

   • 自動化したい、繰り返し可能な複数ステップのタスクは何ですか？
   • 1つのサブエージェントが一度に行う作業単位は何ですか？
   • 作業単位はいくつありますか？既知のリストですか、それともループで見つけますか？
   • 後続のステップでは、先行するすべての結果を一度に必要としますか？それとも各項目を個別に処理できますか？
   • いずれかのステップで、判定、リスト、スコアなどの構造化データが必要ですか？
   • おおよそ何トークンを使う想定ですか？どの程度深く実行しますか？

2. ユーザーの説明が曖昧でも、そこで止まらないでください。 推薦エンジンを実行して、得られている情報から1～2件の具体的な提案にまとめ、理由とともに提示してください。

   python scripts/workflow_intake.py --task "their description" \
     --units unknown --stages unknown --needs-all unknown --structured unknown
   

   エンジンは、推奨するトポロジー（ファンアウト／パイプライン／ループ／バリア／判定パネル）、モデルの選択、予算ガード、各選択の簡潔な理由を返します。これらを「このように構築するのがおすすめです。その理由は次のとおりです」として提示してください。ユーザーがすでに部分的に回答した質問を、再度尋ねてはいけません。

3. ファイルを作成する前に、ユーザーに構成を確認します（トポロジー＋フェーズ＋並列処理かパイプライン処理か）。承認が必要なのはこの段階だけです。

質問の全体像、曖昧な入力への対応方法、推奨例については、references/decision_and_intake_guide.md を参照してください。

ワークフローが適切なツールか判断する

シナリオ	使用するもの
1つのタスクを1つのサブエージェントで行う	通常の Agent ツール
再利用可能な手順で、Claude が動的にステップを選択する	Skill
固定トポロジーで多数のサブエージェントを使い、決定論的かつ再開可能である	Workflow ✓

作業が並列処理または複数段階である場合、再現性が必要な場合、途中で失敗するほど長く再開が重要な場合、または各ステップをそれぞれ独立したコンテキストウィンドウに分離するメリットがある場合、ワークフローを使う価値があります。単発のタスクでは、Claude を直接使ってください。

作成 → 検証 → 実行のループ

1. 確認したトポロジーに基づいて、ひな形を作成します。

   python scripts/scaffold_workflow.py --topology pipeline --name pr-triage \
     --description "Triage open PRs" > .claude/workflows/pr-triage.js
   

2. 編集します。まず meta ブロックを記述します（純粋なリテラルで、最初の文である必要があります）。続いて、注入されたグローバル変数（agent()、pipeline()、parallel()、phase()、log()、budget、args、workflow()）を使って非同期の本体を記述します。利用できる機能の全容は references/api_reference.md に、コピーして使える形式は references/orchestration_patterns.md にあります。
3. 実行前に検証します。パーサーを停止させる誤りを検出します。

   python scripts/validate_workflow.py .claude/workflows/pr-triage.js
   

4. 実行します。export CLAUDE_CODE_WORKFLOWS=1 で機能を有効にし、ファイルを .claude/workflows/ に保存してから、/workflows を使って起動し、実行状況をライブで確認します。P を押すと一時停止／再開、X を押すとサブエージェントをスキップできます。失敗したエージェントは自動的に再試行されます。

厳守事項（バリデーターによるチェック対象）

• meta は純粋なリテラルで、最初の文である必要があります。内部で変数、スプレッド構文、テンプレート文字列、関数呼び出しを使用してはいけません。
• 非決定的な処理は禁止です。 Date.now()、Math.random()、引数なしの new Date() は再開を妨げます。タイムスタンプは args 経由で渡してください。
• オーケストレーターで ファイルシステムや Node API（require、fs、process、ネットワーク）を使ってはいけません。その処理は agent() のプロンプト内で行ってください。
• parallel() に渡すのはプロミスそのものではなく、**関数（() => agent(...)）**です。ステージ全体の結果が必要な場合を除き、pipeline() を使ってください。
• 終了条件のないループには必ずカウンターか budget.remaining() のチェックを設けてください。ガードのないループはエージェント数の上限 1000 件に達します。
• スキップされたエージェントや失敗したエージェントをフィルターしてください：results.filter(Boolean)

ツール

• scripts/workflow_intake.py — 推奨エンジン（曖昧な入力からトポロジー、モデル、予算、根拠を提示します）。
• scripts/validate_workflow.py — 上記のルールに対応する標準ライブラリのリンターです。行番号付きで PASS／WARN／FAIL を表示します。
• scripts/scaffold_workflow.py — 任意のトポロジー用のスターター .js を生成します。
• assets/templates/ — fan-out、pipeline、loop-until-budget のスターターです。assets/examples/ — 実行可能なワークフロー一式です。

すべてのスクリプトは --sample（引数なし）と --help で実行できます。