opencode-ensemble

OpenCode Ensemble

OpenCode Ensemble は、判断を避けるための近道ではなく、調整システムとして使用してください。並列エージェントが最も効果を発揮するのは、リードが作業の分解、順序付け、レビュー、マージ、検証を担う場合です。

基本原則

独立して検証できる作業に限り、チームメイトを起動してください。優れた Ensemble チームでは、担当範囲が狭く明確で、依存関係が整理されており、リードが結果を慎重に統合します。

Ensemble を使う場面

• 調査、実装、テスト、レビューを独立した作業単位に分割できる場合。
• 読み取り専用の調査担当が、編集開始前に不慣れなコードを把握できる場合。
• 担当範囲が重複しないように、複数のファイルやサブシステムを変更できる場合。
• リスクの高い変更について、編集前に plan_approval: true を適用する利点がある場合。
• 別のブランチを作成せずに、最終レビュアーがマージ済みの変更を確認できる場合。

Ensemble を使わない場面

• 1 人のエージェントがすぐに完了できる小さなタスクの場合。
• 作業の結び付きが強く、すべてのチームメイトが同じファイルを必要とする場合。
• リードが各チームメイトの成果物と成功基準を説明できない場合。
• ユーザーが並行した探索ではなく、一貫した設計上の判断を必要としている場合。
• 難しいというだけで、分割できないタスクにエージェントを起動したくなる場合。

リードのワークフロー

1. 並列化が妥当かどうかを判断します。
2. team_create でチームを作成します。
3. team_tasks_add でタスクを追加し、順序付けには depends_on を使用します。
4. team_spawn でチームメイトを 1 人ずつ起動します。
5. 読み取り専用の explore チームメイトには worktree: false を使用します。
6. リスクの高い実装作業には plan_approval: true を使用します。
7. ステータスを繰り返しポーリングせず、チームメイトからのメッセージを待ちます。
8. メッセージが途中で切れている場合や、結果が重要な場合は、team_results で結果全体を確認します。
9. 作業を終えたチームメイトは team_shutdown で終了します。
10. team_merge でブランチをマージし、そのまま信頼せずに差分を確認します。
11. team_cleanup の前と完了を報告する前に、プロジェクトの検証を実行します。

役割の既定値

役割	エージェント	ワークツリー	モデルの目安	用途
調査担当	explore	false	例：openai/gpt-5-mini	コードベースの把握、リスクの発見、ファイルの担当計画
実装担当	build	true	例：anthropic/claude-opus-4-7	範囲を限定した実装
QA	build	true	高性能モデル、例：anthropic/claude-opus-4-7	テスト、フィクスチャ、回帰テストの網羅
レビュアー	explore	false	例：openai/gpt-5-mini	差分レビュー、リスクレビュー、テスト漏れの確認

モデル ID は例です。現在の ID はプロバイダーに確認してください。タスクに合わせてコストを調整します。調査担当やレビュアーには安価なモデルを多数使用し、難しい作業を行う実装担当には高性能な高価なモデルを使用します。役割に応じてプロバイダーを変えてもかまいません。team_spawn では必ず明示的に model を指定してください。モデルを省略するとサーバーの既定値が使用されますが、課金対象のモデルや設定に問題のあるモデルである可能性があります。

まずはチームメイトを 2、3 人で始めてください。作業に独立した担当範囲が現在のチームメイト数より多い場合に限り、人数を増やします。

必要に応じてリファレンスを参照

• チームの構成を決めたい場合は、references/coordination-patterns.md を読みます。
• プロンプトが必要な場合は、references/prompt-recipes.md を読みます。
• 起動前、マージ、クリーンアップ、検証のゲートが必要な場合は、references/lead-checklists.md を読みます。
• 何かがおかしい、またはやり取りが多すぎると感じる場合は、references/anti-patterns.md を読みます。
• このスキルを作成または改善する場合は、references/eval-scenarios.md を読みます。

厳守事項

• タスク ID を捏造しないでください。team_tasks_add が ID を生成します。depends_on または claim_task を設定するときは、先行する呼び出しで返された ID を使用してください。
• チームメイトへのプロンプトは短くしてください。プラグインによって、チームの役割、使用可能なツール、ワークツリーのコンテキスト、必須のタスク結果形式がすでに挿入されます。
• 「バグを修正する」「テストに取り組む」のような曖昧なプロンプトをチームメイトに送らないでください。
• team_spawn、team_shutdown、team_merge、team_cleanup など、リード専用のツールを使うようチームメイトに依頼しないでください。
• チームメイトに、プレーンテキストだけで報告するよう指示しないでください。team_message を使用する必要があります。
• 結果を読み、差分を確認する前に、チームメイトのブランチをマージしないでください。
• リポジトリの検証コマンドが通るか、障害があることを明確に報告するまでは、作業を完了したと見なさないでください。
• OpenCode v2 では、チームメイトの報告と通知はトランスクリプト内の永続的な合成システム行として届きます。team_view は navigate: true を渡した場合にのみ TUI を切り替えます（必ずユーザーが明示的に求めた場合に限り、先回りして実行しないでください。ユーザーのクライアントを乗っ取ることになります）。また、team_cleanup のパージでは、確認前にプレビューへの人間の承認が必要です。

最小限の例

team_create({ name: "checkout-idempotency" })

team_tasks_add({
  tasks: [
    { content: "Map checkout webhook flow and risky files", priority: "high" },
    { content: "Implement duplicate-webhook idempotency guard", priority: "high" },
  ],
})
// Record returned IDs, for example: task_abc123 for scout and task_def456 for builder.

team_tasks_add({
  tasks: [
    { content: "Add duplicate-webhook regression tests", priority: "high", depends_on: ["task_def456"] },
  ],
})
// Record returned QA task ID, for example: task_ghi789.

team_tasks_add({
  tasks: [
    { content: "Review merged diff for correctness and missed tests", priority: "medium", depends_on: ["task_def456", "task_ghi789"] },
  ],
})

team_spawn({
  name: "scout",
  agent: "explore",
  worktree: false,
  model: "openai/gpt-5-mini",
  claim_task: "task_abc123",
  prompt: "Trace the checkout webhook flow. Report files, data model, existing tests, risks, and a smallest-safe-change plan. Do not edit files.",
})

team_spawn({
  name: "api-dev",
  agent: "build",
  model: "anthropic/claude-opus-4-7",
  plan_approval: true,
  claim_task: "task_def456",
  prompt: "Use scout's findings to implement only the idempotency guard. Commit your work and send a task-result message with files changed and tests run.",
})