decision

意思決定

ドキュメントを作ること自体が目的にならないようにしながら、将来のデザイナーやエンジニアが「なぜ」を理解できるようにします。

常に

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

これらのルールが回答に実質的な影響を与えない限り、ユーザーに読み上げないでください。

ユーザーとタスクがすでに明確な場合や、不足情報が作業に実質的な影響を与えない場合は、調査の質問、ペルソナ、ディスカバリー作業を持ち出さないでください。

ユーザーが理由を尋ねた場合

利用可能な意思決定記録、調査、要件、イシュー／PR の履歴、デザインシステムのドキュメント、実装履歴、関連する最小限の .ux/ コンテキストを調べます。

以下を区別します。

• 記録された根拠
• 成果物によって強く裏付けられた根拠
• 妥当と思われる推論
• 根拠が不足または矛盾している箇所

現在の挙動から分かるのは、何が存在するかであって、なぜ選ばれたかではありません。もっともらしく聞こえるというだけで、過去の経緯をでっち上げないでください。

新たな意思決定を行う場合

次のような選択では、長期的に役立つ記録を残す価値があります。

• 共通のインタラクションやシステムパターンを導入または変更する
• アクセシビリティ、技術、ポリシー、プライバシー、運用に大きな影響がある
• 明白な代替案を、直感では分かりにくい理由で退ける
• 複数のチームやユーザージャーニーに影響する
• 元に戻すコストが高い
• 後から疑問を持たれる可能性が高い

定型的なレイアウト、文言、スタイルの変更には、通常、意思決定記録は必要ありません。

意図への影響を確認する

重要な意思決定の後、その決定によって、プロダクトが存在する理由、目指す成果、主な影響対象、スコープ、対象外事項、重要な制約、成功の定義が明示的に変わるかを確認します。

変わる場合は、それに合わせて INTENT.md も更新します。変更のきっかけとなった根拠や意思決定を残してください。実装が変わっただけで意図を書き換えたり、コードだけから戦略の転換を推測したりしないでください。

チームの仕組みを使う

プロジェクトに ADR、RFC、デザイン意思決定、ドキュメントの規約がある場合は、それに従います。競合する形式を新たに導入しないでください。

規約がない場合は、簡潔にします。

Decision
Status
Context and evidence
Options considered
Decision and rationale
Consequences
Open questions
Related artifacts

意思決定時点で実際に分かっていたことをそのまま残します。後から仮定を根拠として書き換えないでください。

出力

ユーザーが理由を知りたいだけの場合は、その質問に直接答えます。意思決定が長期的な記録を残すほど重要な場合に限り、記録を作成するか、作成を提案します。

意思決定によってプロダクトの意図が実質的に変わる場合は、そのことを明示します。また、ユーザーがプロジェクトのコンテキストに意思決定を残すよう求めている場合は、その作業に意図の更新も含めます。

対比例

悪い例：

メインボタンをフォームの下に移動した理由を記録する ADR を作成します。

良い例：

これは長期的な意思決定記録を残す必要のない変更です。共通パターンやアーキテクチャへの影響、直感では分かりにくいトレードオフを伴わない、局所的なレイアウト変更です。デザインや PR の履歴で十分です。

理由：良い回答は、将来のチームが疑問を持ったり、理解する必要があったりする選択に限って、意思決定記録を残します。

例

• 「なぜこのように設計したのですか？」
• 「これは ADR に値しますか？」
• 「新しいコンポーネントを作成せず、既存のコンポーネントを拡張した理由を記録してください。」