setup-ux

セットアップ UX

今後の UX 作業を、推測ではなく意図と根拠に基づいて始められるよう、必要な情報を把握します。

常に

• コンテキスト — ユーザーに同じことを繰り返し尋ねる前に、既知の情報を確認します。製品の目的や成果によって回答が変わり得る場合は .ux/INTENT.md を使用し、タスクに必要な追加のプロジェクトコンテキストだけを読み込みます。
• ユーザー — 影響を受ける人々、その目標、タスク、状況、利用可能な根拠に基づいて作業します。ユーザーのニーズ、行動、ペルソナをでっち上げてはいけません。
• 根拠 — 違いが重要な場合は、既知の情報、推測、仮定、不明な情報、矛盾する情報を区別します。
• システム — 新しいものを考案する前に、確立された製品の用語、コンポーネント、パターン、ルールを優先します。
• 明確さ — 役立つポイントから始め、必要最小限の構成にし、ありきたりな AI の水増し表現を取り除きます。
• 信頼 — 根拠、要件、理由、実装状況、コンプライアンスをでっち上げてはいけません。
• 成果 — 複数の手順を伴う重要な作業では、意図を常に念頭に置き、継続性が必要な場合に限って簡潔な .ux/STATE.md を使用します。仕上げに入る前に、影響の大きい未解決の課題を優先し、完了を宣言する前に実際の体験が意図に沿っているか確認します。

これらのルールが回答に実質的な影響を与えない限り、ユーザーに繰り返し説明しないでください。

ユーザーとタスクが明確な場合や、不足情報が作業に実質的な影響を与えない場合は、調査の質問、ペルソナ、発見のための作業を持ち込まないでください。

セットアップの進め方を決める

新規プロジェクトか既存プロジェクトかを判断します。利用可能なプロジェクト情報から明らかな場合は、その進め方を推測します。それ以外の場合は、新しいプロジェクト／製品なのか、既存のものを扱うのかを短く一つだけ質問します。

セットアップスキルを別に作成しないでください。どちらの進め方でも、同じ簡潔な .ux/ コンテキストレイヤーにたどり着きます。

新規プロジェクト：対話を通じて意図を把握する

有用なプロジェクトの根拠がほとんどない場合があるため、まずユーザー自身の言葉でアイデアを話してもらいます。答えによって設計内容が実質的に変わり得る、次の質問だけを尋ねます。

必要に応じて明らかにする項目は次のとおりです。

• なぜこれを作るのか、何をより良くするのか、または何を新たに可能にするのか。
• 誰が影響を受け、何を達成する必要があるのか。
• 中核となる体験やユーザージャーニー。
• 現在のスコープと、明示的な対象外事項。
• すでに把握している制約。
• 定義されている場合、成功とは何を意味するのか。
• 利用可能な根拠と、仮定や不明な点。

一度に尋ねるのは、一つ、または関連する少数の質問にとどめます。定型的な質問票を使ったり、作業を始める前にすべての見出しを埋めるよう求めたりしないでください。

意図が判断の指針として十分に具体化したら、まず .ux/INTENT.md に記録します。有用な要約をデザイナーに提示し、推測よりも訂正を優先します。

既存プロジェクト：意図を再構築する前に調べる

質問する前に、リポジトリと接続された情報源を調べます。README や製品ドキュメント、既存のユーザー調査、分析データやサポートの根拠、パッケージファイル、Storybook、コンポーネント、トークン、デザインシステムのドキュメント、Figma やその他の接続されたデザイン情報源、アクセシビリティガイドライン、issue／PR テンプレート、既存の決定事項など、利用できる情報を確認します。

信頼できる根拠に基づいて製品の意図を再構築した草案を作成します。ただし、現在の動作と意図する成果は分けて扱います。コードからフローの存在は確認できても、組織がそれを選んだ理由までは通常確認できません。

重要な情報の不足、矛盾、または信頼できる形で確定できない意図についてのみ質問します。調べれば分かる情報をユーザーに尋ねないでください。

古い .ux/ ディレクトリに CONTEXT.md、DESIGN-SYSTEM.md、DECISIONS.md だけが含まれている場合は、それらのファイルを保持して INTENT.md を追加します。新しい構成に合わせるためだけに、確立されたコンテキストを書き換えてはいけません。

コンテキストを簡潔に保つ

役に立つ最小限のコアを作成または更新します。

.ux/
├── INTENT.md
├── CONTEXT.md
├── DESIGN-SYSTEM.md
└── DECISIONS.md

所有権、テンプレート、根拠のステータス、移行、意図の更新、プロジェクトのコンテキストを小さなファイルに分割する妥当性については、references/context-contract.md をお読みください。

INTENT.md

製品や機能が存在する理由、目指す成果、影響を受ける人々、中心となるタスク／体験、現在の対象範囲と対象外、重要な制約、分かっている場合は成功の定義、重要な前提や不明点を記録します。

簡潔にまとめてください。PRDではなく、北極星となる指針です。

CONTEXT.md

運用環境を記録します。観察可能な製品の仕組み、主要なユーザージャーニー、エビデンスの所在、エンジニアリングの技術スタックとワークフロー、アクセシビリティへの期待、用語、そして今後のUX作業に役立つ安定したプロジェクト情報が含まれます。

両方のファイルに製品についての記述があるというだけで、意図を重複して記載しないでください。

DESIGN-SYSTEM.md

実際のデザインシステムの情報源とルールを記録します。Storybook、Figma、コンポーネントパッケージ、トークン、情報源の優先順位、再利用に関する期待、コントリビューションの手順が含まれます。

DECISIONS.md

重要なUXまたはアーキテクチャ上の決定を簡潔にまとめたインデックスを管理します。プロジェクトにADRや別の意思決定システムがすでにある場合は、競合するものを作成せず、そちらを参照してください。

コンテキストを段階的に使う

セットアップ時に、調査リポジトリ、ペルソナライブラリ、ジャーニーカタログ、制約フォルダーをデフォルトで作成しないでください。

情報の密度、繰り返しの利用、または明確な管理主体の違いによって分割が有用になる場合に限り、情報を小さなファイルに分けます。たとえば、本当に必要なプロジェクトでは、.ux/users/tasks.md、.ux/evidence/research.md、.ux/constraints/accessibility.md などが該当します。

今後のスキルでは、製品の目的、成果、対象範囲、成功の定義によって回答が変わり得る場合に INTENT.md を読み込み、そのうえでタスクに関連する追加のコンテキストだけを読み込んでください。あらゆるリクエストに .ux/ ディレクトリ全体が必須のコンテキストだと見なさないでください。

.ux/STATE.md はセットアップの対象ではなく、5つ目のコアコンテキストファイルでもありません。将来のエージェントがこれを作成できるのは、継続性が失われるおそれのある大規模な複数ステップの作業に限られます。これは破棄可能な作業状態であり、永続的な製品情報ではありません。

情報が不足していてもかまいません

不明な点があるからといって、セットアップを止めないでください。回答によって今後の提案が大きく変わる場合に限り、質問してください。

前提を事実として扱わないでください。区別が重要な場合は、人々、エビデンス、要件、決定、意図、重要な不明点に関する主張に、既知、推測、仮定、不明、または見解の相違があるというラベルを付けてください。通常の製品の仕組みにはラベルは不要です。

意図を慎重に更新する

INTENT.md は安定したものとして扱いますが、固定されたものではありません。既存の意図をデフォルトとし、通常の設計や実装作業を経ても維持してください。

明示的な人間からの指示、または信頼できるエビデンスによって、製品の目的、目指す成果、対象となる人々、対象範囲、対象外、重要な制約、または成功の定義が実際に変わったと示された場合に限り、変更してください。ファイルを再生成するのではなく、有用な範囲で最小限の編集を行ってください。

意味を変えずに既に確立された意図をより明確にできる場合は、小さな説明の追加を既存の箇所に加えてください。重要な変更の場合は、その根拠となった決定やエビデンスを DECISIONS.md またはプロジェクト既存のADR／RFCシステムに残してください。

現在の実装を正当化したり、不都合な制約を取り除いたり、完了した作業が後から意図に沿っていたように見せたりするために、意図を書き換えないでください。エージェントの推測だけでは、確立された意図を覆せません。

有用な形で終える

学んだこと、見つかった重要な不足点、意図、ユーザーコンテキスト、デザインシステムを理解できており、作業を開始できるかどうかをデザイナーに伝えてください。

その後は終了してください。セットアップを監査やディスカバリーワークショップに発展させないでください。