冬ぞ寂しさまさりけるので初投稿です。
この記事はMOSH Advent Calendar 2025の6日目の記事です。
仕事をしているとコードレビューについてレビュイーとしての振る舞いにポジティブなコメントをいただくことがあります。また、最近チーム内でレビューリクエストの流量とレビュー負荷が課題として挙げられており、レビュイー・レビュワーの振る舞いについてどう工夫すればいいだろうと考える機会が増えました。
そこで、思考の整理のためにも自分がコードレビュー時に気にしていることを一度言語化しておこうと思います。ついでに、せっかくなら記事にしてしまおうという寸法です。
この記事では、レビュイー・レビュワー二つの視点からお互いに負荷を下げ合うための、自分なりの工夫や理想状態を整理します。コードレビューを議論の中心としますが、コード以外も含む成果物全般へのレビューに適用できる内容も含まれると思います。また、記事中コードレビューを受ける成果物の単位としてPR（pull request）を用いますが、これは適宜読み替えてください。
レビュイーとして
セルフレビュー
チームや同僚にレビューリクエストを投げる前にセルフレビューを行うことは、不要なコミュニケーションラリーやレビュー負荷を避けることに繋がります。
当たり前にやっている人も多いかとは思いますが、それでも全員やっているわけではなさそうだなあというのが自分の印象です。
AI agentが流行する前後でセルフレビューの重要性が一段階増したようにも思います。レビュイーの預かり知る部分が減り、出力の振れ幅が大きくなったためです。
明らかに消してはいけないコードやコメントが消えている、テストが不十分であるといった、明らかに指摘され得る状態のままレビュワーに丸投げしてしまうのは時間的にも精神的にも負担をかけてしまうことになるので避けたいところです。
（明らかな）誤りを見つけるという点ではagent自体にレビューをさせることもできますし、GitHub Copilotのreview機能のようなものに乗っかって仕組み化することだって可能です。
AI agentに頼らずとも、PRのテンプレート（あるいはそれに準ずるもの）にセルフレビュー用のチェックリストを入れるだけでもいいかもしれません。
セルフレビューの時間がないような場合、習慣づけが難しい場合などには特に上記のような仕組みを活用するのが肝要だと考えます。
サンプルのために健気にレビューしてくれるCopilotさん
また、どのようなセルフレビューを行ったかを記載しておくこともレビュー時間の節約に繋がります。例えば、行った動作確認の内容を残しておけばレビュワーはその作業を省略できる場合もあるでしょう。
文脈を残す
レビュワーができるだけ自分と同じ情報量を持ってレビューに臨めるよう手助けすることも大切です。
例えば、以下のような内容です：
- 親タスクであるNotionやGitHub Issueなどのリンク
- 関連するADRやdesign doc
- prior artなど、過去の類似の取り組みなども有用です
- 前後のPR
- 加えて、このPRがどこまでのスコープを持つのか
- 関連する外部リソース・APIのドキュメント
- 作業中に使われたAI agentへのprompt
- etc...
毎回これらすべてを提供するのは大変な部分もありますが、一連のタスクにおいては前回のものをコピペしておけば足りる部分も多いでしょうし、レビュワーとのラリーが増えるよりは時間の節約になるケースもあるでしょう。
すでにPR templateとしてこれら情報を記載するよう推奨している場所も多くあるかとは思いますが、タスクの内容やチームの状況に応じて適宜項目を修正するよう意識づけておく（一時的なものであればその都度追加するでもいいですし、それが複数人に持続的に影響するのであればテンプレートを編集する必要があるでしょう）ことも大事だと思います。
その他、コードコメントとして記載するほどではないがコメントとして残しておくと役に立つ内容もあります。
例えば、一見無関係そうな変更や意図を追いかけるのにちょっと時間がかかり得る変更、あるいは実装に議論の余地がある箇所を補足するケースが該当します。
また、関連する外部リソース・APIのドキュメントについて、あるパラメーターの近くにレビューコメントとして残しておいた方がレビューしやすくなる場合もあるでしょう。
そして、これらの情報は将来第三者が歴史を辿るときの手掛かりになることにも注意してください。
チーム間では暗黙的に共有できていた内容でも、時を経て関係者が退職したり忘れたりしてしまうと、そのコンテキストは失われてしまいます。
もちろんそれを防ぐためにADRやdesign docなどが存在していますが、コードベースを起点として調査するときにそれら関連ドキュメントに安易にたどり着けないのでは本末転倒です。
未来の同僚を困らせないためにも気をつけたいところです。
レビューしやすいサイズにする
ここはケースバイケースな側面もあると思っているのですが、基本レビューしやすいサイズにPRを分割すべきというのは世でよく言われている通りで、このレビューしやすいサイズというのがチームや作業内容によって変わり得る話だと認識しています。
個人的にはrust-lang/rustで幼少期を過ごしたということもありlinearなGit historyが好みなので[1]、PRを小さくしsquash mergeしても問題ない量に抑えるようにしています。GoogleのEngineering Practicesでも小さい変更の利点やレビュワーが大きすぎる変更を拒否する権利について記載があります：
ですが実際問題、過度な分割はレビュー回数の増加に繋がり、レビューのラリーが増えることで（短期的な）アジリティが損なわれ、それがクリティカルになるフェーズ・タイミングもあります。
チームの熟練度やフェーズなどによって適切なサイズの基準も変わるでしょうし、レビューしやすいサイズについて個人の感覚で終わらせずチーム内で適宜合意形成すべき部分かなあというふうに思っています。
また、行数だけで変更の複雑性を表すことには諸説ありそうで、ぱっと見クソでかい処理でもやっていることは単純で理解しやすい場合もあります。その逆も然りです。そのような場合にはコメントなどで補足してレビュワーを身構えさせないことが大事なように思います。
レビュワーとして
コメントの曖昧さをなくす
レビューコメントをもらったがこれは修正してほしいのかどうか分からない、あるいはただの質問のつもりだったのに修正すべきと受け取られてしまった、といった経験はないでしょうか。
こういった出来事はレビューコメントの曖昧さを示唆しており、何らかの対処が必要です。
このためのフレームワーク・手法として、有名なものだと"Conventional Comments"というものがあります。
Conventional Commentsは以下のようなラベル・デコレーターなどを用いて曖昧さを減らすことを目的とします。
ラベルには例えば以下のようなものがあります：
| ラベル | 用途 |
|---|---|
praise: |
良いコードを褒める |
nitpick: |
些細な指摘 |
suggestion: |
改善提案 |
issue: |
問題点の指摘 |
question: |
質問・確認 |
thought: |
アイデアの共有 |
これに加えて、ラベルの後にデコレーターを付けることで要対応か否かの詳細なニュアンスを伝えられます：
-
(blocking): 対応が必要 -
(non-blocking): 対応は任意 -
(if-minor): 軽微なら対応してほしい
Conventional Commentsを使ったコメントを以下に例示します：
issue (blocking): このクエリはN+1問題を起こしそうなので修正してほしいです！
suggestion (non-blocking): 判断はお任せしますがこれ使って実現する方法もあります！: <URL>
GitHubのsaved replies機能などを使えば、これらラベルやデコレーターを簡単に取り出すことができるのでおすすめです。
自分は最近 label を使ってレビューコメントを書くよう心掛けてみています：
Conventional Commentsの他にもMoSCoW methodなど流派がありますが、ここはチームの風土に合うものを選択すれば良いと思います。肝要なのはレビューコメントの曖昧さを減らすことで、その達成を念頭に置いて手段を選択する必要があります。
LGTMにグラデーションをつける
変更を承認する場合、同じ"LGTM"でも隅々まで確認したとき、大枠の方針を承認したいとき、あるいは特定部分だけを承認して他は別のチームメンバーに任せたいときなど、そこには濃淡が存在するはずです。
そのようなグラデーションを承認する際に明記しておくと、他のレビュワーが何を重点的に見るべきかが明確になりますし、レビュイー視点でも他の人のレビューを待つ必要があるのか、どの部分があまりレビューされていないか（例えば細かい動作確認がなされていない場合はフォローアップが必要になりそうなことをある程度予期できる）などを知ることができます。
LLVMのreview policyの中でもこの点について言及があります：
When providing an unqualified LGTM (approval to commit), it is the responsibility of the reviewer to have reviewed all of the prior discussion and feedback from all reviewers ensuring that all feedback has been addressed and that all other reviewers will almost surely be satisfied with the patch being approved. If unsure, the reviewer should provide a qualified approval, (e.g., “LGTM, but please wait for @someone, @someone_else”). You may also do this if you are fairly certain that a particular community member will wish to review, even if that person hasn’t done so yet.
要約すると、LGTMを出す際は他のレビュワーのフィードバックがすべて対応されているか確認し、不確かな場合は条件付き承認としてコメントすべき、という内容です。例えば、先に他のレビュワーが指摘している部分以外は良さそうだと思えばその旨を記載しつつ承認するのもいいでしょう。
OSS開発での経験で"thank you"付きで承認することの大切さを学んだというのもあり、先のconventional commentsでいうところのpraiseを盛り込むためにも無言承認をしないよう心掛けています。
トーンに気を付ける
これは書籍『Looks Good To Me』でも触れられていますが、レビューコメントを投げる際の口調・トーンには気を付ける必要があります。
コードレビューという構造上、どうしてもレビュイーの立場が心理的に下になりやすく、レビューコメントの微妙なニュアンスがレビュワーの想像以上に増大して受け取られることがあります。
"Characteristics of Useful Code Reviews: An Empirical Study at Microsoft"では、ネガティブなコメントよりニュートラルなコメントの方が有用であると受け取られやすいことが示唆されています。
Slackなどでのコミュニケーションでも度々話題に上がりますがテキストコミュニケーションはネガティブに受け取られやすいという話もありそうで、絵文字を多用する・柔らかい表現を心がけるなど、気配りが必要な部分だと思います（レビュワーの職位が高い場合は特に）。
conventional commentsでもpraiseというラベルが用意されているように、柔らかいコードレビューはプラクティスとして一定認知を得ているものだと認識しています。
とどのつまり、どこまでいっても人間同士で開発を進めていることに変わりはないので（少なくとも、今のところは）。
その他やりたいがまだできていないこと
コードレビューの負荷を下げるためにはできる部分はどんどん自動化してしまうのが楽です。
これがGitHubのcodeowner機能やCI（e.g. linting）などになってくると思うのですが、AI agentの勃興によりコーディングポリシーなどの静的解析に落とし込みづらい部分もCIとしてチェックできるようになったと感じています。
作業者による品質のばらつきを抑えるためにも、この辺りはうまく仕組み化したいなあと思っていますが、弊社では現状できていない部分も多く、次のチャレンジだなあと思っている次第です。
最後に
以上、自分がコードレビューを行う・受ける際に気をつけていることを整理しました。
人によっては当たり前の内容もあるかもしれませんし、メリットが薄いと感じる内容もあるかもしれません。実際チームの状況によってベストなコードレビュー体制・文化は変わり得る部分もあると思っています。
レビュー文化は一朝一夕には完成しませんし、色々試行錯誤しながら根付かせていく、議論していく必要があります。
そういった取り組みの中でこの記事が何かの参考になっていれば幸いです。
参考文献
-
Rustには"no merge policy"という、merge commitを入れずlinearにGit historyを保っていこうというポリシーが存在します: https://rustc-dev-guide.rust-lang.org/git.html#no-merge-policy ↩︎
Discussion