はじめに
早いもので12月ですね🎄 皆さんはどんな1年だったでしょうか？
今年のトピックの1つはやはりAI agentによる開発の変化でしょう。コード生成は当たり前となり、「最近手でコードを書いてないな？」というレベルまで浸透してきています。大量のコードを短時間で生成できるようになった一方で、コードレビューの負担が増えがちだなと感じています。
この記事では、コードレビューをスムーズに回すために私が意識していることを整理してみます。
前提：チームの認識を揃える
コードレビューをスムーズに回すには、まずチーム内で認識を揃えることが大事だと考えています。「◯◯分以内にレビューをしよう！」とか「◯◯のチェックリストを用意しよう！」といった個別のルールや仕組みを検討する前に、チームとして何を重要視するのか、なぜそのルールが必要なのか"Why"の部分をすり合わせておきたいところです。
チームの価値観・期待値をすり合わせる
次のような観点は開発者によって価値観や意識が異なるケースがあると思います。
- PRのボリューム。どれだけの差分を1PRに含めるか
- レビューを出してからレビューがつくまでの時間
- レビューの観点、細かさ
- レビュアー、レビュイー間での動作確認の責務
- コミットのルール
- 機能ブランチに対するforce pushやrebaseのルール
こういった人によって揺れる内容はチーム内で一度擦り合わせておくと良いと思っています。例えば「レビューが小さい方がいいとはいうけど、どれくらい？」「そもそも何で早い方がいいの？」といった議論を重ねて、チーム内で腹落ちできるようにしたいですね。
仕組み・ツールを整備する
方針の合意が取れたら、仕組みやツールでその運用が形骸化しないように担保したいところです。
- 機械的に検出できるものはまず静的解析に組み込めないか検討する
- （GitHubの場合）自動割当の設定やCODEOWNERSの機能を活用するなどして、レビュー依頼を自動化する
- GitHub CopilotやClaude Code Actionsなど、AIによる自動レビュー環境を整備する
- PRテンプレートを設定し、チェックリストを用意する
弊チームの例だと、Prismaを使っているプロジェクトにてスキーマファイルに差分があればスキーマのガイドラインに沿っているかレビューするClaude Code Actionsを動かすなどしています。AIのレビューは完全ではありませんが、ケアレスミスのようなものはある程度気づくことができるのでオススメです。
レビュー依頼時
PRを出す際の心がけをまとめます。
まずセルフレビュー
PRを出す前に、自分でdiffを確認するようにしています。ボリュームが小さいものはlazygitでサクッと確認し、ある程度ボリュームがあるものはdifitで差分を確認、セルフレビューをAgentに投げるというサイクルをよく回しています。Agentで物量あるコードが出てくるので自身での確認が甘くなりがちなので気をつけたいところです（自戒）。
PRサイズを小さく保つ
基本的にPRは小さく早く、目的を絞ることを意識しています。とはいえ、
- 小さくするほど他メンバーが担当するレビューの数自体は増える
- 全体像が見えにくくなる
といったデメリットもあります。恥ずかしながら以前は「PRは小さい方がいい」と一辺倒に考えていたのですが、AI agentの登場で少し考えが変わりました。単純な実装であればAgentがある程度の精度でまとまった量を出せるので、あえて大きくしても問題なさそうな場合はまとめることも意識するようになりました。具体的には、ある程度単純なAPIで他APIとほぼ同様の構造の場合はAI agentに一気に作業をさせてCRUDのAPIをまとめて出してしまうなど。
手戻りや議論があり得そうな場合は細かく、そうでない場合はまとめてレビュー回数を減らすのもありだなと考えています。
PRを分ける際の指針としては以下があります。
- リファクタリング（構造の変更）と機能追加（振る舞いの変更）は別PRにする
- Tidy First?の考え方
- 自動生成コードは生成だけでPR
- e.g. lint結果、shadcnコンポーネント追加などコマンドによる成果物
- ランタイムに影響がないであろう変更と、影響がでうる変更は分ける
- e.g. 部品となるコンポーネント実装と、それの画面からの呼び出しで分ける
- 仮に不具合があってrevertとなった場合にはコンポーネントに関しては戻さなくて済む
レビュー時
レビュアーとして参加する際の心がけです。
基本的に即レビューを目指す
これは色々と議論があるかと思いますが、私としては自身の作業を止めてでもレビューをするというスタンスでいます。レビューが遅れることの弊害を次のように捉えています。
- レビューを受ける側の後続の作業がブロックされる。あるいは手戻りが発生する
- その差分を取り込んで作業をしたい別の開発者にまで影響が及ぶ
- 「レビューつくの遅いし少しまとめて出すか」という力学が働き、PRが大きくなりうる
もちろんレビューには作業コストやコンテキストスイッチのコストもありますが、チームとしての活動がスムーズにいく方を優先した方が良いだろうと考えています。「これぐらいのスピード感でレビューがつくようにしよう」という指針があると良いですね。
私の場合、レビュー依頼になるはやで気づき、かつ漏らさないよう次のような方法を組み合わせています。
- Slack内でのGitHub連携にて担当しているリポジトリの通知を受け取る
- gh triageをwatchのオプションをつけて動かし、未レビューのレビュー依頼がないか一定間隔で確認、あれば自動でブラウザで表示
- RaycastのGitHubのプラグインを使ってメニューバーに通知も表示、タスクの切れ目などで確認する
この辺りは好みがあるので強制にはせず、チーム内でやり方を共有して各自マッチする運用を検討してもらえれば良いと思います。
ポジティブなフィードバックも行う
レビュー時につい改善点の指摘に終始しがちですが、良いなと思った点もフィードバックするように意識しています。PRが単なる指摘の場となると活発なコミュニケーションもしづらいですし、良いコードを認識して共有することは他開発者へのプラクティス共有にもなります。
有益でない指摘は書かない
「明らかに個人の感想の域を出ない」かつ「議論しても学びにならない」と判断したコメントは残さないように意識しています。コメントを出された側は修正すべきか判断するコストが発生してしまいます。
一方で「修正不要だがこういう考え方もある」といった学びがあり得る点は、その旨を添えてコメントを残すようにしています。
AI agentでコーディングスピードが上がった現在、せっかく市場に対して機能をスピーディーに提供できるのにnitsな指摘でレビューに時間をかけるのは勿体無いと考えるようになりました。
- クラスやメソッド、APIエンドポイントのインターフェイスが妥当そうか
- 期待するテストはあるか
- 命名に違和感はないか
- 明らかに無駄な処理がないか（必要のないループがあるなど）
のように保守性・可読性に寄与する大きい部分を意識してレビューするよう心掛けています。
継続的な改善
レビューを回していく中で、以下も意識すると良いと考えています。
レビュー指摘をAIのコンテキストに反映する
レビューで指摘をもらった際に、それが恒久的に有用な指摘であれば、AIのコンテキストに反映するのが理想です。AGENTS.mdやagentが参照するガイドラインに追記することで、同じ指摘を繰り返さないようにできます。
開発プロセス全体を俯瞰する
コードレビューがよく回るようになっても、後続のQAプロセスがボトルネックになって結局効率は変わらない、というケースがあり得ます。
開発プロセス全体のボトルネックにも目を向けて改善できないか考えるとなお良いでしょう。機能実装だけを高速に回してもプロセスが詰まるようなら、受け入れにコストがかからない作業（自動テストの充実、依存パッケージの更新、開発環境・ドキュメントの改善など緊急ではないが重要なタスク）を差し込んで調整するなど、開発全体をコントロールしながら進められると良いですね。
まとめ
コードレビューをスムーズに回すために意識していることを整理してみました。こうして整理してみると、AIの話は限定的で、結局は人・組織のコミュニケーションの話が主だなと感じました。価値観や期待値を揃えてルール化し、ルールが形骸化しないよう仕組みを整え、コストをかける価値のあるレビューを目指したいものです。AIはそのサイクルを加速するツールの1つとして積極的に活用できればと思います。
Discussion