ux-scenarios

ux-scenarios — シナリオベースを維持する

super-ux の一部です。パイプライン全体と4つの同期ルールについては、system-map.mdを参照してください。変更後はリンター（python3 docs/ux/lint.py）を実行してください。

ユーザーの行動モデルなしにUIを構築すると、AIが生成したインターフェースはうまく機能しなくなります。このスキルでは、ユーザーが実行できること、目にすること、遭遇することのすべてを網羅する基準を維持します。対象プロジェクトのdocs/ux/scenarios.mdが、その唯一の信頼できる情報源です。すべての機能、すべてのボタン、すべての状態、すべてのエラー、すべての結果が対象です。

フォーマットの契約： scenario-format.md（ux-contract v4）。シナリオを作成または編集する前に読んでください。フィールド名、IDルール、ステータス、チェックリストから逸脱してはいけません。

WHYレイヤーとHOWレイヤー： docs/ux/foundation.md（ペルソナ、JTBD、ジャーニー、ストーリー — ux-foundationスキル）および／またはdocs/ux/flows.md（タスク分析、ユーザーフロー — ux-flowsスキル）が存在する場合、シナリオはそれらから導きます。フローごとに1つのシナリオセットを作成し、ハッピーパス、すべてのエラー分岐、フロー図のすべての代替分岐を網羅します。Traces:にはストーリーIDとフローIDを記入します。トレーサビリティのルールを適用します（must／shouldのストーリーをすべて網羅すること、すべてのフローノード／エッジを網羅すること、すべてのシナリオがストーリーまたはジョブに役立つこと。何にも役立たないシナリオは実装候補ではなく削除候補です）。ステップはユースケース形式で記述します。ユーザーの操作 → 観察可能なシステムの応答。重要度の高い製品で上位レイヤーが不足している場合は、まずux-foundation → ux-flowsを推奨してください。v1モード（Tracesなし）で進めるのは、小規模なプロジェクト、またはユーザーが明示的に選択した場合に限ります。

デザインの指針： Expected resultsとErrors & recoveryを記述する際は、ux-design-principles.md（画面ごとの状態、エラーからの復帰、主要アクションのルール）を適用してください。

トリガー

このスキルに振り分ける英語とロシア語のフレーズです。スキル一覧が予算内に収まるよう、説明文には最も強いトリガーだけを残しています（2026-10-20）。ファミリーのルーティングフックは、このリストに一致します。

「ux scenarios」／「сценарии использования」、「use cases」、「new feature」／「новая фича」、新機能やプロジェクトの計画、UIの変更。

厳守ルール

1. シナリオをインターフェースより先に作成します。新機能やプロジェクトを始める際は、まずシナリオを作成し、既存のベースとの競合、重複、抜け漏れを検証して、承認を得ます。その後に限り、UIを設計、構築します。
2. ユーザー向けの挙動に関わる変更では、同じ変更内でdocs/ux/scenarios.mdも更新します。シナリオのない新しい挙動は警告ではなく、進行を妨げる問題です。

オプトアウトは明示的に伝えるものであり、推測してはいけません： オペレーターが「no scenarios」／「без сценариев」と言った場合、このルートを辞退したものとして扱います。ベースなしで進め、そのことを納品時に伝えてください。黙って省略してはいけません。

ベストプラクティス： シナリオの作成やレビューでは、best-practices.mdを参照してください。機能／ジャーニーの段階（オンボーディング、ペイウォール、リテンションなど）と製品ドメインに一致するタグで絞り込みます。トレースされたジョブ／ストーリーに役立つ場合にのみプラクティスを適用し、適用したプラクティスのID（BP-NNN）をシナリオのデザイン根拠に記載してください。カタログは随時更新されます。「追加方法」のルールに従い、実証された新しいプラクティスを追加します。

ワークフローの選択

状況	ワークフロー
docs/ux/scenarios.mdがなく、コードがほとんどない、または存在しない	Init（グリーンフィールド）
docs/ux/scenarios.mdがなく、製品コードが存在する	Init（既存コード）
ベースが存在し、挙動を追加／変更する	Update
ベースは存在するが、一貫性に疑問がある、または新機能のアイデアが出ている	Validate

実行するワークフローを伝えてください。docs/ux/が存在しない場合は作成し、このスキル内のtemplates/scenarios.mdをもとにscenarios.mdを用意してください。

初期作成（グリーンフィールド）

ここではシナリオを設計し、リバースエンジニアリングは行いません。

1. ユーザーに一度に1つずつ質問します。ペルソナは誰ですか？それぞれ、どのような業務のためにこの製品を利用しますか？中核となる機能は何ですか？ユーザーに絶対に起きてはならないことは何ですか？
2. ペルソナを作成してから、機能ごとにシナリオを作成します。各機能について、フォーマット契約に定められた機能ごとの完全性チェックリスト（正常系、すべてのエラー経路、空の状態、画面上で確認できる読み込み状態、破壊的操作の確認、再訪ユーザー向けのパターン）と、製品ごとのチェックリスト（初回起動時のオンボーディングから複数エンティティのフローまで）を満たします。ペルソナやシナリオの根拠として使えるのは、実際のユーザーと実際のデータだけです。合成ペルソナ、LLM の「デジタルツイン」、シミュレーションセッションは、検証すべき仮説であって、証拠ではありません（このルールは ux-foundation の research-evidence.md が定めています）。
3. すべての項目を Status: draft、Coverage: none yet、Product: unobserved で開始します。最後の項目は結果の状態であり、現実世界からシグナルが届くまで unobserved のままです。シナリオをリリースしても状態は変わらず、シナリオに対する監査に合格しても変わりません。
4. ベースをセクションごとにユーザーに提示し、承認を得ます。承認されたシナリオは validated に移行します。
5. 画面が依存するシナリオが検証された後に限り、そのシナリオを参照しながら、画面の UI デザインや実装を開始できます。ビルド状態は ux-flows の4状態マシン（full / provisional / tooling-degraded / declined）に従います。承認済みのテキスト仕様は、オプションの Figma がなくてもビルドでき（フレーム同期は延期）、重大な不明点がある場合は依存する画面のみがブロックされます。また、ここで記録された承認は、チェーンを再実行しなくてもすべてのレイヤーで有効です。

初期作成（既存コード）

まず、存在するものすべてをベースに含め、その後に不足箇所を明らかにします。

1. コードベースの全体を棚卸しします（大規模なコードベースでは、利用可能なサブエージェントを使って並行作業し、各エージェントに担当領域を割り当てます。委任しない場合は、同じ網羅性を保ちながら各領域を順番に調査します）。対象は、ルートと画面、インタラクティブな要素（ボタン、フォーム、ダイアログ、メニュー）、状態分岐（読み込み中／空／エラー／成功）、エラー経路とユーザーに表示される内容、オンボーディングと初回起動時のロジック、設定、複数エンティティのフローです。
2. 棚卸しの結果をもとに、機能ごとにシナリオを作成し、調査で見つかった file:line の根拠を Coverage: に記入します。
3. 双方向の不足箇所を、ユーザーへの報告で明示します。
   • シナリオがないコードの動作（場当たり的に作成されたものです。今回、内容を記録します）。
   • コードがないチェックリスト項目（例：空の状態がまったく存在しない）。これらは Coverage: none yet の draft シナリオとして記録します。
4. グリーンフィールドの手順4と同様に、検証のために提示します。

更新

変更（差分、機能の説明、バグ修正）が与えられた場合：

1. 機能と UI 要素に基づいて、影響を受けるシナリオを特定します。ベースを検索してください。記憶だけを頼りにしないでください。
2. 編集を適用します。既存シナリオの手順／要素／エラーを調整し、新しい動作には新しいシナリオを追加し、もはや正しくないシナリオは廃止します（Status: retired と理由を1行で記載し、削除はしないでください）。
3. 変更したシナリオは、再承認されるまで draft に戻します。Index テーブルも最新の状態に保ちます。
4. 変更によってユーザー向けの動作が導入され、この確認を経ても該当するシナリオがまったくない場合は、作業を止めてその旨を伝えます。その動作をリリースする前に、シナリオについて判断する必要があります。

検証

ベースの整合性を確認します（新機能のアイデアを承認する前にも実施します）。

1. 整合性： ID が連番で一意であること、Index が各エントリーと一致していること、参照されているすべてのペルソナが定義されていること、ステータスが有効であること。
2. 網羅性： すべての機能が機能ごとのチェックリストを満たし、プロダクトがプロダクトごとのチェックリストを満たしていること。不足している項目を列挙します。
3. 追跡可能性（foundation.md が存在する場合）：すべての must／should ストーリーに 1 つ以上のシナリオがあること、すべてのシナリオが 1 つ以上のストーリーまたはジョブに紐づいていること、プロダクトとの接点があるすべてのジャーニー段階に 1 つ以上のシナリオがあること。どちらの方向でも孤立している項目は指摘事項です。
4. 矛盾： 互いに矛盾するシナリオ（同じエントリーポイントで結果が両立しない、同じ要素の動作が異なる）。新機能のアイデアの場合：まず foundation と照合して（どのジョブに役立つか、どのジャーニー段階に当たるか）、次に既存のシナリオと照合します。UI 作業に入る前に、調整案を提示します。どのジョブにも役立たないアイデアには異議を唱え、黙って受け入れることはしません。
5. 指摘事項は、項目ごとの修正案を添えたチェックリストとして報告し、承認された修正を適用します。

ベースからのモデレートテスト用タスク（依頼時）

複数画面にわたるジャーニーでは、ベースと併せてクリック可能なシナリオプレビューを推奨します。依頼があれば、これは成果物になります。 interactive-flow-prototypes.md に従ってください。 プレビューでは、本番承認前にドラフトシナリオを調整できます。各ケースを画面状態と遷移に紐づけ、代替／エラー／復旧経路を含め、宣言された網羅性と実際にクリックして確認した内容を分けてください。シミュレーション上の成功によって、実装の網羅性やプロダクトの成果ステータスが変わることはありません。

シナリオはすでに、ユーザビリティテスト用タスクに必要な形を備えています。つまり、状況、目標、観察可能な成功条件です。一方から他方への変換は、新しい成果物を作ることではなく、書き換えです。そのため、ユーザーを対象にテストを行う段階になったら、タスクを新たに書くのではなく、ベースから生成します。

対象となる各シナリオについて：

• シナリオ — プロダクト側の言葉ではなく、参加者自身の言葉で状況を記述します。「SCN-014 を開く」ではなく、「同僚からプロジェクトを引き継いだばかり」。
• 目標 — 達成のために使う UI の名前を挙げずに、達成しようとしていることを記述します。「設定を見つける」は誘導的なタスクです。「通知の送信先を変更する」ならタスクになります。
• 成功 — シナリオの Expected result から取り入れた、観察可能な最終状態です。

タスクの妥当性を保つルール：文面にインターフェース上の動作を表す動詞を入れないこと（「クリック」「タップ」「X ボタン」など）。最初にウォームアップを行い、最後にエッジケースを扱うこと。シナリオ 1 つにつきタスクは 1 つにすること。目標が 2 つ必要なタスクは、2 つのタスクです。シナリオに代替経路やエラー経路がある場合は、それらを負荷テスト用のタスクにします。

得られた結果は、同じベースに照らして評価します。誰も完了できなかったタスクは、参加者ではなく、そのシナリオに対する指摘事項です。参加者は実在する人です。ペルソナになりきって回答するモデルは参加者ではなく、その回答もテスト結果ではありません。

完了の定義

• Index、ペルソナ、エントリーの整合性が取れ、フォーマットの契約が守られていること。
• 新規／変更シナリオをユーザーが確認し、承認していること（validated）。
• ギャップや矛盾が率直に報告され、黙って削除されていないこと。

references/ にはほかに何があるか。 このスキルでは契約を 5 件直接参照していますが、references/ には 13 件あります。このスキルが参照する契約がさらに別の契約へリンクしており、その依存関係一式をスキル内に含める必要があるためです。skills CLI はディレクトリを 1 つインストールするので、兄弟ディレクトリにあるファイルはリンク切れの状態で配置されてしまいます。ここに記載されたファイルを開いてください。残りは、契約から名前を示して参照されたときに、その契約をたどって確認できます。