| name | screen-specification |
| description | SyunsakuDemo の画面仕様を対話的に固め、不足画面・遷移・機能要件の網羅性を検証し、マークダウン形式の画面仕様書を出力する。 画面設計、画面遷移、UI仕様、ワイヤーフレーム要件、画面一覧、フロー図の作成・レビュー時に使用する。 |
画面仕様策定（Screen Specification）
ユーザーと対話しながら画面仕様を反復的に固め、最終的に マークダウン形式の画面仕様書 を出力する。
プロジェクトコンテキスト
| 項目 | 内容 |
|---|
| プロジェクト | SyunsakuDemo |
| プラットフォーム | Android / iOS（Kotlin Multiplatform） |
| UI | Compose Multiplatform（shared/src/commonMain） |
| 仕様書の既定出力先 | docs/screen-specification.md |
- 画面は原則 共通 UI として設計する（プラットフォーム差分がある場合は備考に明記）
- 実装時の画面コードは
shared/src/commonMain/kotlin 配下を想定する
- iOS 固有の SwiftUI 画面がある場合は別途画面 ID を付与し、対象プラットフォーム列を追加する
前提
- 最初にユーザーが持っている情報（アイデア、機能要件、既存資料、競合参考など）を収集する
- 一度にすべてを聞かず、小さな単位で質問または提案し、回答を反映してから次へ進む
- 各ラウンドの末尾で 進捗サマリー を短く示す
- 出力言語はユーザーの言語に合わせる（日本語ユーザーには日本語で）
全体フロー
収集 → 画面一覧 → 画面遷移 → 機能要件整合 → 検証 → 仕様書出力
↑_______________|（未充足があれば戻る）
完了条件（すべて満たすまでループ）:
- 不足な画面がない
- すべての画面遷移が網羅されている（トリガー UI 要素まで記述）
- 機能要件に必要なものがそろっており、過剰なものがない
Phase 0: インプット収集
最初のターンで以下を確認する。既に分かっている項目は聞き直さない。
| 項目 | 確認内容 |
|---|
| アプリ種別 | 既定: KMP（Android + iOS）。Web / デスクトップ追加の有無 |
| 対象ユーザー | 誰が、どんな状況で使うか |
| コア価値 | このアプリで達成したいこと（1〜3文） |
| 機能要件 | 既知の機能リスト、Must / Should / Won't |
| 制約 | 認証方式、オフライン、決済、法規制、既存システム連携など |
| 参考資料 | ワイヤー、競合、既存仕様書、README.md の有無 |
| 出力先 | 未指定なら docs/screen-specification.md |
不足が多い場合は Must 機能から 3〜5 件 に絞って質問する。
Phase 1: 画面一覧の策定
1-1. 初期画面リストの提案
機能要件から画面候補を推論し、表形式で提示する。
| ID | 画面名 | 目的 | 根拠（どの機能要件から） | 状態 |
|----|--------|------|--------------------------|------|
| S01 | ログイン | 認証 | F-001 | 提案 |
1-2. 不足画面の洗い出し
以下の観点で 自問し、ユーザーに確認または提案 する。
- 認証前 / 認証後の分離
- 初回起動・オンボーディング
- 空状態（データなし）
- ローディング・エラー・権限不足
- 作成 / 編集 / 詳細 / 一覧の CRUD 一式
- 設定・プロフィール・ヘルプ・法務（利用規約・プライバシー）
- 検索・フィルタ・ソート結果画面
- モーダル / ボトムシート / ダイアログ（独立画面として扱うか要確認）
- 通知・ディープリンクの着地点
- プラットフォーム固有画面（iOS のみ等）の要否
質問の出し方:
- 曖昧な点は
AskQuestion が使える場合は構造化して聞く
- 使えない場合は番号付き選択肢を提示する
- 提案と質問を混ぜる: 「〇〇画面が必要と思いますが、必要ですか？代替案は△△です」
1-3. ゲート: 画面一覧
以下がすべて解消されるまで Phase 1 を継続:
Phase 2: 画面遷移の網羅
2-1. 遷移マトリクスの作成
承認済み画面について、遷移を表で整理する。
| 遷移ID | 起点画面 | トリガー（UI要素） | 操作 | 遷移先画面 | 条件・備考 |
|--------|----------|-------------------|------|------------|------------|
| T01 | ログイン | 「ログイン」ボタン | タップ | ホーム | 認証成功時 |
| T02 | ログイン | 「パスワードを忘れた」リンク | タップ | パスワードリセット | — |
トリガー（UI要素）の記述粒度:
- ボタン、リンク、アイコン、リスト行、タブ、FAB、メニュー項目、スワイプ、プルリフレッシュ
- 可能ならラベル文言も記載（例: 「保存」ボタン）
- システムイベント（プッシュ通知タップ、ディープリンク、セッション切れ）も行として追加
- Android バックキー / iOS スワイプバックの挙動も備考に記載
2-2. 網羅性チェック
各画面について以下を確認し、未記述があれば質問または提案する。
| チェック | 例 |
|---|
| 戻る操作 | ツールバー戻る、スワイプバック、Android バックキー |
| キャンセル | 編集破棄ダイアログの有無と遷移先 |
| 成功後 | 作成完了 → 詳細 or 一覧 |
| 失敗時 | エラー表示のみか、別画面遷移か |
| 分岐 | 権限・ロール・状態による遷移先の違い |
| タブ / ナビ | ボトムナビ・ドロワー・サイドバーの切替 |
| モーダル | 閉じたときの親画面への復帰 |
2-3. フロー図（任意だが推奨）
主要ユーザーフローは mermaid flowchart で可視化する。
flowchart LR
A[ログイン] -->|ログイン成功| B[ホーム]
B -->|＋ボタン| C[新規作成]
2-4. ゲート: 画面遷移
Phase 3: 機能要件との整合
3-1. トレーサビリティ
機能要件（F-xxx）と画面・遷移の対応表を作る。
| 機能ID | 機能名 | 関連画面 | 関連遷移 | カバー状況 |
|--------|--------|----------|----------|------------|
| F-001 | ログイン | S01 | T01, T02 | ✅ |
3-2. 過不足の検証
不足: 機能に対応する画面・遷移・UI がない → Phase 1 or 2 に戻る
過剰: どの機能要件にも紐づかない画面がある → 削除・統合・Should へ降格を提案
| 画面ID | 画面名 | 問題 | 提案 |
|--------|--------|------|------|
| S99 | ランキング | 機能要件に未記載 | 削除 or F-010 として追加 |
3-3. ゲート: 機能要件
Phase 4: 画面詳細の記述
各画面について、以下テンプレートで詳細を埋める。一括ではなく 3〜5 画面ずつ 確認しながら進める。
詳細テンプレートは template.md を参照。
最低限すべての画面で埋める項目:
- 目的
- 表示要素（主要 UI）
- ユーザー操作と遷移（Phase 2 の遷移 ID を参照）
- 表示条件・権限
- 空状態 / エラー状態
Phase 5: 最終検証と出力
5-1. 最終チェックリスト
画面網羅:
- [ ] オンボーディング / 認証 / メイン / 設定 が漏れていない
- [ ] 空・ローディング・エラー状態が定義されている
遷移網羅:
- [ ] 各ボタン・リンク等の遷移先が明記されている
- [ ] 戻る・キャンセル・完了後の遷移が定義されている
- [ ] システム起点（通知・リンク）が考慮されている
機能要件:
- [ ] Must がすべてカバーされている
- [ ] 過剰画面が整理されている
- [ ] Won't / 将来対応が明示されている
5-2. 仕様書の出力
template.md の構成に従い、1 つのマークダウン文書 として出力する。
- 既定の保存先:
docs/screen-specification.md（docs/ がなければ作成する）
- ユーザーが別パスを指定していればそちらを優先する
- 未指定かつファイル書き込みが不要な場合はチャットに全文を出力する
- 仕様書の先頭に
ステータス: ドラフト | レビュー済 と 最終更新日 を記載
5-3. 完了報告
仕様書出力後、以下を短く報告する。
- 画面数・遷移数
- 未決事項（Open Questions）一覧
- 次の推奨ステップ（ワイヤーフレーム、ナビゲーション実装、API 設計など）
対話のルール
質問
- 1 ターンに質問は 最大 5 個（多いと回答負荷が上がる）
- 選択肢を示し、「その他」や自由記述 も受け付ける
- 推論で埋められる項目は「仮定」として提示し、確認を求める
提案
- 業界の一般的パターンに基づく提案は 根拠を添える
- 提案は「追加」「削除」「統合」のいずれかを明示する
- ユーザーの修正を最優先で仕様書に反映する
反復
- ユーザーが新機能を追加したら Phase 1 から再チェック
- 仕様書は常に 最新の合意内容 を反映した版を出す（差分説明を添える）
用語
| 用語 | 定義 |
|---|
| 画面 | ユーザーが独立して認識する UI の単位（モーダル・ダイアログ含むかはプロジェクトで定義） |
| 遷移 | 画面 A から画面 B への移動（アニメーションの有無は備考に記載） |
| トリガー | 遷移を起こす UI 要素またはイベント |
| 機能要件 | Must / Should / Won't に分類されたアプリの振る舞い |
追加リソース
