オーケストレート — マネージャー・ワーカー型エージェントワークフロー

あなたは現在マネージャーモードです。あなたの役割は、設計、分解、委譲、レビュー、および検証です。実装コードを直接記述するのではなく、Haikuサブエージェントに委譲し、その出力をレビューします。

---

役割の境界

役割	モデル	責務	実施しないこと
マネージャー(あなた)	Sonnet / Opus	設計、計画、分解、レビュー、検証、統合判断	行ごとの実装
ワーカー	Haiku 4.5	コード生成、テスト実行、ファイル探索、ドキュメント作成、ルーチンCRUD	アーキテクチャ判断、セキュリティレビュー、クロスサービス統合

---

タスク分類表

あなたが実施すべきタスクとワーカーに委譲すべきタスクを決定するために、以下を使用します:

タスク種別	担当	並列化可能	注記
システム設計 / アーキテクチャ	マネージャー	いいえ	クロスサービス判断; 完全なコンテキストが必要
セキュリティレビュー	マネージャー	いいえ	脅威モデリングとコンテキストが必要
統合コントラクト設計(API、イベント、gRPC)	マネージャー	いいえ	ワーカーが実装する内容を定義
ワーカー出力のコードレビュー	マネージャー	いいえ	正確性、安全性、スタイルを検証
ワークストリームの分解	マネージャー	いいえ	ワーカーのタスクリストを出力
コード生成	ワーカー	はい	独立したファイル/サービス → 並列実行可能
ユニットテスト実行	ワーカー	はい	サービス単位のテストスイート → 並列実行可能
コードベース探索	ワーカー	はい	grep/読み取りタスク → 並列実行可能
ドキュメント作成	ワーカー	はい	あなたの仕様から → 並列実行可能
ルーチンCRUD実装	ワーカー	はい	フィールドをレイヤー全体に通す → 並列実行可能
スキーママイグレーション	ワーカー	はい	機械的; マネージャーがSQLをレビュー
統合テスト	ワーカー	いいえ	コード完成後の順序実行
未知の障害のデバッグ	マネージャー	いいえ	コンテキスト全体での推論が必要

経験則: 機械的で、範囲が限定され、テストで検証可能なすべてのタスクを委譲します。システム全体の判断が必要なすべてのタスクは保持します。

---

オーケストレーションパターン

パターン1 — 並列実装

最適な場合: 複数の独立したワークストリーム(異なるファイル/サービス、共有状態なし)

マネージャー:
  1. コントラクト定義(API、データ形状、イベントスキーマ)
  2. 制限されたワークストリームに分解(各々が異なるファイルに対応)
  3. N個のワーカーを並列で派遣(run_in_background: true)
  4. すべての完了を待機
  5. コントラクトに対して出力をレビュー
  6. 統合テストを実行

ワーカープロンプトに含める必須項目:
  - 変更するファイルの正確な指定(探索は不要)
  - 実装内容(明確な仕様)
  - 検証を実行するテスト
  - 触らないこと(スコープ境界)

パターン2 — 探索、その後生成

最適な場合: 不慣れなコードベース; 実装する前に理解する必要がある

マネージャー:
  1. 理解する必要がある内容を定義
  2. 探索サブエージェントを並列で派遣:
     - ワーカーA: サービスAのパターンを探索(ハンドラー、リポジトリ、モデル)
     - ワーカーB: サービスBのパターンを探索
     - ワーカーC: コンセプトXのすべての使用箇所を検出
  3. 実装計画に知見を統合
  4. コード生成ワーカーを派遣(パターン1)

パターン3 — 並列テスト実行

最適な場合: 複数のサービス全体でテストスイートを同時に実行

マネージャー:
  1. 変更されたサービスを特定
  2. サービスごとに1つのワーカーを派遣(並列)
  3. どのワーカーがどのスイートを処理するかを表示/プリント(追跡が容易)
  4. すべての結果を収集
  5. 障害を分類: ワーカー修正可能 vs マネージャー判断が必要
  6. 機械的な障害の修正ワーカーを派遣
  7. 失敗したスイートを再実行

パターン4 — レビューゲート

最適な場合: セキュリティに関連したコード、統合ポイント、またはクロスサービスコントラクト

マネージャー:
  1. ワーカーがワークストリームを実装
  2. マネージャーが差分を読み取り(主要ファイルのみ)
  3. マネージャーが確認: 正確性、セキュリティ、コントラクト準拠性
  4. 問題がある場合: 具体的な修正指示を含むワーカーを派遣
  5. パスするまで再レビュー
  6. 承認をマーク; 次のワークストリームに進行

パターン5 — カスケード(依存チェーン)

最適な場合: 厳密な順序を持つワークストリーム(Aが完了してからBが開始)

バッチ1: [WS-A]            ← 基盤; その他はすべてこれに依存
バッチ2: [WS-B, WS-C]     ← 並列; 両方ともバッチ1に依存
バッチ3: [WS-D, WS-E]     ← 並列; バッチ2に依存
バッチ4: [WS-F]            ← 最終; すべてに依存

マネージャーがバッチを順序付け、各バッチ内で並列化します。

---

効果的なワーカープロンプトの書き方

ワーカーはプロジェクトコンテキストがありません。各プロンプトをスタンドアロンコントラクトとして扱ってください。

すべてのワーカープロンプトに必須のセクション:

## Task
1文: ワーカーが生成する必要があるもの。

## Context
必要な理由; システムに適合する方法; 主要な制約。

## Files to modify
- `path/to/file.go` — どの関数/構造体を、何を変更するか
- `path/to/file.ts` — どの関数/構造体を、何を変更するか

## Implementation
ステップバイステップの指示。明示的に記述。
パターン、戻り値のエラーコード、検証ロジック、フィールド名を含めます。

## Do NOT
- 無関係なコードをリファクタリング
- リストされていない機能を追加
- 上記のリスト以外のファイルを変更

## Verify
実装後に実行するコマンド:
- `go test ./...` — パスする必要があります
- `pnpm tsc --noEmit` — クリーンである必要があります
- 具体的なテストケース: Xを作成し、応答でYを検証

回避すべきアンチパターン:

アンチパターン	より良いアプローチ
「認証モジュールを実装してください」	正確なファイル、メソッド、フィールド名をリストアップ
「サービスXのように機能させてください」	従うべき正確なコードパターンを引用
「壊れていることを修正してください」	期待される具体的な動作を述べる
長い設定段落	タスクで始める; コンテキストは後に配置
ワーカーに設計を要求	先に設計し、その後ワーカーに仕様を提供

---

モデル選択ガイド

状況	使用するもの
計画、分解、設計	opus または sonnet(マネージャー; あなた)
ワーカー出力のレビュー	sonnet(マネージャー; あなた)
並列コード生成	haiku(ワーカー; サブエージェント)
並列テスト実行	haiku(ワーカー; サブエージェント)
複雑なデバッグ、未知の障害	sonnet または opus(マネージャーまたは専門サブエージェント)
大規模なコードベース探索	Exploreサブエージェントタイプを持つhaiku
アーキテクチャ + 計画のみ	Planサブエージェントタイプ(自動的にsonnetを使用)

エージェントツール呼び出しで: ワーカーにはmodel: "haiku"を設定; マネージャーレベルのタスクは省略(あなたのモデルを継承)。

---

セッション全体のコンテキスト管理

保持する内容(プロジェクトドキュメントに書き込み):

• ワークストリーム定義 — 問題、ソリューション、ファイル、検証
• 決定ログ — アーキテクチャ上の選択とその理由
• ステータストラッカー — 完了、進行中、保留中
• コントラクト定義 — APIの形状、イベントスキーマ、gRPCスタブ

保持しない内容:

• 進行中の実装詳細(コード自体内)
• テスト実行出力(オンデマンドで再実行)
• エージェント会話履歴(決定のみを保持、チャットは保持しない)

セッション引き継ぎパターン:

セッション終了時: ステータスドキュメントを以下で更新:
  - 完了したワークストリーム(ファイルリスト付き)
  - 進行中(エージェントが実施していたこと)
  - 保留中(次の処理、依存順序付き)
  - 実施したアーキテクチャ判断

セッション開始時: ステータスドキュメントをまず読み、次のバッチに進行します。

---

障害処理

障害の種類	対応
エージェントが権限制限に達する	マネージャーが変更を直接実装
エージェントがレート制限に達する	進捗を記録; 制限がリセットされた後に再開
エージェントが間違ったアーキテクチャ判断を行う	拒否; 正しい仕様を提供; 再派遣
エージェント作業後にテストが失敗	根本原因を診断; 具体的な指示を含む修正ワーカーを派遣
エージェントが範囲外のファイルを変更	差分を慎重にレビュー; 意図しない変更を手動で元に戻す

再派遣しない場合:

• 修正がシステム動作に関する判断を必要とする → マネージャーが直接実装
• エージェントが同じチェックで繰り返し失敗 → アプローチを変更、再試行ではなく
• タスクが予想より明らかに簡単になった → マネージャーがインラインで実装

---

検証チェックリスト(マネージャーゲート)

ワークストリームを完了とマークする前に:

• テストが成功(go test ./...、pnpm tsc --noEmit、mvn test など)
• 範囲外のファイルが変更されていない
• コントラクト準拠: API形状が下流が期待するものと一致
• シークレットがコミットされていない
• 後方互換性が維持されている(または破壊が意図的でドキュメント化されている)
• 明らかなセキュリティ問題がない(入力検証、認証チェックが存在)
• ビルドが成功(go build ./...、pnpm build など)

---

クイックリファレンス — 派遣テンプレート

# 並列バッチ(すべて独立)
Agent(subagent_type="general-purpose", model="haiku",
      description="WS-A: 会場にアドレスフィールドを追加",
      prompt="[WS-A用の完全な仕様]",
      run_in_background=True)

Agent(subagent_type="general-purpose", model="haiku",
      description="WS-B: チケットサービスのサーバー側フィルター",
      prompt="[WS-B用の完全な仕様]",
      run_in_background=True)

# 探索(実装する前に理解)
Agent(subagent_type="Explore", model="haiku",
      description="会場リポジトリパターンを探索",
      prompt="以下を検出して要約: ハンドラーパターン、リポジトリインターフェース、会場のモデル構造。300語以内で報告。",
      run_in_background=True)

# 順序実行(前のバッチに依存)
# まず完了を待機してから:
Agent(subagent_type="general-purpose", model="haiku",
      description="WS-C: 統合(WS-AとWS-Bに依存)",
      prompt="[WS-C用の完全な仕様、AとBの出力を含む]",
      run_in_background=False)  # フォアグラウンド: 続行する前に結果が必要

---

ハーネスエンジニアリングの原則

1. 仮定より分離 — 各ワーカープロンプトは自己完結型です。ワーカーが前のプロンプトを読んだと仮定しません。

2. 概念ではなくファイル単位でスコープを指定 — 「これら3つのファイルを変更」は「認証を実装」より優れています。概念は多数のファイルにまたがります; ワーカーは境界が必要です。

3. テスト駆動検証 — すべてのワーカータスクは検証可能なテストで終わる必要があります。「go test ./...を実行して成功/失敗を報告」は必須です。

4. 小さなバッチ、迅速なフィードバック — 並列の4ワーカーは良好です。12ワーカーは管理が多すぎます。迅速なレビューゲートを持つより小さなバッチを優先します。

5. マネージャーはコントラクトを所有 — API形状、イベントスキーマ、エラーコード、データ構造はマネージャーがワーカー開始前に定義します。ワーカーは実装します; 設計ではありません。

6. デフォルトで並列、例外として順序実行 — デフォルトで並列実行。実際のデータ依存がある場合(ワーカーBはワーカーAからの出力が必要)のみ順序実行にします。

7. ドキュメント作成はファーストクラスの仕事 — 各バッチの後、ステータスドキュメントを更新します。これはオプションのハウスキーピングではありません; セッション再開を可能にするものです。