waves

WAVES — Workers · Aggregate · Verify · Extend (Cursor)

1 つのローカル Cursor セッション内で、ウェーブベースのオーケストレーションを実行します。ウェーブとは、隔離されたエージェントが並行して作業する範囲の決まったラウンド、その結果を検証するラウンド、そしてその成果を発展させるかどうかを慎重に判断するラウンドから成ります。終わりのないループではありません。あなたはオーケストレーターです。情報を収集し、目標を独立した作業単位に分解して、並行するワーカーに割り当てます（1 回のメッセージで複数の Task ツールを呼び出し、利用できる場合はバックグラウンドで実行します）。各ワーカーの構造化された引き継ぎを読み、検証して、1 つの成果物にまとめます。ワーカーは隔離されており、引き継ぎを 1 つだけ返します。

すべてのウェーブの構成 — WAVE：

• W — Workers（ワーカー）。 隔離されたワーカーを、互いに重複しない作業単位に割り当てます（範囲の決まった並行ラウンド）。
• A — Aggregate（集約）。 すべてのワーカーを待ち、統合のバリアで構造化された引き継ぎをまとめます。
• V — Verify（検証）。 要となる段階です。各引き継ぎの根拠を確認してから、信頼できるか判断します。
• E — Extend（拡張）。 もう一度ウェーブを開始するか、ここで終了するかを慎重に判断します。

ループはいつ止めるか分かりませんが、ウェーブは分かります。検証が停止条件となるからです。（/waves で明示的に起動します。通常より多くのエージェントが実行されるため、自動では起動せず、オプトイン方式です。）

Waves はクラウドオーケストレーションの代わりに動作します。Cursor チームがクラウドの orchestrate プラグインで実証した原則、つまりプランナーが計画し、ワーカーが上位に引き継ぎ、相互にやり取りしないという原則を採用しつつ、セットアップ不要でローカルサブエージェント上で実行します。別のクラウドエージェントも、API キーも、ランタイムも必要ありません。ここで扱うのは、すべてローカルサブエージェントの実行です。

使用する場面

• 大きな目標を独立した作業単位に分割できる場合（調査領域、データのまとまり、ファイル／モジュール、監査の観点など）。
• 作業の大半が閲覧／調査／分析であり、ローカルで並列化するのが最も安全な場合（理由については「並列書き込み」を参照）。
• 1 回の直線的な処理では時間がかかり、並行処理による実質的な高速化が必要な場合。

使用を避ける場面

• 小規模または直線的なタスクの場合（そのまま実行してください。作業の割り振りにかかるオーバーヘッドに見合いません）。
• 手順間で頻繁なやり取りや、共有する可変状態が必要な作業の場合。
• 同じファイルへの並列編集（ローカルワーカーは 1 つのファイルシステムを共有します）。

基本原則

orchestrate をもとにしています。これらの原則により、調整なしでも実行を収束させられます。

1. オーケストレーターは計画と統合を担い、主要な作業は行いません。 情報の収集、分解、引き継ぎの読み取り、最終成果物の作成はあなたの役目です。閲覧／調査／分析の大部分はワーカーに委任します。
2. ワーカーは隔離されています。 サブエージェントは、ユーザーのメッセージ、これまでのあなたの手順、他のワーカーにアクセスできません。 すべてのワーカープロンプトは自己完結している必要があります。つまり、目標のコンテキスト、担当する作業単位、調査先、返す内容をすべて含めてください。
3. 1 人のワーカー、1 つの作業単位、1 つの引き継ぎ。 ワーカーから読み取るのは、最終メッセージだけです。返答の正確な形式を定義してください（references/handoff-format.md を参照）。
4. 並列化は閲覧のために使い、書き込みには使いません。 ローカルワーカーはワークスペースを共有します。重複するパスへの同時書き込みは、互いの変更を破損させます。
5. 継続的に進めます。 引き継ぎから新たな作業が見つかることがあります。引き継ぎの不足が見つかった場合も、ユーザーから新たな依頼があった場合も、第 2 のウェーブを開始します。すべての作業単位が完了し、統合が終わるまで停止しません。
6. 信頼する前に検証します。 ワーカーの Status: success は主張であり、証拠ではありません。統合に含める前に、再確認可能な情報と照らし合わせて各引き継ぎを検証してください。以下の「検証」と references/verification.md を参照してください。
7. 分解とはエントロピーを減らすことです。 曖昧な目標はエントロピーが高く、複数の計画がどれも当てはまる可能性があります。作業単位に分割する前に、まず選択肢を絞り込むことがあなたの役目です（ローカルで調べ、次に利用可能なリソースを確認し、そのうえで必要な場合にのみユーザーに尋ねます）。エントロピーの高い目標を分割すると、作業単位が重複したり、範囲が適切でなくなったりします。「エントロピーを優先した分解」を参照してください。

エントロピー優先の分解

作業を分担する前に、目標をエントロピー削減の問題として捉えます。把握している情報で成り立つ、もっともらしい解釈や計画の数を減らしてください。曖昧でエントロピーの高い依頼（「Flappy Bird のゲームを作る」「アプリを高速化する」など）は、まだうまく分割できません。まず不確実性を減らし、エントロピーの低い形にしてから分解します。何が不確かなのかを明確にしてください。次の2種類は、解消方法が異なるためです。

• 仕様に関する不確実性 — ユーザーが何を望んでいるか（曖昧な目標、不足している受け入れ基準、明示されていない制約）。明確な前提を示して進めることで解消します。ただし、誤った推測による損失が大きい場合に限り、質問してください。
• 環境／知識に関する不確実性 — まだ把握していないものの、取得できる事実（リポジトリの構成、スキーマ、API の動作、最新のドキュメント、データ量）。質問ではなく、情報を集めて解消してください。

まず、もっとも少ないコストで最大の確実性が得られるアクション、つまり情報利得の段階的な手順を使い、不明点への調査を行います。回答によってもっとも多くの計画が候補から外れる不明点を優先してください。もっとも情報量の多い質問とは、残っている解釈をおおよそ半分に絞れる質問であり、もっとも簡単に調べられる質問ではありません。

1. まずローカルで調べます（低コスト）。 メインセッションでツールを呼び出し、一覧を確認したり、スキーマ／README を読んだり、grep を実行したり、データをサンプルしたりします。これがエントロピー削減として捉え直したステップ 0 です。多くの場合、コストをかけずに不確実性の大半を解消できます。
2. 次に、接続済みのリソースを確認します。 環境内に答えがない場合は、少人数の調査チームを立ち上げ、Web、Exa/Ref MCP、ドキュメントなどから情報を取得します。読み取り中心の作業は、低コストで高速なモデルに割り当てます（「作業ごとのモデル選び」を参照）。
3. ユーザーへの質問は最後に、必要な場合だけ行います。 残っている仕様に関する不確実性が高く、質問で得られる期待情報利得が明らかにコストを上回る場合に限って質問してください。ほとんどの依頼は、前提を明示すれば進めるだけの情報を含んでいます。質問しすぎること自体が失敗の原因になります。

次に段階的に展開します。大まかな依頼を、分解の波（理解 → 不明点の特定 → 計画の草案作成）に変え、検証したうえで、順序立てたサブタスクを進める実行の波へ移ります。エントロピーが高いままの箇所では、追加の調査の波を設けます。計画は易しいものから難しいものへと並べ、まず最初の段階のサブタスクから着手します。検証済みの結果で次の作業の不確実性を下げていきます。進行中の計画は TodoWrite で管理し、実行できる程度にエントロピーが低くなったら、それ以上の削減は止めます。検証の段階では、「確約できる程度に不確実性が低いか」も確認します。注意点として、計画を立ててから実行する方法で解消できるのは、手順の不足であり、目標の読み違いではありません。誤った捉え方を見つけられるのは、前述の仕様確認だけです。そのため、計画より先に行います。（具体例、波の構成、論文に基づく説明：references/examples.md。）

ループ

波の進行を見えるようにするため、TodoWrite で管理します。

ステップ 0 — まず発見する（メインセッションで順次実行）

何も調べずに作業を分担してはいけません。メインセッションで低コストのツール呼び出しをいくつか行い、ディレクトリの一覧表示、スキーマの確認、データのサンプル、対象範囲や規模の確認などを通じて、問題の全体像を把握します。こうすることで、自然な分解の形（チャンク数、作業の流れ）がわかります。事前調査を省くと、作業範囲が重複したり、分割の規模が適切でなくなったりします。

ステップ 0.5 — データを準備する（リモートにある場合や整理されていない場合）

explore ワーカーは設計上読み取り専用で、読み取り専用モードではすべての MCP ツールがブロックされます（Cursor スタッフ確認済み）。そのため、データベースや MCP を介したソースにはアクセスできません。ソースがリモートにある場合や、ノイズに埋もれている場合は、オーケストレーターが並列処理に着手する前に、クリーンな入力を準備する必要があります。

• リモートからローカルに取り込む。 SSH／rsync／エクスポートを使って、関連データをローカルのスクラッチディレクトリにコピーし、読み取り専用ワーカーが読み込めるようにします（例：リモートの SQLite を読み取り専用でクエリし、行をエクスポートする、Markdown を rsync する）。
• 一元的に一度だけクリーンアップして正規化する。 ラッパー、定型文、バイナリデータ（base64、ログ）を取り除き、タイムスタンプを修正します。すべてのワーカーに同じ処理をやり直させるより、一度だけ実行するほうが効率的です（ワーカーのコンテキストにノイズが入り込むのも防げます）。
• ワーカー向けにあらかじめ分割する。 各プロンプトで単一のパスを指定できるよう、ワーカーごとのファイルまたは範囲に分割します。
• 実行ごとにスクラッチディレクトリを 1 つ用意する。 準備した入力、ワーカーの成果物、各ウェーブ間の統合結果を 1 か所にまとめます（例：.waves/<run>/ に staging/、handoffs/、synthesis-wave-N.md を置く）。そうすることで、プロンプトでは内容を貼り付けずにパスを指定でき、後続のウェーブではチャット履歴ではなくファイルを読み直せます。
• 起動前に検証する。 件数と各スライスの範囲を出力し、分割した合計が全体と一致することを確認します（例：8 チャンク × 約 388 件 = 3,097 件）。これにより、どのスライスも気づかれないまま見落とされる事態を防げます。異常（ソート不良、重複など）は一元的に修正してから、もう一度確認します。（詳細：references/verification.md §1。）

実際には、この逐次的な準備が最も時間のかかるフェーズになることもよくあります。入力をクリーンにしておけば、並列処理への展開は迅速です。

ステップ 0.7 — トリアージ：実行規模を決めてから、各スライスを分類する

まず実行規模を明示して決めます。 範囲の広さ（独立したスライスの数）、深さ（各スライスで必要な推論の量）、曖昧さ（目標がどれだけ明確に定義されているか。「エントロピー優先の分解」を参照）、重要度（誤った回答によってどれだけ大きな損害が生じるか。これは検証レベルを決めます）を考慮し、ワーカーを起動する前に、選んだ構成を 1 行で示します。例：実行構成：1 ウェーブ、ワーカー 4 件（調査 3 件＋データ分割 1 件）；引き継ぎで不足が判明した場合のみ、第 2 ウェーブを実施。 2 つの構成で迷った場合は、小さいほうを選び、そのことを伝えます。また、トリアージの結果、ウェーブが不要であれば、インラインで作業し、そのように伝えます。インラインでの作業を、ウェーブで対応したかのように示してはいけません。

次に、各スライスを3 つの軸で分類します。これは分類して振り分けるパターンで、適切な作業を適切なハンドラーに割り当てます。

• ワーカーの種類 — 読み取り専用（explore）／ウェブ調査（generalPurpose）／シェル／競合試行（best-of-n-runner）／専門レビュー（bugbot、security-review）。（「subagent_type の選択」の表を参照。）
• 依存関係 — このスライスが検証済みの出力を必要とする他のスライス（該当する場合）。ほとんどのスライスには依存関係がないはずです。ウェーブを分けるのは、実際に依存関係がある場合です。
• 検証レベル — スライスの重要度に応じて必要な確認の程度：自動承認（重要度が低く、裏付けがある）→ 検証者 1 名（中程度）→ 複数モデルのパネル（重要度が高い）→ ディベート（意見が分かれ、正解が定まっていない）。一律ではなく、誤った主張による損失が大きい箇所に検証の予算をかけます。

トリアージ結果はウェーブマニフェストとして記録します。ワーカーの起動前に、スライスごとに 1 行記入します（TodoWrite または .waves/<run>/manifest.md）。

slice	scope	worker type	model	depends_on	verification tier
1	msgs 1–500	explore	(default fast)	—	auto-accept
2	voice-stack research	generalPurpose	(default)	—	single verifier
3	voice build spike	generalPurpose	(default)	2	single verifier

depends_on によってウェーブの境界が定まります。ウェーブとは、依存関係がすべて満たされている未実行のスライスすべてを指します。依存関係が満たされたと見なされるのは、引き継ぎ内容が返されただけでなく、検証された場合のみです（ステップ 3）。依存関係のないスライスをウェーブ 1 として並列に起動します。依存するスライスは、要点をまとめた検証済みの調査結果（またはその .waves/<run>/ パス）を、自己完結したプロンプトに含めて起動します。無関係なスライスは並列のまま進めます。マニフェストは完了ゲートでもあります。N 行を起動した場合、統合に進む前に N 件の引き継ぎをすべて受け取り、確認済みにする必要があります。引き継ぎが 1 件でも欠けたウェーブには、見落とされた穴が残ります（ステップ 3）。

ステップ 1 — 独立したスライスに分解する

スライスが独立するよう、適切な軸に沿って分割します。

• データ分割 — 大量のデータを分割し、各ワーカーに重複しない範囲を割り当てます（例：メッセージ 1–500、501–1000、…）。
• ワークストリーム — 調査や分析の領域を分けます（例：「音声スタックを調査する」、「Notion SDK を調査する」、「認証コードを監査する」）。
• ファイル／モジュール — 重複しない個別のパス集合に分割します。

各スライスには、1 行で示す範囲、確認対象、明確に定義された出力が必要です。大規模なウェーブ（おおよそワーカー 5 件以上）の場合は、ワーカーを起動する前に分解計画をユーザーに伝え、簡単に修正できるようにします。スライスが多数ある場合は、実用的な同時実行数の上限内に収まるよう、一度にすべてを起動するのではなく、ウェーブごとに分散します（バッチを起動し、完了を待ってから次を起動します）。

Step 2 — 並列でファンアウトする

依存関係が満たされたスライスごとに（ハンドオフが返ってきただけでなく、検証済みであること）、Task ツール呼び出しを複数含む1つのメッセージを送信します。これにより並行して実行されます（公式に文書化されている並列実行の仕組みです）。スライスごとに subagent_type を選択します（下の表を参照）。各タスクに3〜5語の description と、必須のハンドオフ形式で終わる自己完結型の prompt を指定します。

バックグラウンド実行の方法は、利用するサーフェスによって異なります。文書化されている切り替え方法は、カスタムサブエージェントのフロントマターに指定する is_background: true フィールドです。呼び出しごとの run_in_background: true パラメーターは一部のサーフェスに存在しますが、文書化されていません（クラウドエージェントなど、存在しないサーフェスもあります）。スキーマに公開されている場合は渡し、それ以外では当てにしないでください。バックグラウンドワーカーは完了通知に最終メッセージを含めます。（/multitask はユーザー向けの別個の Agents Window コマンドであり、このスキルの仕組みではありません。）

ワーカーがバックグラウンドで実行される場合は、そこでターンを終了します。 完了するたびに通知されます。AwaitShell を使ったり、ポーリングしたり、ループで出力ファイルを読み込んだりしないでください。Task 呼び出し自体で起動が確認できます。サーフェスが Task 呼び出しを同期実行する場合も、バッチは並行して実行され、まとめて返されます。

Step 3 — 収集して統合する

まず完了条件を確認します。 ウェーブマニフェストと照合し、すべてのハンドオフにチェックを付けます。N 個を起動したなら、N 個すべての結果を確認します。ワーカーが返答しない、エラーになる、または partial／blocked で戻る場合、そのウェーブには欠落があります。そのまま統合すると、スライスが黙って抜け落ちます。ワーカー失敗時の段階的な対応： (1) もう一度タスクを割り当て、範囲を絞ります。スライスに継続作業だけが必要なら同じワーカーを再開します（各 Task はエージェント ID を返し、その ID で再開するとコンテキストが保持されます。完了済みのサブエージェントはチェックポイントを保持するため、ワーカーの完了後でも再開時に以前のコンテキストが復元されます）。または、返ってきた内容を伝えて範囲を絞り、新しいワーカーを起動します。再開は、同じスライスの継続に限ってください。再開したワーカーは以前のスライスのコンテキストを引き継ぐため、無関係な割り当ての妨げになります。(2) 再度失敗した場合は、メインセッションでそのスライスを自分で処理します。(3) それでもブロックされたままなら、そのスライスを not-covered と明記して統合に含めます。欠落したスライスを、網羅できているかのように平均化してはいけません。

ハンドオフが届いたら、それぞれを読みます。Status を確認し、Key findings を抽出し、Open questions／Suggested follow-ups を精査します。それぞれの箇条書きが第2ウェーブのタスクになる可能性があります。ワーカー間の矛盾を整理します。

success と書かれているからといって、ハンドオフを信用してはいけません。 各調査結果の根拠（引用されたファイルと行番号／URL／指標）を検証し、参照先が実在して主張を裏付けていることを確認します。見出しとなる数値は原資料から再集計し、確信度が低い主張、矛盾する主張、引用の多い主張は検証担当者に回します（Step 3.5）。下記の「検証」を参照してください。ウェーブのハンドオフは、これらの確認に合格し、かつマニフェストの段階要件で検証担当者が必要なすべての主張について判定が返ってきた場合にのみ、検証済みとして扱います。簡単な確認だけでは、single verifier 以上の段階要件は満たされません。

その後にのみ、区切りで要約を圧縮します。 要約した内容を .waves/<run>/synthesis-wave-N.md に書き込み、そのファイルを基に作業します。次のウェーブのプロンプトでは、スクラッチディレクトリ内のパスを指定し、生のハンドオフを再貼り付けしません。このファイルは依存するスライスや後続のウェーブが参照するため、未検証の内容を調査結果として含めてはいけません。判定待ちの主張は、明示的な pending-verification の行としてのみ記載します。

圧縮後も制約を固定しておきます。 ウェーブマニフェスト、停止条件／予算、安全性や範囲に関するルールは、すべての統合ファイルとウェーブ間の要約に原文のまま引き継ぎます。言い換えたり要約したりしてはいけません。コンテキストの圧縮により、コンテキスト内の制約が気付かないうちに失われます（実測では、圧縮後に違反率が0%から30〜59%に上昇し、固定すると0%に戻ります — arXiv 2606.22528）。停止条件が圧縮で失われた実行は、ループするか、ランダムに終了する実行です。

ステップ 3.5 — 検証パス（ティアで必要とされる場合）

ウェーブの統合結果を書き始める前に、マニフェストのティアが single verifier 以上のすべての主張について、専任の検証担当ワーカーを起動します。また、異論が出ている、意外である、単一の情報源しかない、または信頼度が低い主張も対象にします。各検証担当者には、主張と引用された情報源のみを渡し、生成側の推論や作成者ラベルは渡しません（「Verification」を参照）。検証担当者は、その結果を待つ間に周辺の下書きを進められますが、判定結果が必要なのは最終成果物だけでなく、ウェーブの統合そのものです。判定が返るまでは、主張を synthesis-wave-N.md に記載できるのは、明示的な pending-verification の行としてのみです。確定した所見として記載してはならず、依存するスライスのプロンプトにも含めてはなりません（ステップ 0.7 の「検証済みの場合にのみ充足」ルール）。

ステップ 4 — 第 2 ウェーブ以降（継続的な進行）

引き継ぎによって不足や追加確認事項が明らかになった場合、または検証済みの引き継ぎによって依存するマニフェストのスライスが実行可能になった場合は、同じ方法で別の並列ウェーブを起動します。pending のスライスがなくなり、新たな事項も見つからなくなるまで繰り返します。真に追加確認事項が残っているのに早期に停止することこそ、このスキルが防ぐ失敗パターンです。停止の判断基準は、マニフェストと明示された予算（「Bounded waves」を参照）であり、「すでに 1、2 回ウェーブを実施したから」ではありません。

追加確認のウェーブを省略してよいのは、次の 3 つの場合に限られます。判断時には、該当するケースを明記してください。残っている未解決項目が一次情報源で検証済み（検証担当者が証拠を上回る検証はできない）、時期依存（外部イベントが起きるまで解決不能で、明示的な未解決項目として引き継ぐ）、または真に意見が分かれている（独立した質の高い情報源同士で見解が異なり、さらにサンプリングしても好みの問題は解決しないため、相違点を記録する）のいずれかです。

ステップ 5 — 提出

すべての引き継ぎ内容を統合し、ユーザーが求めた単一の成果物（ロードマップ、レポート、要約、計画）にまとめます。役立つ場合は、どのワーカーがどの所見を出したかを引用し、各主張の信頼度（verified / single-sourced / unverified）も維持します。low を確信に満ちた文章に変えてはなりません。

その後、コードやファイルは自分で作成するか、専用の実装ウェーブを起動します（「Parallel writes」に注意）。引き継ぎ内容だけでなく、成果物そのものを検証してください。提供された成果物を再実行／curl／検証し、関連するルートのリグレッションを確認し、自分が作成した重要なファイルを読み直します（references/verification.md §6 を参照）。

境界を設けたウェーブ — 規模、予算、停止関数

ウェーブには意図的に境界を設けます。ただし、境界はウェーブ数ではなく、完了と予算によって定めます。「完了するまでループする」方式で際限なく実行すると、ほとんど成果がないままトークンを消費します。候補の生成は安価ですが、選定による改善は頭打ちになり、ラウンドを重ねても単調に良くなるとは限りません。反復を増やすことで、コストが上がるだけでなく、品質が低下することもあります。同じくらい現実的なのが、マニフェストに未完了のスライスが残っているのに停止するという逆の失敗です。境界を設けたウェーブなら、探索は維持しながら暴走を防ぎ、終端状態に至っていない作業を放棄することもありません。

• 幅：1 ウェーブあたり N = 3〜8 個のワーカー。 N 個すべてを完全に検証できる規模に設定します。安価な自動チェック（テスト、スキーマ、実行など）で結果を判定できる場合に限り、幅を広げます。（根拠：同質なエージェントチームは N≈4〜8 で頭打ちになり、ワーカーを増やしても重複する根拠が増えるだけです。上限を超える鍵は人数ではなく多様性です — arXiv 2606.02646、2602.03794。実務面では、Cursor のスタッフがサブエージェントに固定上限はない一方、約 40 個のワーカーを同時に実行すると拡張ホストに過負荷がかかることを確認しています。そのため、ウェーブに分けてください。）
• 深さ：マニフェストが停止関数です。 マニフェストのスライスに終端状態でないものがあり、かつ直近のウェーブで検証済みの進捗があった場合は、拡張を続けます。停止するのは、次の 3 つのいずれかに該当する場合だけです。完了（すべてのスライスが終端状態にあり、統合も完了）、停滞（ウェーブで新たな情報が見つからず、出力が直前のウェーブとほぼ重複している、または品質が低下した）、予算の枯渇です。実行の形を示す行で、予算を最初に明記してください。ウェーブ数ではなく、ワーカーまたはトークンの予算を指定します（例：budget: ~20 workers）。ウェーブ数がきりのよい数字に達したからといって停止しないでください。現実的な実行では、3 つのウェーブにわたって 12 + 3 + 1 個のワーカーを使うこともよくあります。また、目標が曖昧な場合は、分解を重ねる過程でウェーブが増えるのも当然です。（根拠：完了度のしきい値、収穫逓減、トークン予算に基づいて停止する、検証主導の再計画ループ。固定の反復上限ではありません — arXiv 2603.11445。品質を同等に保つ場合、収束に基づく停止は固定の max_iterations を使うより優れています — arXiv 2606.27009。）
• 探索は安価です — 予算を使い切らないようにしてください。 エントロピーを低減するウェーブ（探索、分解）は安価なモデルで実行し、実行予算とは別に計上します。実行を始める前の探索で上限を使い切ったことを理由に、「ウェーブが残っていない」として実行を終えてはいけません。
• 予算の配分：生成に約 60％、検証に約 40％。 選定が希少なリソースです。そこに予算を使ってください。
• 難易度に応じて幅を調整します： 易しい → 1 + 軽い調整、中程度 → 3〜5、難しい／自由度が高い → アプローチの多様性を確保するため 5〜8、最難関／新規性が高い → ループせず、モデルを上位に切り替えます。
• 汚染を防ぐ引き継ぎ： 次のウェーブに引き継ぐのは、要点をまとめて検証済みの情報（採用候補と短い批評）のみとし、生のトランスクリプトや不採用候補は決して渡しません。長く無関係なコンテキストは、推論の質を実際に低下させます。

「完了するまでループする」方式が正当化されるのは、次の条件をすべて満たす場合だけです： 安価で信頼性の高い、おおむね真の正解を確認できる検証手段があること。シグナルが明確で、実際の行動につながること（「もっと頑張る」ではなく、テストの失敗など）。各反復で測定可能な進捗があること。作業の難易度が易〜中程度であること。そして、厳格な上限を設けること。これは、テスト付きのコード作成や、実行フィードバックを使うパイプラインには適しています。一方、自由度の高い研究、執筆、設計には適しません（そうした作業は境界を設けたウェーブで検証してください）。

検証

オーケストレーターにとって、最も効果の大きい仕事です。推論時にワーカーを賢くすることはできませんが、引き継ぎの検証は成果物の作成よりはるかに低コストです。また、複数のウェーブで実行する場合、確認されていない不適切な引き継ぎがひとつあるだけで、最終的な統合にまで悪影響が及びます。

• 起動前にゲートを設ける — 件数、カバレッジ、分割の合計（Step 0.5）。
• 引き継ぎごとに低コストのチェックを行う — 根拠が提示され、解決可能か、スコープが一致しているか、矛盾がないかをざっと確認し、引用が実際に主張を裏付けているかを確かめます。
• プロンプトに自己チェックを含める — 根拠がなければ削除する、確信度タグを付ける、「完全に」読む、最新の情報源を使う、未検証であることを明示する。（自由形式の「もう一度自分で確認してください」に頼らず、判定基準や独立した検証者を用意してください。）
• 重要度が高い、意見が分かれる、または引用が多い主張には、専任の検証ワーカーを使う — 主張と情報源を渡しますが、生成側の推論や作成者ラベルは渡しません（自身の成果物と示された出力を判定者は好むため、作成者を伏せます）。判定を下す前に、評価基準や参照資料に照らして推論させます（参照資料に基づく推論とCoTの組み合わせは、信頼できる判定者にするための最も低コストな改善策です）。生成側には検証者の評価基準を絶対に見せないでください（不正な対策を防ぐためです）。最も重要度の高い判断には、複数モデルのパネルと統合による、さらに厳密なチェックを使います（「複数モデルへのファンアウト」を参照）。
• 測定して相互確認する — 判定基準を再実行し、情報源から数え直し、主張を実際に含意する独立した情報源を2つ以上求めます（引用があることと、引用が主張を裏付けていることは同じではありません）。
• 確信度が低い、または調査結果に食い違いがある場合は、無理に統合せず、エスカレーションする（より条件を絞ったプロンプトで再依頼 → 専任の検証者 → 強力なモデルを選ぶ可能性もあるユーザーに確認）。

最も効果を発揮するのは、客観的で検証可能な作業（件数、コード、情報源に基づく事実）です。好みや判断が関わる場合は、部分的な主張を検証し、評価を偽造しないでください。主張は正確に保ちましょう。分離によってエラーの伝播や経路依存性は軽減されますが、「汚染を防ぐ」と定量的に主張してはいけません。分離だけを対象としたアブレーションはありません。完全な手順書については、references/verification.md を参照してください。

subagent_type の選び方

スライスの内容	使用するもの	備考
読み取り専用のコード／データ探索	explore	高速で、設計上読み取り専用です。また、読み取り専用モードではすべての MCP ツールがブロックされます。詳細度として「quick」／「medium」／「very thorough」を指定します。
Web／MCP（Exa、Ref、ドキュメント）を必要とする調査	generalPurpose	複数ステップの作業で、利用可能な Web／MCP ツールを使用できます。readonly: true は設定しないでください（読み取り専用ではすべての MCP がブロックされます）。
読み取りと軽い推論を組み合わせた複数ステップの作業	generalPurpose	汎用の主力です。
シェル／git を多用する調査	shell	コマンド実行のスペシャリストです。
ブラウザーのテスト／UI の検証	browser-use	画面遷移とスクリーンショットを行います。ステートフルで、共有インスタンスを自動的に再開するため、browser-use を並列に複数起動しないでください — UI 作業は単一のスライスで順番に実行します。エージェントモードが必要です（readonly ではありません）。
同じタスクに対する複数の競合する試行	best-of-n-runner	それぞれが分離された git ワークツリー／ブランチで実行されるため、共有チェックアウトを破壊せずに安全に試行できます。その後、試行結果を比較し、最良のものをマージします。

サーフェス間での名称の揺れ。 Cursor のドキュメントでは組み込みの値を explore、bash、browser と説明していますが、Task ツールのスキーマでは サーフェスによって異なる値（generalPurpose、explore、shell、browser-use、 best-of-n-runner、レビュー専門家など）が公開されています。この表の名称を前提にせず、 Task ツールから現在の subagent_type の列挙値を確認してください — 役割は 安定していますが、ラベルは変わります。

カスタムサブエージェントと、型が見つからない場合のフォールバック。 カスタムサブエージェント （プロジェクトの .cursor/agents/、ユーザーの ~/.cursor/agents/、またはプラグイン提供のもの）は、 独自の subagent_type 値として表示されます。繰り返し実行する役割（検証担当者、ドキュメント調査担当者など）では、 プロンプト、固定の model、readonly、is_background の既定値を1つのファイルにまとめられるため、 定義しておく価値があります。確認済みの注意点が2つあります （フォーラムでスタッフが確認済み、ドキュメントには記載なし）：新しいエージェントファイルは Cursor を 再起動した後にのみ登録されます。また、列挙値にない型があっても、その役割を省略してよいわけでは ありません — 代わりに generalPurpose として実行し、ワーカーのプロンプトにその役割の指示を インラインで含めてください（呼び出し時に意図した model を渡します）。ネストに関する補足： プラットフォームでは現在、メインエージェントとその直接のサブエージェントがサブエージェントを 起動できます（1段階のみ追加でき、それ以上は不可 — SDK のドキュメントにも同じ上限が記載されています）。 ただし、このスキルではポリシーとして、ファンアウトはオーケストレーターだけに許可します。 ネストしたファンアウトでは、マニフェストから作業が見えなくなり、検証ゲートも機能しなくなるためです。

スライスごとのモデル選択（コスト／速度のルーティング）

モデルの選択はコストと速度を左右します。すべてのスライスに最先端モデルを使うのではなく、適切に振り分けてください。

• 調査／分解／読み取り中心の探索 → 低コストで高速なモデル。 Cursor 組み込みの explore と検索サブエージェントは、まさにこの用途に合わせて、デフォルトで Composer の高速モデルファミリー（例：composer-2.5-fast）を使用します。コードベースの理解とツールの使用に最適化されており、高速で低コストです。そのため、読み取り中心の処理はデフォルトで低コストになり、多くの場合、model を設定する必要もありません。モデルを固定するには、Task ワーカーに model: "composer-2.5" を渡すか、カスタム .cursor/agents/ サブエージェントの model フィールド（inherit | モデル ID）を設定します。GPT 系でコンテキストが短い軽量なスライスには、より高いエフォートで gpt-5.6-luna を使うと、作業単位あたりのコストを最も抑えられます。ただし、Luna に長いコンテキストの読み取りをさせないでください（OpenAI 独自の MRCR 表によると、256K 以上のコンテキストでは想起性能が大幅に低下します。大きなファイルを扱うスライスは、より高性能なモデルティアに振り分けるか、細かく分割してください）。これはエントロピー低減の主力モデルです。
• モデルごとのオプションは、モデル ID の後ろに角括弧で指定します（構文は文書化されています）： gpt-5.6-sol、claude-opus-4-8[effort=high,context=300k]、 composer-2.5[fast=false]、composer-2.5[]（空の角括弧を付けると、標準の非高速版に固定されます）。別個の「thinking」スラッグを推測するのではなく、[effort=…] を使用してください。
• 重要度の高い検証、統合、または複数モデルのパネル → 意図的に選んだ、より強力な推論モデル（例：effort=high の最先端ティア。未解決のスライスに限ってエフォートを段階的に上げます）。ユーザーからの依頼による場合や重要度が高い場合に、複数モデルのパネルを使うなら、使用するモデルを確認してください。スラッグを推測しないでください（「複数モデルへのファンアウト」を参照）。
• それ以外の場合は、ユーザーが指定したモデルを尊重してください。指定されたモデルが利用できない場合は、黙って別のモデルに置き換えず、その旨を伝えてください。

注意事項：利用可否は異なる場合があります（Max Mode、プラン、または管理者による制限によって、互換性のあるモデルにフォールバックすることがあります。Max Mode を使わない従来のリクエストベースプランでは、model の設定にかかわらず、サブエージェントは Composer で実行されます）。スラッグは変わるため、変わりやすいものをハードコードせず、Cursor のモデル選択画面で確認してください。inherit は一部の環境で信頼性に欠ける場合があるため、継承させるには model を省略してください。カスタムエージェントのモデルが重要な場合は、フロントマターでモデルを固定し、Task の呼び出しにも同じ model を渡してください。フィールドが一部の条件下で無視されることがあり（文書化されたフォールバックに加え、確認済みのバグ報告もあります）、ワーカーの出力品質に問題がある場合は、意図したモデルが実行されていない可能性を考慮してください。ここで示すデフォルトよりも、ユーザーのコストとモデルに関する希望を優先してください。

レビュー／監査のスライスでは、利用可能な場合、Cursor が専用のサブエージェント（例：bugbot、security-review、ci-investigator、ci-watcher）も提供しています。その種のスライスには、これらを優先して使用してください。

マルチモデルのファンアウト（パネル＋統合）

デフォルトのファンアウトでは、各スライスを1つのモデルで処理します。重要度の高いスライス――アーキテクチャや設計に関する判断、正確性に関するリスクの高い問題、セキュリティや監査のレビュー、重要な調査結果の統合など――では、同じスライスを異なるモデルで構成するパネルにファンアウトし、その後、判定者および統合者として処理します。

出力を単につなぎ合わせるのではなく、整合性を取ります。2つ以上のモデルが同意する見解には**「合意」、それ以外には「単独モデルの指摘」**とラベルを付け、矛盾を解消し、重複を整理して、各主張の確信度を最終回答に反映します。価値の大部分は統合の段階にあります。OpenRouter の Fusion の研究によると、性能向上の約4分の3はモデルの多様性ではなく統合の段階から生まれます。そのため、出力を貼り合わせるのではなく、統合に力を注ぎましょう。根拠として、独立したモデルのパネルに判定者と統合者を加えた構成は、難易度の高い深掘り調査の課題で、単一の最上位モデルに匹敵し、それを上回りました（OpenRouter、Surpassing Frontier Performance with Fusion、openrouter.ai/blog/announcements/fusion-beats-frontier/）。

Cursor で実行するには、同じスライスに対する兄弟関係の Task ワーカーごとに異なる model を渡し、1つのメッセージで（並列に実行し、利用可能な場合はバックグラウンドで）起動してから、結果を統合します。これはモデルの振り分けにおける重要度の高いケースです。オーケストレーターが最上位モデルを選ぶのは、ユーザーがマルチモデルでの処理を求めた場合、またはスライスの重要度が明確に高い場合のみです。そのため、使用するモデルを確認し、モデルの識別子を推測しないでください。（低コストなケース――調査や読み取り中心の作業を Composer 2.5 に振り分ける方法――については、「スライスごとのモデル選択」を参照してください。）

注意点：パネルではワーカーごとに料金がかかるためトークンコストが増え、遅延も大きくなります。定型作業ではなく、重要度の高いスライスに限定してください。対抗的なマルチモデルレビュー（レビューモデルのパネルと、1つに統合した判定結果）は、同じパターンをコードレビューに適用したものです。特に採点を行うパネルでは、異なるモデルファミリーから選んだ判定者は、単一の最上位判定者よりも人間との評価一致度が高く、自己選好バイアスとコストも抑えられます（PoLL）。効果を生むのはモデルの数ではなく、ファミリーの多様性です。

生成とフィルタリング、トーナメント

自由形式のアイデア出しや「最高の X を1つ作る」タスクでは、候補を複数生成してフィルタリングします。1回の試行だけを信用しないでください。

• まず低コストのフィルターを使う。 判定者のトークンを使う前に、正解に近い基準で候補を絞り込みます（テスト、スキーマ検証／実行、重複排除／クラスタリング）。生成は安価ですが、判定にはコストがかかります。（AlphaCode の方式：多数生成 → テストで約99％をフィルタリング → クラスタリング → 少数を提出。）
• 総当たりではなく、段階的に選抜する。 重複排除／クラスタリング → 候補の絞り込み → 最終候補どうしだけをペアごとに判定します。素朴な O(N²) のトーナメントでは、大半のトークンを勝ち目のない候補との比較に費やします。
• 実装の試行を競わせる場合は best-of-n-runner を使い（各試行を別々の git worktree で実行します）、その後、自分で勝者を確認、テストし、マージします。
• 重要度の高い判断を行う場合は、上記のマルチモデルパネルが検証のための生成とフィルタリングにあたります。
• コストを確認する。 同じコストなら、独立した試行を k 回行って多数決を取る方法、または低コストのフィルターを使う方法のほうが、通常は批評や議論を繰り返すループより優れています。反復ループにコストをかける前に、必ずこの基準と比較してベンチマークしてください。

ワーカープロンプト＝契約

ワーカーは追加の質問ができません。仕様が不十分なプロンプトは、気付かないうちに逸脱します。 各プロンプトは、一度きりの機会だと思って書いてください。すべてのワーカープロンプトには、次の内容を含めます。

1. 全体の目標（あくまで背景情報です。「目標全体を自分で担おうとしないでください」）。
2. このワーカーが担当する正確な範囲（重複しない範囲／領域／パス）。
3. 参照先（ディレクトリ、ファイル、データ範囲、使用する MCP／ツール）。
4. 返す内容 — references/handoff-format.md に記載された構造化ハンドオフ。
5. 自己検証ルール — すべての主張に出典を付けるか削除し、信頼度（high|med|low）を明記し、検証できなかった内容を示します。分析ワーカーの場合：「完全に読み込み（N 行）、行数を報告してください」。調査ワーカーの場合：「トレーニングデータではなく、最新の情報源を使用してください」。
6. 範囲の境界 — 兄弟ワーカーと重複しないよう、明示的に対象外とする内容。
7. ハンドオフのみを返し、要点を絞ること。 ワーカーの最終メッセージ全体がコンテキストになります。構造化ハンドオフのみを返し、調査結果は最大約 15 件に絞り、各項目に 1 行の根拠を添えるよう指示してください。表、ログ、完全なリストなど大きな成果物はファイルに書き込み、本文に貼り付けず、パスを記載するよう伝えてください。
8. 編集ワーカー：あなた以外にも作業者がいます。 実装範囲を担当するワーカーには、兄弟ワーカーも作業中の可能性があることを警告してください。指定されたパスのみを担当し、他の変更を元に戻さず、自分でサブエージェントを起動しないでください（振り分けを行うのはオーケストレーターのみです）。

コピーして使えるワーカーハンドオフのテンプレートについては references/handoff-format.md を、完全な実行例（スクリーンショットにある health-coach の調査タスク）と再利用可能な分解レシピについては references/examples.md を参照してください。

並行書き込み（ローカル環境での注意点）

ローカルのサブエージェントは、同じ作業ディレクトリを共有します。 重複するファイルへの同時書き込みは、互いの変更を上書きします。

• 並行する読み取り／調査／分析：常に安全です。通常はこの方法を使います。
• すべての変更を採用する、互いに重複しない編集：パスの集合が厳密に重複しない場合に限り、通常のワーカーを使用します。それ以外の場合は、調査の各段階が終わってから順番に編集します。
• 同じタスクへの競合する試行：best-of-n-runner を使用します（各ワーカーはそれぞれ独自の git worktree／ブランチで作業）。その後、選んだ結果を自分で確認、テスト、マージしてください。worktree が防ぐのは上書きであり、マージの競合ではありません。

クラウドオーケストレーションの代わりに Waves を使う

Waves は、クラウドへの作業分散につなげるための段階ではなく、意図的にその代替手段として設計されています。このスキルが対象とする調査、監査、データ分析、探索、範囲を限定した実装といった作業は、ローカルのサブエージェントで一通り対応でき、隔離、並列処理、中断後の再開、検証も可能です。また、クラウドで必要となる個別の VM、API キー、ランタイムの設定も要りません。Cursor チームのクラウド orchestrate プラグインから残すべき教訓は、すでにこのスキルに取り入れられています。プランナーは計画し、ワーカーは上位へ引き継ぎ、相互に連絡せず、ディスク／git を永続的な媒体とします。Waves の実行でクラウドエージェントを起動しないでください。実行が本当に 1 台のマシンでは収まらない規模（数日間にわたる大規模運用、タスクごとに PR を作成するパイプラインなど）なら、それはユーザーが選ぶべき別のツールです。その旨を伝え、判断を委ねてください。

ここに記載した Cursor のサブエージェントの仕組みは、2026-07-19 時点の最新ドキュメント、変更履歴、スタッフフォーラムの返信で確認済みです。同じメッセージ内で複数の Task を呼び出す方法が、ドキュメントに記載された作業の振り分け方法です。is_background frontmatter がドキュメントに記載されたバックグラウンド実行の切り替え方法です。一方、呼び出しごとの run_in_background は実際に使えますが、ドキュメントには記載されておらず、利用できないインターフェースもあります。完了したサブエージェントは再開用のチェックポイントを保持します（CLI release 2026-07-06）。ネストは追加で 1 階層までです。読み取り専用モードでは、すべての MCP がブロックされます。ドキュメントに記載された同時実行数の上限はありませんが、スタッフによれば、約 40 個のワーカーを同時に実行すると拡張機能ホストに過負荷がかかる可能性があります。そのため、複数の段階に分けて実行してください。特に変更されやすい詳細は、Task のパラメーター名、subagent_type の列挙値、モデル ID の角括弧オプションです。実行内容に関わる場合は、これらを再確認してください。

チェックリスト

• 分解する前に、問題の全体像を把握しました。
• 分割する前にエントロピーを下げました（まずローカルで調査し、次に添付リソースを確認し、それでも価値がある場合にのみユーザーに質問しました）。エントロピーの低い目標を分割しました。
• 起動前に実行の形を一行で示しました（迷った場合は、より小さな形を選びました）。インライン作業を複数ウェーブでカバーしたかのように見せることはありませんでした。
• 各スライスをトリアージしました（ワーカーの種類、依存関係、検証ティア）。
• 調査／読み込み中心のウェーブには、低コストで高速なモデル（Composer 2.5、または短いコンテキストのスライスに限り gpt-5.6-luna）を割り当てました。重要度の高いスライスには最先端モデル／パネルモデルを確保し、Luna クラスのモデルに長いコンテキストの読み込みをさせませんでした。
• スライスは独立しています（データ／領域／パスが重複していません）。独立していない場合は、depends_on の依存関係をマニフェストに記録しました。
• 起動前にウェーブのマニフェスト（スライス／ワーカーの種類／モデル／depends_on／検証ティア）を作成しました。依存するスライスは、依存先の引き継ぎ内容を検証した後にのみ起動し、要点を抽出した調査結果をプロンプトに反映しました。
• 各ワーカーのプロンプトは完全に自己完結しており、チャット履歴に依存していません。
• 各ウェーブの Task 呼び出しはすべて一つのメッセージで送信しました。実行環境が対応している場合は、バックグラウンドで実行しました（is_background ／ run_in_background）。
• バックグラウンド処理の完了を待つためにターンを終了しました。ポーリングループは使用していません。
• 並列ワーカーが同じパスに書き込むことはありません。
• 起動前にカバレッジを検証しました（件数／範囲／分割合計）。
• 収集時にマニフェストの各行を確認しました（完了ゲート）。スライスが欠落またはブロックされている場合は失敗時の手順を実行し、スライスを黙って破棄することはありませんでした。
• すべての引き継ぎ内容を読み、未解決の質問について後続処理を起動しました。
• ウェーブはマニフェストと明示した予算の範囲内に収めました（幅は約3～8、調査ウェーブは別途計上）。スライスが未完了で進捗が検証されている間は続行し、完了、停滞、または予算到達の場合にのみ停止しました。後続処理を省略した場合は、「第2ウェーブを行わない3つのケース」のどれに該当するかを明示しました。
• 要点を抽出した引き継ぎ内容だけを次に引き継ぎました。マニフェスト、停止条件、予算は、すべての統合／圧縮を通じて一字一句変えずに維持しました。
• 各引き継ぎ内容の根拠を検証しました（Status だけではありません）。確信度の低い調査結果、矛盾する調査結果、出典のない調査結果はエスカレーションしました。synthesis-wave-N.md は、判定を通過した調査結果のみを基に作成し、保留中の主張には pending-verification のタグを付け、依存するスライスには渡しませんでした。
• 最終成果物を検証しました（再実行／検証し、重要な書き込みを再読しました）。
• 引き継ぎ内容を統合し、単一の成果物を作成しました。