チームの認識を揃えるためのレビューガイドライン

はじめに

私たちのチームでは開発のボトルネック解消のためにメンバー同士の「相互レビュー」を導入していますが、人によって指摘の観点や優先度が異なるという新たな課題が生まれました。そこで、認識のズレを解消し、メンバー育成にもつなげるためにガイドラインを作成しました。

本記事では、そのガイドラインの内容を紹介します。

ガイドラインの目的

あらゆるチームに適用可能な方針を作るのは困難ですが、「この方針でいこう」というチーム内の認識を揃えることはできます。
ここで言う「認識を揃える」とは、思考の画一化ではありません。「迷いや対立を減らすためのベースライン」を共有し、その上で個人の視点を活かすことが狙いです。

チーム内の認識を揃えるだけでも、次のようなメリットがあると考えています。

• レビュアー、レビュイー双方のストレスを軽減できる
• レビュアーの違いによる品質のばらつきを低減できる

このガイドラインでは、レビューにあたって認識を揃えたほうがよさそうなポイントを記載します。最終的にどのようなやり方を採用するかは、チームの状況に合わせて判断してください。

レビューの目的

レビューの目的には以下のようなものがあります。

• A. 品質の維持または向上
  • バグやパフォーマンス、セキュリティ等の問題を未然に防ぐ。
• B. 設計・実装への合意形成
  • チーム全員が同じ認識で作業を進められるよう、合意形成を行う。
  • 設計・実装の保守性や一貫性の観点も含む。
• C. 知識・技術の共有と教育
  • 知識や技術的な理解を共有し、メンバー全体のスキルを向上させる。

レビューの課題

レビューの課題には以下のようなものがあります。

レビューの基本方針

前述の課題を回避し、目的を達成するための基本方針を示します。

各課題に対する有効なアプローチを、経験則に基づいてマッピングしました。
定性的/定量的に分析した結果ではありません。

以下、各方針について補足します。

■共通

レビューを最優先とする

• 1～2営業日以内を目安にレビューし、遅れる場合は連絡します。
  • レビューを最優先にするという共通認識をチーム内で持つことが重要です。
  • 何かしらレスポンスするだけでも、レビュイーのストレスは軽減されます。
  • 例：レビューを開始する旨を伝える、いつ着手するか伝える、スタンプを付与するなど
• レビュー依頼が自身のタスクの最中だった場合は、キリのよいタイミングを待ってからレビューします。
  • 例：今の実装が終わった後、ミーティング後、ランチ後など
• レビュー結果の反映も迅速に行います。

横の意識（横断的調査、横展開）を持つ

• ある部分を変更するときには、関連して変更すべき部分がないかを調査し、その結果も共有するのが望ましいです。
• 共通して存在しそうな不具合が検知された場合は、なるべく横断的に調査し、修正を横展開するようにします。
• 頻繁に出そうな指摘はなんらかのアクションをとります。将来の指摘を減らそうとするのも、時系列的な横の意識と言えます。
  • 例：その指摘の根本原因と回避策を検討し、実施する
  • 例：その指摘をチェックリストに加える

込み入った変更や指摘は事前に議論する

• 大きな設計変更や影響範囲の広い修正は、事前に合意形成を行います。
• 文章だけでなく会話で認識をすり合わせることも重要です。
  • 会話で方針を決めた場合、経緯や結論を設計書などに残しておきます。

レビューを分担する

• レビュー経験の浅いメンバーもレビューに関与できるように工夫します。
  • 例：基本的な観点は一次レビューとして切り出して、相互レビューする
• 自動チェック（静的解析など）を活用し、一部をツールに任せるのも有効です。

レビューの文化を育て、定着させる

• レビューは「単なるチェック作業」ではなく、「チームの成長機会」と捉えることもできます。
• 規約やルール、設計方針や実装方法を、レビューを通じて浸透させましょう。
• 共通的な設計方針や実装方法は規約やルールにフィードバックしましょう。

■レビュアー視点

レビューの粒度が大きすぎる場合は分割を促す

• レビューに時間がかかる場合は、対象範囲が大きすぎるか、内容が複雑すぎることが多いです。
  • たとえば「30分以内に理解できなければ返す」というように、時間で区切ってもよいでしょう。
  • その時間以内にできないのであれば、なにかしら改善の余地があるのかもしれません。
  • これを推し進めるとレビューしたい範囲でタスクを分割するという考え方にもなります。
• 時間を取れるか不安なときには、全体的な内容に関してコメントを送り、先に改善を求めてもよいです。
  • レビュアーは全知全能ではなく、レビュアーに理解できないものは誰にも理解できないと考えてよいです。
  • レビュアーがわからないところは率直に質問しましょう。

重要な問題から拾うように意識する

• レビューの優先順位を明確にし、後戻りが大きい問題を最優先します。
  • 細かいスタイルなどは後回しにし、本質的な問題にフォーカスします。
• レビューで不具合を取り切ろうとする必要はありません。
  • レビューでしか拾えないもの ＞ テストで拾えるもの

指摘の背景や理由を明記する

• 指摘、コメントの際は解決策だけでなく「なぜそうするか」の理由も説明します。
  • このとき、自分の考え方を押し付け過ぎないよう注意します。
• Must/Want/IMO/NITS/Askなどのラベルを活用し、指摘の優先度を明示するのもよいでしょう。
  • 参考：レビューのやり方をちょっと整理した話

レビュー基準または観点を明確化する

• レビュー基準・観点を明確にし、レビュアーごとにブレないようにします。
• どういう基準・観点でレビューするかはチーム全員が共通認識を持っておくと効率的です。

■レビュイー視点

未検討の課題を残さない

• 既知の問題を未検討のままレビューに出さないようにします。
  • 解決が必須ということではなく、「今は解決不要」ということが分かるのも重要です。
• 他にも「この部分は議論が必要」と思ったら、事前に相談します。

セルフチェックを行い、軽微な指摘を減らす

• レビュー負担を減らすため、基本的なミスは事前に潰しておきます。
• レビュー前にチェックリストを活用してセルフチェックを行いましょう。

レビューに必要な情報を提供する

• レビュアーが理解しやすいよう、変更の背景や意図を明確に記載します。
  • レビュイーはレビューを出すまでに十分な時間をかけており、一番詳しい存在です。
  • レビュアーが1つのタスクにレビュイーと同等の時間を費やすことは困難です。
• gitのコミットは、意味のある単位でコミットを分けておくとレビューしやすいです。
  • 異なるタスクの変更を1つのコミットに混ぜない
• 以下のように修正した資源やテスト内容もまとめてあるとレビューしやすくなります。

■対応方針
// なにをどのように修正すべきか、理由も含めて書いてください。

■修正箇所
// 実際に修正した箇所（資源）を書いてください。レビュー時に確認するものです。

■テスト内容
// テストした場合はその内容を書いてください。

レビューの観点

「品質特性×優先度」のマトリクス（アプリケーションチームの例）

レビュー観点には様々な切り口がありますが、ここでは一例として『品質特性』を用いて整理します。

1. 機能適合性：要求された機能を正しく実装できているか、システム全体として最適化できているか
2. 性能効率性：クライアント、サーバそれぞれで快適に動作するか
3. 使用性：使いやすいか、複雑になっていないか
4. 信頼性：動かせばすぐ気づくレベルのバグはないか
5. 保守性：他機能や既存部分から逸脱していないか、共通化すべきか
6. 後方互換性：既存ユーザがそのまま使えるか（仕様変更の影響がないか）
   ※システム及びソフトウェアの品質測定量とその測定方法を一部改変

また、優先度の切り口も交えて整理してみます。優先度については以下のように考えます。

• 変更時の影響が大きい問題、後から修正するときのコストが大きいものの優先度を高くする。
• 優先度「高」の指摘をひと通り洗い出せたら、より低い優先度についてレビューする運用にできると理想的。
• 機能の重要度や時間的制約を考慮して、優先度の低い指摘が対応されていなくてもOKと判断することもある。
• 優先度が分かるように指摘コメントに目印をつけるとよい。

開発フェーズごとの観点リスト（アプリケーションチームの例）

どの観点をどのタイミングでレビューするかを明記することも重要です。
以下はアプリケーション開発チームで実際に使っている観点リストです（一部改変）。

比較対象ごとの観点

最後に、視点を変えて『何と比較するか』というアプローチにも触れてみます。

レビューの本質は「比較すること」にあると言えます。
そのため、何と比較しながらレビューしていくのかを意識することが重要です。
レビュアーの経験や知識のような暗黙知と比較されることもあるため、比較対象は視覚的に見えないこともあります。
重要な暗黙知は規約やルールとして明文化していくとよいでしょう。

設計書と比較して、実装を確認する

• 設計の意図に沿った実装になっているか
• 設計時の前提条件や制約が守られているか
• 変更の影響範囲が十分に考慮されているか

規約やルールと比較して、設計・実装を確認する

• 命名規則や実装方法が統一されているか
• 開発規約やルール（例：後方互換性維持の方針）に沿っているか

他機能と比較して、設計・実装を確認する

• 既存の実装や他機能と一貫性があるか
• 同じような機能を実現するための実装方法にばらつきがないか

実動作と比較して、設計・実装を確認する

• 実際に触ってみて設計に違和感がないか、使いやすいか、複雑になっていないか
• 実装が期待通りに動作するか（すぐ気づくレベルのバグがないか）
  • ただし、レビュアーによる動作確認は最小限にすべきです

設計書と比較して、テストケースを確認する

• テストケースが設計・実装の意図を正しく反映しているか
• 境界値やエッジケースが考慮されているか

おわりに

元のガイドラインを作成した後、AIによるレビューの事例を多く見かけるようになりました。今後AIがレビューする、あるいは、AIの実装を人間がレビューするようになると、人間同士で発生していた課題はなくなっていくのかもしれません。

しかし、AIを活用する時代だからこそ、ガイドラインの重要性が高まることもあると思います。AIに的確な指示を出し、AIからの指摘を適切に判断するためには、チームとして「何を良しとするか」という基準が必要だからです。ガイドラインは、人間同士の認識を揃えるだけでなく、AIを含めたチーム全体の「共通言語」として機能するはずです。
AIとの協業を前提としたガイドラインも今後検討していけたらと思います。