はじめに

レビューで指摘を受けたとき、内容を理解する前に落ち込んだり、すぐに反論したくなったりすることがあります。

たとえば、Pull Requestに次のコメントが付いた場面です。

この実装では、user.profile が存在しない場合に例外になりませんか。
入力値が必ず存在すると判断した根拠も確認したいです。

このコメントを「実装者として評価されていない」と受け取ると、必要以上に謝るか、正しさを証明することに意識が向きます。しかし、まず確認すべきなのは、 成果物にどのようなリスクが残っているか です。

レビューの対象は、コードだけではありません。設計書、手順書、テスト仕様書、インフラ構成、Pull Requestの説明などでも、基本的な進め方は共通します。

この記事では、筆者の実務経験とGoogleのコードレビュー指針などをもとに、指摘を次の成果物へ生かすための進め方を整理します。特定の組織が定めた公式手順ではないため、最終的には参画先やチームのルールを優先してください。

最初に切り分けたい3つのこと

指摘を読んだら、頭の中で次の3つを分けます。

区分	確認すること	例
事実	現在の成果物がどうなっているか	`user.profile` がない場合に例外になる
解釈	指摘をどう受け取ったか	実装全体を否定された気がする
行動	次に何を確認・修正するか	入力仕様と既存データを確認してテストを追加する

「厳しく言われた」と感じること自体は不自然ではありません。ただし、その感情と技術的な判断を同じものとして扱うと、修正の目的を見失います。

すぐに返答すると感情的になりそうな場合は、コメントを読み直し、事実と確認事項をメモしてから返します。即答よりも、認識をそろえることを優先します。

指摘の重要度と種類を分ける

すべてのコメントが、同じ優先度とは限りません。

GoogleのEngineering Practicesでは、必須の修正と提案などを区別できるよう、コメントの重要度をラベルで示すことを勧めています。また、コメントは人ではなくコードに向け、理由を説明することも重視しています。

この記事では、レビュー指摘を次のように整理します。

種類	意味	最初に行うこと
Blocking	マージや承認前に対応が必要	影響範囲と修正方針を確認する
Question	意図や前提の確認	根拠を説明し、説明だけでよいか修正が必要か確認する
Suggestion	より良くするための提案	効果と変更コストを比較する
Nit	表記や軽微な改善	チームルールを確認してまとめて直す
Out of scope	今回の変更範囲を超える課題	Issueや別チケットへ分けるか相談する

これは記事内で使う実務上の整理です。チームによっては Must、Should、IMO、Nit など、別の表現を使います。

コメントの意図を統一する方法として、suggestion: や issue (blocking): のように書くConventional Commentsという形式もあります。導入する場合は、チーム内でラベルの意味を先に決めておくと、必須修正と任意提案を区別しやすくなります。

指摘を受けてから再レビューまでの進め方

ここからは、筆者が実務で使いやすい形に整理した流れです。

1. 先にコメント全体を読む

1件目を見てすぐに修正を始めると、後のコメントと重複したり、設計変更によって修正が無駄になったりします。

まず、レビュー全体を確認します。

同じ原因から発生している指摘はないか
設計を変える必要がある指摘はないか
仕様確認が必要な指摘はないか
修正範囲がPull Requestの目的を超えていないか
複数のレビュアーの意見が食い違っていないか

大きな設計変更が必要なら、細かな命名修正より先に方針を合わせます。

2. 指摘の根拠を確認する

コメントをそのまま正解と決めつけず、次の情報を確認します。

要件、受け入れ条件
設計書、ADR（Architecture Decision Record。設計上の判断と理由を残す記録）、チームのコーディング規約
実際の入力データ
エラーログ、監視結果
既存テストと再現手順
使用しているライブラリやサービスの公式ドキュメント

レビュアーが勘違いしている場合もあります。逆に、自分が前提を思い込んでいることもあります。立場ではなく、確認できる根拠で判断します。

3. 理解した内容と修正方針を返す

修正前に認識を合わせる必要がある場合は、次の4点を短く返します。

指摘をどう理解したか
何を確認したか
どこまで修正するか
いつ再確認を依頼するか

ご指摘ありがとうございます。
user.profile がないデータで例外になる点を確認しました。
一覧表示を継続できるように既定値を返し、欠損時のテストも追加します。
影響範囲を確認したうえで、本日16時までに再レビューを依頼します。

必要以上に長く謝るより、理解と次の行動を明確にする方が、レビュアーも状況を判断しやすくなります。

4. 指摘の周辺まで確認して修正する

指摘された1行だけを直すと、同じ前提を持つ別の処理に問題が残ることがあります。

次の順番で確認します。

指摘箇所で問題を再現する
同じ処理やデータを使う箇所を検索する
修正による影響範囲を確認する
修正する
同じ問題を検出できるテストを追加する
差分全体をセルフレビューする

たとえば、次のコードは profile や name がない場合に例外になります。

def get_display_name(user: dict) -> str:
    return user["profile"]["name"].strip()

仕様として「名前が未登録でも一覧表示を継続する」と決まっているなら、次のように修正できます。

def get_display_name(user: dict) -> str:
    # 名前がない利用者でも一覧表示を継続できるようにする
    profile = user.get("profile") or {}
    name = profile.get("name")

    # 文字列以外や空文字も未設定として扱う
    if not isinstance(name, str):
        return "未設定"

    return name.strip() or "未設定"

再発を検出するため、正常系だけでなく欠損時のテストも追加します。

def test_get_display_name_returns_default_when_profile_is_missing():
    # profileがない場合もnullの場合も、仕様で決めた既定値を返す
    assert get_display_name({"id": 1}) == "未設定"
    assert get_display_name({"id": 2, "profile": None}) == "未設定"

このコードは説明用の例です。"未設定" を返す、エラーにする、対象データを除外するなどの判断は、実際の要件に合わせてください。

GoogleのEngineering Practicesでは、変更に応じた単体・結合・E2E（利用者の操作に近い一連の流れ）テストを確認し、原則として本体コードと同じ変更にテストを含める考え方が示されています。

5. 修正内容を証拠と一緒に返す

修正しました だけでは、レビュアーが差分を最初から追い直すことになります。

次の情報を返すと、再レビューしやすくなります。

修正したファイルや処理
修正方法
追加・更新したテスト
テスト結果
対応しなかった範囲と理由

修正しました。

- user.profile がない場合は「未設定」を返すように変更
- 同じ参照をしていたCSV出力処理も修正
- profile欠損時の単体テストを追加
- pytest: 24件成功

CSVの既存データ補正は今回の変更範囲外のため、別Issueへ登録しました。
再レビューをお願いします。

GitHubでは、提案された変更の適用、修正コミットのpush、会話の解決、再レビュー依頼をPull Request上で管理できます。会話を誰がResolveするかは、チームの運用に合わせてください。

指摘の意味が分からないときの聞き方

分かったふりをして修正すると、意図と違う変更になり、レビューが長引きます。

対象が分からない

認識を合わせたいです。
今回の指摘は、このメソッド内の例外処理だけが対象でしょうか。
それとも、同じ入力値を使うCSV出力処理まで確認する必要がありますか。

理由が分からない

修正方針を判断するため、懸念点を確認させてください。
今回優先したいのは、処理速度、保守性、障害時の切り分けのどれでしょうか。

完了条件が分からない

対応完了の条件を確認したいです。
欠損時の処理修正と単体テスト追加まででよいでしょうか。
既存データの確認も必要であれば、対象期間を教えてください。

質問するときは「分かりません」だけで終わらせず、どこまで理解し、何を判断できないのかを示します。

指摘に同意できないときの返し方

レビューコメントが常に正しいとは限りません。納得できない場合でも、感情や経験年数ではなく、根拠とトレードオフを示します。

ご提案の方法も確認しました。
今回は、既存クライアントがこのレスポンス形式を使用しているため、
すぐに変更すると互換性へ影響します。

今回は現行形式を維持して入力チェックを追加し、
レスポンス形式の変更は別Issueで移行手順と合わせて検討する案を考えています。
この方針で問題ないでしょうか。

「前からこの実装です」「自分はこちらが正しいと思います」だけでは判断材料が不足します。

意見が割れた場合は、次を整理します。

要件を満たすか
利用者への影響
セキュリティや障害リスク
実装と保守のコスト
将来の変更しやすさ
最終判断をする担当者

複数のレビュアーから相反する指摘が来た場合は、両方を無理に実装せず、責任者を含めて方針を決めます。決定理由は、Pull Request、Issue、ADR（設計判断の記録）など、後から確認できる場所に残します。

指摘を次回の仕組みに変える

レビューで直しただけでは、次の作業で同じ指摘を受ける可能性があります。

繰り返す指摘は、注意力ではなく仕組みへ移します。

繰り返す指摘	仕組みに変える例
フォーマットや命名	formatter（自動整形）、linter（静的検査）、静的解析
境界値や例外処理	単体テスト、テストケース表
Pull Requestの説明不足	Pull Requestテンプレート
要件の読み違い	着手前の完了条件確認
設計意図が伝わらない	構成図、ADR、設計レビュー
ログや監視の不足	運用チェックリスト、監視テンプレート
手順の抜け	手順書テンプレート、自動化スクリプト

指摘の理由を理解すると、別の成果物にも応用できます。

たとえば「例外処理を追加してください」という指摘を、単に try-except を書く作業として終わらせないことが大切です。

どの入力で失敗するのか
失敗時に処理を継続するのか
利用者へ何を返すのか
ログへ何を残すのか
監視や再実行は必要か

ここまで考えると、指摘が設計と運用を見直す材料になります。

よくある失敗

指摘を読んですぐにコードを直す

理由を理解しないまま直すと、別の場所に同じ問題が残ります。まず再現条件と影響範囲を確認します。

すべてのコメントを必須修正だと思う

質問や任意提案まで無条件に実装すると、変更範囲が広がります。重要度と完了条件を確認します。

説明だけで終わらせる

レビュー画面だけに複雑な理由を書いても、将来コードを読む人には残りません。コードを単純にする、必要なコメントを入れる、ADRへ残すなど、成果物側へ反映します。

修正前に会話をResolveする

未対応の指摘が見えにくくなります。実装、テスト、返信が終わってから、チームルールに従って解決済みにします。

指摘と関係ないリファクタリングを混ぜる

差分が大きくなり、修正内容を確認しづらくなります。必要なら別のPull RequestやIssueへ分けます。

指摘メモのテンプレート

同じ種類の指摘を探せるよう、修正内容だけでなく原因と再発防止を残します。

対象成果物:
指摘内容:
重要度:
確認した事実:
指摘の理由:
修正方針:
修正した箇所:
確認・テスト結果:
今回対応しなかった範囲:
次回の確認項目:
仕組みに変える内容:

すべての指摘を個人メモへ転記する必要はありません。繰り返しやすいもの、他のメンバーにも役立つものは、チームのチェックリストやドキュメントへ反映します。

再レビュー前のチェックリスト

コメントをすべて読み、重要度を確認した
指摘の事実と自分の解釈を分けた
要件・設計・ログ・テストなどで根拠を確認した
指摘箇所だけでなく、同じ処理を使う箇所も確認した
必要なテストを追加・更新した
指摘と無関係な変更を混ぜていない
修正内容とテスト結果をコメントへ書いた
対応しない指摘には理由と次の扱いを書いた
formatter、linter、CI（継続的インテグレーション）などの自動チェックを通した
差分全体をセルフレビューした

参考資料

関連記事

まとめ

レビュー指摘へ対応するときは、次の順番で進めます。

指摘の事実と、自分の受け取り方を分ける
必須修正、質問、提案、軽微な指摘を区別する
要件やテストなどの根拠を確認する
理解した内容と修正方針を共有する
周辺への影響とテストまで確認する
修正内容と確認結果を添えて再レビューを依頼する
繰り返す指摘をチェックリストや自動化へ変える

レビューで本当に身につけたいのは、指摘された1行の直し方だけではありません。なぜ問題になるのかを理解し、次の成果物ではレビュー前に気づける状態へ変えていくことです。

おわりに

次にレビューを受けるときは、まず1件だけでも「事実・理由・修正・再発防止」に分けて記録してみてください。指摘を受ける回数をゼロにするのではなく、同じ指摘を減らし、より本質的なレビューへ進めることが成長につながります。

Wealthy Designでは、レビューと知識共有を通じて、エンジニアが継続して成長できる会社づくりに取り組んでいます。会社の取り組みや採用情報は、会社サイトにまとめています。