ux-persona

ux-persona — ペルソナ主導のユーザビリティウォークスルー

実際のユーザーになりきり、アプリケーションの1つの利用フローを進めて、使いやすいかどうかを評価します。コードが「動く」かどうかではなく、実際の人が自力で目的を達成できるかを評価します。摩擦が生じる箇所をすべて記録し、実行可能なレポートを作成します。あらゆる Web プロジェクトで利用できます。プロジェクト固有の情報（開始 URL、ペルソナ、手順）はすべて、このスキルではなくフローファイルから取得します。

これらのスキルでは、抽象的なユーザビリティだけでなく、実装された画面と計画されたデザインとの整合性（デザイン忠実度）も検証します。フロー（またはステップ）でデザイン参照（design_ref — 例：Figma ノードの URL、エクスポートされた画像、仕様書）が指定されている場合、実装された画面をその参照と照らし合わせて評価します。画面が計画されたデザインと一致していなければ、「動く」場合でも指摘事項になります。

入力（フローが最初です）

• $ARGUMENTS = フローファイルへのパス（慣例：プロジェクト内の e2e/flows/<id>.md）。空の場合は、プロジェクト内で利用可能なフローを一覧表示し、どれを実行するか尋ねます。
• フローファイルでは、ペルソナ、開始地点（最初の URL。通常はホーム／ランディングページ）、事前条件、ステップ（各ステップは UI 操作と期待される結果）を宣言します。
• ペルソナは、採用する評価の視点です。次の順に解決します。
  1. プロジェクトのペルソナ（e2e/personas/<persona>.md、プロジェクト固有）。
  2. このスキルに同梱された共通ペルソナ（この SKILL.md からの相対パス personas/<persona>.md）— 詳しくは以下の 同梱ペルソナ を参照してください。
  3. フォールバック：急いでいて、URL を入力したりパスを推測したりしない初心者ユーザー。

最重要ルール（絶対遵守）

操作はインターフェースを通じてのみ行います。 フローで宣言された開始地点から、以降の各ステップには、表示されている要素をクリック／入力して到達しなければなりません。画面に「直接移動」するために、内部ルートの URL を入力することは絶対にしないでください。次のステップに URL の入力でしか到達できない場合、これはブロッカーとなるユーザビリティ上の指摘事項です。記録し、その時点でフローを停止してください（画面自体は存在していても、ユーザーはそこに到達できません）。直接 URL に切り替えると不具合が隠れてしまいます。切り替えてはいけません。

実行バックエンド

セッションで利用可能なブラウザー自動化ツールをデフォルトで使用してください。ユーザーが Webwright、再現可能な証跡、生成されたブラウザースクリプト、またはより充実したスクリーンショット／操作ログによる監査証跡を明示的に求めた場合は、実行バックエンドとして Webwright スキル／プラグインを使用してください。

Webwright を使用する場合：

• このスキルのフローファイルを信頼できる情報源としてください。フローのユーザー目標、手順、事前条件、期待される結果、ペルソナの視点、および design_refs を Webwright のクリティカルポイントに反映してください。
• 最重要ルールを守ってください。生成するスクリプトはフローの entry URL から開始し、それ以降の画面には、内部 URL を入力するのではなく、表示されている UI 操作を通じて到達しなければなりません。
• Webwright の final_runs/run_<id>/ アーティファクトは証跡として扱い、永続的なレポートにはしないでください。このスキルの通常の e2e/usability/<flow-id>--<YYYY-MM-DD>.md レポートで、関連するスクリーンショット／ログ行を引用してください。
• Webwright が機械的には成功しても、ペルソナの評価基準で見つけやすさの悪さ、わかりにくい文言、フィードバックの欠如、デザインの不一致、または偽データが見つかった場合は、ユーザビリティ上の指摘事項として記録してください。自動化の成功は UX の成功ではありません。
• Webwright スクリプトが回帰テストとして広く役立つ場合は、安定した経路をプロジェクトのネイティブな Playwright E2E スイートに移植することを推奨してください。生成された Webwright スクリプトを CI の信頼できる情報源として扱ってはいけません。

手順

1. 事前条件。 フローを読みます。アプリがフローのエントリーポイントでアクセスできること（できない場合は、プロジェクトの実行コマンドで起動するか、報告して停止します）、およびフローに必要な最小限のデータが存在することを確認します。
2. ブラウザーを開きます（セッションで利用可能なブラウザー自動化ツールを使います）。タブのコンテキストを取得 → このウォークスルー用の新しいタブを作成 → エントリーポイントに移動します。最初のスクリーンショットを撮ります。
3. ペルソナになりきります。 各ステップで次の操作を行います。
   • 一人称で、ペルソナになりきって語ります（「<ペルソナ>として、<目標>を達成したいです。…のようなものを探します。」）。
   • スクリーンショットを撮り、画面を確認して、UI を通じて操作（クリック／入力）を試みます。
   • 忠実度チェック — フローまたはステップに design_ref が指定されている場合、デザイン案（Figma ノード／画像／仕様）を取得します。まず、デザインに含まれるすべてのセクション、ブロック、コンポーネントを上から順に列挙します。 次に、それぞれをレンダリングされた画面と照らし合わせて評価し、present（一致）、missing（デザインにあるがコードにない）、extra（コードにあるがデザインにない）、different（存在するが異なる — レイアウト、文言、色／トークン）のいずれかに分類します。忠実度の判定は、セクションごとの列挙に基づくものとし、全体的な印象だけで判断してはいけません。 セクションを「任意」として黙って扱ったり、「簡略化」して省いたりしてはいけません。デザインにあって未実装のものはすべて、明示的に列挙する missing の指摘事項です。「忠実」という主張には、意見ではなくセクションごとの一覧による裏付けが必要です。デザインと一致しないプレースホルダー画面や未スタイルの画面は、たとえ「動作」していても指摘事項です。
   • データの真正性チェック — 確認画面、詳細／結果画面、一覧、概要など、画面にユーザーへデータが表示される場合は、実際のデータが反映されていることを確認します。フローの前の段階で実際に入力した値、またはバックエンドが実際に返した値である必要があり、プレースホルダー、lorem ipsum、サンプル、ハードコードされた値であってはいけません。洗練された画面でも、モック／スタブの内容（例：「Lorem ipsum」、000000/00、固定の名前、静的な日付）に接続されていれば、「動作」してデザインに忠実に見えていても指摘事項です。実際のユーザーに偽のデータを見せているためです。ウォークスルー中に生成した値（検索したプロトコル、入力したテキスト、アップロードしたファイルなど）と、少なくとも 1 つのフィールドを照合します。ユーザー自身のデータであるかのように偽造データを表示することは、通常、重大度 high に該当します。デザインモックに lorem ipsum が含まれるのは想定内ですが、同じ lorem ipsum が実行中のアプリに残っているのは不具合です。
   • 以下の評価基準で評価し、問題点を記録します。
4. 締めくくり。 レポートを作成し（出力を参照）、短い要約を返します。

ユーザビリティ評価基準（各ステップを評価）

項目	ペルソナの問い
発見しやすさ	推測せずに目的の操作への道筋を見つけられましたか？操作や入口は見つけやすかったですか？
明確さ	ラベル、タイトル、指示は明確でしたか？何を入力すればよいか分かりましたか？
フィードバック	操作のたびにシステムから応答がありましたか（成功、エラー、読み込み）？
手間	ステップやフィールドが多すぎませんでしたか？重複した要求はありませんでしたか？必要な情報を持っていませんでしたか？
エラー／行き詰まり	途中で壊れたり、エラーになったり、次の手順が分からなくなったりしましたか？
忠実度	コード上の画面は予定されたデザイン（design_ref）と一致していますか？ブランド／ヘッダー、レイアウト、コンポーネント、文言、色／トークンを確認します。
データの真正性	画面には自分の実データ（入力した値や操作による実際の結果）が表示されていますか？それともプレースホルダー／サンプル／lorem／ハードコードされたデータですか？デザインに忠実に見える画面でも、実ユーザーにモックの内容を表示していれば指摘事項です。

各指摘事項には重大度を付けます。blocker（完了できない） · high（大きな手間がかかるが完了できる） · medium（煩わしい） · low（仕上げの問題）。

出力（永続レポート）

e2e/usability/<flow-id>--<YYYY-MM-DD>.md に書き込みます（日付は環境から取得します。尋ねるか導き出してください。作り出してはいけません）。

# Usability — <flow name> (<flow-id>)
- **Persona:** <persona> · **Date:** <YYYY-MM-DD> · **Entry:** <flow url>
- **Verdict:** ✅ completable | ⚠️ completable with friction | ❌ blocked at "<step>"

## Walkthrough
<one line per step: what the persona did and saw>

## Findings (prioritized)
| # | Severity | Step | What happened | Suggested fix |
|---|---|---|---|---|
| 1 | blocker | ... | ... | ... |

## Key screens
<reference to the saved screenshots>

最後に、判定 + 重大度ごとの指摘件数 + レポートのパスを返します。

同梱のペルソナ

このスキルには、すぐに使える一般的なプロジェクト非依存のペルソナが personas/（このファイルと同じ階層）に含まれています。novice、rushed、skeptical、mobile、accessibility、power-user を利用できます。プロジェクト独自のペルソナを e2e/personas/ に定義することもできます（こちらが優先されます）。一覧については personas/README.md を参照してください。

運用上の注意

• 成功を偽らないでください： ページが応答しなかった場合は、「フィードバックなし」と報告してください。これは調査結果であり、あなたの失敗ではありません。
• ループ防止： ブラウザーの操作に2～3回失敗したら、そこで止めて報告してください。クリックを繰り返したり、フロー外の画面をあちこち見たりしないでください。
• 妥当なテストデータを使い、前のステップで生成された値（たとえば、新しく作成した参照 ID）を再利用してください。前提条件が満たされていない場合は、無理に進めず、調査結果／前提条件として記録してください。
• ブラウザーは単一の共有リソースです。検証は一度に1つのフローだけ行ってください。ux-flows スキルが順番に呼び出します。