saga

Saga

Saga は、中規模から大規模の機能を、いくつかの限定的な確認ポイントを除き、ほとんど人の介入なしで実装するための、自律型の仕様主導開発ワークフローです。あなたはオーケストレーターとして、粗いプロンプトを隙のない仕様に仕上げたうえで、コンテキストウィンドウをすっきり保ちながら、実装を複数のワーカーサブエージェントに委任します。

この手法の根幹にあるのは、1つの賭けです。各タスクの検証基準を契約となるほど厳密に定めた仕様があれば、ワーカーは並行して実行し、自ら検証できます。その結果、ほとんど人の手を煩わせることなく Saga を成功させられます。したがって、Saga の品質は Phase 1 で決まります。コードが1行でも書かれる前です。

基本原則

• 善意より、隙のない契約を。 検証基準が、満たせばタスクを誤って完了した可能性がほとんど残らないほど明確になって初めて、タスクを委任する準備が整います。曖昧さは敵です。実装中ではなく、計画中に解消してください。
• 曖昧さを残さない。 計画中に、すべての要件を明確にしてください。ユーザーが裁量を明示的に認めていない限り、判断をワーカーに委ねてはいけません。ワーカーに「完了」の意味を推測させてはいけません。
• オーケストレーターのコンテキストを守る。 あなたは長期にわたって調整を行うコーディネーターです。重い読み込み、調査、実装はワーカーに任せ、簡潔な報告を受け取ってください。状態はディスク上（saga ディレクトリ内の仕様ツリーと PROGRESS.md）に保持し、コンパクション後も理解を引き継げるようにしてください。状態を記憶し続けるのではなく、読み直せるようにします。これにより、コンパクションまでの時間を最大限に延ばし、実行全体を通して一貫性を保てます。
• 検証を最優先に。 すべてのタスクと Saga 全体に、あらかじめ定めた検証基準と、それを確認する具体的な方法（コンピューターの操作、対話型 CLI、またはテスト）が必要です。references/validation-strategies.md を参照してください。
• 人による確認ポイントは少数設け、ゼロにはしない。 人が仕様を承認するのは Phase 1 の終わりで、仕様だけでは本当に解決できないブロッカーがある場合に限り Phase 2 で相談し、Phase 3 では最後に人が手動で受け入れ確認を行います。

Saga ディレクトリ

各 Saga は、セッションをまたいでも保持され、新しいエージェントが再開できるように、リポジトリの外部にある ~/.sagas/ の下の専用ディレクトリに置きます。機能を表すスラッグとタイムスタンプを組み合わせて、一意の名前を付けてください。例：~/.sagas/dark-mode-20260609-0028/。ユーザーに正確なパスを確認し、記録してください。このパスが Saga の恒久的な識別子になります。

ディレクトリには、仕様ファイルのツリーと進捗ログを置きます。各階層に独自の検証基準を設けることで、1つのファイルを肥大化させずに、Saga の規模に応じて詳細度を調整できます。

~/.sagas/<saga-name>/
├── SAGA.md                      # overview, environment, saga-level exit criteria, milestone index
├── PROGRESS.md                  # live, continuously-updated execution log and current state
└── milestones/
    ├── 01-<slug>/
    │   ├── MILESTONE.md          # milestone spec + milestone-level validation criteria
    │   └── tasks/
    │       ├── 01-<slug>.md      # task spec + task-level validation criteria
    │       └── 02-<slug>.md
    └── 02-<slug>/
        ├── MILESTONE.md
        └── tasks/ ...

SAGA.md は小さく保ち、マイルストーンの索引として、Saga 全体に関わる内容だけを記載します。詳細はマイルストーンとタスクの仕様に記載します。こうすることで、コンテキストをすっきり保てます。現在調整しているマイルストーンまたはタスクの仕様だけを読み、状態は再構成するのではなく PROGRESS.md で確認してください。

仕様を作成する前に references/saga-spec-template.md を読み、そのテンプレートとフィールド定義をそのまま使用してください。

---

Phase 1 — 計画と仕様の作成（オーケストレーター + ユーザー）

目標：包括的で曖昧さのない Saga 仕様ツリーを作成します。この Phase はユーザーとの完全な協働で進めます。ユーザーが仕様を承認したときにのみ終了します。

この Phase でユーザーに質問する際は、必ず ask_user_question ツールを使用し、自由回答形式の質問ではなく、具体的な選択肢（単一選択または複数選択）を提示してください。妥当なデフォルトがある場合は recommended_option_index を設定します。自由回答形式の質問はユーザーの手間を増やし、曖昧な回答を招きます。選択肢を提示することで、明確な判断を促せます。

1. 受付と概要の整理

依頼を、問題の説明と機能のおおまかな構成をまとめた1段落に書き直します。解消する必要がある主な不明点を特定します。~/.sagas/ の下に一意の saga ディレクトリパス（機能のスラッグ＋タイムスタンプ）を選び、ユーザーに確認してから作成します。以下の内容はすべてそのディレクトリに記録します。

2. マシンとランタイムの機能を確認する

このマシン上で、またこのプログラムに対して実際に何をテストできるかを把握しないと、現実的な検証基準を定められません。まずリポジトリと環境を調べて確認し、調べても分からないことだけをユーザーに尋ねます。

• どのような種類のプログラムですか？ Web アプリ、ネイティブ GUI、TUI、CLI／ライブラリ、バックエンドサービスなどです。これによって検証方法が決まります（references/validation-strategies.md を参照）。
• コンピューターを操作できますか？ コンピューター操作／ブラウザー自動化の機能が、自分またはクラウドワーカーで利用可能か確認します。GUI／Web の検証が必要で、コンピューター操作がリモートでしか利用できない場合は、その検証をリモートワーカーに割り当てる計画を立てます。
• テスト／ビルドのツールチェーンは何ですか？ テストランナー、ビルド、リンター、型チェックのコマンドを確認します（README、CI 設定、パッケージマニフェスト、プロジェクトルールなどを参照します）。実行できることも確認します。
• 手動または対話的な検証では、プログラムをどのように実行／起動しますか？

これらの調査結果を、環境セクションの SAGA.md に記録します。ワーカーと今後のオーケストレーターは、この情報を参照します。

3. 曖昧さをすべて解消する

ask_user_question で選択肢を提示しながら、要件に曖昧さがなくなるまでユーザーとやり取りします。動作、対象範囲の境界、エッジケース、データ形式、エラー処理、対象外事項、受け入れ基準を確認します。関連する質問はまとめて提示します（1回につき最大4問）。残っている判断事項が解決するか、ユーザーから裁量に任せると明示されるまで続けます。

4. saga の完了基準を定義する

作業を分解する前に、機能全体が完成し、正しく動作していると判断できる、具体的かつ確認可能な saga レベルの完了基準を記述します。これは saga 全体の契約であり、フェーズ3の根拠となります。

5. マイルストーンとタスクに分解する

作業を、依存関係の順に並べた、まとまりのある独立した意味を持つマイルストーンに分けます。各マイルストーン内では、1人のワーカーエージェントが1回の集中した作業で完了できる範囲にタスクを設定します。各タスクには、対象範囲、担当するファイル／領域、他のタスクへの依存関係、検証基準と検証方法を指定します。機能の実際の依存関係に応じて、現実的に作業を構成します。マイルストーン内では並行実行できるタスクをできるだけ増やし、後続の作業が先行作業に依存する場合は、マイルストーンを順番に進めます。

saga ディレクトリ内に、仕様ツリーとしてこの内容を記述します。マイルストーンの一覧と saga の完了基準は SAGA.md に、各マイルストーンの詳細とマイルストーンレベルの検証基準は各マイルストーンの MILESTONE.md に、各タスクの詳細と検証基準はそれぞれのタスク仕様ファイルに記述します。各タスクの検証基準は、references/validation-strategies.md に沿って、漏れのないものにします。漏れのない基準を記述できない場合、そのタスクは要件が不十分です。タスクを分割するか、ユーザーに確認します。

6. 承認を得る

SAGA.md とマイルストーン／タスク仕様を順に説明しながら、saga の仕様を提示し、ユーザーに承認または変更の要望を尋ねます（ask_user_question を使用します）。ユーザーの承認を得るまで、フェーズ2を開始してはいけません。ここが人間による主要な確認ポイントです。

---

フェーズ2 — 実装と検証（ワーカーフリート、反復実行）

目標：ワーカーに作業を委任し、自分の作業負荷を抑えながら、マイルストーンごとに各タスクを検証基準に達するまで実行します。仕様から解決できない阻害要因がある場合に限り、ユーザーに対応を求めます。

オーケストレーションの仕組み

• 実装せず、委任してください。 run_agents を使ってワーカーを起動します。あなたは調整役であり、機能コードは自分で書きません。こうすることで、コンテキストを保護できます。

• 並列化できる単位でまとめてください。 マイルストーン内では、独立したタスクをすべて 1 つの run_agents バッチとして起動します（共通の base_prompt と、タスクごとの prompt を指定します）。依存関係のあるマイルストーンは順番に実行します。タスクの依存関係を Mermaid／DAG のメンタルモデルで考えてください。

• ローカルワーカーを分離してください。 ワーカーが同じリポジトリを変更する場合は、それぞれに専用の git worktree とブランチを用意します。saga ブランチの命名規則に従い、PROGRESS.md を参照しなくても、すべてのブランチが saga ディレクトリ、マイルストーン、タスクまでたどれるようにします。

  saga/<saga-name>/m<M>t<T>-<task-slug>
  

  例：saga/dark-mode-20260609-0028/m1t2-setup-tokens。次のコマンドで作成します。

  git worktree add ../saga-<saga-name>-m<M>t<T> -b saga/<saga-name>/m<M>t<T>-<task-slug> <base>
  

  チームまたはリポジトリにブランチの接頭辞に関する規約（ユーザーごとの <username>/ など）や、CI で必須となる接頭辞がある場合は、saga/<saga-name>/... の構造を保ちながら、一貫して前に付けます。これにより、ブランチを引き続き絞り込めます。ワーカー間でチェックアウトを共有したり、ユーザーの現在のブランチで作業したりしてはいけません。マージ戦略はあらかじめ決めておきます（通常は、各マイルストーンの区切りで、そのマイルストーンのブランチを統合します）。ワーカーの変更は、worktree を削除する前に、コミット、プッシュ、またはその他の方法で確実に引き継がれている必要があります。

  saga のすべてのブランチを一覧表示するには、git branch --list '*saga/<saga-name>/*' を実行します。

• コンピューター操作が必要なリモートワーカー。 タスクの検証にコンピューター操作が必要で、その操作をリモートでしか行えない場合は、コンピューター操作を有効にして、そのワーカー（または検証手順）をリモートで起動します。また、作業をリモート環境だけに残さず、確実に引き継げる成果物（プッシュ済みブランチ、ドラフト PR、簡潔なパッチ／diff など）を返すようにします。

各ワーカーに渡すタスクごとの契約

共通ルール（リポジトリのパス、ベースブランチ、ツールチェーンのコマンド、コーディング規約、検証方法、報告方法）は base_prompt に記述し、タスク固有の内容は各ワーカーの prompt に記述します。すべてのワーカーに、次の事項を指示してください。

1. 割り当てられたタスクと担当ファイルだけを実装します。
2. タスクの検証基準に照らして、自己検証を繰り返します。 指定された方法（コンピューター操作／対話型 CLI サブエージェント／単体テストと統合テスト）で検証します。すべての基準に合格するまで、または実際に作業が阻まれるまで、修正と検証を繰り返します。
3. クリーンアップの前に、確実に引き継げる状態にします。 ローカル git worktree を使うタスクでは、検証済みの変更をタスクブランチにコミットし、そのブランチをオーケストレーターが確認できる状態にします。リモートタスクでは、ブランチをプッシュする、ドラフト PR を作成する、または完全なパッチ／diff を返します。作業の唯一のコピーをリモートのチェックアウトに残してはいけません。有用な作業が一部でも残っている状態で阻まれた場合は、報告前に WIP コミットまたはパッチとして保存します。保存に値する作業が残っていない場合は、その旨を明記します。
4. 確実に引き継げる状態になってから worktree を削除します：git worktree remove <worktree-path> --force。ブランチまたはパッチは保持され、worktree は削除されます。古い worktree を残してはいけません。ただし、クリーンアップによって、検証済みの作業や有用な部分的成果の唯一のコピーが失われることがないようにします。
5. 簡潔に報告します。ブランチ名、コミットハッシュまたはパッチ／プッシュ済みブランチの成果物、変更したファイル、検証の証拠（テスト出力、スクリーンショット、CLI の記録）、合格または阻害中の明確なステータスを記載します。コンテキストを保護するため、調査結果は簡潔にまとめます。

検証方法の選択と適用、および十分な証拠とみなされるものについては、references/validation-strategies.md を参照してください。

オーケストレーションループ

各マイルストーンについて、順番に次の手順を実行します。

1. マイルストーンの並列実行可能なタスクをワーカーとして起動します。各ワーカーのアドレス指定可能なエージェント／実行 ID を、タスク、ブランチ、ワークツリーと併せて、すぐに PROGRESS.md に記録します。再開時に表示名だけでは不十分です。新しいオーケストレーターが進行中のワーカーにメッセージを送るには、実行 ID が必要です。
2. 報告が届き次第、内容を確認します（ワーカーのメッセージ内容を読み、ライフサイクル上の成功だけを根拠にしないでください）。サガディレクトリ内の PROGRESS.md を更新し、タスクごとのステータスと証拠へのポインターを記録します。
3. ブロックされたタスクに対処します。 ワーカーが基準を満たせない場合は、対応を決めます。スコープを見直して同じワーカーに再委任する（コンテキストは保持されます）、タスク仕様ファイル内のタスクを調整する、または、ブロッカーが仕様の真の不足や外部の判断に起因する場合に限り、選択肢を示してユーザーにエスカレーションします。エスカレーションはできる限り避けてください。通常、答えは仕様に記載されています。
4. 統合し、マイルストーンレベルの検証を実行します。 マイルストーンのブランチを統合ブランチにマージし、競合を解決して、統合後の結果で関連するテスト／検証を実行し、マイルストーン全体が成立していることを確認します。指示に反してワーカーがワークツリーを残していた場合は、次に進む前に削除します（git worktree remove <path> --force）。
5. 次のマイルストーンに進みます。

状態をコンテキスト内に保持するのではなく、必要に応じて関連する仕様ファイルと PROGRESS.md をディスクから読み直してください。作業を進めながら PROGRESS.md を更新してください。新しいオーケストレーターがサガを再開するときの信頼できる情報源であり、ログが古いとサガの状態が失われます。コンテキストがいっぱいになりそうな場合は、まず PROGRESS.md に簡潔な進捗チェックポイントを記録してください。

---

フェーズ 3 — 最終検証（オーケストレーターとユーザー）

目標：サガの終了基準を満たしていることを確認し、手動受け入れのためにユーザーへ引き渡します。

1. 利用可能な最も強力な方法を使って、サガ全体の終了基準を実行します（GUI／Web にはコンピューター操作、TUI には対話型 CLI、それ以外にはテスト／統合スイート全体を使用します）。各終了基準に対する証拠を要約します。
2. 簡潔な完了報告をユーザーに提示します。構築したもの、各終了基準の検証方法、手動で確認するための具体的な手順（実行／起動方法と確認箇所）を説明します。
3. ask_user_question を使って、手動受け入れをユーザーに依頼します。受け入れるか、具体的な問題を報告してもらいます。問題が報告された場合は、新しいタスクとして記録し、対象を絞ったフェーズ 2 のミニループ（委任 → 自己検証 → 統合）を実行してから、再度提示します。ユーザーが受け入れるまで繰り返します。

ユーザーが受け入れを確認するまで、サガが完了したものとして扱わないでください。

---

サガの再開

サガディレクトリと PROGRESS.md はリポジトリの外にあり、状態全体を記録するため、コンパクション後、新しいセッション、または引き継ぎの後でも、いつでも新しいオーケストレーターが作業を再開できます。サガの続行、再開、または引き継ぎを依頼された場合は、references/continuing-a-saga.md を読み、その指示に従ってください。

実践上の注意

• ユーザーから依頼されない限り、コミットやプルリクエストの作成は行わないでください。作成する場合は、リポジトリのバージョン管理ルールに従ってください。
• 仕様ツリーを最新の状態に保ってください。実装によってスコープや基準の変更が必要になった場合は、仕様にずれが生じないよう、該当する仕様ファイルを更新してください。
• 非常に大規模なサガ（同時におよそ 10 人以上のワーカーを使う場合）では、ユーザーのマシンのリソースを使い果たさないよう、リモート実行を優先してください。
• 求められない限り、ユーザー向けの要約で内部ワーカーのエージェント ID を明かさないでください。

参考ファイル

• references/saga-spec-template.md — サガディレクトリの構成と、SAGA.md、MILESTONE.md、タスク仕様、PROGRESS.md の正確なテンプレートです。仕様の作成前に読んでください。
• references/validation-strategies.md — 検証方法の選び方、厳密な基準の書き方、十分な証拠の収集方法です。フェーズ 1（基準）とフェーズ 2（実行）で読んでください。
• references/continuing-a-saga.md — 新しいオーケストレーターが既存のサガディレクトリを引き継ぎ、安全に再開する方法です。サガの続行／再開を依頼された場合に読んでください。