byratio/ux-agents

UXテスティングエージェント — ペルソナベースのブラウザ駆動レビュー

ユニットテストや人間によるセルフレビューでは見逃されがちなUX問題を発見するパターン：ペルソナエージェントを定義し、Playwright経由で実際のブラウザを操作し、特定のユーザー視点からジャーニーをウォークスルーして、摩擦点を報告します。この手法が有用であることを示した実際の結果として、エージェントが初回実行時に、誰も報告していなかったワークスペースドロップダウンの非同期バグをフラグした事例があります。

いつ設定するか

• プロジェクトに複数の異なるユーザータイプが存在するWebフロントエンドがある — 新卒vs.ミッドキャリアvs.退職者、無料枠vs.エンタープライズ管理者、患者vs.プロバイダなど。ペルソナは、デフォルト設定、語彙、利用可能な機能が各ユーザーにとって実際に異なると感じられるほど十分に異なっている必要があります。
• アプリの表面積が十分に大きく、全ての変更に対してすべてのペルソナを手動でウォークスルーすることが現実的でない。
• 開発サーバーを認証の手間なくローカルで実行できる（または認証にスクリプト化されたバイパスが存在する）。

以下の場合はスキップしてください：UIのないAPI、CLI、単一ペルソナの内部ツール。

エージェントの配置場所

プロジェクトスコープで.claude/agents/に配置し、ユーザーのグローバル設定には配置しません。ペルソナにはプロジェクト固有の知識（数値範囲、機能名、ジャーニー）が埋め込まれており、一般化できません。各ペルソナは独自の.mdファイルで、フロントマターを持ちます：

---
name: <persona-slug>-ux
description: <アプリ>を<ワンラインペルソナ>の視点からUXテストします。Playwright経由で実際のブラウザを駆動し、各タブをスクリーンショットし、摩擦点を報告します。<領域>に影響を与えるUI変更の後にプロアクティブに使用します。
tools: Bash, Read, Write, Edit
---

あなたは<ペルソナ>をロールプレイするUXテスティングエージェントです。

## あなたのペルソナ
<5～10行：年齢、役割、知識レベル、このセッションでの目標、知らないこと>

## ワークフロー
1. API経由で新しいワークスペースを作成する（実際のデータを汚染しない）。
2. API経由でペルソナに合わせた入力をシードする。
3. /tmp/ux-<slug>.mjsでPlaywrightを使ってブラウザを駆動する。
4. このペルソナに関連するタブをスクリーンショットする。
5. 各スクリーンショットを読み取り評価する。
6. 結果をplans/ux-reports/<slug>-<date>.mdに書き込む。
7. テストワークスペースをクリーンアップする。

また、同じディレクトリに_shared-ux-protocol.md（先頭のアンダースコアによりエージェントと誤認されるのを防ぎます）も配置します。このファイルには、環境の前提条件、出力形式、「何を評価するか」のルーブリックなどが含まれます。各ペルソナファイルは必要に応じてこれを引用します。

必要なスキャフォールディング

• plans/ux-reports/ が存在すること（セットアップ時に作成し、レポートの出力先を確保します）。これは、リポジトリ内のplans/が進行中の作業に関するドキュメントを保持し、gitにコミットすることで推論がチャットセッションより長く残るという規約に基づきます。UXレポートはそのようなドキュメントの1つです。プロジェクトにplans/ディレクトリがない場合は作成するか、ユーザーと別の場所を合意し、全てのペルソナファイルにそのパスを記述します（エージェントはパスをハードコードするため）。
• Playwrightがnpx playwrightで動作すること（エージェントは新しいマシンでnpx playwright install chromiumを一度実行する必要があるかもしれません — これをエージェントの指示に組み込んでください）。
• データをシードするためのAPIが存在するか、決定論的なUIフローが文書化されている必要があります。これらのどちらかがないと、エージェントは脆くなりすぎます。

ペルソナ設計ルール

• 知識のギャップが価値を生む — 新卒エージェントは経験者が気に留めない専門用語を発見し、退職者は過度な単純化を発見します。2つのペルソナが同一のレポートを出す場合は、統合してください。
• セッションごとに具体的な目標を設定する — 「アプリを探検する」のような曖昧なものではなく、「この給料で将来リタイアできるか？」のような検証可能なものにします。「アプリを使う」は検証不可能です。
• 知らないことを明示する — 「SWR / Coast FI / 72(t)が何を意味するか知らない」と指定することで、エージェントがそれらの用語を無視せずにフラグするよう強制します。
• 数値範囲が重要 — ペルソナの貯蓄額が$5Kの場合、$500Kの貯蓄者向けに設計されたデフォルト値では、グラフの軸スケーリングやゼロハンドリングなどのバグが表面化します。これらは中央値のペルソナでは見逃されるでしょう。

出力の規律（各エージェントにエンコード）

• すべての発見を[blocker] / [friction] / [polish]でタグ付けする。
• 問題ごとに一行の修正提案を添える。
• 「次に出荷すべきトップ3修正」セクションで締めくくり、ユーザーに優先順位付けされたアクションリストを提供する。
• スクリーンショットやAPIレスポンスで実際に観察されたことのみを報告する — 推測による苦情は不可。

エージェントの実行

.mdファイルを配置した後、Claude Codeを再起動してください — エージェント定義はセッション開始時にスキャンされます。新しいセッションで、use the <persona>-ux agent to review the calculator after my latest changesのように使用します。各実行は数分かかります（実際のブラウザを使用するため）、すべての変更に対して連続実行せず、意味のあるUI作業の後にのみ実行してください。

ユーザー向けの追跡事項

このパターンを設定する際、プロジェクトのCHANGELOG.mdまたはplans/下の計画ドキュメントに以下の事項を記録してください：

• エージェントが存在することと、レポートの出力先。
• 開発サーバーの前提条件（新しいコントリビューターがコールドプロジェクトに対してエージェントを実行しようとしないように）。
• ペルソナが依存するプロジェクト固有のデータシードに関する注意点。

よくある落とし穴

• エージェントに開発サーバーを起動させないこと。 ゾンビプロセスを残す傾向があります。curl -fsS http://localhost:<ポート>で確認させ、サーバーがダウンしている場合は処理を拒否させる — ユーザーが起動します。
• 実際のワークスペースやデータセットを再利用しないこと。 常にUX: <ペルソナ>ワークスペースを作成し、削除します。過去の状態による汚染された発見は、ユーザーのレビュー時間を無駄にします。
• ペルソナを汎用的な「カジュアルユーザー」にしないこと。 そこからノイズが発生します。ペルソナが具体的であればあるほど、レポートは有用になります。
• あまりに多くのエージェントを並列実行しないこと。 Playwright + 開発サーバー + エージェントごとのChromiumにより、ラップトップのメモリがすぐに不足します。逐次実行で問題ありません。