fable-delegate

Fable Delegate

独立性が実際にある場合に並列ワーカーを使います。単にタスクが複数あるという理由だけで使ってはいけません。

ミッション

委任によって曖昧さを増やすことなく、待ち時間を短縮する必要があります。タスクの分解、契約の安定性、統合、最終確認については、親が引き続き責任を負います。

ワーカーはコンテキストを丸ごと押し付ける場所ではありません。独立して作業できるだけの根拠と、統合時にレビュー可能な成果物を返すための契約を添えて、範囲を限定した責任を一つ割り当てます。

有効にする条件

• 2つ以上のカードが、互いの判断を待たずに進められる場合。
• 専門家の視点から、独立した仮説を並行して調査できる場合。
• コンポーネントごとにインターフェースが安定しており、受け入れ確認を独立して行える場合。
• 変更を共有せずに、独立したレビューや調査を並列化できる場合。

有効にしない条件

• ワーカーが同じ不安定な契約や不変条件を変更する場合。
• あるカードの設計結果によって、別のカードの要件が変わる場合。
• 小規模なタスクで、実行するより説明や統合のコストが高くつく場合。
• 親が、ワーカーとの明確な契約を作成するために必要なコンテキストを十分に把握していない場合。
• すべてのワーカーが、未解決のアーキテクチャ上の判断に依存している場合。

独立性の分類

候補となる各ペアについて、結合度を分類します。

結合度	並列化	理由
異なるファイル＋異なる契約	通常は可	意味上の重複が少ない
異なるファイル＋共有する不安定な契約	不可	パスが分かれていても、意味上の競合が生じる
同じ統合ファイル＋別々のコンポーネント	条件付きで可。ただし統合は順番に行う	コンポーネントの作業は並列化できるが、統合はできない
共有される読み取り専用の根拠	可	所有権の競合がない
同じデータベーススキーマ／不変条件	通常は不可	あるワーカーが別のワーカーの前提を無効にする可能性がある
独立した調査仮説	可	ソースの編集ではなく、結論を統合する
どちらも親の判断が必要	不可	先に判断を解決する

委任プロトコル

ステージ 1 — 独立性を証明する

以下を確認します。

• 書き込みの所有権。
• 共有する契約／不変条件。
• 依存関係の順序。
• 生成される成果物。
• 移行／状態の結合。
• 統合時の競合箇所。
• あるワーカーの失敗によって、別のワーカーの前提が変わるかどうか。

独立性を短い段落一つで説明できない場合は、まだ並列化しないでください。

ステージ 2 — ワーカーとの契約を作成する

各契約には、以下を含めます。

• 目標。
• すでに確立したコンテキスト／根拠。
• 担当するパスまたは意味上の領域。
• 担当範囲外の作業。
• 安定していると想定する依存関係。
• 提出する受け入れ確認の根拠。
• 期待する返却パケット。
• 作業停止／エスカレーションの条件。

リポジトリ全体を渡し、境界を設けずに「Xを担当して」と頼んではいけません。

ステージ 3 — 変更の所有権を決める

意味上の領域ごとに、書き込み担当者を1人にすることを優先します。複数の読み取り専用の調査担当者が重複するファイルを確認するのは構いませんが、複数の書き込み担当者が同じ契約を独自に再定義してはいけません。

共有する統合ファイルがある場合は、コンポーネントの作業が収束した後に、親または指名した1人のワーカーが統合を担当します。

ステージ 4 — 作業を割り当て、例外に応じて監督する

すべてのコマンドを細かく管理してはいけません。以下の場合に介入します。

• ワーカーが、重大な影響を及ぼす未知の事項を発見した場合。
• 担当範囲の拡大が必要な場合。
• 受け入れ条件を満たせない場合。
• 契約の前提が誤っている場合。
• ワーカーが停滞したり、失敗を繰り返したりする場合。

ステージ 5 — 要約だけでなく、返却物を確認する

具体的な成果物を求めます。差分／パス、コマンドと結果、根拠、未解決のリスクが該当します。「完了しました」という文章だけでは、統合の根拠になりません。

ステージ 6 — 中央で統合する

親は以下を確認します。

• 統合した差分。
• 契約の互換性。
• ワーカー間の動作。
• 生成される成果物。
• 統合テスト。
• マージ／統合による変更後も、ワーカー側で得た根拠が最新であるかどうか。

判断ルール

• ファイルが異なることは、独立性にとって必要条件でも十分条件でもありません。
• 契約が安定していて実装が分離されていれば並列化できます。契約が不安定であれば、ファイルが分かれていても並列化すべきではありません。
• ワーカーが競合するアプローチを提案した場合は、親が選択するまで読み取り専用にします。両方の実験結果をむやみにマージしてはいけません。
• ワーカーが所有範囲を越える必要がある場合は、そのワーカーを一時停止し、暗黙に範囲を拡大するのではなく、契約を再調整します。
• ワーカーが失敗またはハングしても、同じプロンプトを再実行する理由にはなりません。失敗を分類し、カードを fable-recover に回すか、ローカルで実行します。
• 委任した作業がユーザーに見える単一の動作に影響する場合、親による統合検証は必須です。

不変条件

• すべての変更可能な領域には、明確な所有者がいます。
• ワーカーには、範囲を限定した判断に必要なコンテキストだけを渡します。
• ワーカーの完了は、全体の完了を意味しません。
• 共有契約の変更には、統合を担当する所有者を一人だけ割り当てます。
• すべての統合作業による変更が完了したら、統合済みのワークスペースを検証します。

失敗の分類

所有権の衝突

2人のワーカーが同じ変更可能な契約またはファイルを必要としています。並列での変更を中止し、所有権を再計画します。

意味上の衝突

ファイルは異なっていても、どちらも同じ不変条件またはスキーマを変更しています。連動する作業として扱います。

コンテキスト不足

ワーカーが、親が解決しておくべき質問を繰り返し尋ねています。契約を改善するか、発見フェーズに戻します。

範囲逸脱

ワーカーが、所有範囲外の必要な作業を見つけています。一時停止し、評価したうえで、明示的に範囲を拡張するか再計画します。

ワーカーローカルでは成功、統合後は失敗

ローカルのチェックには合格しても、統合後の動作に失敗しています。診断は親が担当します。むやみにワーカーへ差し戻してはいけません。

ワーカーの停滞

意味のある進捗がない、または失敗を繰り返しています。際限なく予算を消費するのではなく、終了または復旧します。

アンチパターン

• 「タスクが2つなら、エージェントも2つ」。
• 並列化の判断基準を、パスが重複していないことだけにする。
• すべてのワーカーに、広範なタスク全体を渡す。
• 各ワーカーが共有マニフェストやルートを個別に更新できるようにする。
• 差分や証拠を確認せず、文章による要約を受け入れる。
• 前提を確認する前に、ワーカーの成果物をマージする。
• サブエージェントに委任すれば、親の責任がなくなると思い込む。
• 親がまだ下していない判断を、単に判断を避けるために委任する。

必須の TOON 委任プロトコル

すべてのサブエージェントへの委任契約と、ワーカーからの返却パケットでは、**TOON（Token-Oriented Object Notation）**を使用する必要があります。これにより、次のことが保証されます。

1. トークン効率：冗長な Markdown／JSON と比べて、トークン数を35～70％削減します。
2. 決定論的な解析：明示的な長さタグ [N] により、親エージェントはタスクの切り捨てや脱落を即座に検出できます。
3. 構造化されたスキーマ：フィールドヘッダー {fields} により、契約への準拠を徹底できます。

ボスからワーカーへの委任契約（TOON）

contract:
  workerId: worker-1
  targetCard: CARD-101
  objective: "Implement JWT authentication guard"
ownedPaths[2]: src/auth/guard.ts,test/auth/guard.test.ts
forbiddenPaths[2]: src/config/keys.ts,.env
acceptanceChecks[2]: "bun test test/auth/guard.test.ts","bun run typecheck"
rules[2]: "Do not touch files outside ownedPaths","Use TOON format for the return packet"

ワーカーからボスへの返却パケット（TOON）

result:
  workerId: worker-1
  targetCard: CARD-101
  status: complete
  allChecksPassed: true
mutations[2]{path,action}:
  src/auth/guard.ts,modified
  test/auth/guard.test.ts,created
verifications[2]{command,result,durationMs}:
  "bun test test/auth/guard.test.ts",pass,120
  "bun run typecheck",pass,340
notes[1]: Successfully implemented guard with full test coverage

完了条件

次のすべてを満たした時点で、委任は完了です。

• すべてのワーカー契約で、所有権と受け入れ条件が明示されている。
• 返却された成果物と証拠を確認している。
• 所有権や契約の競合が解決されている。
• 統合後の差分が、現在のワークスペースでの統合検証に合格している。
• 残存する失敗が明示的に振り分けられ、ワーカーの要約に隠されていない。

段階的なリソース

• 詳細ガイド：references/parallelism-and-integration.md
• 既存の契約ガイド：references/subagent-contracts.md
• テンプレート：templates/delegation-contract.template.md
• 例：examples/parallel-workers-walkthrough.md