git-pr

Files (1)

• SKILL.md

SKILL.md (first lines)

# Git PR

PRはdraftで作る。書く前にベースブランチとの全差分とコミットログを読む。会話の記憶で書かない。
descriptionの目的は、レビュワーがコードを読み始める前に知るべきことを伝え、レビューの認知負荷を下げること。
読者は「リポジトリは知っているが、この作業の経緯と会話は知らない人」。会話の内容はレビュワーには見えない。

## 原則

- diffを読めばわかることは書かない
- diffを読んでもわからないが、diffを理解するのに必要なことは書く
  - なぜ変えるのか、マージ後に利用者やシステムから見て何が変わるか、根本原因
- Whyは会話・issue・コミットメッセージから取る。出所がなければ推測で埋めず、ユーザーに聞く
- PRの大きさに合わせる。1文で足りるなら1文で終える
- 書き終えたら各文を検査する。diffを読めばわかる文と、出所のない推測の文は消す

## 構成

- タイトルはマージ後に何が変わるかを1行で書く。作業の経過や手段ではなく結果を書く
  - 悪い例: 「UserRepositoryにキャッシュを追加」
  - 良い例: 「ユーザー一覧の再表示を高速化する」
- `PULL_REQUEST_TEMPLATE`があればその骨格と順序に従う。該当しない項目は見出しごと省く
  - チェックボックスは実際に確認した項目だけ埋める。記入ガイドのコメントは消す
- テンプレートがなければ見出しを作らず、散文で書く
- 冒頭で「なぜ」と「マージ後に何が変わるか」を伝える。判断の経緯や補足はその後ろに置く
- 大きな話から細かい話へ並べる。思いついた順・書きやすい順にしない
- 言語やprefixの有無は、マージ済みの既存PRに合わせる

## 表・図・画像

- 変更前後の挙動が条件や入力ごとに異なるなら、表で並べる。前後が1組なら文で書く
- UIが変わるなら、スクリーンショットを `gh pr create --attach './before.png#変更前'` で添付する（`gh pr edit`も同様）。手元にないファイルは参照せず、ユーザーに求める
- 図(Mermaid)は、3つ以上の要素の相互作用、状態遷移、変更前後で構造が変わる場合だけ使う。1本道の流れは図にしない

## 該当する場合だけ書く

- 自信のない判断、副作用が読み取りにくい箇所。変更箇所の一覧にしない
- 却下した選択肢とその理由
- スコープ外にしたこと、後続で対応すること
- 実際に実行した確認と、していないこと。実行していないものを確認済みと書かない
- 前提となる別PR、設定変更、デプロイ順

## 書かないこと

- 変更ファイルや関数の列挙、差分の言い換え、「〜を追加しました」の羅列
- 「保守性が向上」「堅牢な」「大幅に」「適切に」のような、根拠のない評価や強調
- 「レビュー指摘に対応」「依頼どおり」のような作業報告や会話の参照
- 「このPRは〜します」「本PRでは〜を行います」のように、PRを主語や前置きにしない。何がどう変わるかを直接書く
- 太字や絵文字による装飾
- 悪い例: 「このPRはUserRepositoryにキャッシュ機構を追加し、パフォーマンスを大幅に改善します」
- 良い例: 「ユーザー一覧の表示に毎回2秒かかっていた。同一セッション内では同じデータを再取得しないようにする」

## 文の書き方

- 一文一義。「ので」「し」でつながず、「。」で区切る。主語が曖昧なら補う
- 「また」「さらに」「加えて」で文を続けない。消して通じるなら消す
- 「〜することができる」「〜を実現する」「〜を提供する」「〜を可能にする」は使わない。「〜できる」「〜する」に直す
- 社内用語やissue番号だけで済ませず、一言添える

From rmakiyama/skills, MIT.

More from rmakiyama/skills