github-commit-pr

github-commit-pr

目的

変更をコミットし、GitHub のプルリクエストを作成または更新して、CI を監視し、GitHub Actions が成功したら PR をマージするエンドツーエンドのワークフローです。自動クローズキーワードによる issue の関連付け、Conventional Commits 形式のコミットメッセージ、既存の PR への新しいコミットのプッシュ、CI 後のブランチ削除を伴う自動マージに対応しています。

使用する場面

• 変更をコミットして新しい PR を作成し、CI が成功したらマージする場合
• 既存の PR ブランチに追加のコミットをプッシュし、CI の成功後にマージする場合
• GitHub issue を参照して自動クローズする PR を作成する場合
• 実装済みの複数の issue をマージする場合 — ツリー全体で一度ではなく、issue ごとにこのワークフローを実行します
• PR のマージ前に人間によるレビューを受けたい場合は、--no-merge を渡してマージの手順を省略します

1 issue、1 コミット、1 PR

プルリクエストは、レビュー担当者が読み、メンテナーが議論し、リバートによって取り消す単位です。1 つの issue に正確に対応していれば、この 3 つがすべてシンプルになります。3 つの issue をクローズする PR は、個別にレビューすることも、個別にリバートすることもできず、そのうち 1 つだけに関心のあるレビュー担当者にも、3 つすべてを読ませることになります。そのため、このワークフローでは作業ツリーに複数の issue の完了済み作業がすでに含まれている場合でも、issue ごとに 1 つのコミットと 1 つの PR を作成します。

問題が起きるのはステージングの段階です。git add -A はツリー内のすべてのものを取り込み、別の issue の作業まで含めてしまいます。2 つの issue が 1 つのコミットを共有すると、手作業でしか分けられなくなります。ステージングの前に、このコミットが何のためのものかを確認します。

• $ARGUMENTS の --issue <number>、またはユーザーが直前に指定した issue があれば、それで確定します。その issue がこのコミットと PR の対象です。
• それ以外の場合は git status --porcelain を確認し、変更ファイルが 1 つのまとまりを示しているかを見ます。無関係なモジュールのファイル、別の機能のテスト、または残された実験のファイルがあれば、ツリーに複数の作業が含まれている兆候です。

複数の作業が含まれている場合は、推測したりまとめたりせず、確認できたグループ分けを示してユーザーに確認してもらいます。

The working tree looks like two separate jobs:
  #12 — dark mode toggle: src/theme/*, src/components/Toggle.tsx
  #13 — token refresh fix: src/auth/refresh.ts, tests/auth.test.ts

I'll commit #12 first and open its PR; #13 stays in the tree for the next run.
Which one should go first?

その後、その issue のパスだけをステージングし（新しい PR のフローの手順 5）、マージしてから、次の issue に対してワークフローを再実行します。小さな PR を 2 つ作るほうが、混在した PR を 1 つ作るよりレビュー担当者の負担が少ないため、この追加のやり取りは無駄ではなく、意図したものです。

例外は 2 つあり、どちらも明示的な場合に限ります。ユーザーが、変更は本当に 1 つの作業単位である（複数の issue が求めていたリファクタリングなど）と言った場合、またはコストを伝えたうえで、ユーザーが複数をまとめた PR を承知のうえで受け入れた場合です。判断はユーザーに委ねます。そのまま進め、関連付けが漏れないよう PR の本文にすべての issue を記載します。

詳細リファレンス

各リファレンスは、必要な手順で読み込みます。事前にすべて読まないでください。

• references/sensitive-files.md — ステージング前のシークレットスキャン。常にシークレットとして扱うファイル名、一般的なファイルに貼り付けられたキーの内容スキャン、検出時の対処方法
• references/commit-conventions.md — Conventional Commits 形式とブランチ名の導出
• references/pr-body.md — PR テンプレートの検出、本文のデフォルト構成、issue の関連付けとクローズキーワード
• references/ci-and-merge.md — CI 監視スニペット、課金エラーの検出とローカル検証、マージ可能性の解釈、マージ戦略の選択と確認

サブエージェントへの委任

このワークフローの大部分は、迅速で状態を変更する git／gh コマンドであり、メインエージェントが実行する必要があります。メインエージェントは全体像を把握しており、リポジトリの状態を変更すべき唯一のエージェントです。ただし、読み取りが中心のステップが2つあり、結論だけが必要な資料によってオーケストレーターのコンテキストが膨らむことがあります。これらは読み取り専用のサブエージェントに任せ、メインエージェントがコミット → PR → マージの流れを進めることに集中できるようにします。役割分担はシンプルです。サブエージェントが読み取って報告し、メインエージェントが判断して実行します。

デフォルト：Task ツールで Claude のサブエージェントを起動します。 どのマシンでも、スキルがインストールされていれば使えるため、移植性に優れています。委任用 CLI エージェントが設定されているマシン（ユーザーのグローバル CLAUDE.md を参照）では、代わりに読み取りをそれらに渡してもかまいません。差分やログの分析には agy -p "…"、扱いが難しいコミットについて別の意見を聞くには git diff HEAD | codex exec "…" を使えます。ただし、これらは常に利用できるとは限らないため、依存しないでください。

次の場合は委任してください：

• 差分が大きい場合（大まかな目安は、多数のファイルがある場合、または変更行数が数百行を超える場合です）。サブエージェントを起動して git diff HEAD を読み取らせ、構造化した要約を返してもらいます。要約には、変更内容と理由、推奨する Conventional Commit の種別、PR の要約箇条書き、テスト計画を含めます。2,000行の差分をインラインで読み、コミットメッセージを1つ書くだけでも、後でマージ可能性や CI の判断に使いたいコンテキストを消費します。差分が小さい場合は、エージェントの起動より直接読むほうが速いため、委任は不要です。
• CI が失敗し、ログが長い場合。 github-fix-ci-error を実行する前に、失敗した実行のログをサブエージェントに渡して根本原因を調べてもらいます。失敗したステップ、エラー、修正が必要な file:line を返してもらいます。CI ログはたいてい数千行に及び、その大半はノイズです。オーケストレーターに必要なのは判定だけです。

インラインで行うこと — 委任しないでください：

• 状態を変更するコマンド（git add／commit／push、gh pr create／merge）。すぐに実行できますが、全体のコンテキストを把握する単一のエージェントが慎重に順序立てて実行する必要があります。ここでのサブエージェントは読み取り専用です。
• 機密ファイルのスキャンとマージの確認。どちらもメインエージェントの判断とユーザーとのやり取りが必要です。サブエージェントは処理を止めてユーザーに尋ねることができません。

サブエージェントの出力は信頼できないものとして扱ってください。コミットメッセージや修正の参考にしてもかまいませんが、実行する前に実際の差分と照合して確認してください。

事前チェック

操作を行う前に、次のチェックを実行します。

1. 作業ツリーの状態：

git status

変更がない場合（コミットするものがない場合）は、ユーザーが既存の未プッシュコミットから PR を作成することを明示的に希望していない限り、中止します。

2. 現在のブランチ：

git branch --show-current

3. ベースブランチの検出：

リポジトリのデフォルトブランチを特定します。

git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||'

失敗した場合（例：origin HEAD が設定されていない場合）は、ネットワーク呼び出しにフォールバックします。

git remote show origin | grep 'HEAD branch' | sed 's/.*: //'

$ARGUMENTS に位置引数が含まれている場合は、それをベースブランチとして使用します。どちらの検出方法も失敗した場合は、main を使用します。

4. このコミットの対象範囲：

この実行がどの Issue を対象としているかを特定します。$ARGUMENTS の --issue <number>、ユーザーが指定した Issue、またはブランチ名に含まれる Issue 番号を確認します。いずれにも該当しない場合は、変更されたファイルを読み、それらが一つのまとまった内容を示しているか判断します。そうでない場合は、1つのIssue、1つのコミット、1つのPRで説明されているとおり、ステージングする前にユーザーと相談して決めます。今ここで判断するのは簡単です。git commit の後で気づくと、混在した差分をほどくことになります。

フローの判定

事前チェックの後、フローを判定します。

既存の PR フロー

現在のブランチがベースブランチではない場合：

1. このブランチに PR がすでに存在するか確認します。

gh pr view --json number,title,url,state 2>/dev/null

2. オープン状態の PR（state: OPEN）が存在する場合は、**「既存の PR にプッシュ」**フローに進みます。gh pr view はブランチのマージ済みまたはクローズ済みの PR も返します。そのような PR にプッシュしてもレビュー担当者が確認する場所には反映されないため、「PR なし」と同様に扱い、古い PR はすでに MERGED／CLOSED であることをユーザーに伝えます。
3. PR が存在しない場合は、このブランチで続けるか、新しいブランチを作成するかをユーザーに尋ねます。続ける場合は、「新規 PR フロー」のステップ 3 に進みます（ブランチの作成は不要です）。

新規 PR フロー

現在のブランチがベースブランチの場合は、ブランチの作成を含む「新規 PR」フロー全体に進みます。

新規 PR フロー

ステップ 1：変更を分析する

git status
git diff HEAD
git log --oneline -5

差分が大きい場合は、すべてをインラインで取り込まず、サブエージェントへの委任を参照してください。読み取り専用のサブエージェントを起動して git diff HEAD を要約させ、コミットの種類、PR の概要を示す箇条書き、テスト計画を返してもらいます。その要約をステップ 3 とステップ 7 で再利用します。

ステップ 2：機密ファイルを確認する

ステージングする前に、変更されたファイルの名前と追加された内容の両方に秘密情報が含まれていないか確認します。通常のソースファイルにハードコードされたキーは、git status には決して表示されません。パターン、スキャンコマンド、検出時の対応については、references/sensitive-files.mdを参照してください。test_token.sh のような名前はヒントにすぎません。警告する前に内容を確認してください。実際に秘密情報が検出された場合は、ユーザーに警告し、ステージングの前に確認を求めます。秘密情報を黙ってステージングしてはいけません。「確認不要」の事前承認が対象とするのはコミットメッセージとマージであり、認証情報の公開ではありません。

ステップ 3：コミットメッセージを提案する

差分から規約に沿ったコミットメッセージを作成し、ユーザーに提示して承認または編集してもらいます。形式とルールについては、references/commit-conventions.mdを参照してください。

ステップ 4：ブランチを作成する

コミットメッセージからブランチ名を決めて作成します。references/commit-conventions.mdを参照してください。

ステップ 5：ステージングしてコミットする

ツリー全体がこの 1 件の課題に関するものである場合は、すべてをステージングします。

git add -A

ツリーが複数の課題にまたがる場合（事前確認 4）は、この課題が対象とするパスのみをステージングし、残りはそれぞれのコミット用に作業ツリーに残します。

git add -- <path> <path> ...
git status --short   # confirm the staged set is exactly this issue's work

コミットする前に git status --short の出力を確認してください。ステージング済みのもののうち、この課題に関係すると判断できないものは次の PR に含めるため、コミットに含めずに git restore --staged <path> でステージングを解除します。

git commit -m "$(cat <<'EOF'
<type>: <summary>

<optional body>
EOF
)"

pre-commit フックによってコミットに失敗した場合は、フックの出力を確認し、問題を修正して再ステージングしたうえで、新しいコミットを作成します（amend はしないでください）。同じ対象パスを再ステージングしてください。この時点で反射的に git add -A を実行すると、別の課題の作業が紛れ込みます。

ステップ 6：プッシュする

git push -u origin <branch-name>

リモート側で拒否されてプッシュに失敗した場合は、エラーを報告して中止します。強制プッシュはしないでください。

ステップ 7：PR の本文を作成する

リポジトリに PR テンプレートがあるか確認して記入します。テンプレートがない場合は、デフォルトの Summary／Test plan の構成を使用して差分の内容を反映し、関連する課題がある場合は課題をクローズするキーワードを追加します。詳しくはreferences/pr-body.mdを参照してください。

ステップ 8：PR を作成する

gh pr create --title "<summary>" --base "<base-branch>" --body "$(cat <<'EOF'
<PR body from Step 7>
EOF
)"

タイトルとベースブランチのルールについては、references/pr-body.mdを参照してください。スカッシュマージするとタイトルがベースブランチ上のコミットの件名になるため、タイトルには規約に沿った type(scope): のプレフィックスを残します。

Step 9: CI を監視する

プッシュによってトリガーされたすべての GitHub Actions の実行が完了するまで待ちます。実行はブランチではなくコミットで選択してください。スニペットと失敗時の対処については、references/ci-and-merge.md を参照してください。

• すべての実行が成功した場合 → Step 10 に進みます。
• 実行が失敗した場合は、まず失敗の種類を判定します。
  • GitHub の課金／利用上限 — 実行されたステップがゼロで、「job was not started … payments / spending limit / billing」という注釈が付いているジョブです。コードは実行されていないため、修正するものはありません。ワークフローのチェックをローカルで実行し（リポジトリ独自の pre-commit 検証も実行します）、すべて成功した場合は、その結果を根拠として PR をマージできます。マージ確認とレポートでは、CI が実行されなかったことと、代わりにローカルで何を検証したかを伝えてください。
  • その他 — 根本原因を特定し（ログが長い場合は作業を委任し）、github-fix-ci-error で修正してプッシュし、再度監視します。すべて成功するか、ユーザーが中止するまで繰り返します。

Step 10: PR をマージする

CI が成功しました。このスキルを実行したユーザーの意図は変更を取り込むことなので、$ARGUMENTS に --no-merge が渡されていない限り、マージに進みます。--no-merge が設定されている場合は、Step 11 に進みます。

references/ci-and-merge.md のマージ手順に従います。マージ可能であることを確認し、リポジトリで許可されている方法を選択し（--squash を優先）、ユーザーに一度確認してから、--delete-branch を付けてマージし、ベースブランチに戻ります。ブランチ保護、競合、または保留中のチェックによってマージできない場合は、そこで停止して報告してください。ユーザーから明示的な指示がない限り、--admin で回避してはいけません。

Step 11: 報告する

PR の URL、最終的な CI の状態（成功／GitHub の課金制限によりスキップ — <commands> をローカルで検証済み）、マージ結果（squash でマージ／--no-merge によりマージをスキップ／...によりマージをブロック）を出力します。

別の課題に対応するため、変更を意図的に作業ツリーに残した場合は、そのことと次に取り組む内容を明記してください。残った差分は次回の実行で対応する作業であり、見落としではありません。

Landed #12 → <pr-url> (squash-merged, branch deleted).
Still in the tree: #13 — src/auth/refresh.ts, tests/auth.test.ts.
Say the word and I'll commit #13 as its own PR.

既存の PR にプッシュするフロー

現在のブランチにすでに PR がある場合：

Step 1: 新しい変更を分析する

git status
git diff HEAD

Step 2: 機密ファイルを確認する

New PR フローの Step 2 と同じ確認を行います。references/sensitive-files.md を参照してください。

Step 3: コミットメッセージを提案する

New PR フローの Step 3 と同じ規則に従います。references/commit-conventions.md を参照してください。

Step 4: ステージング、コミット、プッシュを行う

New PR フローの Step 5 と同じ方法でステージングします。作業ツリーの変更がすべてこの PR の作業ならすべてを、そうでない場合は対象パスを指定します。すでに 1 件の課題に紐付いている PR は、その対象範囲を維持します。無関係な変更をプッシュすると、レビュー済みの PR が後から複数の内容を含むものになってしまいます。

git add -A          # or: git add -- <this PR's paths>
git commit -m "$(cat <<'EOF'
<type>: <summary>
EOF
)"
git push

pre-commit フックが原因でコミットに失敗した場合は、問題を修正して新しいコミットを作成してください（amend はしないでください）。

リモートに新しいコミットがあるためにプッシュに失敗した場合は、まず rebase で pull します。

git pull --rebase origin <branch-name>
git push

rebase で競合が発生した場合は、停止して報告してください。force-push や自動解決はしないでください。

Step 5: CI を監視する

課金制限による失敗への対処も含め、New PR フローの Step 9 と同じです。references/ci-and-merge.md を参照してください。ここでは、実行をコミットで選択することが特に重要です。短時間に 2 回プッシュすると、--branch ... --limit 1 が先の実行を返すことがあります。

Step 6: PR をマージする

references/ci-and-merge.md に記載されている、New PR フローの Step 10 と同じマージ手順に従います。$ARGUMENTS に --no-merge が渡されている場合は、このステップをスキップします。

Step 7: 報告する

既存の PR の URL、新しいコミットの概要、最終的な CI の状態、マージ結果を示します。

Pushed to PR #<number>: <pr-title>
New commit: <type>: <summary>
URL: <pr-url>
CI: <success|fixed after N attempts|not run (GitHub billing) — local: <commands> passed>
Merge: <merged via squash|skipped per --no-merge|blocked by required reviewers|declined by user>

新しい PR は作成しないでください。既存の PR にプッシュするだけにしてください。 PR のタイトルや本文は変更しないでください。

エラー処理

シナリオ	検出方法	対応
gh がインストールされていない	command -v gh が失敗する	https://cli.github.com に案内します
Git リポジトリ内にいない	git rev-parse --show-toplevel が失敗する	明確なメッセージを表示して中止します
コミットする変更がない	git status で作業ツリーがクリーンと表示される	既存のコミットから PR を作成する場合を除き、中止します
作業ツリーの変更が複数の Issue にまたがる	変更ファイルから一貫した内容を読み取れない、または複数の Issue が挙げられている	変更の分類を示し、最初の Issue のみコミットして、残りは作業ツリーに残します
無関係なファイルがステージされている	git status --short にこの Issue の範囲外のパスが表示される	コミット前に git restore --staged <path> を実行します
機密ファイルまたはシークレットが検出された	シークレットを含む可能性が高いファイル名（.env、*.pem、…）、または diff／未追跡ファイルのコンテンツスキャンで該当箇所が見つかる	ファイル名と行番号を示してユーザーに警告し、ステージング前に除外または修正するよう依頼します。確認を依頼できない場合は、該当する内容を含むものを一切送信しません
pre-commit フックが失敗する	git commit がゼロ以外の終了コードを返す	出力を確認して問題を修正し、新しいコミットを作成します
プッシュが拒否される	git push がゼロ以外の終了コードを返す	エラーを報告し、強制プッシュはしません
ブランチがすでに存在する	git checkout -b が失敗する	数字の接尾辞を追加します（例：-2）
PR の作成に失敗する	gh pr create がゼロ以外の終了コードを返す	エラーを報告します（ブランチ保護、権限など）
リモートが先行している（プッシュに失敗する）	git push が non-fast-forward で拒否される	git pull --rebase を実行してから、再度プッシュします
リベースで競合が発生する	git pull --rebase で競合が発生する	停止して報告し、自動で解決しません
ブランチ保護によりマージがブロックされる	mergeStateStatus: BLOCKED、または gh pr merge が 405／"not mergeable" で失敗する	ブロックしている条件（必須のレビュー担当者、コードオーナー、署名付きコミットなど）を報告して停止します。依頼されない限り、--admin で回避しません
ブランチがベースより遅れている	mergeStateStatus: BEHIND	gh pr update-branch <number> の実行を提案し、CI を再確認してから、マージを再試行します
ベースとのマージ競合が発生している	mergeable: CONFLICTING	停止し、ユーザーに手動で解決するよう依頼します
PR で変更が要求されている	reviewDecision: CHANGES_REQUESTED	停止し、ユーザーがレビューに対応するまでマージしません
GitHub の課金により CI がブロックされている	失敗したジョブの実行ステップ数が 0 で、アノテーションに支払い／支出上限／課金について記載されている	ワークフローのチェックをローカルで実行します。すべて合格した場合は、CI が実行されなかったことを明示して確認後にマージします。いずれかが失敗した場合は修正し、マージしません
必須チェックによりマージがブロックされている	mergeStateStatus: BLOCKED で、必須チェックが保留中または失敗している	チェックの完了を待つか、問題を修正します。課金の失敗後はブロックされていることを報告し、--admin を使うかどうかはユーザーに判断を委ねます
必須でないチェックが失敗または保留中	mergeStateStatus: UNSTABLE	チェック名（gh pr checks）を示し、マージ前に確認を求めます
マージ可能かどうかがまだ計算されていない	mergeable: UNKNOWN	数秒待って、再度確認します
ブランチの PR がすでにマージまたはクローズされている	gh pr view が state: MERGED または CLOSED を返す	PR がないものとして扱い、新しい PR を作成します
ユーザーがマージ確認を拒否する	マージ確認のプロンプトにユーザーが「n」と回答する	マージをスキップし、PR の URL と CI の状態を報告して、正常に終了します

制約

次の境界を守ることで、ユーザーのリポジトリとチームのワークフローを保護します。

• ベースブランチ（例：main）に直接コミットしないでください。必ず一連のフローを通じて作業を取り込みます。まずフィーチャーブランチを作成し、その後、コミット → プッシュ → PR を開く → CI が成功するまで確認 → スカッシュマージ → ブランチを削除します。ベースブランチは共有され、通常は保護されています。直接コミットするとレビューと CI を省略することになり、このスキルが徹底するためにある重要なゲートを通過できません。事前チェックで現在のブランチがベースブランチだと検出された場合は、ステージングする前にフィーチャーブランチを作成してください（新規 PR フローのステップ 4）。
• 強制プッシュをしないでください。共有履歴を書き換え、共同作業者のデータ損失につながる可能性があります。
• 既存のコミットを修正しないでください。コミットの履歴を透明でレビュー可能な状態に保つため、代わりに新しいコミットを作成してください。
• pre-commit フック（--no-verify）をスキップしないでください。フックは、正当な理由があって設けられたプロジェクトレベルの品質ゲートを適用します。
• .env、認証情報、シークレットをコミットしないでください。ステージングする前に必ず機密ファイルのチェックを実行し、検出されたものがあれば警告してください。
• いずれかの手順が失敗した場合は、停止してエラーを報告してください。後続の手順は先行する手順の成功を前提としているため、状況を確認せずに続行しないでください。
• 1 つのコミットと 1 つの PR につき、課題は 1 つにしてください。レビュアーが読むのも、revert で取り消すのも PR であるため、ちょうど 1 つの課題に対応させる必要があります。ユーザーがコストを聞いたうえで明示的に求めた場合に限り、複数の課題をまとめてください。その場合は、PR 本文にすべての課題を記載してください。
• ステージングには git add -A を使用してください（全変更のコミットフロー）。ただし、機密ファイルのチェックに合格した後で、作業ツリー全体がこの課題に関係する場合に限ります。それ以外の場合は、課題に関係するパスを明示してステージングしてください。
• 「ついでに」他の課題の変更をコミットせず、作業ツリーに残してください。それらは次に、それぞれの PR で取り込むことで、レビュアーが変更と依頼元の課題を関連付けられるようにします。
• PR 本文には定型文ではなく、差分に基づく実際の変更内容を記載してください。レビュアーは変更内容を理解するために PR 本文を参照します。
• 課題をクローズするキーワード（Closes #N）はコミットメッセージではなく、PR 本文に記載してください。GitHub がクローズ用キーワードを処理するのは、デフォルトブランチに対する PR 本文だけです。
• 既存の PR にプッシュする場合、PR のタイトルや本文は変更せず、新しいコミットだけをプッシュしてください。
• GitHub Actions の実行結果が実際に成功するまで、PR をマージしないでください。gh run watch --exit-status で確認することがゲートです。実行中や保留中のステータスを信頼してはいけません。確認する実行は、ブランチの最新の実行ではなく、直前にプッシュしたコミットのものでなければなりません（gh run list --commit "$(git rev-parse HEAD)"）。
• 例外は、課金上の理由で GitHub がジョブの開始を拒否したことだけが CI の失敗原因の場合です（実行ステップが 0、課金に関する注釈あり）。この場合、ワークフローのチェックがローカルで合格すれば、PR をマージしてもかまいません。ローカルでの検証は CI の代わりになりますが、検証を省略することはできません。クォータが原因だというユーザーの推測は判断材料になりません。実行されたジョブが失敗した場合は、実際の失敗です。
• マージする前に、必ず一度ユーザーの確認を得てください。マージは共同作業者からも見える共有状態であり、revert は煩雑です。確認はユーザーが処理を一時停止できる最後の機会です。
• ユーザーが明示的に求めない限り、ブランチ保護を回避するために gh pr merge --admin を使用しないでください。保護ルールはレビューと品質ゲートを徹底するためにあり、黙って回避するとチームのプロセスが損なわれます。
• $ARGUMENTS の --no-merge を尊重してください。指定されている場合は、プッシュして結果を報告しますが、gh pr merge は決して呼び出さず、ユーザーが PR を人間のレビュアーに引き継げるようにしてください。