Design（設計）

Gate： ユーザーが仕様を承認するまでコードなし。

何を作るかわかるまで、一度に一つずつ質問する。2〜3つのアプローチとトレードオフを提案し、一つを推薦する。その後、仕様を書く。

仕様 = 決定事項のリスト

仕様はこの変更の未解決の質問に答える。典型的なもの：

• 契約 / インターフェース？
• データ形状？
• 失敗モード？
• スコープ外？
• 何のテストがそれを証明するか？
• アーキテクチャ？

慣用的に仕様を書く。

質問なし → セクションなし。Risks / Non-goalsが空なら埋めない。

宣言を使い、物語を使わない：

contract:  <インターフェース>
invariant: <何が成立しなければならないか>
test:      <どうわかるか>
deferred:  <今は決めない>

コードはパスで参照し、貼り付けない。

引き渡し前に、実装に影響する決定だけを閉じる：契約、データ、失敗、テスト。未解決の Working notes は決定、deferred、または質問になる。

2層、1ファイル：docs/staging/specs/YYYY-MM-DD-<topic>.md

• 上部：決定、契約、不変条件（永続的）。
• ## Working notes：草案、未解決の質問（ship 時に削除）。

Roadmap（スコープが≥3マイルストーンにわたる場合）

一度に全部計画できないほど大きい場合、仕様に ## Roadmap を追加：

## Roadmap
- [ ] M1: <一行ゴール>  ← 今詳細に計画
- [ ] M2: <一行ゴール>  ← stub
- [ ] M3: <一行ゴール>  ← stub

マーカーは必須。現在のマイルストーンに ← 今詳細に計画、他はすべて ← stub。スタブは意図であり約束ではない。展開前に更新する。

Gate

docs/staging/specs/YYYY-MM-DD-<topic>.md がディスク上に存在し、ユーザーが確認した後に plan へ引き渡す。

2つの出口のいずれか：

• → design：方向が解決すべき問題 → plan で詳細なタスクへ。
• → archive：方向が知識成果物（リバースエンジニアリング発見、プロトコル仕様）、直接アーカイブ。