wave-executor

Wave Executor

概要

Wave Executor は、Claude Agent SDK を介して各ウェーブごとに新しい Claude Code プロセスを起動し、EPIC ティアのバッチパイプラインを実行します。各ウェーブは、蓄積された spawn() や abort_signal の状態が一切ないクリーンな Bun ランタイムを使用します。これにより、単一の Bun プロセスで数千の並行サブエージェントを起動したときに発生する、JSC ガベージコレクターの use-after-free クラッシュ（oven-sh/bun、anthropics/claude-code#21875、#27003）を防ぎます。

これは、ファイルベースの調整を使って新しいプロセスで反復する、Ralph Wiggum パターンのフレームワーク実装です。

使用するタイミング

次の場合にこのスキルを使用してください：

• EPIC ティアのバッチ作業：アーティファクトが 10 個超、ウェーブが 5 回超
• 複数ウェーブにわたるスキル更新、バンドル生成、大規模なリファクタリング
• 並行サブエージェントを使って 30 分を超えて実行される想定のパイプライン
• 以前に Bun のセグメンテーション違反でクラッシュした作業

次の場合は使用しないでください：

• 1～3 個の単純なスキル更新（skill-updater を直接使用してください）
• 単一スキルの作業（Task() サブエージェントを使用してください）
• 1 つのコンテキストウィンドウに収まる作業（インラインで実行してください）

仕組み

Router invokes wave-executor via Bash
  │
  └─ node .claude/tools/cli/wave-executor.mjs --plan <path>
       │  (runs on system Node.js — NOT Bun)
       │
       ├─ Reads plan.json with wave definitions
       ├─ Reads inventory.json for resume state
       │
       ├─ For each pending wave:
       │    ├─ SDK query() → NEW Bun process (fresh GC)
       │    ├─ Claude executes wave tasks
       │    ├─ Streams output to stdout
       │    ├─ Bun process exits → memory freed
       │    ├─ Updates inventory.json
       │    └─ Sleeps → next wave
       │
       └─ Returns JSON summary

重要な不変条件：単一の Bun プロセスで蓄積される起動数が約 100 を超えないこと。

呼び出し方法

Bash 経由（エージェント）：

node .claude/tools/cli/wave-executor.mjs --plan <path> --json

スラッシュコマンド経由（ユーザー）：

/wave-executor --plan .claude/context/plans/my-plan.json

CLI フラグ：

フラグ	デフォルト	説明
--plan <path>	必須	ウェーブ計画 JSON のパス
--model <model>	claude-sonnet-4-6	ウェーブ実行に使用するモデル
--max-turns <n>	50	ウェーブごとの会話ターン数の上限
--start-from <n>	1	ウェーブ N から再開
--dry-run	false	実行せずにプレビュー
--json	false	機械可読な出力

計画ファイルの形式

{
  "name": "enterprise-bundle-generation",
  "waves": [
    {
      "id": 1,
      "skills": ["rust-expert", "python-backend-expert", "typescript-expert"],
      "domain": "language",
      "promptTemplate": "Update enterprise bundle files for skills: {skills}. Read each SKILL.md and .claude/rules/ file. Do 3-5 WebSearch queries for current {domain} tools and patterns. Generate domain-specific bundle files (append-only, never overwrite non-stubs). Validate JSON schemas and Node.js syntax. Commit results."
    },
    {
      "id": 2,
      "skills": ["nextjs-expert", "react-expert", "svelte-expert"],
      "domain": "web-framework"
    }
  ],
  "config": {
    "model": "claude-sonnet-4-6",
    "maxTurnsPerWave": 50,
    "sleepBetweenWaves": 3000,
    "inventoryPath": ".claude/context/runtime/wave-inventory.json"
  }
}

各ウェーブには id（数値）と skills（空でない配列）が必要です。domain と promptTemplate は任意です。

インベントリの追跡

エグゼキューターは、設定されたパス（デフォルトは .claude/context/runtime/wave-inventory.json）にインベントリファイルを保持します。これにより、次のことが可能になります：

• クラッシュからの再開： --start-from N で、失敗した実行の続きから再開します
• 進行状況の監視： インベントリファイルを読み、完了したウェーブを確認します
• コストの追跡： 各ウェーブのコストが記録されます

Router との統合

プランナーが作業を EPIC ティアに分類した場合、Router はこのスキルを使用してください：

1. プランナーがウェーブ定義を含む計画ファイルを作成します
2. Router が呼び出します：Skill({ skill: 'wave-executor' })
3. エージェントが実行します：node .claude/tools/cli/wave-executor.mjs --plan <path> --json
4. Router が JSON の結果を読み取り、成功または失敗を確認します

実行中、Router の Bun プロセスはアイドル状態を維持します（Bash 呼び出しは 1 回のみ）。サブエージェントの起動も、フックの蓄積もありません。

厳守事項

1. 長時間実行セッションでの GC 関連クラッシュを防ぐため、必ず各ウェーブを新しい Bun プロセスで起動してください
2. 設定された MAX_PARALLEL_WAVES の上限より多くのウェーブを並行してバッチ処理しないでください
3. 次のウェーブを起動する前に、ウェーブ完了の確認を必ず待ってください
4. 現在のウェーブに失敗または未完了のエージェントがある場合、次のウェーブに進まないでください
5. パイプラインの可観測性を確保するため、ウェーブのメタデータ（ウェーブ番号、エージェント数、所要時間）を必ず記録してください

アンチパターン

アンチパターン	失敗する理由	正しい方法
ウェーブ間で同じプロセスを再利用する	GC の負荷により、長いパイプラインでクラッシュする	ウェーブごとに新しい Bun プロセスを起動する
MAX_PARALLEL_WAVES を超過する	リソースが枯渇し、不安定な失敗が発生する	設定された同時実行数の上限を守る
現在のウェーブが完了する前に次のウェーブを開始する	競合状態や不完全なパイプライン状態が発生する	次に進む前にウェーブ完了シグナルを待つ
ウェーブ内で失敗したエージェントを無視する	部分的な状態が伝播し、誤ったデータが後続に渡る	続行する前に処理を停止し、失敗を明らかにする
ウェーブのメタデータをログに記録しない	問題の原因となったウェーブを特定できない	ウェーブ番号、エージェント、所要時間をコンテキストに記録する

メモリプロトコル（必須）

開始前：

• 過去のウェーブ実行に関する知見を確認するため、.claude/context/memory/learnings.md を読む
• 再開状態を確認するため、インベントリファイルを確認する

完了後：

• ウェーブ実行の概要を .claude/context/memory/learnings.md に追記する
• エラーがあれば .claude/context/memory/issues.md に記録する
• アーキテクチャ上の決定事項を .claude/context/memory/decisions.md に記録する

中断されることを前提にしてください。コンテキストがリセットされる可能性があります。メモリに記録されていないことは、起きていないのと同じです。