pr

PR

PR を、設計の議論に参加していなかったエンジニアにも理解できる内容にします。

常に守ること

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

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

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

執筆前に確認すること

実際の差分または変更ファイル（参照可能な場合）、関連するデザイン／引き継ぎ資料／契約、意思決定の記録、必要最小限のプロジェクトコンテキスト、デザインシステムのコンテキスト、リポジトリの PR テンプレートを確認します。

コードが実際に変更する内容を説明します。設計意図を、すでに実装済みであるかのように PR に記載してはいけません。

レビューしやすい内容にする

役立つ PR の説明では、通常、次の点に答えます。

• この変更はなぜ必要ですか？
• ユーザーから見える動作、またはシステムの動作はどう変わりましたか？
• どの既存コンポーネントやパターンを再利用、拡張、追加しましたか？
• 重要な状態のうち、どれに対応していますか？
• 関連するアクセシビリティの動作は何ですか？
• 何をテストまたは検証しましたか？
• 意図的に対象外としたものは何ですか？
• レビュアーは特にどこを確認すべきですか？

参照可能な場合は、信頼できるデザイン、意図、意思決定、チケット、契約の成果物へのリンクを含めます。

PR テンプレートに空のセクションを無理に追加しないでください。

レビューを容易にする

リスクの高い遷移、非同期の動作、新しい共通パターン、移行への影響、未解決の制約、初期デザインから意図的に変更した箇所を明記します。

「UI を更新」などの曖昧な説明や、時系列に沿った膨大な変更ログは避けます。

リポジトリでの操作

ユーザーが PR の作成を依頼し、ツールで実行可能な場合は、まずブランチ／差分とリポジトリの状態を確認します。PR の作成、更新、マージ、レビュアーの依頼、その他 PR を変更する操作には、ユーザーの承認が必要です。説明が完成しただけでマージしてはいけません。

対比例

悪い例：

新しいデザインに合わせてアカウント復旧 UI を更新します。アクセシビリティの問題とエラー状態もいくつか修正します。

良い例：

理由： アカウント復旧中に確認に失敗すると、ユーザーが先に進めなくなることがありました。

変更内容： 確認に失敗した場合、入力済みのコードを保持し、既存の Alert エラーパターンを表示して、フォーカスをエラー概要に移動するようになりました。新しいデザインシステムのコンポーネントは追加していません。

レビュー： API エラーのマッピングとフォーカスの動作を確認してください。コードの有効期限切れからの復旧は、この PR の対象外です。

理由：良い例では、すべてのファイル変更を順に説明することなく、エンジニアに必要な理由、実装された動作、システムへの影響、レビュー時の注目点、対象範囲を示しています。

例

• 「この UX 変更の PR 説明を書いてください。」
• 「エンジニアが実際にレビューできる PR を作成してください。」
• 「このデザインとエンジニアリングの変更を PR で説明してください。」