# UX レビュー方法論: ユースケース駆動

> /beacon-review シリーズ Skill の companion ドキュメント。プロダクト全体の UX レビューを再現性をもって実行するための作法・チェックリスト・判断基準を集約する。

## 設計原則

### 0. なぜユースケース駆動か

機能リスト駆動（「CLIコマンド一覧を見て改善点を探す」）ではなく、**ユーザーがプロダクトを通じて達成したいシナリオ単位** で精査することで:
- 機能が連携した「実際の体験」が見える
- 個別機能の最適化ではなく、フロー全体の最適化に向かう
- 非開発者・初心者の視点も自然に組み込める
- 機能の網羅性ではなく、価値の網羅性で見られる

### 1. ペルソナ駆動

各UCで、最初に **誰が何のためにこれをやるか** を明確にする。ペルソナが具体的になればなるほど、何が摩擦かを判定しやすい。

良いペルソナ:
- 「3ヶ月開発を続けている個人開発者、コミット50+、READMEあり、Beaconを後から導入したい」

悪いペルソナ:
- 「ユーザー」

### 2. AI主導の対話、ユーザーの精緻化

レビュー作業はAIが主導するが、各判断はユーザーと議論して確定する。AIが一方的に「これがギャップ」と断定しない。

理由: プロダクトのユーザー像、業務の細かな機微はユーザーが詳しい。AIは構造化と提案、ユーザーは認識訂正と優先度判断を担う。

### 3. 横断的テーマへの感度

個別UCで見つけたギャップが、他UCにも同じ構造で現れることが多い。各UCで「これは他にも波及しそう」とメモしておくとメタレビューが効率化する。

例（過去のBeaconレビュー）:
- 「cwd-aware化」: 個別Skill で発見した課題が、結果的に全Skill共通テーマだった
- 「Beaconはリズム提案、概念導入はClaude Code本体に委ねる」: UC6 で発見した設計指針が、UC5/UC7 にも波及した

---

## レビューのフェーズ

### Phase 1: Init（初回設定）

UC リストを定義する。プロダクト性質に応じて違うが、汎用ソフトウェアプロダクトなら以下の典型UCがある:

| 典型UC | 説明 |
|---|---|
| UC1 | 新規プロジェクト立ち上げ |
| UC2 | 既存リポジトリ導入 |
| UC3 | 日次の開発作業（コミット→記録→次） |
| UC4 | セッション間コンテキスト引き継ぎ |
| UC5 | 週次振り返り |
| UC6 | リリース（push / deploy） |
| UC7 | Operation立ち上げ・運用 |
| UC8 | 並列実装 |
| UC9 | PRレビュー・マージ |
| UC10 | プロジェクト史を辿る |
| UC11 | 共同開発（複数人） |
| UC12 | UI/監査閲覧体験 |

プロジェクトの性質に応じて取捨選択・追加。

### Phase 2: UC Review（各UCの精査）

1つのUCに対して、以下の手順を踏む:

1. **ペルソナ確認**: 誰が、どんな状況で、何を期待するか
2. **想定フロー追跡**: ステップごとに「何をする」「どこで」「誰と」を書き出す
3. **現状確認**: 該当する Skill / CLI / Web UI を実際に Read して動作確認
4. **ギャップ列挙**: 想定フロー vs 現状で乖離している点を全て出す
5. **タスク化**: 各ギャップを `beacon task add` で起票

#### ギャップ発見のチェックリスト

各UCで、以下の観点を順に確認する:

| # | 観点 | 質問 |
|---|---|---|
| 1 | ターミナル戻り | ユーザーをターミナルに戻していないか？ |
| 2 | 質問数 | 不要な質問・確認が多くないか？推定で進められる箇所は？ |
| 3 | デフォルト | 経験ユーザー向けにデフォルト適用で1回承認だけにできないか？ |
| 4 | 専門用語 | プロダクト独自用語を説明なく使っていないか？（commit/push等の一般用語はOK） |
| 5 | 並列表示 | Web UI/Tauri との連携が成立しているか？ターミナル+UI並列が前提か？ |
| 6 | cwd 対応 | Skill が正しい cwd で動作するか？ホーム起動でも動くか？ |
| 7 | データ整合性 | 同時書き込み・stale state・race condition は？ |
| 8 | AI提案 | 「次にすべきこと」を AI が文脈で提案するか？ |
| 9 | エラーリカバリ | 失敗時の復帰経路は？認証切れ・タイムアウト時の体験は？ |
| 10 | share/引継ぎ | 別マシン・別ユーザーへの伝達経路は？deep link は？ |
| 11 | 非開発者対応 | ターゲットに非開発者が含まれるなら、その人にも回るか？ |
| 12 | 監査性 | 人間が「これで合ってる？」と確認する経路は？ |

#### タスクの書き方

各 finding タスクには以下を含める:
- **description**: 「<UC>-<番号>: <一行で具体的に>」
- **why (motivation)**: なぜそれが問題か。誰にどう影響するか。背景の議論
- **acceptance_criteria**: どうなれば解消されたかの基準
- **priority**: high / middle / low（UC内ローカルで判断、メタレビューで再調整）

例:
```
UC1-F2: brew caveats を vision/roadmap Skillベースの案内に書き換え
  why: brew install直後の最重要案内が旧来CLIフロー（milestone add手動）。今日完成した
       vision/roadmap onboarding が一切告知されず、新規ユーザーがその恩恵を受けられない
  ac: packaging/homebrew/beacon.rb のcaveatsが: (1) cloud利用なら beacon setup 
      (2) その後 Claude Code を起動して /beacon-init で会話形式で始める、という流れに更新
  priority: high
```

### Phase 3: Meta Review（俯瞰）

全UCのレビュー完了後、findings を俯瞰してクラスタリング。

#### クラスタリング基準

意味的に関連するタスクをまとめる。デフォルトクラスタ候補:

1. **データ整合性・基盤バグ**: lost update / race / 認証切れ / 監視停止 等。多くはhigh以上
2. **AI主導の体験**: AIがリズム提案する / retrospection / cwd-aware化等の自動化系
3. **要求書/SPEC運用**: 設計記録のフォーマット・タイミング
4. **オンボーディング**: 新規ユーザー導線・低リテラシー対応
5. **共同開発**: メンバー管理・PR・並列・リリース
6. **UI/UX磨き**: Web UI 検索・モバイル・細部
7. **個別バグ**: 小さい / 局所的

プロジェクト性質で増減可。「その他」は極力作らない（分類できないものは概念が曖昧）。

#### 優先度の再評価

個別UCでつけた priority を、全体観で見直す:
- **格上げ候補**: 他改善の前提になっているタスク（cwd-aware等の基盤系）
- **格下げ候補**: 局所的すぎる、影響範囲が狭い
- データ整合性系は基本最優先（基盤が壊れたら他改善が無意味）

#### MS再分割の判断

各クラスタを 1 MS にするのが基本。判断のポイント:
- **既存MSに統合できるか**: 既に進行中の関連MSがあれば吸収
- **大きすぎないか**: 30件超のMSは細分化を検討
- **小さすぎないか**: 3件未満は既存MSへの吸収を検討
- **依存関係**: あるクラスタが他の前提になっていれば優先順位を明確に

### Phase 4: Apply（適用）

合意した再分割案を実行する。

- 新規MS を `beacon milestone add` で起票
- 既存タスクを `beacon task update <id> -m <new-ms>` で **移動**（複製ではない、entry_id維持）
- 旧レビューMSを `beacon milestone observe` で観察化（削除はしない）

---

## アンチパターン（やってはいけないこと）

### 1. 機能リストベースで進める
全Skill / 全CLIコマンドを列挙して 1 つずつ評価する方法。
→ 価値ではなく機能網羅で見てしまう。フロー全体が見えない。

### 2. AIが断定する
「これがギャップです」と AI が言い切る。
→ ユーザーの認識・判断を無視する。実装したら違ったが頻発する。常に対話する。

### 3. 一度に全UCを精査しようとする
UC1-12 を1セッションで終わらせようとする。
→ 解像度が下がる。1UCあたり丁寧に時間をかける。複数セッションになって OK。

### 4. findings の優先度を最初に決めすぎる
個別UCで priority を最初に決めて、それを動かさない。
→ 全体観で見ると違う優先度が見える。メタレビューで再評価する前提で。

### 5. クラスタリングを完璧にしようとする
全ての finding が完璧にクラスタリングされるまでメタレビューを終わらない。
→ クラスタは便利な分類であって正解ではない。「概ね合ってる」で十分。

### 6. メタレビューで「その他」クラスタに逃げる
分類しにくい finding を「その他」に放り込む。
→ 「その他」が肥大化すると本質が見えない。本気で考えて分類するか、保留する。

### 7. 再分割案を実行する前に十分な議論をしない
AIが出した分割案をユーザーが鵜呑みにする。
→ プロジェクトのコンテキストを最も知るのはユーザー。必ず議論を経る。

---

## 過去事例（Beacon自身のレビュー）

参考として、Beacon プロジェクトで実施したレビューの結果（2026-05）:

- 12 UC を精査
- 95件の findings を起票
- 6 クラスタに分類
- 5 つの新規MS（ms-39〜43）に再分割
- 既存ms-37（Onboarding）にも14件統合

レビューに要した期間: 約1セッション（長時間集中）  
レビューで発見された最重要事項: データ整合性の根本欠陥（同時書き込みlost update、token expire 無限ループ、1M context monitor 停止）

詳細は beacon doc の SPEC scope に保存された:
- UC1-3 ユーザーフロー
- UC4-9 ユーザーフロー
- UC10-12 ユーザーフロー
- メタレビュー: タスククラスタリングとMS再分割案

---

## 期待される効果

このプロセスを正しく実行すると:
- プロダクト全体の品質を一度に底上げできる
- 「気付かなかった問題」が体系的に洗い出される
- 改善タスクが構造化されてバックログ化される
- AI と人間の協奏作業の再現性が確立される
- 別プロジェクトで同じ手法を適用可能

## 反復について

このレビューは **半年〜1年に1回** 実施するのが目安。プロダクトが成熟するにつれ、典型UCの数も増え、レビュー観点も増える。methodology 自体も更新していくこと（このドキュメントを直接更新するか、forkして派生methodology を作る）。
