Review And Merge

レビュー確認 & マージ

Claude Code Action による自動レビューのコメントを確認し、対応が必要なものは修正案を提示、問題なければマージする。

引数

$ARGUMENTS

対象 PR の決定

1 回の呼び出しで処理する PR は 1 つのみ。

改善の経緯: review-and-merge で複数 PR を同時処理しようとした

手順

Step 1: PR 状態確認 + base branch 同期

PR 状態と base branch 同期を一括で確認する。分離して実行しないこと。

gh pr view --json number,state,isDraft,reviewDecision,statusCheckRollup,url,baseRefName
git fetch origin main && git log HEAD..origin/main --oneline

以下の判定に基づいて対応する:

CI 再実行時の既存レビューコメント先行確認

rebase + push 後は CI + Review が再実行される。前回のレビューサイクルで既にコメントが存在する場合、CI 完了を待たずに先行して確認・対応する:

1. rebase + push 後、Step 3 の API で既存のレビューコメントを取得する
2. コメントがあれば Step 4 の手順で対応する
3. 対応完了後、Step 2 に進んで新しい CI + Review の完了を待つ
4. 新しいレビューで追加コメントがあれば、通常フロー（Step 3 → Step 4）で対応する

コメントがない場合はそのまま Step 2 へ進む。

改善の経緯:

• review-and-merge で rebase 確認が遅い
• review-and-merge で base branch 同期確認をスキップ
• CI 再実行時にレビューコメント確認を後回しにする

Step 2: Claude Auto Review 完了確認

gh pr checks

"Claude Auto Review" のステータスを確認する:

Step 3: レビューコメント取得・分析

以下の 3 つの API で claude[bot] のレビュー情報を取得する。

注意: 各コマンドは gh api で始めること。変数代入を && で繋ぐとパーミッションルール Bash(gh *) にマッチしなくなる。

# 1. 全レビュー（APPROVED / CHANGES_REQUESTED）
gh api "repos/{owner}/{repo}/pulls/{pr_number}/reviews" \
  --jq '[.[] | select(.user.login == "claude[bot]")]'

# 2. Review コメント（コードの特定行への指摘）
gh api "repos/{owner}/{repo}/pulls/{pr_number}/comments" \
  --jq '[.[] | select(.user.login == "claude[bot]")]'

# 3. 全 PR レベルコメント（全体フィードバック・サマリー）
gh api "repos/{owner}/{repo}/issues/{pr_number}/comments" \
  --jq '[.[] | select(.user.login == "claude[bot]")]'

{owner}/{repo} と {pr_number} は実際の値に置き換える。gh pr view --json number --jq '.number' で PR 番号を、gh repo view --json nameWithOwner --jq '.nameWithOwner' でリポジトリ名を取得できる。

メタデータ抽出

取得した各 PR レベルコメント（3 の結果）について、メタデータブロックを抽出する:

# コメント本文からメタデータを抽出（grep の -z オプションで複数行マッチ）
echo "$COMMENT_BODY" | grep -Pzo '(?<=<!-- review-metadata\n)[\s\S]*?(?=\n-->)' || echo ""

メタデータが存在する場合はそれを使用し、存在しない場合は従来通り本文を解釈する。

取得した情報を以下の形式でユーザーに提示する:

## レビュー結果サマリー

レビュー: N 件（APPROVED: X, CHANGES_REQUESTED: Y）
Review コメント: N 件

### 全体フィードバック

#### コメント 1（Auto Review）

**メタデータ:**
- Type: auto-review
- 重大度: Critical=0, High=1, Medium=2, Low=3
- 対応要否: false（APPROVED）

（内容要約）

#### コメント 2（Rules Check）

**メタデータ:**
- Type: rules-check
- 重大度: Critical=0, High=0, Medium=0, Low=0
- 対応要否: false（pass）

（内容要約）

注: メタデータが存在しない場合（古いコメント）は、「メタデータ:」セクションを省略し、従来通り本文を解釈してサマリーを提示する。

### Review コメント一覧
1. `ファイルパス:行番号` — 内容要約
2. ...

レビュー状態に応じた分岐:

Step 4: 対応（半自動）

指摘を含むコメントが存在する場合、各コメントについて以下を行う。対象は Review コメント（inline）と PR コメント（全体フィードバック内の指摘）の両方。

1. コメント内容と該当コードを表示（ファイルを読んで前後のコンテキストを含める）
2. 修正案を提示する
3. ユーザーに対応方針を確認する（修正する / スキップ / 延期 / カスタム修正）
4. 承認された修正を適用する
5. 修正に対応するテストが存在するか確認する。存在しない場合はテストを追加する

対応方針の判断基準:

スキップ判断の事実検証要件

スキップを選択する場合、指摘内容が事実として正しいかをコードで検証済みであること（成果物要件）。

手順:

1. 指摘が言及しているコード箇所を Read/Grep で確認する
2. 指摘の内容が事実として正しいか（問題が存在するか）を判定する
3. 判定結果と根拠を返信に記載する

スキップ理由として有効な根拠:

スキップ理由として無効な根拠:

改善の経緯: レビュー指摘の確信度を問題の重要度と混同した

延期を選択した場合:

1. 指摘内容を元に Issue を作成する（gh issue create）
2. Issue 番号を含む返信をレビューコメントに投稿する（下記テンプレート参照）
3. 延期返信には 必ず Issue 番号を含めること（成果物要件）。Issue 番号のない延期返信は禁止

一括適用はしない。必ずコメントごとにユーザーの判断を仰ぐ。

CHANGES_REQUESTED の場合:

• 全コメントへの対応完了後、just check でローカルチェックを実行
• コミット・プッシュ
• Claude Auto Review が再実行されるため、Step 2 に戻る
• レビューが APPROVED になるまでこのループを繰り返す

APPROVED（コメントあり）の場合:

• 対応するかどうかはユーザーの判断に委ねる
• 対応した場合は同様にコミット・プッシュ → Step 2 に戻る
• 対応しない場合は Step 5 へ

Review コメント（inline）への返信

対応完了後、レビューコメントに返信し、スレッドを resolve する:

# 対応した場合
gh api "repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies" \
  -f body="修正しました。"

# スキップした場合（理由を記載）
gh api "repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies" \
  -f body="（スキップ理由）"

# 延期した場合（Issue 番号必須）
gh api "repos/{owner}/{repo}/pulls/{pr_number}/comments/{comment_id}/replies" \
  -f body="Issue #<番号> で対応予定です。"

返信後、未 resolve のスレッドを resolve する:

# 未 resolve スレッドの ID を取得
gh api graphql -f query='
query {
  repository(owner: "{owner}", name: "{repo}") {
    pullRequest(number: {pr_number}) {
      reviewThreads(first: 100) {
        nodes { id isResolved }
      }
    }
  }
}'

# 各未 resolve スレッドを resolve
gh api graphql -f query='
mutation {
  resolveReviewThread(input: {threadId: "{thread_id}"}) {
    thread { isResolved }
  }
}'

注意: required_review_thread_resolution ブランチ保護ルールにより、未 resolve スレッドがあるとマージがブロックされる。返信だけでは自動 resolve されないため、明示的に resolve が必要。

PR コメント（全体フィードバック）への返信

PR コメント（issues/comments）に指摘事項が含まれる場合も、対応完了後に返信コメントを投稿する。PR コメントはスレッド構造を持たないため、元コメントの URL を含めて関連性を明示する。

# 元コメントの URL を取得（Step 3 で取得済みの html_url を使用）
# 対応した場合
gh api "repos/{owner}/{repo}/issues/{pr_number}/comments" \
  -f body="[コメント]({comment_url}) への対応: 修正しました。"

# スキップした場合（理由を記載）
gh api "repos/{owner}/{repo}/issues/{pr_number}/comments" \
  -f body="[コメント]({comment_url}) への対応: （スキップ理由）"

# 延期した場合（Issue 番号必須）
gh api "repos/{owner}/{repo}/issues/{pr_number}/comments" \
  -f body="[コメント]({comment_url}) への対応: Issue #<番号> で対応予定です。"

注意: PR コメントには resolve の仕組みがない。返信の有無が Step 5 の未対応検証で使用される。

改善の経緯:

• レビュー返信の検討事項に Issue 追跡が欠如
• Issue #451: review-and-merge でレビュースレッドの resolve 漏れ

Step 5: マージ

マージ前に以下を確認する。

未対応レビュー指摘のゼロ検証

Step 3 と同じ API で最新のレビュー状態を再取得し、未対応の指摘がゼロであることを検証する。セッション復元の有無に関わらず常に実行する。

検証項目:

# 1. reviewDecision
gh pr view --json reviewDecision --jq '.reviewDecision'

# 2. 未 resolve の review threads
gh api graphql -f query='
query {
  repository(owner: "{owner}", name: "{repo}") {
    pullRequest(number: {pr_number}) {
      reviewThreads(first: 100) {
        nodes { id isResolved }
      }
    }
  }
}'

# 3. claude[bot] の PR コメントと全コメントを取得し、返信の有無を確認
gh api "repos/{owner}/{repo}/issues/{pr_number}/comments" \
  --jq '[.[] | select(.user.login == "claude[bot]")]'

検証 #3 の判定手順:

1. claude[bot] の PR コメントを取得する
2. 各コメントからメタデータを抽出する:

   echo "$COMMENT_BODY" | grep -Pzo '(?<=<!-- review-metadata\n)[\s\S]*?(?=\n-->)' || echo ""
   

3. メタデータが存在する場合（機械的判定）:
   • 指摘件数（severity-critical, severity-high, severity-medium, severity-low）の合計を計算する
   • 合計がゼロでなければ「指摘を含むコメント」として扱う
4. メタデータが存在しない場合（後方互換性）:
   • 従来通り、コメントの内容を読んで具体的な指摘事項を含むか判定する（サマリーのみのコメントは対象外）
5. 指摘を含むコメントについて、そのコメント URL を参照する返信コメントが存在するか確認する
6. 指摘を含む未返信のコメントがあれば、ユーザーに提示してマージを止める

判定ロジックの疑似コード:

for comment in claude_bot_comments:
    metadata = extract_metadata(comment.body)
    if metadata:
        # メタデータがある場合（機械的判定）
        total_issues = (
            metadata["severity-critical"] +
            metadata["severity-high"] +
            metadata["severity-medium"] +
            metadata["severity-low"]
        )
        has_issues = total_issues > 0
    else:
        # メタデータがない場合（従来の解釈）
        has_issues = contains_specific_feedback(comment.body)

    if has_issues:
        # 返信の有無を確認
        if not has_reply(comment):
            # 未返信の指摘があるのでマージを止める
            abort_merge(comment)

改善の経緯: セッション復元時のレビューコメント検証省略

全チェックの pass 確認

gh pr checks

改善の経緯:

• force-push後の自動レビュー待機漏れ
• CI失敗を無視してマージを強行しようとした

マージ実行

gh pr merge --squash
just clean-branches
just sync-epic <Issue番号>

just sync-epic は Story Issue の親 Epic タスクリストを自動更新する。Epic に属さない Issue の場合は何もしない。

マージ完了後、PR の URL を表示して終了する。

禁止フラグ: --auto、--admin は使用しない。

• --auto: 全チェック通過時に即座にマージするため、その後にプッシュしたコミットがマージに含まれない
• --admin: branch protection をバイパスするため、品質ゲートが無効になる

gh pr merge 失敗時の対応

gh pr merge --squash が失敗した場合、--auto にフォールバックせず以下の手順で対応する:

1. エラーメッセージから原因を特定する
2. 原因を解消する（下表参照）
3. 解消後、gh pr merge --squash を再試行する

改善の経緯: auto-merge による後続コミット漏れ

Converted and distributed by TomeVault — claim your Tome and manage your conversions.