create-pr

name	create-pr
description	GitHub Pull Request を作成するときに使用する。タイトル規約、説明欄テンプレート、各セクションに書くべき内容、ベースブランチ、許可される操作、説明欄に含めるべき情報と禁止事項を定義する。

GitHub Pull Request 作成ガイド

gh コマンドを利用して GitHub への PR を作成する。

PR を書く目的（最重要・常に意識すること）

PR の説明欄を書く際は、以下の 2 つの観点が 超重要 である。テンプレートに沿って機械的に埋めるのではなく、すべての判断は常にこの観点に立ち戻ること。

1. 未来の開発者が PR を見た時に、設計理由や実装の意図を理解できるか

• PR は 「コードに残らない設計判断の文脈・意思決定の記録」 を残す場である
• 数ヶ月後・数年後の自分や他の開発者、AI エージェントが過去 PR を辿って「なぜこの実装になっているのか」「なぜ別案ではなくこれを選んだのか」を理解できる必要がある
• コードからは「何が」（What）は読み取れるが、「なぜ」（Why）「他にどんな選択肢があり、なぜ採用しなかったか」（Why not other）は PR にしか残らない
• この観点で書かれていない PR は、未来において「履歴があるのに役に立たない」状態になる

2. レビュアーの視点に立って書かれているか

• レビュアーは PR 全体を 初見で読む。コミット履歴を順番に追えるとは限らないし、Issue の経緯を全部把握しているわけでもない
• レビュアーが理解しやすいように、変更の 背景 → スコープ → 判断の根拠 を順序立てて説明する
• 専門用語や略語を使う場合は、レビュアーが知らない可能性を考慮して補足する
• レビュアーへの「動作確認の丸投げ」は禁止。動作確認は PR を出す側の責任で完結させ、レビュアーには 設計判断の妥当性を議論してもらう

判断に迷ったら問い直す

各セクションの記述に迷ったときは、以下の 2 つを自問する。

• 「半年後の自分が読んで、なぜこの実装になっているか分かるか？」
• 「PR を初見で開いたレビュアーが、5 分で文脈を把握できるか？」

NO なら情報が足りていないか、書き方が不適切。再検討すること。

これらに反する PR 説明（変更内容の羅列だけ、コミットメッセージのコピー、CI で分かる情報の重複記載、レビュアーへの動作確認依頼）は ノイズ であり、書く価値がない。

許可されている GitHub 操作

• GitHub への PR の作成
• GitHub への PR へのコメントの追加
• GitHub Issue の新規作成
• GitHub Issue へのコメントの追加

以下の操作は ユーザーの許可があれば 可能。許可なく勝手に実行してはならない。

• Git へのコミット
• GitHub へのプッシュ

PR 作成ルール

事前確認：現在のブランチを必ずチェック

PR を作成する前に、必ず以下のコマンドで現在のブランチを確認する。

git rev-parse --abbrev-ref HEAD

• 原則：ユーザーが作業用ブランチ（例：feature/issue7/add-docs）を作成済みなので、現在のブランチをそのまま利用する

• 例外（要ユーザー確認）：現在のブランチが以下の 保護対象ブランチ だった場合、ユーザーがブランチ作成を忘れている / 操作ミスをしている可能性があるため、そのまま PR を作成してはならない

  • main（本番リリース先）
  • staging（PR のデフォルトベースブランチ）

  この場合は、ユーザーに次のように確認する：

  現在 <保護対象ブランチ名> ブランチに居ます。通常は feature/issue<番号>/<内容> のような作業ブランチを切ってから PR を作成しますが、このまま進めてよろしいでしょうか？それとも新しいブランチを切り直しますか？

  ユーザーの返答を得るまで gh pr create を実行してはならない。

その他のルール

• PR のタイトルは 日本語 で、変更内容を端的に表す（例：「依存 package を最新安定版に更新」「MCP ドキュメントに Streamable HTTP トランスポートを追加」）
• PR の作成先は特別な指示がない場合は staging ブランチ（gh pr create --base staging）
• PR の説明欄は .github/PULL_REQUEST_TEMPLATE.md のテンプレート構造に従って入力する（後述）
• 対応 issue がある場合は、PR の説明欄に issue URL を記載する
• Issue 番号は現在のブランチ名から取得できる
  • 例：feature/issue7/add-docs の場合は 7 が Issue 番号

PR の説明欄に含めるべき情報

• 「なぜその変更が必要なのか」を最重視する。変更内容の列挙だけでは不十分
• 変更が複数の論点にまたがる場合は、論点ごとに「なぜ XX としているか」のサブセクションを作って説明する（過去 PR #473 の「なぜ patch / minor 更新のみで完結しているか」「なぜ Node.js を 22 → 24 に更新したか」のスタイル）
• 影響を受ける機能・API エンドポイント・他のファイルがあれば明記する
• 数値で示せる影響範囲（変更ファイル数、テスト件数）があれば補足情報に書く

PR の説明欄に記載してはいけない情報

• fix #issue番号 や close #issue番号 のような自動 close 系コメント
  • 1 つの issue で 1 つの PR とは限らないため
• 「全てのテストをパス、Linter、型チェックを通過」「npm run format / lint / test 全て成功」などのコメント
  • テストや Linter が通過しているのは当たり前であり、わざわざ書くべき事ではない
  • CI の実行結果を見れば分かる情報を PR 説明に書くのは ノイズ

PR 説明欄のテンプレート構造と各セクションに書くべき内容

.github/PULL_REQUEST_TEMPLATE.md で定義されている構造に従う。各セクションに何を書くかを具体的に整理する。

全セクション必須の原則

テンプレートに記載されているセクションは必ずすべて埋める。任意とされるセクションでも、空のまま省略してはならない。該当する内容が無い場合は、〇〇のため記載なし のように 理由付きで明示的に「なし」と記載する。

• ❌ NG：該当しないセクションを丸ごと省略する → レビュアーが「書き忘れ」か「該当なし」か判別できない
• ✅ OK：「README.md のドキュメント変更のみで Component / UI の変更を伴わないため、Storybook 連携は不要」のように、判断の根拠を含めて記載

これは「未来の開発者・レビュアーが PR を初見で読んだ際に、なぜそのセクションが空なのかを判断できる」状態を保つために重要。

# issueURL（必須）

• 対応する GitHub Issue の URL を フル URL で 記載する
  • 例：https://github.com/nekochans/lgtm-cat-frontend/issues/451
• 関連 issue がある場合は箇条書きで列挙してよい
  • 例：- #470 - 関連: #471, #472

# この PR で対応する範囲 / この PR で対応しない範囲（必須）

• ## 対応する範囲 と ## 対応しない範囲 の H2 サブセクションに分けて箇条書きで記載する

• 「対応しない範囲」は積極的に書く。スコープを明示することでレビュー観点が明確になり、別 PR での対応が必要な事項を共有できる

• 例：

  ## 対応する範囲
  
  - `package.json` / `package-lock.json` の依存 package を最新安定版へ更新
  - GitHub Actions の Node.js バージョンを 22 → 24 に更新
  
  ## 対応しない範囲
  
  - 動作確認中に検出した既存の警告は別 Issue へ切り出して個別対応
    - LCP 警告（`priority` 未設定）→ #471
  

# Storybook の URL、 スクリーンショット（必須・該当なしの場合も理由付きで記載）

このセクションは PR 作成時点では空になることが多いが、省略は禁止。以下の運用ルールに従って必ず記載する。

UI 変更がある場合

PR 作成後、Chromatic ビルドが完了するのを待ってから URL を取得し、gh pr edit で説明欄を更新する流れになる。

1. PR を作成する（gh pr create --draft ...）
2. Chromatic CI が走り、Storybook が公開される（数分かかる）
3. PR の Storybook URL を取得する。以下のいずれかの方法で取得できる
   • CLI 経由（AI エージェント向け推奨）：gh pr checks <PR番号> --repo <owner>/<repo> の出力から Storybook Publish 行の URL を抽出
   • GitHub UI 経由（人間向け）：PR ページの「All checks have passed」セクションで Storybook Publish のリンクをクリック
   • どちらの方法でも、PR 毎に Chromatic が生成した 公開 Storybook のベース URL が得られる
     • 例：https://622b6c5dc31e9e003a111eb5-vwrshrxnjd.chromatic.com/
4. 必要に応じて、特定の Story を指す ?path=/story/<story-id> を末尾に付ける
   • 例：https://622b6c5dc31e9e003a111eb5-cprksiyplm.chromatic.com/?path=/story/features-docs-docsmcppage--japanese
5. gh pr edit <PR番号> --body "..." で取得した URL を該当セクションに貼り付けて更新

スクリーンショットを併載する場合は、デスクトップ / モバイル の両方を別見出し（H2）で載せると親切。

注意：gh pr checks の出力には Deploy Storybook to chromatic という GitHub Actions ジョブ行（https://github.com/.../actions/runs/... 形式）も含まれる。これは Storybook の URL ではなく CI ジョブの URL なので混同しないこと。PR 説明欄に書くべきは Storybook Publish 行の *.chromatic.com/ 形式の URL。

UI 変更がない場合

「なし」とだけ書くのではなく、なぜ該当しないのか を理由付きで記載する。

例：

• 「README.md のドキュメント変更のみで Component / UI の変更を伴わないため、Storybook 連携は不要」
• 「src/scripts/ 配下の開発用スクリプトの追加のみで、レンダリング対象の Component は含まれないため不要」
• 「依存 package のバージョン更新のみで、UI 表示への影響は無いため不要」

# 変更点概要（必須）

• このセクションは「何を変更したか」と「なぜ変更したか」をセットで書く

• 推奨構成：

  1. ## なぜこの変更が必要か：背景・動機を明示
  2. ## 主な変更内容：番号付きリストで、変更したファイルパスとセットで詳細を説明
  3. 必要に応じて ## なぜ XX としているか のサブセクションを追加

• 例：

  # 変更点概要
  
  ## なぜこの変更が必要か
  
  Issue #470 の Done 定義「依存 package が全て最新安定版に更新されている事」を満たす定期メンテナンスのため。
  
  ## 主な変更内容
  
  1. **API エンドポイント実装** (`src/app/(default)/api/lgtm-images/route.ts`)
     - Cognito Client Credentials Grant でアクセストークンを取得
     - 外部 API から LGTM 画像を取得し、後方互換性のある形式に変換して返却
  
  2. **テスト追加** (`src/app/(default)/api/lgtm-images/__tests__/route.test.ts`)
     - 成功時、外部 API エラー時、アクセストークン取得失敗時の 3 パターンをカバー
  

# レビュアーに重点的にチェックして欲しい点（任意だが極力書く）

前提：コードレビューは「コード品質をブラッシュアップする場」「設計判断を議論する場」「将来の開発者・AI エージェントが意思決定の文脈を辿るための記録」である。動作確認やバグ検査をレビュアーに丸投げする場ではない。

• ❌ NG な書き方：「〜に挙動変化がないか」「〜が正しく動くか」「〜にバグがないか」「〜に懸念がないか」
  • レビュアーへの動作確認の丸投げになり、PR を出す側の態度として不適切
  • 動作確認は PR を出す側の責任。CI と自分の検証で完結させる
• ✅ OK な書き方：設計判断の 根拠と妥当性 を問う形で書く
  • 「XX のアプローチを採用したが、設計判断として妥当か」
  • 「複数案あった中で YY を選んだ。別観点があれば指摘してほしい」
  • 「設計書では AA に配置する想定だったが、依存解決のため BB に配置した。是非を議論したい」
  • 「XX のルールを変更した。レイヤー構造の原則に照らして適切か」
• 自分でも判断に迷った箇所、トレードオフの判断、ルール / 規約の解釈ゆれが発生する箇所を中心に書く
• 過去 PR #465 の良い例：
  • src/types/url.ts と src/functions/url.ts の分割が適切か（isUrl は型ガードだが functions に配置）
  • src/constants/url.ts に i18nUrlList を配置した判断（設計書では lib/config/ だったが、functions/meta-tag.ts からの依存解決のため constants に配置）
  • src/lib/ → src/features/ 全面依存を許可するルール変更の是非

# 補足情報（任意）

• ブラウザ等で行った特別な検証（標準的な表示確認を超えて、特定のシナリオ・エッジケースを確認した場合のみ）
  • 例：「Chrome / Safari / Firefox の 3 ブラウザで Drawer の挙動を確認」「モバイル実機で Sentry へのエラー送信を確認」
• 関連する設計ドキュメントや実装計画書のパス
• 検出した既存課題で本 PR では対応しないもの（別 Issue 起票済みなら番号を併記）
• 書かないこと：CI で確認できる情報（format / lint / test の通過状況、テスト件数、変更ファイル数）はノイズになるため記載しない

実行例

gh pr create --base staging --title "依存 package を最新安定版に更新" --body "$(cat <<'EOF'
# issueURL

https://github.com/nekochans/lgtm-cat-frontend/issues/470

# この PR で対応する範囲 / この PR で対応しない範囲

## 対応する範囲

- `package.json` / `package-lock.json` の依存 package を最新安定版へ更新
- GitHub Actions の Node.js バージョンを 22 → 24 に更新

## 対応しない範囲

- 動作確認中に検出した既存警告は別 Issue へ切り出し（#471, #472）

# 変更点概要

## なぜこの変更が必要か

Issue #470 の Done 定義「依存 package が全て最新安定版に更新されている事」を満たす定期メンテナンスのため。セキュリティパッチや安定性向上を取り込み、後続の機能追加を最新版前提で進められるようにする。

## 主な変更内容

1. **依存 package 更新** (`package.json`, `package-lock.json`)
   - `next`: 16.2.1 → 16.2.4
   - `react` / `react-dom`: 19.2.4 → 19.2.5

2. **CI Node.js バージョン更新** (`.github/workflows/ci.yml`)
   - 22.x → 24.x

# レビュアーに重点的にチェックして欲しい点

- patch / minor 更新に絞った今回の判断について、追従すべき設計変更が他に存在しないか別観点で意見があれば指摘してほしい
- CI の Node.js を 22 → 24 に揃えた構成（ローカル / Vercel / CI のバージョン乖離をなくす目的）の是非。matrix を 24 一本に絞るかどうかも含め、設計判断として妥当か

# 補足情報

特になし。
EOF
)"

特別な検証や補足情報がない場合は、# 補足情報 セクションを丸ごと省略してもよい。