dont-make-me-think

Don't Make Me Think — ユーザビリティレビューと再設計

Steve Krug の「Don't Make Me Think」の原則に基づいて、UI を評価し、改善します。レポート自体も Krug の教えを実践する必要があります。つまり、ざっと読みやすく、視覚的で、余計な情報がないことです。人間なら30秒で目を通せて、AI エージェントなら内容を解析して修正に取りかかれるようにしてください。

使用するタイミング

ユーザーから、スクリーンショット、ライブ URL、HTML/CSS コードを対象とするユーザビリティ監査、UX レビュー、UI フィードバックを求められた場合に、このスキルを使ってください。ビジュアルやブランドの批評、WCAG アクセシビリティ監査、バックエンド/API のレビューには使用せず、適切な別の手段に振り分けてください。

依存関係の事前確認（必須）

このスキルは /browse（frontmatter の dependencies）をライブ URL の場合にのみ呼び出します。最初のページ遷移の前に一度実行してください。

if test -f "$HOME/.claude/skills/browse/SKILL.md"; then
  echo "browse_mode=installed browse_skill=$HOME/.claude/skills/browse/SKILL.md"
elif test -f "$HOME/.agents/skills/browse/SKILL.md"; then
  echo "browse_mode=installed browse_skill=$HOME/.agents/skills/browse/SKILL.md"
elif command -v asm >/dev/null && asm deps --help >/dev/null 2>&1; then
  asm deps discover dont-make-me-think --json || echo "discover failed; acquire still runs" >&2
  echo "browse_mode=lease"
else
  echo "Missing skill: browse. Install: asm install github:garrytan/gstack:browse -p claude -s global --yes" >&2
  echo "No asm yet: npm install -g agent-skill-manager@latest" >&2
  echo "browse_mode=none"
fi
printf 'dmmt_session=%s\n' "dont-make-me-think-$(date +%s)-$$"   # record it; reuse it verbatim

gstack が /browse をインストールしていても、asm が認識していない場合があるため、インストール経路のテストを先に実行します。

1. browse_mode=installed：記録された browse_skill パスを読みます。
2. browse_mode=lease：asm deps acquire browse --session <dmmt_session> --json を実行し、返された skillMdPath を直接読みます。
3. browse_mode=none、または手順2が失敗した場合：「エラーハンドリング」の「レビュー可能な入力がない」行に従います（フェイルソフト）。読み込めなかった URL は決してレビューしないでください。
4. 必ず finally で解放してください。 手順2を実行した場合は、最終的にどのような結果になっても（停止した場合も含む）、asm deps release --session <dmmt_session> --json を一度実行してください。

編集前のリポジトリ同期（必須）

以下の手順1～4は読み取り専用です。**再設計モード（手順5）では UI のソースファイルに書き込みます。**ユーザーがドライランの差分を確認したら、最初の編集の前に references/redesign-mode.md の「リポジトリ同期の7つの手順」（git -C "$repo"、スタッシュを優先し、スキップした項目を記録）を実行してください。リベースの競合が発生した場合は git -C "$repo" rebase --abort を実行し、ファイルには書き込まず、作業を停止してユーザーに確認してください。同期を強制してはいけません。このスキルは何もコミットしません。

手順

エージェントのコンテキスト予算を抑えるため、次のワークフローに従ってください。各手順の後に、その手順の完了レポートを出力してください。

1. 前提条件を確認する — 「入力の処理」テーブルから入力タイプを特定します。
   • 入力がない場合は、「エラーハンドリング」の「レビュー可能な入力がない」行に従います。
   • レビューでライブ URL を読み込む場合（evidence-dir がない場合、または references/orchestrated-runs.md に従ってライブ URL にフォールバックする場合）は、依存関係の事前確認を実行します。
2. 入力を処理する — そのタイプに対応する「入力の処理」の操作を実行します。
3. 評価する — 「10の観点」のうち該当する各観点を0～10点で評価し、各問題に重大度を付けます（「レポート形式」を参照）。根拠が不十分な観点は推測せず、「評価対象外」とします。
4. レポートを生成する — references/report-format.md のテンプレートに記入し、出力します。output-dir が指定されている場合は、<output-dir>/usability-review.md にも書き込みます。
5. 再設計（任意） — ユーザーが修正を求めた場合に限り、再設計モードを実行します。

前提条件

レビュー可能な入力が1つ必要です。ライブ URL の場合のみ /browse が必要です。再設計モードの場合のみ、UI ファイルへの書き込み権限が必要です。

入力の処理

入力タイプ	操作
スクリーンショット/画像	直接レビューします。正確なパレット、寸法、密度の数値が必要な場合や、画像が複数ある場合は、python3 scripts/process_screenshots.py <image_path> [--recursive] を実行します（references/screenshot-processing.md）。
ライブ URL	「ライブサイトの操作方法」に従って /browse を使用します
オーケストレーターの evidence-dir	/browse の代わりに、その中の page.html と screenshots/ をレビューし、テストしていない操作を明示します
HTML/CSS/JS コード	コードを読み、ユーザー体験を中心に評価します
ワイヤーフレーム/モックアップ	仕上がりではなく、情報アーキテクチャに注目します
口頭での説明	まず確認の質問をします

数値に関する主張には、必ずスクリプトの標準出力 JSON を使用してください。視覚的な推定値を実測値として示してはいけません。

ライブサイトのレビュー

1. /browse でページに移動し、幅を 1280 px に設定してページ全体のスクリーンショットを撮影します。
2. メインの CTA、メインナビゲーション、フォームフィールドがあればそのうち 1 つをクリックまたはホバーします。それぞれの動作を記録します。
3. 幅を 375 px にしてページを読み込み、スクリーンショットを撮影します。幅を設定できない場合は、レンズ 9（モバイル）を未評価とします。
4. これらのスクリーンショットと操作をもとにレビューし、実施しなかった項目をすべて 未テスト に列挙します。

オーケストレーションされた実行

orchestrated-by、evidence-dir、または output-dir の行がある場合は、 references/orchestrated-runs.md に従います。これらがない場合、変更はありません。再設計モードには引き続き 明示的な確認が必要です。

10 のレンズ

各レンズの詳細については references/krug-principles.md を読みます。該当するレンズを使って評価します。

#	レンズ	核となる問い
1	自明さ	これが何で、何をするものかを理解するために、ユーザーは立ち止まるでしょうか？
2	スキャンしやすさ	2〜3 秒でページの構成を把握できますか？
3	視覚的階層	視覚的な重みは重要度に合っていますか？
4	言葉の簡潔さ	すべての言葉に意味がありますか？
5	ナビゲーション	現在地と移動方法が常にわかりますか？
6	トランクテスト	何の予備知識もなくここに来た場合、サイトは何か、どのページか、何ができるかを答えられますか？
7	ランディングページの明確さ	5 秒以内に、このサイトが何をするものか説明できますか？
8	アフォーダンス	何がクリックまたはタップできるか、すぐにわかりますか？
9	モバイル	タッチ対象、操作のしやすさ、隠れたジェスチャーがないことは確保されていますか？
10	信頼への配慮	UI はユーザーの時間と信頼を尊重していますか？

レポート形式

references/report-format.md のテンプレートとレポートのルールに従います（段落は使わず、指摘事項ごとに 1 行、問題ごとにセレクターを記載し、スコアは正直に付けます）。ここにはバリエーション、BLOCKED ブロック、読み手向けのチェック項目も記載されています。output-dir を指定した場合、主要な問題の前に出力するインライン要約行の例：

Thinking Cost: HIGH — 3 critical issues found (disabled button, missing nav labels, no landing clarity)

ステータス（タイトル直下の **Result:** 行の最初の単語）：

ステータス	条件
COMPLETE	レポートが作成され、該当するすべてのレンズが採点されている。
PARTIAL	レポートは作成されているが、該当するレンズのうち少なくとも 1 つが未評価とされている。
BLOCKED	レビュー可能な入力がないため、レポートは作成されない。代わりに 4 行の BLOCKED ブロックを出力する。

深刻度： 🔴 重大 — ページの主要タスクを妨げる、またはエラーや離脱を引き起こす可能性が高い。 🟡 中程度 — ユーザーは目的を達成できるが、操作中に止まったり、読み返したり、前の画面に戻ったりする。 🟢 軽微 — 仕上げの問題で、速度低下は予想されない。

思考コスト： 🔴 の問題が 1 つでもある場合は HIGH、🔴 はなく 🟡 が 1 つでもある場合は MODERATE、それ以外は LOW。

再設計モード

ユーザーが指摘の報告だけでなく修正の適用を希望する場合は、references/redesign-mode.md に従います。以下のルールは必須です。

• まずレビューを作成し、その後、修正ごとにドライランの差分（ファイルパス、セレクター、変更前／変更後）を示します。🔴 の問題を最初に扱います。
• ユーザーが明示的に確認するまで、何も書き込みません。オーケストレーターがユーザーに代わって確認することはありません。
• 必要最小限の変更にとどめ、ブランドを維持します。編集する前にファイルの内容を記録し、書き込みに失敗した場合はその内容を復元します。
• git checkout や git restore でロールバックしてはいけません。これらはユーザーによる他の編集内容を破棄します。
• 最後に再設計の要約（Result:、Evidence:、Uncertainty:、Decision:）を記載します。

エラー処理

状況	対応
レビュー可能な入力がない：何も提供されていない、/browse が利用できない、URL にアクセスできない、画像を読み取れない、または説明に関する質問への回答がない	URL、PNG/JPEG スクリーンショット、HTML エクスポート、または説明を一度だけ求めます。提供されない場合は BLOCKED ブロックを出力します
スクリーンショットの前処理に失敗	目視でレビューし、失敗を 測定結果 に記録します
HTML/CSS コードが不完全	提供されている内容を評価し、欠けている部分を 未評価 に記載します
再設計モード — ファイルに書き込めない	再設計の要約でそのファイルを挙げ、修正案を仕様として示します

エッジケース

各エッジケースの簡易チェック、問題のないページ、ネイティブアプリ、CSS フレームワーク、多数または非常に大きなスクリーンショット、埋め込み指示については、references/edge-cases.md を参照してください。

受け入れ基準

期待される出力：references/report-format.md の Usability Review レポート。以下を満たすと実行は合格です。

• 該当するすべての観点が採点されているか、未評価に記載され、ステータスが PARTIAL になっている
• 各問題に、Problem、Impact、Fix、Where の各フィールドが1行ずつある
• Thinking Cost が問題の件数と一致している。Fix Priority は影響度、次に工数の順で並んでいる
• 完全版テンプレートには mermaid Issue Map が含まれ、簡易確認版と問題なし版には含まれていない
• レポートは **Result:** の行で始まり、Evidence and Limits と Next Decision で終わる。測定値にはスクリプトの出力のみを記載する
• 出力が references/report-format.md の4つの読者チェックに合格している。人間のレビュアーの回答がない場合、人間が理解したことは確認されていない
• Redesign Mode では確認前に何も書き込まず、Redesign の要約で終わる
• リースされた /browse は、すべての終了時に解放される
• レポートは30秒で流し読みできる。表と箇条書きを使い、段落は使わない

ステップ完了レポート

各 Instructions ステップの後に1つ出力します。テンプレートとチェック項目：references/step-completion-reports.md。