product-from-scratch

ゼロからのプロダクト設計

コードに制約される前に、ユーザーが何を見て、何をするのかを決めます。対象ユーザー、成果、ジャーニー、インタラクション、状態、失敗、復旧を定めます。実装によって実際の制約が明らかになったときは、コードに合わせて再設計するのではなく、その制約を決めている判断を見直します。

コストのルール

1. 設計にかける労力は、結果の重大さと未解決の不確実性に見合ったものにします。通常の変更では、変更を二度実装する場合よりも大幅に少ないコストに抑えます。
2. すべての成果物とすべての項目は、固有の判断を促すか、検証を改善する必要があります。どちらの役割も繰り返し果たさないものは削除します。
3. 新たに作成する前に、既存の規範を再利用します。インターフェースに手を加えるからといって、新しい文書が必要になるわけではありません。

判断を解決することも、もっともらしいリスクを減らすこともなく作業が膨らむ場合は、プロセスを削減します。プロセス上の不備を別のプロセス層で解決してはいけません。マニフェスト、ハッシュ、計算で生成されるステータス、承認記録、エビデンスの分類体系、レビュアー向けの仕組み、成果物の割り当て数などを追加してはいけません。ドキュメントのリンターで確認できるのは仕組み上の問題であり、設計の承認にはなりません。

一連の流れ

BRD  when business intent changes
PRD  when product behaviour changes
XDS  when a material experience decision exists
SDD  when a material technical decision exists
then implementation, then verification

判断が存在するレイヤーのみを使用します。条件付きにすることでダミーの文書を防げますが、判断を未解決のままにしてよいわけではありません。新しい機能や複数の画面にまたがるジャーニーでは、通常すべてのレイヤーを使用します。

成果物	使用する場合	担うもの	担ってはならないもの
BRD、ビジネス要件	ビジネス上の意図、対象ユーザー、成果、スコープ、または譲れない品質が変わる場合	取り組みを行う価値がある理由、ユーザーとビジネスの成果、許容可能な労力、犠牲にしてはならない品質	コントロール、レイアウト、コピー、色
PRD、プロダクト要件	新しい機能や重要な動作変更に、継続的に参照できるルールが必要な場合	プロダクトのストーリー、ルール、データ、権限、成功・失敗・中断・復旧・再訪時に求められる成果と不変条件、観測可能な受け入れ条件	コントロールの選択、操作の流れ、レイアウト、コピー、階層、モーション、技術的な実現方法
XDS、エクスペリエンス設計（簡潔な UX メモを PR に含めても構いません）	新規または大幅に変更されるジャーニー、接続部分、階層、状態モデル、共有コントロール、またはインタラクションの選択に設計が必要な場合	ジャーニー、状態と遷移、コントロールとイベント、コピー、フィードバックの責任、状態の保持、再試行、再訪、レスポンシブな構成、モーション、代替手段	新しいビジネス要件やプロダクト要件、技術的な実現方法
SDD、ソリューション設計	アーキテクチャ、データ、セキュリティ、デプロイ、パフォーマンス、またはモジュール間の動作に、継続的に参照できる技術的な判断が必要な場合	スキーマ、API、永続化、パフォーマンス、セキュリティ、技術的な障害対応	エクスペリエンスの再設計

順序と権限：

• ビジネス上の意図をプロダクトの動作より先に、プロダクトの動作をエクスペリエンスより先に定めます。どちらも技術的な実現より先に定めます。技術のみを扱う SDD には XDS は不要です。
• PRD はプロダクトが何をしなければならないかを示します。XDS はユーザーがどのように操作し、理解し、問題から復旧するかを示します。設計中に見つかったプロダクトのルールは XDS ではなく、必ず PRD に記載します。
• 実現可能性に関する矛盾が生じたら、その判断を担うプロダクトまたはエクスペリエンスの判断を見直します。技術的な作業では制約を明らかにして選択肢を提案できますが、ユーザーに提示する解決策を決めることはできません。
• XDS のスコープは、一貫性のあるジャーニーまたは画面群を単位にします。1 つの XDS が複数の PRD を対象にすることも、1 つの PRD が複数のジャーニーに登場することもあります。
• 現在の実装、調査、測定結果はエビデンスです。目標を定めるための参考にはなりますが、それ自体が目標を定義するわけではありません。目標と実装済みの記録は区別して管理します。

書き始める前に、判断を明確にし、その判断を担う、または制約する成果物だけを読みます。判断が変わる場合にのみ、規範となる文書を改訂します。内容を繰り返すのではなく、判断を記載した箇所にリンクします。成果物の蓄積がないレガシープロダクトでは、小さな修正の前に過去分を埋める必要はありません。issue または PR に不足している最小限の判断を記載し、その判断を変更後も残す必要がある場合にのみ、継続的に参照する規範を作成します。

比例性

変更	有用な最小限の資料
ユーザーから見える影響も操作への影響もない	なし。ただし、ビジネス、プロダクト、技術上の判断を独立して永続的に扱う必要がある場合を除きます
小規模なメンテナンス変更	イシューまたは PR に、実行者とタスク、現在の失敗、期待される動作、影響を受ける到達可能な状態、維持されるコンテキスト、復旧と復帰のルール、観測可能な受け入れ条件を記載します。既存の要件やテストを言い直すのではなく、リンクします
新機能または重要な動作変更	PRD を追加または修正します。変更によってジャーニー、接合点、階層、状態モデル、共有コントロール、操作上の選択が導入または変更される場合は、XDS 資料を追加または修正します
新規または大幅に変更されたジャーニー、あるいはサーフェスをまたぐ接合点	ジャーニーに必要な判断だけを網羅した XDS を、順にたどれる形で 1 つ作成します
重大な技術上の選択	SDD を 1 つ作成します

分量のノルマはありません。重要な判断が暗黙のまま残らない、最も簡潔な資料を使います。 簡潔な資料では判断を下せなかった場合に限り、詳細化します。ドキュメントを増やしてほしいという要望だけでは、詳細化の理由になりません。

エクスペリエンスのプロンプト

変更の解決に役立つプロンプトを使い、それ以外はコメントなしで省略します。

1. プロダクトストーリー：誰が、どのような状況で、何をし、どのような結果を得るのか。
2. エクスペリエンスの主張：新機能または新しいジャーニーの場合のみ。確約する方向性と、ユーザーが覚えておくべき 1 つのことを示す 1 文。他社製品にもそのまま当てはまる説明文になりうるなら、まだ主張とはいえません。
3. ジャーニー：開始地点、決定的な場面、完了、復帰または再開。
4. 操作シナリオ：名前の付いたコントロールとイベント、目に見える応答、終了状態、そして絶対に起きてはならないこと。感じられる品質は、観測可能な値として示します。入力は 100 ms 以内に受け付けられ、1 s 以内に完了するか、設計された低速状態に入ること（従来の応答時間の基準）、動きの特性は明確に示し、範囲を定めます。裏付けとなる値のない形容詞は単なる願望です。代替案を比較するのは重大な分岐点に限り、採用しなかった案とその理由を 1 行で記録します。
5. 状態モデル：ユーザーに見える内容やユーザーができることを変える、到達可能な状態。
6. 復旧：失敗しても残るもの、失われるもの、再試行できるもの、再試行の場所。
7. 受け入れ条件：誰かが実際に試す観測可能なシナリオ。

レイアウト、情報密度、動き、タイミング、レスポンシブ対応が判断を左右する場合は、状態ボード、モックアップ、またはプロトタイプを作成します。新しいサーフェスまたはジャーニーでは、開始、決定的なインタラクション、失敗と復旧、完了はすべて視覚的な主張になるため、これらを描画します。

文法

従来のストーリー（「クリエイターとして、自分のゲームを追加して、プレイヤーが見つけられるようにしたい」）は、状況、手間、中断、または反証によって判断が変わる可能性がある場合、弱すぎます。

STORY        <id>
As           <actor>
in           <context: first-run, returning, signed-out, empty account, ...>
I            <the task, independent of route, schema, or control>
so that      <the business or personal outcome>

Arrives at   <the observable state that constitutes success>
Abandons at  <plausible exit points and what makes leaving plausible>
Effort       <inputs, decisions, context switches, external tools; quantify when useful>
Falsified by <the observation that disproves the story>

各行が判断を促す場合は、完全な文法を使います。局所的なメンテナンス変更に必要なのは、実行者、タスク、期待される結果、受け入れ条件だけです。意味のある終了点がない単一のアクションには、Abandons at の行は不要です。

ストーリーだけではコントロールは選べません。重要なストーリーを、次のようにインタラクションへ落とし込みます。

SCENARIO     <id, linked to the story when one exists>
Starts in    <state and context>
User         <activates a named control or performs a named event>
Immediately  <visible response>
While        <pending, slow, or interrupted behaviour, when applicable>
Succeeds as  <terminal state>
Fails as     <truthful failure state, when reachable>
Recovers by  <durable action and preserved context>
Returns to   <resume, back, refresh, authentication return, later return, when material>

重要なコントロール、応答、終了状態、または到達可能な復旧手段が欠けているシナリオでは、その部分のインタラクションは設計されていません。

状態プロンプト

作成者は、覚えていない状態を省略しがちです。ユーザーの一連の操作をたどり、影響を受ける体験を変えうるものを選ぶために、次の4つの観点すべてを確認してください。

観点	確認すること	たとえば、次の状態が見つかります
データ	値：なし、一部あり、無効、最大。コレクション：0件、1件、数件、非常に多数	空のアカウント、半分まで入力されたフォーム、上限を超えるタイトル
時間	非同期アクション：保留中、遅い（1秒超）、成功、失敗、後続処理に置き換えられる、繰り返される、完了が遅れる	遅延状態の通知、トーストが消えた後も残る確定済みの結果、古い完了通知の破棄
経路	値の取得経路と中断：入力、復元、初期値の設定、取得、認証、更新	古い事前入力値が有効かどうか、認証を経由しても下書きが保持されること
表示枠	対応する幅、入力方法、コンテンツの極端なケース	狭いビューポートへの適合、最長のラベル、画像の読み込み失敗

ユーザーに見える動作が変わる状態、または起こりうる失敗を伴う状態のうち、到達可能なものだけを記録してください。起こりうる状態を意図的に除外し、その理由を記すことで曖昧さを防げる場合に限り、除外を記録します。直積を網羅的に列挙したり、網羅的なカバレッジを主張したりしてはいけません。

影響を受ける各コントロールについて、キーボード、ポインター、タッチでの動作、フォーカスの配置と復元、画面の向き、安全領域、幅への対応を決めてください。これらは通常のインタラクション上の判断です。

症状から逆にたどって判断する

観察された症状	判断
成功がトーストにしか表示されない	時間。成功は持続する結果状態に表示します。トーストはせいぜい補足にとどめます
1秒を超えて待っても応答がない	時間。遅延状態も設計された状態です
有効な事前入力、復元、修正の後もエラーが残る	経路。表示した判断には、解除される条件も示す必要があります
エラーが行き止まりとして表示される	回復。再試行はエラーの表示箇所に置き、トーストが消えた後も使えるようにします
ページが表示された後、レイアウトが組み替わる	最終的な構造に近いスケルトンを使います。スピナーは構造を隠します（references/vocabulary.md、loading）
幅が狭い場合や実際の最長ラベルで崩れる	表示枠。極端なコンテンツもテスト入力です
仕様に「ドロップダウン」「モーダル」「タブ」「トースト」とだけ書かれている	まだ判断できていません（references/vocabulary.md）

コントロールの選択と命名

コントロールの選択はスキーマの型ではなく、タスクに従います。

1. 再利用の確認：プロダクト内の別の場所では、同じタスクをどのように解決していますか。また、どのコンポーネントが担当していますか？タスクに実質的な違いがない限り、プロダクトの文法を再利用します。
2. 検索方法：ユーザーは値を思い出しますか、それとも候補の集合から見分けますか？
3. 選択肢の数と比較：選択肢はいくつありますか、どの程度なじみのあるものですか、横並びで比較する必要がありますか？
4. 現実の値の個数：スキーマより先に、現実に照らして単数か複数かを決めます。
5. 支援方法：値を取得、導出、初期設定、提案できますか？スキーマ上の必須要件を、人に転記させる根拠にしてはいけません。
6. 動作がわかるだけの精度でコントロールに名前を付けます。references/vocabulary.md では、選択によって動作、状態、入力モデル、回復方法が変わる名称を定義しています。名称が曖昧な場合は参照してください。これは参照資料であり、追加の義務を生じさせるものではありません。共通の名称が合わない場合は、プロジェクト独自の用語を定義できます。

永続的な引き継ぎ

次のエージェントが参照できるのは、リポジトリと Issue または PR だけです。引き継ぎの前に、後続作業に不可欠な事実をすべて、永続的に残る一か所にまとめてください。ユーザーと成果、現在の不具合または判断、選択した挙動と操作、影響を受ける状態、保持、復旧、中断、復帰、対象外の事項、判断の覆りを防ぐために必要な採用案と却下案、観察可能な受け入れ条件と実際に行った検証、既知の不足と実施できなかったチェックを記録します。

文書の内容を重複させるのではなく、該当する文書にリンクしてください。規範となる文書には現在の目標を記載し、PR にはその理由、却下した代替案、差異を記載します。「チャットを参照」とは決して書かず、重要な判断を非公開の推論だけに残さないでください。公開レビューの判定が変わった場合は、PR のスレッドで明示的に訂正してください。黙って編集しても、すでに別のエージェントが読んだ引き継ぎは修正されません。

レビュー

プロダクトに関する判断をレビューします。成果物が存在することは、何も証明しません。

• 公開判定を出す前に、変更されたプロダクトまたはデザインのファイルを、ブランチ上の状態で最初から最後まで読みます。差分、リンター、リンクチェックで検証できるのは、仕組み上の正しさだけです。
• 有用な指摘では、ユーザー向けの判断の何が不足または誤りなのかを示し、その根拠を指摘します。
• 新機能または新しいユーザーフローには、作成者以外の人によるデザインレビューを一度実施し、視覚面と時間面の判断を評価できるレンダリング結果を用意します。小規模な変更には通常の PR レビューを行います。
• 修正後は、具体的な指摘を再確認します。レビューのレビューや、合意に至るための儀式を設けないでください。
• オーナーが方針を承認したら、それを実行します。オーナーが方針を変更した場合、要件が修正された場合、重大な制約が明らかになった場合、または具体的な根拠によって判断が誤り、不可能、あるいは危険だと分かった場合に限り、デザインレビューを再開します。

検証

実装前にデザインの準備が整うことはあります。変更が完了したと言えるのは、その結果が実際に動作するときだけです。

• 影響を受ける実際のフローを、代表的なホストで実行し、発生しうる失敗、復旧、中断、復帰の経路も確認します。成功経路のスクリーンショットや HTTP ステータスでは操作について何も検証できず、静止画では動きを検証できません。
• インストゥルメントを用いたウォークスルーでは、デザインで確定したタイミング、状態、動きの特性を測定します。使用感の最終判断を下すのは、実物を使う人です。その人が正常なウォークスルーの結果に同意しない場合、デザインに必要な確定事項が不足していました。問題を検出できる値を追加してください。
• リポジトリで必須のチェックと、変更に関連するテストを実行します。テストは実環境での検証の代わりにはなりません。
• ホストや接続部分を実行できない場合は、未検証のシナリオを PR に正確に記録し、完了したとは主張しないでください。
• 主な不確実性が理解度や、ユーザーが感じる労力にある場合は、可能であれば代表的なユーザーを観察します。それが難しい場合は、前提と今後の確認事項を記録します。文書を増やしても、この問いには答えられません。
• 読者向け文書は、対象読者に合っているか確認します。プロジェクト外の読者にとって理解しにくい箇所はありませんか。プロダクト文書にワークフローの専門用語を持ち込まないでください。
• 機械によるチェックは機械的な確認にとどめます。リンクが解決できること、ID が一意であること、参照先の文書が存在すること、形式が解析できることを確認します。

半径、イージング、スタッガー、押下状態、視覚的な配置調整といったビルド時の仕上げは、作業時に参照するクラフトスキルの範囲です。この手法では重複して扱いません。

完了の定義

実装準備完了：

1. 判断に必要な成果物だけが、連鎖の順序に沿って作成または修正されています。
2. ユーザー、タスク、結果、観察可能な受け入れ条件が、判断の誤りを明らかにできる程度に明確です。
3. 変更に該当する場合、インタラクション、状態、保持、復旧、中断、復帰、労力、放棄、非目標に関する判断が明示されており、どのストーリーも制御方法を選んでいません。
4. 完全性の台帳を作成せずに、データ、時間、パス、フレームを検討しました。
5. 視覚的および時間的な判断をレンダリングし、レビュアーが確認しました。
6. 別のエージェントが、リポジトリだけから判断の根拠と既知のギャップを把握できます。
7. 判断を妨げる要因はすべて取り除かれています。

実装済み：

1. 制約によって選択したエクスペリエンスが黙って書き換えられることなく、実装に反映されています。
2. 代表的なホストで実際のフローとその失敗および復旧経路を検証しました。または、完了したと主張せず、未検証の境界を記録しています。
3. 必要なチェックと関連するテストを実行しました。ブロックされたチェックも記録しています。
4. 読者向けドキュメントに現在の対象を記載し、対象読者に適しているかの確認に合格しました。