otomatty/handle-pr-review

PR レビュー対応（仕様駆動）

PR のレビューコメントを取得し、プロジェクトの仕様（TSDoc/JSDoc・テスト・型定義）に照らして妥当性を検証したうえで、対応方針を提案・実行する。

基本方針

• レビューコメントをそのまま受け入れない。仕様と文脈に基づいて判断する。
• 指摘の問題意識が正しくても、提案された解決策が最適とは限らない。代替案を検討する。
• 対応不要と判断した場合は、仕様根拠を添えて丁寧に説明する。

Step 0: PR の特定

ユーザーが PR URL や番号を指定していない場合、ブランチから自動検出する:

gh pr list --head "$(git branch --show-current)" --json number,url,title --jq '.[0]'

セッション中に既に PR を扱っている場合は、その情報を再利用する。

Step 1: PR コンテキストの把握

レビューコメントを読む前に、PR の変更意図と仕様を理解する:

1. gh pr view <番号> で PR の概要・本文を取得
2. gh pr diff <番号> で差分を取得
3. 変更対象ファイルの TSDoc/JSDoc コメントを読み、仕様上の意図を把握する
4. 関連するテストコードを読み、振る舞いの契約を確認する
5. AGENTS.md / SPECIFICATION_POLICY.md の方針を参照する

この段階で「この PR は何を達成しようとしているか」を明確にする。

Step 2: 未返信コメントの取得

返信済みコメントを除外し、未返信のトップレベルコメントを取得する:

gh api repos/{owner}/{repo}/pulls/{number}/comments \
  --jq '
    [.[] | select(.in_reply_to_id != null) | .in_reply_to_id] as $replied |
    [.[] | select(.in_reply_to_id == null and (.id | IN($replied[]) | not))]
    | .[] | {id, path, line, body: (.body | .[0:300]), user: .user.login, created_at}'

フィルタリングの仕組み

1. 全コメントから「返信コメント」の in_reply_to_id を収集 → $replied
2. トップレベルコメント（in_reply_to_id == null）のうち、$replied に含まれないもの = 未返信
3. 「未返信」≠「未解決」。返信済みだがスレッドが未解決の場合はこの方式では検出されない
4. body は先頭 300 文字に切り詰め、全文が必要なら個別に読む
5. bot の自動コメント（coderabbitai の summary 等）は分析対象外
6. コメントが 30 件超の場合は ?per_page=100 や --paginate でページネーションを指定する

Step 3: 仕様に基づくコメント分析

各コメントについて以下を行う。

3.1 指摘箇所の文脈確認

• コメントが指摘するコードの該当箇所を読む
• その関数・モジュールの TSDoc/JSDoc を確認し、設計意図を把握する
• 関連するテストがある場合、テストが表現する振る舞いの契約を確認する
• PR の変更意図（Step 1 で把握済み）と照合する

3.2 指摘の妥当性を検証

各コメントを以下の 3 択 で判断する:

A. 修正する — 以下のいずれかに該当する場合:

• バグ・論理エラーの正しい指摘
• セキュリティ上のリスク
• 型安全性・エラーハンドリングの明確な不備
• パフォーマンス上の実害
• プロジェクト規約（AGENTS.md）への明確な違反

B. 代替案で対応する — 以下のいずれかに該当する場合:

• 指摘の問題意識は正しいが、提案された解決策が仕様や設計意図と合わない
• 提案を取り入れると別の問題（型安全性の低下、テスト破壊等）が生じる
• 同じ問題をより適切に解決する方法がある

C. 対応不要 — 以下のいずれかに該当する場合:

• 指摘が技術的に誤っている、または誤解に基づいている
• 現在の実装が仕様上正しい（TSDoc/テストで裏付け可能）
• 好みやスタイルの違いでありプロジェクト規約に反していない
• PR のスコープ外の改善提案
• 既に別の方法で対処されている
• ESLint 等のツール制約で採用不可

3.3 分析結果の報告

コメントごとに以下の形式で報告する:

### コメント #N: [コメントの要約]
**投稿者:** @username
**対象:** `ファイルパス` L行番号
**指摘内容:** コメントの要点
**判断:** 修正する / 代替案で対応 / 対応不要
**仕様根拠:** 判断の裏付け（TSDoc、テスト、型定義、AGENTS.md 等を引用）
**対応案:** 具体的な修正内容 / 代替案の詳細 / 不要の理由

最後にサマリーテーブルを提示する:

| # | ファイル | 指摘 | 判断 | 仕様根拠（一言） | 対応案 | | --- | -------- | ---- | ----- | ---------------- | ------ | | 1 | ... | ... | A/B/C | ... | ... |

ユーザーの承認を得てから Step 4 に進む。

Step 4: 修正の実装

承認された対応方針に基づき修正を行う:

1. 対象ファイルを読み、指摘箇所を確認
2. 修正を実装（代替案の場合はその方法で）
3. 既存のテストが通ることを確認する
4. bun run lint でエラーがないか確認
5. 全修正をまとめて 1 コミット:

   fix: address PR #{number} review comments
   

Step 5: 返信の投稿

各コメントに対する返信を作成し、投稿前にテーブルで一覧表示する:

| # | コメント要約 | 対応 | 返信内容 | | --- | ------------ | ----- | -------- | | 1 | ... | A/B/C | ... |

返信の書き方:

• 修正する場合: 何を修正したか簡潔に伝える
• 代替案の場合: 指摘の問題意識に同意しつつ、別の方法を選んだ理由を仕様根拠とともに説明する
• 対応不要の場合: 丁寧に理由を説明し、仕様やテストの根拠を示す

ユーザーが承認するまで投稿しない。

承認後、replies エンドポイントで投稿:

gh api -X POST repos/{owner}/{repo}/pulls/{number}/comments/{comment_id}/replies \
  -f body="返信内容"

Step 6: 再レビュー依頼

修正コミットを push し、再レビューを依頼する。

対象 PR が develop → main（リリース PR）の場合

develop に直接 push できない場合は、作業ブランチを作成し develop 向け PR を出す:

1. 修正をコミットした状態で作業ブランチを作成:

   git checkout -b fix/pr-{number}-review-comment
   

2. push して develop ベースの PR を作成:

   git push -u origin fix/pr-{number}-review-comment
   gh pr create --base develop --head fix/pr-{number}-review-comment \
     --title "fix: address PR #{number} review comments" --body "..."
   

3. 元のリリース PR にはコメントで報告する。

通常（feature ブランチなど）の場合

git push origin HEAD

gh pr comment {number} --body "レビューコメントへの対応をコミットしました（{SHA}）。最新の変更に対する再レビューをお願いします。

@coderabbitai review
@devin
@claude"

セッション内コンテキスト再利用

• PR 番号・owner/repo は一度特定したら再取得しない
• 未対応コメントの判別は「返信済み除外」方式のため、新規チャットでも正しく動作する
• セッション中に since を併用すれば、さらに API レスポンスを削減できる