Agent Skills: PR を作成する

PR を作成する

現在のブランチの変更を分析し、プロジェクトの PR テンプレートに沿って、レビューしやすい PR を作成する。

なぜ重要か

PR はレビューの入口である。変更を書いた本人はすでに内容を理解しているが、PR 本文はそれ以外の人、つまりレビュー担当者、将来の保守者、この変更をチームのコードとして受け入れる人のために書く。

読み手は実装の背景を知らない。diff を開く前に、何を読むべきか、どこに注意すべきか、どの観点で質問すべきかを PR 本文から判断する。そのため、本文に書くべきことと書くべきでないことは明確に分かれる。

PR 本文の役割は、diff だけでは分からないことを伝えること。動機、検討した選択肢、制約、特に注意して見てほしい箇所を書く。 文章の品質判断は writing-tech-text skill に委譲する。この skill では、PR 作成に必要な調査、テンプレート反映、GitHub 操作に責務を絞る。

ワークフロー

1. 状況を確認する

現在の状態を理解するため、次のコマンドを並列に実行する。

• git status — 未コミットの変更を確認する
• git log --oneline -1 — 最新 commit を確認する
• git rev-parse --abbrev-ref HEAD — 現在のブランチ名を取得する
• remote ブランチを確認し、base ブランチを判断する。通常は main または development

2. 未コミットの変更を確認する

未コミットの変更がある場合は、先に commit するか、それらを含めずに進めるかをユーザーに確認する。未コミットの作業を黙って無視しない。

3. PR テンプレートを読む

次の場所を上から順に探す。

1. .github/PULL_REQUEST_TEMPLATE.md
2. .github/pull_request_template.md
3. docs/pull_request_template.md

テンプレートがない場合は、概要、主な変更内容、動作確認 を含む簡潔な構成を使う。

テンプレートがある場合は、そのセクションと構造をそのまま維持する。特定の PR では不要に見えるセクションでも、省略、統合、削除しない。テンプレートはチームで合意された形式であり、すべてのセクションを出力に残す。該当する内容は埋め、該当しないセクションはテンプレートに別の指示がない限り空のまま残す。

4. 変更を分析する

PR に含まれる内容を理解するため、次のコマンドを並列に実行する。

• git diff <base-branch>...HEAD — すべてのコード変更を確認する
• git log <base-branch>..HEAD --oneline — このブランチの commit 履歴を確認する

diff を注意深く読む。機械的な変更内容だけでなく、変更の意図を理解する。コミットメッセージから、なぜその変更が行われたのかの手がかりも拾う。

5. 変更の意図が分からない場合は質問する

変更の動機、判断理由、含めた範囲、含めなかった範囲が diff とコミットメッセージから分からない場合は、PR 本文を書き始める前にユーザーへ質問する。推測で「なぜ」を埋めない。

質問は、PR 本文を書くために必要な最小限に絞る。たとえば次のように聞く。

• この変更で解決したかった問題は何ですか？
• この方針を選んだ理由、または避けた代替案はありますか？
• レビュー担当者に特に見てほしい観点はありますか？

ユーザーの回答が得られたら、その内容をもとに PR 本文を書く。回答が得られない場合は、分かっている事実だけを書く。意図が不明な箇所は断定せず、必要に応じて本文ではなくユーザーへの確認事項として残す。

6. PR を下書きする

分析結果をもとに PR テンプレートの各セクションを埋める。 PR 本文を書く前に writing-tech-text skill を使い、読者起点、根拠、主体、具体性、読み手の負荷を確認する。 日本語で PR を書く場合は、writing-tech-text/references/ja.md も読む。

• 言語: PR のタイトルと本文は、会話でユーザーが使っている言語に合わせる。ユーザーが日本語なら日本語、英語なら英語で書く。

• タイトル: 70 文字未満を目安に簡潔にする。プロジェクトが Conventional Commits を使っている場合はそれに合わせる。タイトルは目的を表すもので、ファイル名の一覧にしない。

• 本文: テンプレートの構造に従う。本文は、変更の動機、判断、制約、レビューしてほしい観点を中心にする。diff のファイル別要約は避ける。

• 変更内容を箇条書きにする場合でも、path/to/file: X を変更、のようにファイル名と説明を並べる形式は避ける。読み手がレビュー前に理解すべき観点、つまり振る舞い、方針、外部仕様、制約、移行リスク、意思決定を軸にする。

  悪い例:

  - `src/auth.ts`: token validation を追加
  - `src/api.ts`: error handling を修正
  

  よい例:

  - 認証失敗時に曖昧な 500 ではなく、原因に応じた 401/403 を返す
  - token の検証を入口で揃え、呼び出し側が認証状態を個別に解釈しないようにする
  

• 該当しないセクションに N/A を並べない。テンプレートが許すなら空のままにする。

• 関連 issue がある場合は #issue-number または URL でリンクする。

下書き後、PR 作成前に writing-tech-text のセルフチェックで本文を見直す。

7. 作成前に確認する

remote へ push する前に、次の内容をユーザーに提示して確認する。

• base branch
• head branch
• PR title
• PR body
• push と PR 作成を実行してよいか

ユーザーが「確認不要」「そのまま作って」のように明示している場合だけ、この確認を省略してよい。

8. push して PR を作成する

• 現在のブランチを remote に push する。upstream tracking を設定するため -u を使う。
• 整形した本文で gh pr create を実行する。

本文の形式を保つため、HEREDOC を使う。

gh pr create --title "title here" --body "$(cat <<'EOF'
PR body here
EOF
)"

代替手段: gh が使えない、または API 制限に当たる場合

gh がインストールされていない場合、または API rate limit で PR を作成できない場合は、GitHub の PR 作成 URL を生成する。これにより、ユーザーはタイトルと本文が入力済みの状態でブラウザから PR を開ける。

URL は次の形式で作る。

https://github.com/<owner>/<repo>/compare/<base>...<branch>?quick_pull=1&title=<url-encoded-title>&body=<url-encoded-body>

• <owner>/<repo> は git remote get-url origin から取得する。
• タイトルと本文は URL encode する。改行、空白、特殊文字も percent-encode する。

生成したリンクと、下書きしたタイトル / 本文をプレーンテキストでユーザーに提示する。必要なら手動でコピー & ペーストできるようにする。

9. 結果を報告する

作成した PR の URL、または代替の作成 URL を返し、ユーザーがブラウザで確認できるようにする。

ユーザーからの追加 context

$ARGUMENTS