/create-draft-pr

PR を作成する。テンプレートのセクションは削らず、各セクションは書きすぎない。この2つを同時に守るのが本スキルの主眼。

引数

• ベースブランチ名（省略時: PJ CLAUDE.md の BASE_BRANCH）
• --no-draft: Draft 以外で作成する場合に指定

実行手順

1. 現在の状態確認

git branch --show-current
git status --short
git log <base-branch>..HEAD --oneline
git diff <base-branch> --stat

未コミット変更が残っていれば /commit を先に実行する（品質チェックもそこで通す）。

2. PR テンプレートの確認

cat .github/PULL_REQUEST_TEMPLATE.md 2>/dev/null || cat .github/pull_request_template.md 2>/dev/null
ls .github/PULL_REQUEST_TEMPLATE/ 2>/dev/null

テンプレートがあれば、すべてのセクションを埋める。レビュアーが記入を前提にした項目が欠けると差し戻しの原因になるので、セクションは削除しない。該当なしのセクションも見出しを残して「特になし」と1行書く。テンプレート内の HTML コメント（<!-- ... -->）は消す。

3. 変更内容の確認

git diff <base-branch> --name-only
git diff <base-branch>

4. 動作確認とスクリーンショット

PR を作る前に、変更をローカルで実際に通す。lint・typecheck・test の通過は挙動の保証にならないため。

• すべての差分: 変更を実際に通す確認（実行・テスト・起動のどれか）をローカルで行う。変更した関数・コマンド・エンドポイントを、変えた入力で呼ぶ
• 画面・UI・挙動が変わる差分（コンポーネント・テンプレート・CSS・ルーティング・API の応答形式を含む）: ローカルで起動し、変えた操作を画面で通す。ブラウザ操作ツールを使う前に context/browser-automation.md を Read する
• 画面が変わる差分: 変更後の画面のスクリーンショットを撮り、手順6の「テスト方法」に ![<説明>](./<file>.png) で置く。手順8で同じパスを --attach に渡す（挙動と失敗時の扱いは context/github-cli-notes.md「画像・動画の添付」）
• 確かめられなかった範囲（ローカルで起動できない外部連携など）は、何を確かめられなかったかと理由を「テスト方法」に1行書く

5. 分量予算を決める

本文を書く前に上限を決める。放っておくと設計判断・トレードオフ・将来案・テスト実行数まで盛り込み、そのチームの実運用の2〜3倍に膨らむ。

予算は repo ごとに一度実測してキャッシュする。毎回の PR 作成で測り直さない。

5-1. キャッシュを読む

cat ${MEMORY_DIR}/context/pr-conventions.md 2>/dev/null   # MEMORY_DIR未定義時: .local/context/
grep -n "pr-conventions\|PR 分量" CLAUDE.local.md 2>/dev/null

あればそこに書かれた上限・セクション別目安・定型フレーズをそのまま使い、5-2を飛ばす。ただし実測日が半年以上前か、テンプレート自体が変わっている場合は再実測して上書きする。

5-2. キャッシュがなければ実測して書き出す

# 変更ファイル数と本文長の分布を見る（bot・release PRは除いて読む）
gh pr list --state merged --limit 40 --json changedFiles,body,author \
  -q '.[] | select(.body != null) | "\(.changedFiles)\t\(.body | length)\t\(.author.login)"' | sort -n

そのうえで今回と同規模（変更ファイル数が近い）の PR 2〜3件を実際に読み、粒度と長さをそれに揃える。author 別に差がある場合は、レビュアー層に受け入れられている多数派に合わせる。

測った結果は ${MEMORY_DIR}/context/pr-conventions.md に次の形で残す（.local/ は global gitignore 済みでコミット不要。CLAUDE.local.md に直書きでもよい）:

# PR 分量規約（実測キャッシュ）

実測日: YYYY-MM-DD / 対象: <owner>/<repo> merged PR n件（bot・release除く）

## 本文長の上限（チェックリスト部を除く、実測の中央値）
| 変更ファイル数 | n | 中央値 | 上限として使う値 |
## セクション別の中央値
## テンプレの必須セクション・チェックリストの扱い
## そのrepoの定型フレーズ・PRの型

完了基準: キャッシュファイルが存在し、今回使う上限値がそこから引けている。

5-3. どちらもできないときの初期値

PR が少ない・新規 repo 等でキャッシュも実測もできない場合:

変更ファイル数	本文（チェックリストを除く）の上限
1-3 files	1,500字
4-9 files	2,000字
10-30 files	2,500字
31+ files	3,500字

セクション別の目安（キャッシュに記録がなければこれを使う）:

セクション	目安	書き方
概要	1〜2文	「〜する」で言い切る。背景は書かない（動機へ）
動機	1〜2段落	現状の問題 → 放置した場合の影響。自明なら1文
やったこと	3〜5項目	1変更=1行。path + 何をしたか
やらなかったこと	1〜2行	原則「特になし」。スコープ外があるときだけ理由を1行添える
影響範囲	1〜3行	画面・エンドポイント・経路の列挙。無影響なら「挙動に変化なし」
テスト方法 / 使い方	1〜3行 + スクリーンショット	手順4で実際に通した操作と結果。画面が変わるならスクリーンショット
関連リンク	リンクのみ	チケット・スレッド・公式docs。無ければ「なし」
チェックリスト	補足なし	[x] を付けるだけ

6. PR 本文の作成

テンプレートがあれば使用、なければ以下:

## 概要
[1〜2文]

## やったこと
- 変更1
- 変更2

## やらなかったこと
- スコープ外の内容（なければ「特になし」）

## 影響範囲
- 影響を受ける画面・処理

## テスト方法
[手順4で通した操作と結果]
![<説明>](./<file>.png)

## チェックリスト
- [ ] 型チェック通過
- [ ] Lint通過
- [ ] テスト通過

文体は /ukwhatn-writing スキルを実行して、その GitHub 向けガイド（PR 概要欄）に従う。箇条書きは体言止め・常体、地の文は敬体。パス・関数・設定値・コマンドは ` で囲む。事実は断定、推測・提案だけぼかす。

チェックリストは、依存追加・スキーマ変更・環境変数・migration の有無を diff で確かめてから [x] を付ける（確かめずに付けると、レビュアーがその項目を見なくなる）。補足を書くのは2ケースだけ:

• [ ] のまま残すとき（理由と後追いの合意を1行）
• 該当ありでレビュアーが判断に迷うとき（1行）

1つの箇条書きに複数の論点を詰め込まない。What+Why+詳細が1文に連なって長くなる場合は文を分割し、設定値・理由・根拠はネストした箇条書きに移す。項目が多く雑多になったら ### 小見出しでグループ化する。

7. 削る（AI の書きすぎを落とす）

書き終えたら、以下を上から順に検索して消す。いずれもレビュアーの判断材料にならず、本文を長くするだけ。

消すもの	代わりに
実装の設計判断・採用理由の解説段落	判断を仰ぐものだけ「レビュー時チェック」相当に1行
トレードオフ・将来の代替実装案（「必要になれば〜に切替可能」）	書かない。指摘されたら返信で書く
テスト実行結果の数値羅列（「N suites / M tests green」）	「関連テストgreenを確認」1行、または実行コマンド1行
やったこと各項目にぶら下げた2〜4行の解説	1項目1行。非自明な1点だけネスト1行
チェックリスト各項目への長い根拠説明	[x] のみ（例外は手順6の2ケース）
「〜することが可能です」「〜に関しまして」等の硬い言い回し	「〜できます」「〜について」
概要内の背景説明・まとめの再説明	概要は1〜2文。背景は動機に1回だけ
セクション末尾の要約・結び	書かない

完了基準: 上表8項目の該当がゼロで、手順5の上限内に収まっている。

8. PR 作成

本文はファイルに書き出して --body-file で渡す（heredoc だとバッククォートのエスケープが本文に混入することがある）。

gh pr create --draft \
  --base <base-branch> \
  --title "<タイトル>" \
  --assignee @me \
  --body-file <scratchpad>/pr-body.md \
  --attach ./<file>.png   # 手順4でスクリーンショットを撮ったときだけ。複数なら繰り返す

• --assignee @me を付ける（未アサインの PR はレビュー担当・追跡の割り当てから漏れるため）
• --no-draft 引数が指定された場合のみ --draft を外す
• reviewer が CODEOWNERS 等で自動付与される repo では --reviewer を指定しない
• 別ディレクトリ・worktree から実行するときは --repo <owner>/<repo> を付ける
• --attach が非0で終わったら、失敗したファイルを gh pr edit <n> --attach で再送する

9. CI と conflict の確認

CI の結果と conflict の有無を自分で確かめてから報告する。走行中なら完了まで監視し、失敗・conflict があれば指摘を待たずに原因調査に入る。

gh pr view <n> --json mergeable,mergeStateStatus,statusCheckRollup

完了基準: CI が結論（success / failure）に達しており、mergeable を確認済み。走行中のまま報告していない。

10. レビュー待ち・マージ待ちの監視

PR を出したら、Monitor で PR の状態を見張る。Draft でも仕込む（ready にされた後のレビューと CI の再実行を拾うため）。

監視するのは CI の結論・レビューの到着・変更要求・マージ（またはクローズ）。状態が変わるたびに1行出し、gh が失敗したときも行を出す（沈黙は成功ではなく、監視が死んでいるのと区別できない）。

prev=""
while true; do
  cur=$(gh pr view <n> --repo <owner>/<repo> \
    --json state,reviewDecision,mergeStateStatus,statusCheckRollup,reviews \
    --jq '[.state, (.reviewDecision // "" | if . == "" then "NO_DECISION" else . end), .mergeStateStatus,
           "reviews=\(.reviews | length)",
           "checks=" + ([.statusCheckRollup[] | if (.conclusion // "") != "" then .conclusion elif .status then .status else .state end]
                        | group_by(.) | map("\(.[0]):\(length)") | join(","))] | join(" ")' 2>&1) \
    || cur="ERROR $(echo "$cur" | head -1)"
  [ "$cur" != "$prev" ] && echo "$cur"
  prev=$cur
  case "$cur" in MERGED*|CLOSED*) break ;; esac
  sleep 60
done

Monitor には timeout_ms を上限（1800000）で渡す。期限で切れた通知が来たら、PR が開いている限り同じコマンドで張り直す。

各イベントでやること:

イベント	やること
checks に FAILURE・ERROR・TIMED_OUT が出た	ログを読んで原因を直し、同じブランチへ push する（出した PR の承認に含まれる）。push 後は手順9をやり直す
reviews= が増えた・CHANGES_REQUESTED になった	付いたコメントを読み、/pr-comment スキルで対応と返信案を作る。返信の投稿はユーザーの承認を得てから
mergeStateStatus が DIRTY になった	base を取り込んで conflict を解消し、push する
MERGED	worktree を削除し、ブランチを git branch -d で消し、taskboard の作業項目を done にする（列は daemon が進める）。片付けたものを報告に並べる
CLOSED（マージなし）	片付けずにユーザーへ報告する
ERROR 行	認証切れ・ネットワークなど原因を確かめ、直してから張り直す

worktree・ブランチを消す前に context/worktree-guide.md を Read する。

11. 結果の報告

次を各1行で報告する:

• PR の URL、base、Draft か
• 本文の文字数（予算に対して）
• CI と conflict の状態
• 手順4で確かめた操作と、確かめられなかった範囲
• 監視を仕込んだことと、起きる条件

---

PR を分ける条件

条件は AGENTS.md「コミット・ブランチ・PR」が真実源（常駐する側に置くのは、分けるかの判断が本スキルの発動より前に起きるため）。

PR の型

• 同期 PR（同一変更を複数ブランチへ入れる）: タイトル先頭に宛先を置き（[to main] / [to develop] 等）、本文はメイン PR へのリンク1行で足りる。差分（conflict 解消・追加変更）が入ったときだけ、その差分を書く。メイン PR 側の末尾に「同時マージ依頼」を太字で置く
• スタック PR（他 PR をベースにする）: 概要直後に blockquote でベース PR と、分けた理由（上の条件のどれか）を1行
• 複数 repo にまたがる変更: 概要直後に相手側 PR を相互リンクし、マージ順・デプロイ順の前後関係があれば1行添える
• テンプレートのない repo: 概要 / やったこと / 影響範囲 / テスト方法 の見出し程度に留める
• 運用作業を伴う PR（マージ後に手動適用が必要等）: 冒頭に GitHub alert で明示する

  > [!IMPORTANT]
  > マージ後に <適用作業> を実施します
  

PJ 固有の運用ルール

hotfix 等で複数のベースブランチへ PR を作る運用（sync PR 等）や、リリース PR の作成手順が PJ 固有で定義されている場合は、PJ 側のスキル・ドキュメントの指示を優先する。テンプレートの必須セクション・チェックリストの解釈も PJ 側の規定が優先する。マージを人が行う PJ では、手順10の MERGED は人のマージを待って起きる。