ux-design-for-architects

アーキテクトが、UI 以外のユーザー接点(API / 設定 / 拡張機能) の UX を設計・レビューするための指針。UI 画面のデザイン (配色・レイアウト等) は対象外。

UX は UI だけでなく、システムとユーザーのあらゆる接点に及ぶ。接点の UX が悪いと、後から変えにくく (利用者が依存するため)、システム全体の成功確率が下がる。だから実装より先に決める。

進め方

接点を特定する: 対象は API / 設定 / 拡張機能のどれか (複数可)。
ユーザーを特定する (原則1): 誰が、何のために、どの技術レベルで使うか。
該当する接点の詳細ガイドを読む:
- 設定 → references/configuration.md
- API → references/api.md
- 拡張機能 → references/extensions.md
6 原則でチェックする (下記)。設計案を出すなら、原則に照らした根拠を一言添える。
レビューなら、references/review-checklist.md の形式で指摘する。
判断が割れる点は、ユーザーに仮説付きで確認する (AskUserQuestion)。

#	原則	要点	なぜ
1	ユーザーを理解する	目標・技術レベル・メンタルモデル・典型ワークフローを把握し、期待どおりに動かす (驚き最小の原則)	ユーザーは自分の予想と違う行動を取る。聞くより観察・計測が有効
2	必要最小限のことをする	必要なフィーチャーだけ出す。広く使われる標準 (OAuth, OpenID 等) があれば採用	提供したものは負債になる。一度出すと慣れられ、直しにくい
3	マニュアル不要にする	使い方を自明にし、レコメンドや手がかりで導く	ユーザーはマニュアルを読まない。解決できなければ製品が悪いと判断する
4	情報交換の観点で考える	聞かずに済ませる > 少なく聞く > 答えやすい形で聞く。同じことを二度聞かない	入力は負担。推測・記憶・導出で減らせる
5	シンプルなものをシンプルに	最初の数操作の障壁を取り除く。事前設定済みクライアントやサンプルを用意	初心者ほど離脱しやすい。最初の体験が定着を決める
6	実装より前に UX を設計する	アーキテクチャより先に UX、フィードバックを回しながら詰める	実装後の UX 変更は高コスト。実装は遅らせ、設計は深く

優先順位で考える:

聞かない: 妥当な既定値、環境からの自動検出、過去の入力の記憶、既知情報からの導出
少なく聞く: 本当に必要なものだけ
答えやすく聞く: 内部実装の言葉ではなく、ユーザーが頭の中で計算せず答えられる形で聞く (例: 「最大キャッシュエントリ数」ではなく「キャッシュに使うメモリ上限」、さらに「サーバーかクライアントか」のようなモード選択から詳細を導出)

性能上の問題がなければ、ユーザーが理解できる形で多めに情報を返し、次の行動を予測できるようにする。ある呼び出しの結果を次の呼び出しへ渡す場合は、加工を最小限にして渡せるようにする。

設定: 設定は「導入しない」が最善。次に自動決定、最後に妥当な既定値付きで導入。問いは「ユーザーは我々より良い文脈を持っているか?」— Yes のときだけ設定にする。未知キー・適用失敗は黙殺せずエラー。有効な設定値は起動時などに確認できるようにする。
API: 利用者は開発者。学びやすく、誤用しにくく、次の一歩が常に明確に。1 つのことをうまくやる。定型コードを書かせない。標準に乗る。最初からバージョン管理。公開は必要になるまで遅らせ、まず内部で使う。
拡張機能: ユースケースを深く理解するまで追加を待つ (後からリファクタリングで足せる)。1 つのことをうまくやる。入出力を定義し、内部構造を露出しない。一度公開すると変更しにくい。

専門家がいない場合は、その旨を明示し、UX の専門家を早期に巻き込むことを推奨する。ただし助言を拒んで設計を止めず、本ガイドに沿った暫定案を出す。

設計提案: 「対象接点 → ユーザー像 → 提案 → 該当原則と理由 → 未決事項」の順で簡潔に。レビュー: references/review-checklist.md の形式。