13eholder/zflow

Stage

概要

Stage は、一連の開発変更を連結するドキュメントです。個々のスキルの成果物を置き換えるのではなく、各スキルが何を生み出し、それらの成果物がどのような関係にあるのか、そしてこの変更全体のストーリーを記録します。

Stage は4つの質問に答えます：

1. 私たちは本来何をしようとしていたのか？（MISSION + あるべきドキュメント）
2. 実装作業はどのように安全に委任されたのか？（Task Contract 前方索引）
3. 私たちは実際に何を成し遂げたのか？（実際のドキュメント + ADR）
4. なぜ差異が生じたのか？（あるべき vs 実際の差異 + 学習サマリー）

                          STAGE.md
                   （連結層 / 索引 + ナラティブ）
                          │
    ┌────────┬────────┬────┴────┬────────────┬────────┬────────┐
    │        │             │    │            │        │        │
  MISSION  あるべきドキュメント 実装計画  Task Contract  実際のドキュメント 検証
  (目標)   (設計)      (plan+todo) (委任範囲)    (結果)    (証拠)
                                                │
                                              ADR
                                      (必須、各Stageに最低1つ)

いつ使うか

Stage の作成は完全にユーザーの判断に委ねられます。 ユーザーが明示的にリクエストした場合のみ作成され、自動トリガーはありません。

ユーザーは通常、以下のように発言します：

• "Stage を作成して" / "Stage を開始して"
• "この作業のための Stage を立てて"
• "Stage を封印して" / "Seal Stage"
• /plan の出力後、ユーザーが「Stage ドキュメントは必要ですか？」に「はい」と回答

典型的な適用シナリオ（ユーザーの参考用であり、トリガールールではありません）：

• 複数のタスクにまたがり、論理的に1つのまとまりを構成する変更
• 複数のモジュールにまたがる新機能
• 内部構造を変更するが振る舞いは変わらないリファクタリング
• 本番環境の不具合に対する完全な修正チェーン
• アーキテクチャ上の意思決定を記録する必要がある変更

自動トリガーされないもの：

• 単一の孤立したタスクや機械的な変更は自動では作成されない
• 純粋なドキュメント更新は自動では作成されない
• Agent はタスク数やモジュール横断度に基づいて自動判断しない — ユーザー確認が必要

delegated-task-contract が属するStageを必要とする場合でも、自動的にStageを作成してはいけません。Stageがまだ存在しない場合は、停止してユーザーに明示的な判断を求めなければなりません。ディレクトリの帰属、単方向索引、状態同期、封印ゲートは、すべて Stage と Task Contract 連動ルール に従います。

Stage の種類

種類	動機	成功基準	あるべき vs 実際	ドキュメントの重点
feat	新しい機能の追加	新しい振る舞いが出現し、仕様を満たす	差異があって当然、記録必須	spec + api-contract + api-doc
opt	既存の振る舞いの改善	指標が目標値に達する	最適化効果の比較を簡潔に記録	パフォーマンスベースライン + 最適化結果
debug	誤った振る舞いの修正	問題が再現しなくなり、回帰テストが根本原因パスをカバーする	あるべき=実際（修正が目標）	現象 + 根本原因 + 修正戦略 + 予防策
refactor	内部構造の変更、振る舞いは不変	既存のすべての振る舞いが変わらず、回帰テストがすべてパス	あるべき=実際は厳格な要件	アーキテクチャ設計 + 構造変更の説明

Stage のライフサイクル

/plan 出力後               実装中                    全実装完了後              /ship 実行時
     │                          │                            │                      │
     ▼                          ▼                            ▼                      ▼
  スケルトン作成            ドキュメントと Contract 索引の保守  封印 STAGE.md            Stage の存在確認
  (MISSION +              (状態、乖離、証拠サマリー)           (終了ゲート、実際のドキュメント、       (pre-launch
   あるべきドキュメントパス、                                        ADR、差異分析、          checklist
   実装計画リンク)                                          検証結果、学習サマリー)         ブロック項目)

作成（スケルトン段階）

/plan が tasks/plan.md と tasks/todo.md を出力した後、Agent はユーザーに Stage ドキュメントが必要かどうかを尋ねます。ユーザーが確認した場合：

1. stages/<stage-id>/ ディレクトリを作成する（stage-id は kebab-case の短いタイトル）
2. STAGE.md スケルトンを作成し、以下を事前入力する：
   • 種類（feat | opt | debug | refactor）
   • ステータスを draft に設定
   • 意思決定者
   • MISSION（spec から抽出）
   • あるべきドキュメントパス（TODO とマーク）
   • 実装計画リンク（tasks/plan.md と tasks/todo.md を入力）
   • Task Contracts 前方索引テーブル（初期は空）
   • 実際のドキュメント（TODO とマーク — 実装完了後に入力）
   • ADR（TODO とマーク — 各Stageに最低1つ、実装完了後に入力）
   • 検証結果（TODO とマーク）
3. stages/INDEX.md に行を追加する

充填（構築段階）

実装中：

• 通常のタスク完了時に STAGE.md を修正する必要はありません。ただし、Contract が初めて記録されたとき、ステータスが変更されたとき、または deviation / evidence が返されたときは同期が必要です。
• あるべきドキュメント（spec、api-contract）が出力されたら、対応するリンクを更新し、TODO マークを削除します。
• Contract は STAGE.md によってのみ前方索引されます。Contract に Stage フィールドや逆リンクを追加しないでください。
• none 以外の Contract deviation は「あるべき vs 実際の差異」テーブルに同期し、封印時に記憶に頼って後から記述することを防ぎます。

封印（完了後）

すべてのタスクが完了し、検証が成功したら、Agent はユーザーに封印を促します。ユーザーが確認した場合：

1. task-contract/ と索引テーブルを照合し、漏れ、無効なリンク、ステータスのずれがないことを確認する
2. すべての Contract 本文のステータスが COMPLETED または CANCELLED であることを確認する。DRAFT、READY、BLOCKED_BY_ARCHITECTURE のいずれかがあると封印を阻止する
3. 実際のドキュメントリンク（api-doc、ADR）を入力する
4. あるべき vs 実際の差異テーブル（「あるべきドキュメントを遡及更新するか」列を含む）を記入し、Contract レポートに含まれる意味のある乖離を組み込む
5. 検証結果を記入し、Contract の Required Evidence にリンクする
6. 学習サマリーを抽出する（「次回はこうする」と「次回はこうしない」）
7. ステータスを done に変更する
8. stages/INDEX.md の対応する行のステータスを更新する

チェック（リリース前）

/ship の pre-launch checklist には以下が含まれます：

• "□ 重大な変更に対応する Stage ドキュメントがあるか？" — 今回の作業で Stage が作成されていた場合、これはブロック項目

Stage テンプレート

以下は stages/<stage-id>/STAGE.md の標準テンプレートです：

# Stage: [短いタイトル]

**種類**: feat | opt | debug | refactor
**日付**: YYYY-MM-DD — YYYY-MM-DD
**ステータス**: draft | in-progress | done | abandoned | superseded | split
**意思決定者**: @username

---

## MISSION（今回の目標）

<!-- feat / opt / refactor は標準 MISSION を使用 -->

- **目標**: [今回何を達成するのかを一言で]
- **ユーザー**: [誰が恩恵を受けるか]
- **成功基準**: [完了したことをどうやって知るか — 具体的で検証可能な条件]
- **制約**: [制限事項 — 技術、リソース、時間]
- **やらないこと**: [明示的に除外する内容とその理由]

<!-- debug タイプは以下の構造に置き換え：-->
<!--
- **現象**: [ユーザーが何をしたか、何が見えたか、何が見えるべきだったか]
- **影響**: [影響範囲、継続時間、データ整合性リスク]
- **根本原因仮説**: [初期判断 — 実装完了後に確定した根本原因に更新]
- **修正戦略**: [止血策 + 根本原因修正 + 予防策]
- **成功基準**: [問題が再現しない、回帰テストが根本原因パスをカバーする、類似問題に静的チェックがある]
-->

→ 詳細は [MISSION.md](./MISSION.md) を参照

---

## あるべきドキュメント（私たちがどうする予定だったか）

| ドキュメント | ソーススキル | 説明 |
|------|---------|------|
| [spec/xxx.md](./spec/xxx.md) | spec-driven-dev | 機能仕様 |
| [design/api-contract.md](./design/api-contract.md) | api-and-interface | API 契約 |
| [design/xxx.md](./design/xxx.md) | — | [補足説明] |

> 実装開始前に入力してください。今回のラウンドで該当しないドキュメントタイプがある場合は、対応する行を削除してください。

---

## 実装計画

| ドキュメント | ソーススキル | 説明 |
|------|---------|------|
| [tasks/plan.md](./tasks/plan.md) | planning-and-task | 技術計画 |
| [tasks/todo.md](./tasks/todo.md) | planning-and-task | アトミックタスクリスト |

---

## Task Contracts（委任実行範囲）

> `delegated-task-contract` ゲートを必要とする書き込み委任のみを索引します。Contract 本文、ステータス、Required Evidence は対応するファイルを基準とします。このテーブルは前方リンクとサマリーのみを保持し、Stage への逆リンクを Contract に書き込みません。

| Task | Contract | ステータス | Deviation / Evidence |
|------|----------|------|----------------------|
| [Task ID] | [Task ID](./task-contract/TASK-XXX.md) | DRAFT \| READY \| BLOCKED_BY_ARCHITECTURE \| COMPLETED \| CANCELLED | [ブロック、乖離、証拠、またはキャンセル理由。なければ `—` と記述] |

> Contract がまだない場合は、テーブルヘッダーを残してサンプル行を削除してください。Contract が初めて記録されたとき、およびステータス、乖離、証拠が変更されるたびに、このテーブルを同期してください。

---

## 実際のドキュメント（私たちが実際にどうなったか）

> 実装完了後、このセクションを入力してください。

| ドキュメント | ソーススキル | 説明 |
|------|---------|------|
| [docs/api/xxx.md](./docs/api/xxx.md) | documentation-and-adrs | 実際の API ドキュメント |
| [docs/adr/XXX-title.md](./docs/adr/XXX-title.md) | documentation-and-adrs | アーキテクチャ意思決定記録（必須、各Stageに最低1つ） |

### ADR（必須）

各 Stage は**必ず**最低1つの ADR を生成しなければなりません。ADR は重要なアーキテクチャ上の意思決定とそのコンテキストを記録します。

| ADR | 決定内容 | 代替案 |
|-----|---------|---------|
| [ADR-XXX](./docs/adr/XXX.md) | [決定内容を一言で] | [却下された案とその理由] |

**ADR の内容要件：**
- 「なぜ A ではなく B を選んだのか」を記録する
- 検討されて却下された代替案とその却下理由を列挙する
- 決定の制約条件と結果を記述する
- その決定が既存の ADR に関連する場合は、明示的に参照する

**Stage の種類別 ADR の重点：**

| Stage の種類 | ADR の典型的な内容 |
|-----------|-------------|
| **feat** | なぜこのアーキテクチャ/フレームワーク/プロトコルを選んだのか。データモデルの設計トレードオフ。 |
| **opt** | なぜこの最適化戦略を選んだのか。なぜ他の案（キャッシュ vs インデックス最適化など）を選ばなかったのか。 |
| **debug** | 根本原因がなぜ発生したのか。なぜこの修正案を選んだのか。予防策の設計。 |
| **refactor** | なぜこの新しい構造を選んだのか。なぜ特定のエッジケースを統一しなかったのか。新旧構造の比較。 |

---

## あるべき vs 実際の差異

> 実装完了後に入力してください。計画と実際の間の意味のある乖離をすべて記録します。

Contract の `Required Evidence` レポートが `none` 以外の deviation を報告した場合、その Contract を承認すると同時に乖離をこのテーブルに同期してください。Contract にのみ痕跡を残さないでください。

| 差異 | あるべき（計画） | 実際（結果） | 理由 | あるべきドキュメントを遡及更新するか |
|------|------------|------------|------|-------------------|
| [簡潔に] | [計画ではどうする予定だったか] | [実際にどうなったか] | [なぜ乖離したか] | はい / いいえ |

**「あるべきドキュメントを遡及更新するか」列の説明：**
- **はい**: この乖離は正しい設計方向であると判断され、spec または api-contract を実際と一致するように遡及修正した
- **いいえ**: この乖離は一時的な妥協または折衷であり、あるべきドキュメントは後続の Stage が参照できるよう元のまま残す
- 「いいえ」とマークされたすべての差異行は、次回の backlog の候補入力となる

---

## 検証結果

| チェック項目 | ステータス | 証拠 |
|--------|------|------|
| [受け入れ基準 1] | ✅ / ❌ | [テストレポート、パフォーマンスデータ、スクリーンショットなど] |
| [受け入れ基準 2] | ✅ / ❌ | [証拠] |
| 回帰なし | ✅ / ❌ | CI 実行リンク |

→ 詳細は [VERIFY.md](./VERIFY.md) を参照

---

## 学習サマリー

> 封印時に入力してください。2 文以内。

- **次回はこうする**：[今回何が正しかったか — 他の Stage で再利用する価値があるもの]
- **次回はこうしない**：[今回何を間違えたか — 回避、警戒、改善すべきこと]

---

## 関連

- **前回の Stage**: [STAGE-XXX](../stage-XXX/STAGE.md)（または「なし」）
- **次回の計画**: [簡潔に、または「なし」]

---

増分（封印後に追加）

Stage が封印され（ステータスが done）、その後小さな問題の修正が必要になったが、新しい Stage を立てるほどではない場合、STAGE.md の末尾に増分セクションを追加できます：

---

## 増分 1（2026-07-28）

- **変更**: [何を修正したかを簡潔に]
- **理由**: [なぜ封印後にこの修正が必要だったか]
- **影響範囲**: [どのファイル/モジュール]

増分を追加する際のルール：

• Stage のステータスは done のまま維持し、in-progress に戻さない
• 増分エントリは時系列順に追加する
• 修正に新しい ADR の意思決定が含まれる場合は、実際のドキュメントの ADR テーブルに追加し、[増分 1] と注釈する
• 増分が 3 つ以上累積した場合、増分を続ける代わりに新しい Stage を作成すべきか検討する

---

INDEX.md

stages/INDEX.md はすべての Stage のナビゲーションエントリです。各 Stage の作成時および封印時にメンテナンスされます。

# Stage 索引

| ID | タイトル | 種類 | ステータス | 関連モジュール | 日付 |
|----|------|------|------|---------|------|
| 001 | raft-election-optimization | opt | done | consensus, rpc | 2026-07-15 — 2026-07-17 |
| 002 | wal-checksum-verification | feat | done | storage, wal | 2026-07-18 — 2026-07-20 |
| 003 | replica-sync-refactor | refactor | done | replication, net | 2026-07-22 — 2026-07-23 |
| 004 | multi-az-placement | feat | abandoned | placement, scheduler | 2026-07-23 |

メンテナンスルール：

• Stage 作成時に行を追加し、ステータスは draft
• Stage 封印時にステータスを done に更新
• Stage のステータスが abandoned、superseded、split に変わった場合も同期して更新
• 関連モジュール には影響を受けるトップレベルのモジュール/ディレクトリを列挙し、モジュール別の検索を容易にする

---

ステータスモデル

ステータス	意味	いつ使うか
draft	スケルトンが作成され、実装はまだ開始されていない	Stage 作成後
in-progress	実装中	実装期間中（オプション）
done	計画通り完了、封印済み	すべてのタスクが完了し、検証が成功し、学習サマリーが記述されている
abandoned	途中で放棄	方向性が間違っていた、要件がキャンセルされた、より優先度の高いタスクが割り込んだ
superseded	別の Stage によって上書きされた	Stage-B の範囲が Stage-A を飲み込んだ
split	複数のより小さな Stage に分割された	Stage が大きすぎて、独立したサブ Stage に分割された

abandoned の処理：

• MISSION セクションを更新し、「放棄理由」を段落として追加する
• ADR テーブルには最低1つ残し、「なぜ続行しなかったのか」を記録する
• 学習サマリーは通常通り記入する — 放棄の教訓は成功よりも価値があることが多い
• 放棄された Stage で完了したコード/ドキュメントの一部をロールバックするかどうかは、意思決定者が判断し、ADR に記録する
• 関連 セクションの「次回の計画」を「なし（放棄済み）」に変更する

superseded の処理：

• MISSION セクションを更新し、「どの Stage に置き換えられたか、およびその理由」を段落として追加する
• 関連 セクションに「置き換え先: STAGE-XXX」を追加する
• ステータスを superseded に変更する
• 置き換えられた Stage に増分を追加し続けない — 以降の作業はすべて置き換え先の Stage に移管する

split の処理：

• MISSION セクションを更新し、「どのサブ Stage に分割されたか、およびその理由」を段落として追加する
• 関連 セクションに「分割先: STAGE-XXX, STAGE-YYY」を追加する
• ステータスを split に変更する
• 元の Stage に増分を追加し続けない — すべての作業はサブ Stage に移管する

ディレクトリ構造

stages/
  INDEX.md                      ← 索引、各行に1つの Stage
  001-raft-election-optimization/
    STAGE.md                    ← Stage 連結ドキュメント
    MISSION.md                  ← 詳細な目標説明（オプション、複雑なプロジェクトに推奨）
    spec/                       ← あるべき：機能仕様
    design/                     ← あるべき：プロトコル契約、データレイアウト
    tasks/
      plan.md                   ← 実装計画
      todo.md                   ← タスクリスト
    task-contract/              ← 委任実行範囲、tasks/spec と同階層
      TASK-001.md
      TASK-002.md
    docs/
      protocol/                 ← 実際の：プロトコルドキュメント、RPC インターフェース
      adr/                      ← 実際の：アーキテクチャ意思決定記録（必須）
    verify/                     ← 検証証拠
      fault-injection-report.md
      consistency-check.txt
      perf-before-after.json
  002-wal-checksum/
    ...
    ...

Task Contract のパスを除き、ディレクトリ構造は推奨パターンです。コア制約は：STAGE.md が存在しなければならない、各 Stage に最低1つの ADR が含まれていなければならない。Task Contract が存在する場合、その Stage の task-contract/ 配下に配置し、STAGE.md が前方索引しなければなりません。

他のスキルとのインタラクション

スキル	インタラクション方法
spec-driven-development	Stage の MISSION は spec の Objective から抽出される
planning-and-task-breakdown	/plan 出力後、Agent は Stage スケルトンを作成するかどうかを尋ねる
delegated-task-contract	Contract は現在の Stage の task-contract/ に保存される。STAGE.md がそのステータス、乖離、証拠を単方向索引し、Contract は Stage を逆索引しない
api-and-interface-design	あるべきドキュメントのプロトコル契約（gRPC/protobuf）と実際のドキュメントのインターフェースドキュメントの両方が Stage にリンクされる
failure-injection-testing	フォールトトレランスと障害復旧に関わる場合、障害注入計画とカオス実験レポートが Stage の実際のドキュメントにリンクされる
consistency-and-durability-verification	ストレージまたは状態レプリケーションに関わる場合、一貫性/耐久性検証レポートが Stage の検証結果にリンクされる
エージェントネイティブ実装プロセス	すべてのタスクが完了し検証された後、Agent は Stage の封印を促す
documentation-and-adrs	ADR は Stage の必須成果物。各 Stage に最低1つ
shipping-and-launch	/ship は Stage の存在をチェックする（今回作成された場合はブロック）

よくある合理化の言い訳

合理化の言い訳	現実
"この変更は小さすぎて Stage は必要ない"	変更が小さすぎて Stage が必要ないなら、ADR もおそらく必要ない。しかし、ユーザーは Stage を作成することを既に決めている — ユーザーの判断を信じましょう。
"要件が単純すぎて、あるべきと実際に差異は生じない"	差異はどこにでも存在する — 最も単純な変更でも、実装中に計画から乖離する可能性がある。Stage のコアバリューはまさにこれらの差異を記録することにある。
"とにかくコードを書いて、Stage は後で埋める"	封印前の Stage は生きたディレクトリであり、一度に書き切る必要はない。しかし、後から書き直すということは、差異分析を記憶に依存することを意味する — 記憶は信頼できない。
"これに ADR は必要ない"	すべての Stage には記録に値する決定が少なくとも1つある — たとえ「現在の制約ではより複雑な案が許されないため、最もシンプルな実装方法を選んだ」というだけでも。
"もう abandoned だから、学習サマリーに意味はない"	放棄の教訓は成功の教訓よりも価値があることが多い。「なぜ放棄したか」を記録することは、「なぜ成功したか」を記録することと少なくとも同じくらい重要です。
"差異テーブルで「いいえ」とマークすれば十分で、説明は不要"	差異テーブルの各行は将来の意思決定のインプットです。「いいえ」とマークされた行は、次の担当者に「ここには技術的負債があり、意図的に残されている」と伝えます。
"INDEX.md は後で追加できる"	INDEX.md の価値は Stage の数とともに増大する — 最初の Stage では感じられなくても、10 個目には必需品になる。最初からメンテナンスしよう。

レッドフラグ警告

• STAGE.md が作成されたが MISSION が空 — スケルトンの価値は MISSION にある。目標のない Stage は単なるプレースホルダーである
• 実際のドキュメントに API ドキュメントはあるが対応する ADR がない — 「各Stageに最低1つのADR」というルールに違反している
• 差異テーブルが空だが、ユーザーが実装中の乖離について言及していた — 差異が捕捉されていない
• 学習サマリーが「なし」または「すべて順調」 — すべての Stage に教訓がある。見つからないのは内省が十分でない証拠
• abandoned の Stage に「放棄理由」がない — 最も価値のある情報を失っている
• INDEX.md の特定の行が長期間 draft のまま — 実装を進めるか、abandoned とマークするか。スケルトンを腐らせてはいけない
• 増分セクションが 3 つ以上累積したが、新しい Stage への分割が検討されていない — 今回の範囲判断に誤りがあった可能性があり、増分を続けるのではなく反省すべき
• 意思決定者フィールドが空 — 複数人での協業時に、意思決定のトレーサビリティチェーンが途切れる
• task-contract/ に STAGE.md で索引されていないファイルが存在する、または索引リンクが存在しない Contract を指している
• Contract のステータス、deviation、evidence が変更されたが、Stage のテーブルに古いサマリーが残っている
• Contract が STAGE.md を逆リンクしており、帰属関係が双方向で管理されている
• DRAFT、READY、BLOCKED_BY_ARCHITECTURE の Contract が残っているにもかかわらず、Stage を done とマークしている

検証

Stage スケルトン作成後：

• stages/<stage-id>/STAGE.md が存在する
• Stage の種類（feat | opt | debug | refactor）が入力されている
• ステータスが draft
• 意思決定者が入力されている
• MISSION が入力されている（標準形式または debug 形式、種類に応じて）
• 実装計画リンクが tasks/plan.md と tasks/todo.md を指している
• 「Task Contracts（委任実行範囲）」セクションと空の前方索引テーブルが作成されている
• stages/INDEX.md に対応する行が追加されている

Stage 封印後：

• 実際のドキュメントリンクが入力されている
• ADR が最低1つあり、実際のドキュメントテーブルにリンクされている
• あるべき vs 実際の差異テーブルが入力されている（差異がない場合は明示的に「差異なし」と記述し、その理由を簡潔に説明）
• 差異テーブルの各行に「あるべきドキュメントを遡及更新するか」がマークされている
• 検証結果テーブルが入力されており、各チェック項目にステータスと証拠がある
• task-contract/ 内のすべての Contract が前方索引されており、Contract に Stage フィールドや逆リンクがない
• 索引ミラーステータスが Contract 本文と一致しており、すべての Contract が COMPLETED または CANCELLED
• Contract の deviation、完了証拠、キャンセル理由が対応するサマリーまたは差異セクションに同期されている
• 学習サマリーが入力されている（2文、空虚ではない）
• ステータスが done（または他の最終状態）に変更されている
• stages/INDEX.md の対応する行のステータスが同期更新されている