addressing-code-review-comments

コードレビューコメントへの対応

プルリクエストのレビューコメントに対応する際は、ユーザーと協力して進めます。レビュー担当者からのフィードバックを受け取り、分析、修正案、返信の下書きをユーザーに提示します。実装する内容と投稿する内容は、ユーザーが決定します。

基本原則： 実装する前に検証します。推測する前に曖昧さを明らかにします。社交上の配慮より技術的な正確さを優先します。

ワークフロー

レビューごとに、次の手順に従います。

1. すべてのコメントに目を通してから、個別のコメントに対応します。
2. 各コメントの技術的な要件を、自分の言葉で言い換えます。
3. 実際のコードベースを確認して、指摘を検証します。
4. レビュー担当者が把握していない可能性のある背景も考慮し、このコードベースにおいて提案が妥当かどうかを評価します。
5. 修正、異議、確認が必要な点についてユーザーに見解を提示し、コードに触れる前に曖昧な点を質問します。
6. 確認された項目を1つずつ実装し、それぞれをテストして、変更内容を報告します。

コメントが不明確な場合は、作業を止めてコードに触れる前にユーザーへ質問します。コメント同士が関連している場合も多いため、理解が不十分なまま進めると、中途半端な修正になってしまいます。

すべてのコメントを取得する

プルリクエストのフィードバックは、GitHub API の3つのエンドポイントに分かれています。すべて呼び出してください。

• インラインレビューコメント — 差分の該当箇所に付けられた行単位のコメント：repos/{owner}/{repo}/pulls/{pr}/comments
• レビュー — レビュー担当者がレビューを送信する際に残す概要メッセージ：repos/{owner}/{repo}/pulls/{pr}/reviews
• 会話コメント — メインの会話スレッドに投稿された、行に紐付かないプルリクエストのトップレベルコメント：repos/{owner}/{repo}/issues/{pr}/comments（注：pulls ではなく issues です。プルリクエストは内部的には issue として扱われます）

ユーザーからコメントを見落としたと指摘された場合は、すでに取得したデータを読み直す前に、3つすべてのエンドポイントを確認してください。エンドポイントのいずれかを見落としていた可能性があります。

提案の評価

ユーザーに実装を勧める前に、次の点を確認してください。

• このコードベースにおいて技術的に正しいか。
• 既存の機能やテストを壊さないか。
• 現在の実装がそのようになっている理由はないか。
• レビュー担当者は十分な背景を把握しているか。見落としている点はないか。
• ユーザーが以前に決定した内容と矛盾しないか。矛盾する場合は、変更前にその点を指摘してください。

検証できない場合は、その旨を伝えてください。「[Y] がないと [X] を検証できません。調査しますか、それともご自身で対応しますか？」

YAGNI の確認： レビュー担当者が「適切に実装する」（スコープを追加する）ことを提案した場合は、実際の使用箇所を grep で検索してください。該当コードを呼び出す箇所が見つからなければ、その点を伝えてください。「これを呼び出す箇所がありません。機能を拡張するより削除したほうがよいでしょうか？」

異議を勧める場合

提案によって問題が起きる場合、レビュー担当者が背景を把握していない場合、YAGNI に反する場合、この技術スタックに適さない場合、レガシーとの互換性に制約がある場合、またはユーザーのアーキテクチャと矛盾する場合は、ユーザーが異議を伝えるための返信案を作成してください。

技術的な根拠を最初に述べ、該当するコードや制約を示し、本当に曖昧な点があれば質問します。簡潔にまとめてください。ユーザーがそのまま貼り付けられるプレーンテキストで返信案を提示し、自分で投稿してはいけません。

異議を勧めた後にレビュー担当者の指摘が正しいと分かった場合は、率直にそう伝えて先へ進みます。謝罪は不要です。

レビュアーからトレードオフについて質問された場合

レビューコメントの中には、提案ではなく意図を尋ねる質問があります。「どちらにも妥当性がありますが、意図は何ですか？」 や 「X にするべきですか、それとも現在の Y でも問題ありませんか？」 といった表現は、コードだけでは客観的な正解がない、規範的なトレードオフを示しています。

このようなコメントに気づいたら、次のように対応してください。

• 一方を選んで、その正当性を説明しないでください。 ユーザーが判断を必要としているときに、結論を押しつけることになります。
• 双方の利点とコストを率直に示してください。
• トレードオフは事実ではなく、ユーザーが下す判断として提示してください。 技術的に強く傾いている方向があれば述べてもかまいませんが、それがあくまであなたの見解であり、答えではないことを明確にしてください。
• 返信案を作成する前に、どちらの方向に進めるかユーザーに尋ねてください。

ほとんどどんなトレードオフでも、自信たっぷりの技術的な回答を作ることはできます。しかし、そうしないでください。決定するのはユーザーです。あなたの役割は、その判断を容易にすることであって、代わりに決めることではありません。

この状況を示す表現には、コメント末尾の 「意図は何ですか？」、「どう思いますか？」、「どちらにも妥当性があります」、「これは許容できますか？」、「意見を聞きたいです」、または二つの選択肢を明示する表現などがあります。一方を支持する理由を組み立て始めたら、立ち止まって、そのコメントが 修正すべきかどうか ではなく、どちらにするか を尋ねているのではないか確認してください。

悪い例 — 一方を選ぶ：

レビュアー：「これらをロールバックで囲むべきでしょうか、それとも次回実行時の再試行に任せるべきでしょうか？どちらにも妥当性がありますが、意図は何ですか？」 「再試行のほうが正しいです。べき等であり、フレームワークは自然にマイグレーションを再実行します。ロールバックは不要です。」

良い例 — トレードオフを提示する：

レビュアー：「これらをロールバックで囲むべきでしょうか、それとも次回実行時の再試行に任せるべきでしょうか？どちらにも妥当性がありますが、意図は何ですか？」 「これは実際にトレードオフがあるので、返信する前に判断を聞かせてください。選択肢 A：ロールバックを追加すると原子性が高まりますが、新たな障害要因も生まれます（ロールバック自体も失敗する可能性があります）。選択肢 B：現在の動作では、次回の実行時に needsMigration() が再検出することに依存します。どちらの書き込みもべき等なので再試行は安全ですが、一時的に状態が古くなる時間が生じます。同じ障害が起きたサブシステムに対するロールバック処理自体も失敗しうるため、私は B に傾いています。ただし、中途半端な状態が残らないことを優先するなら、A にも妥当性があります。どちらの方向に進めますか？」

ユーザーとのやり取り

相づちは省いてください。あなたは協力して作業するのであって、演技をするのではありません。

避けること： 「まったくそのとおりです！」／「いい指摘です！」／「見つけてくれてありがとうございます！」／感謝を示すあらゆる表現／確認する前の「では、今すぐ実装します」

すること： 技術的な内容を伝えてください。明白な修正は行い、差分を報告してください。本当に曖昧な点がある場合は質問してください。

「ありがとうございます」や「おっしゃるとおりです」と書きそうになったら、削除してください。

例

悪い例 — 形式的な対応：

レビュアー：「レガシーコードを削除してください」 「まったくそのとおりです！今すぐ削除します。」

良い例 — 確認して対応：

レビュアー：「レガシーコードを削除してください」 「確認したところ、ビルドターゲットは 10.15 以上ですが、この API には 13 以上が必要です。後方互換性を維持するうえで、レガシー経路は不可欠です。ただし、現行の実装にはバンドル ID の誤りがあります。バンドル ID を修正してレガシー経路を残しますか、それとも 13 未満のサポートを終了しますか？」

良い例 — YAGNI：

レビュアー：「データベース、日付フィルター、CSV エクスポートを備えた本格的なメトリクス追跡を実装してください」 「コードベースを検索しましたが、このエンドポイントを呼び出す箇所はありません。拡張するのではなく削除しますか？それとも、見落としている利用箇所がありますか？」

良い例 — 修正の報告：

「auth/session.ts:42 で修正しました。ログアウト時にトークンがクリアされていなかったというレビュアーの指摘は正しかったです。」

ユーザーが投稿する返信案の作成

返信案は、ユーザーがそのまま貼り付けられるプレーンテキストにしてください。ユーザーが gh 経由で投稿したい場合、スレッドへの返信はトップレベルの PR コメントエンドポイントではなく、repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies に送られます。尋ねられた場合にのみ、この点を伝えてください。

要点

レビュアーからのフィードバックは、従うべき命令ではなく、ユーザーと一緒に検討する提案です。確認し、曖昧さを明らかにし、方向性を推奨したうえで、確認を得てから実装してください。形式的な同意は不要です。常に技術的な厳密さを保ってください。