writing-specs-designs

仕様とデザインの作成

対象範囲

対象

• プロダクト、デザイン、エンジニアリングの各チームが、すばやく共通認識を得るための仕様・デザイン文書パックを作成します
• 「インサイト」を、具体的な成果物（低忠実度の図、フロー／状態、プロトタイプ計画、テスト可能な受け入れ基準）に変換します
• 必要に応じて、モバイル特有のタップ効率（タップ数と操作コストの明示的な最適化）を扱います

使用する場面

• 「この機能の仕様書／機能仕様書／技術仕様書を書いてください。」
• 「このメモを、エンジニアリングチームが開発に使えるデザイン文書にまとめてください。」
• 「動作要素を示す図を含む、シェイピング形式の文書を作成してください。」
• 「この操作感を評価するためのプロトタイプ計画が必要です。」

使用しない場面

• 解決すべき問題をまだ検証している段階（先にディスカバリー／問題定義を行います）。
• ハイレベルな戦略／ビジョン文書が必要な場合（先にプロダクトビジョン／ノーススターに取り組みます）。
• プロダクトの操作性の明確化ではなく、詳細なエンジニアリングアーキテクチャ設計（API、スキーマ、スケーリング、信頼性）が必要な場合。
• ピクセル単位で完全なUIモックのみが必要な場合（ここでは仕様と体系的な指針を作成します。最終的なビジュアルは作成しません）。

入力

最低限必要な情報

• 機能／変更内容：1～2文の説明
• 対象ユーザーと主なユースケース（ハッピーパス）
• プラットフォーム：Web／iOS／Android／デスクトップ（モバイルの場合は明示してください）
• 目標と対象外事項（v1の範囲）
• 制約：スケジュール、依存関係、ポリシー／法務／プライバシー、技術的制約
• 成功指標（1～3個）とガードレール（2～5個）

情報が不足している場合の進め方

• references/INTAKE.mdから最大5つの質問をしてから、作業を進めます。
• 重要な情報が不足したままの場合は、前提を明示し、2～3個の選択肢（スコープ／フロー／プロトタイプの進め方）を提示します。

出力（成果物）

Markdown形式の仕様・デザイン文書パックを作成します（チャット内、またはユーザーから依頼された場合はファイルとして作成します）。

1. コンテキストの概要（問題、今取り組む理由、目標／対象外事項、制約、ステークホルダー）
2. 動作要素を示す低忠実度の図（10要素以下）と主な判断事項
3. ユーザーフローと状態（ハッピーパスと主なエッジケース）を、明確な開始点／終了点とともに記載
4. プロトタイプ概要（プロトタイプの対象、忠実度、期間、データの現実性、成功基準）
5. 要件と受け入れ基準（テスト可能な内容。必須／推奨／任意）
6. 測定計画（指標 → データ／イベント → 担当者 → 頻度）
7. リスク／未解決の質問／次のステップ（必ず含めます）

テンプレート：references/TEMPLATES.md

ワークフロー（8ステップ）

1) チームの作業を進めるために必要な最小限の成果物セットを選ぶ

• **入力：**ユーザーの依頼と制約。
• **アクション：**次のどちらを提供するか決定します。(a) 仕様・デザイン文書のみ、または (b) 仕様・デザイン文書＋プロトタイプ概要を重視した内容（操作感が重要な場合）。
• **出力：**成果物の選定とその理由。
• **確認事項：**成果物が、下すべき判断（認識合わせ、開発の実行、操作感）に合っていること。

2) インテークとコンテキストの概要

• 入力：references/INTAKE.md。
• **アクション：**最大5つの質問を行い、対象者／DRI、プラットフォーム、制約、成功指標／ガードレールを確認します。
• **出力：**コンテキストの概要セクション。
• **確認事項：**問題、ユーザー、成功指標を1～2文で説明できること。

3) スコープの境界を定める（モバイルの場合は「タップ予算」も定義する）

• **入力：**コンテキストの概要。
• **アクション：**目標、対象外事項、スコープ外の項目、前提、依存関係を記述します。モバイルのフローでは「タップ予算」（価値に到達するまでの最大タップ数）と、ユーザーの注意が最も途切れやすい箇所を定義します。
• **出力：**スコープの境界と（任意の）タップ予算。
• **確認事項：「取り組まないこと」が明確であり、モバイルで価値に到達する経路に明確なタップ数の目標があること。

4) 低忠実度の図を作成する（「シェーピング」の成果物）

• 入力： スコープと制約。
• アクション： 動きのある要素（10 個以下）、データ／受け渡し、UX の判断が重要となる箇所を示す図を作成します。ピクセル単位の UI は避け、構造のわかりやすさを優先します。
• 成果物： 低忠実度の図と、注釈付きの判断内容。
• 確認項目： パートナーが会議なしで「何を作ればよいかわかりました」と言えること。

5) ユーザーフローと状態を定義する（エッジケースを具体化する）

• 入力： 図とユースケース。
• アクション： エントリーポイント、通常のフロー、主要なエッジケースを文書化します。エラー／空／読み込み状態、権限、曖昧さがバグにつながる箇所のコピーに関する注記を含めます。
• 成果物： フローと状態テーブル。
• 確認項目： 別の人がフローをロールプレイでき、各エッジケースに意図した結果が定められていること。

6) プロトタイプの概要を作成する（「感覚」が重要な場合に限る）

• 入力： フロー／状態と不確定要素。
• アクション： リスクの高いインタラクション上の不確定要素を1〜3個特定します。プロトタイプの種類（低忠実度、高忠実度、またはコード内）、期間、リアリティ（可能な限り実データを使用）、そして「良い」と感じられる状態を指定します。
• 成果物： プロトタイプの概要。
• 確認項目： プロトタイプ計画がテスト可能（シナリオと成功基準を含む）であり、使い捨てのコードを使用する場合は、明確に破棄できること。

7) テスト可能な要件と受け入れ基準に落とし込む

• 入力： フロー／状態とプロトタイプから得た知見（ある場合）。
• アクション： 受け入れ基準（必須／望ましい／可能なら実施）を含む要件を作成します。非機能要件（アクセシビリティ、パフォーマンス、プライバシー）と計測要件も含めます。
• 成果物： 要件セクション。
• 確認項目： エンジニアリング／QA が意図を再解釈せずにテストケースを導き出せること。

8) 品質ゲートを実施し、共有用に仕上げる

• 入力： ドラフト一式。
• アクション： references/CHECKLISTS.md を実行し、references/RUBRIC.md に基づいて評価します。リスク／未解決の質問／次のステップを追加し、決定事項と前提を明確に区別します。
• 成果物： 最終版の Spec & Design Doc Pack（そのまま共有可能）。
• 確認項目： 担当者、指標、未解決の質問が明確であり、図とフローによって最大の曖昧さが解消されていること。

品質ゲート（必須）

• references/CHECKLISTS.md と references/RUBRIC.md を使用します。
• 常に Risks、Open questions、Next steps を含めます。

例

例 1（モバイルフロー）：「iOS アプリに新しい『友達を招待』フローを追加するための仕様書と設計ドキュメントを作成してください。目標は招待の成功数を増やし、最初の価値に至るまでのタップ数を最小限に抑えることです。」
期待される成果：タップ数の上限とフロー／状態テーブル、画面／遷移を示す低忠実度の図、重要なインタラクションのプロトタイプ概要。

例 2（B2B ウェブ機能）：「管理者向けの『ロールの一括編集』の設計ドキュメント／仕様書を作成してください。エッジケースと受け入れ基準を含めてください。」
期待される成果：権限に重点を置いたフロー／状態、受け入れ基準付きの要件、計測計画。

境界例：「『エンゲージメントを改善する』ための仕様書を作成してください（プロダクトの背景、ユーザー、成功指標がありません）。」
対応：必要最低限の確認質問をします。それでも情報が不足している場合は、スコープを定めた選択肢を2〜3個、前提とともに提示し、仕様を確定する前に上流のディスカバリーを行うことを推奨します。