コードレビューの観点とチェックリスト

コードレビューの観点とは

観点とは、レビューで何を確かめるかを言葉にしたものです。観点が共有されていないと、ある人は命名ばかり、別の人はパフォーマンスばかりを見て、誰も異常系を見ていないという状態が起きます。観点を分野ごとに並べておけば、レビュアーが変わっても確認の範囲がそろいます。

Google のコードレビューガイドでは、レビューで確認すべき最も大切なことを CL （変更）の全体的な設計としています。そのうえで機能、複雑さ、テスト、命名、コメント、スタイル、ドキュメントを順に挙げ、完璧なコードは存在せず、より良いコードがあるだけだという考え方を基準にしています。

コードレビューの観点は、仕様・機能、設計、可読性、セキュリティ、信頼性、パフォーマンス、テスト、運用の 8 分野に分けて持つと漏れが減ります。フォーマットや単純なスタイルはリンターと CI に任せ、人のレビューは設計や異常系のように自動化しにくい観点に時間を使います。

分野別のコードレビュー観点

仕様・機能

最初に確かめるのは、変更が説明文や Issue の要件を満たしているかです。正常系だけでなく、空のリスト、null、0、上限を超える入力、ネットワークの失敗、ユーザーの途中キャンセルで何が起きるかを考えます。画面の変更はスクリーンショットだけで判断せず、ピンとこなければ手元やステージングで動かします。

設計

その処理が置かれるべき場所に置かれているか、既存の仕組みと二重になっていないかを見ます。将来使うかもしれない拡張のための抽象化は、今の問題を解く範囲に戻すよう提案します。設計の問題は後から直すほど高くつくので、見つけたら他の細かい指摘より先にコメントします。

可読性・命名

コードを読んですぐに理解できないなら、それは複雑すぎるというのが Google ガイドの基準です。名前が役割を表しているか、1 つの関数が複数のことをしていないか、コメントがコードの「何」ではなく「なぜ」を説明しているかを確かめます。5 年後に自分が保守できるかを判断の目安にする考え方もあります。

セキュリティ

権限チェックがフロントエンドだけでなくサーバー側にもあるか、ユーザー入力をそのまま SQL や HTML に埋め込んでいないか、API キーやトークンを直書きしていないか、ログに個人情報が出ていないかを確認します。マルチテナントのサービスでは、すべてのクエリがテナントで絞り込まれているかが重要です。

信頼性

正常に動くだけでなく、失敗したときに安全に止まるかを見ます。例外を握りつぶしていないか、リトライに回数と待ち時間の上限があるか、同じリクエストが二重に届いても壊れないか、複数の更新がトランザクションでまとまっているかを確かめます。

パフォーマンス

開発環境の数件のデータではなく、本番のデータ量で動かしたときを想像します。N+1 クエリ、ループの中での API 呼び出しや重い計算、全件読み込みが典型的な見落としです。

テストと運用

テストがあるかだけでなく、コードが壊れたときに本当に失敗するテストかを見ます。マイグレーションは稼働中の古いコードと共存できるか、戻せるかを確認し、ビルドやリリースの手順が変わるならドキュメントも更新されているかを見ます。

そのまま使えるコードレビューチェックリスト

Markdown のチェックボックス形式なので、プルリクエストテンプレートや社内の Wiki にそのまま貼れます。チームのスタックに合わない項目は消し、よく出る指摘を足して育てていきます。

## 仕様・機能
- [ ] 説明文や Issue の要件どおりに動く
- [ ] 異常系（空・null・0・上限超え・タイムアウト）を扱っている
- [ ] 画面の変更は実際に動かして確認した

## 設計
- [ ] 変更がこの場所・この層に置かれるべきものである
- [ ] 今必要なものだけを実装している（推測で汎用化していない）
- [ ] 既存の仕組みや共通処理を再利用している

## 可読性・命名
- [ ] 名前だけで役割がわかる
- [ ] 1 つの関数が 1 つのことをしている
- [ ] コメントは「なぜ」を説明している

## セキュリティ
- [ ] 権限チェックをサーバー側でもしている
- [ ] 入力をクエリや HTML にそのまま埋め込んでいない
- [ ] API キーやパスワードを直書きしていない
- [ ] ログに個人情報を出していない

## 信頼性
- [ ] 例外を握りつぶしていない
- [ ] リトライやタイムアウトに上限がある
- [ ] 同時実行や二重送信で壊れない
- [ ] DB の更新はトランザクションでまとまっている

## パフォーマンス
- [ ] 本番のデータ量で遅くならない
- [ ] N+1 クエリがない
- [ ] ループの中で重い処理を繰り返していない

## テスト
- [ ] 変更した振る舞いにテストがある
- [ ] コードが壊れたらテストが失敗する
- [ ] バグ修正には再発防止のテストがある

## 運用・ドキュメント
- [ ] マイグレーションは後方互換で、戻せる
- [ ] 設定値や環境変数の追加を README などに書いた
- [ ] ビルドやリリース手順の変更をドキュメントに反映した

項目が多すぎると誰も読まなくなります。全部を毎回確認するのではなく、変更の種類に関係する分野だけを見る使い方が現実的です。

コードレビューのやり方：6 つの手順

1. 説明文で目的をつかむ。プルリクエストの説明文と関連する Issue を読み、何のための変更か、そもそもこの変更が必要かを確かめます。
2. 主要な変更から読む。ロジックの中心になるファイルを先に読み、設計に大きな問題があればその時点でコメントします。
3. 残りを順に読む。テストを先に読んで意図をつかみ、残りのファイルを漏れなく読みます。
4. 観点リストで抜けを確認する。セキュリティやエラー処理など、読み流しやすい観点をチェックリストで確認します。
5. 温度感を付けてコメントする。必須の指摘と任意の提案を区別し、理由を添えてコメントします。
6. 承認するか判断する。完璧でなくても、コード全体の健全性が上がる変更なら承認します。

最初に説明文を読むのは、変更そのものが不要なケースを早く見つけるためです。その場合は理由と代わりの案を添えて丁寧に伝えます。主要なファイルで設計の大きな問題が見つかったら、残りを読む前にコメントすると、作成者が問題のある設計の上に作業を積み重ねずに済みます。

レビューの速さも品質の一部です。Google のガイドは、依頼への返信までの最長時間を 1 営業日としています。急ぎでない細かい指摘が残っているだけなら、コメント付きで承認して後で直してもらう方法もあります。

指摘の温度感を伝える

必須の修正と好みの提案が同じ書き方だと、作成者はすべて直そうとして時間を使います。[MUST]、[IMO]、[nits] のようなプレフィックスで温度感を示すのが日本のチームでよく使われる方法です。使い方は コードレビューの nits・IMO・LGTM の意味と使い方にまとめました。

レビューしやすいプルリクエストを出す

レビューの質は依頼する側の準備でも変わります。変更を小さく分け、説明文に目的、変更点、確認方法、特に見てほしい箇所を書きます。読みにくいプルリクエストは、分割や説明の追加を頼んでからレビューするほうが結果的に早く終わります。

観点をチームのルールにする

チェックリストは作っただけでは定着しません。何度も出る指摘は、レビューのたびに人が思い出すのではなく、リポジトリに書いて自動で確認される形にします。役割で置き場所を分けると整理しやすくなります。

• リンター・CI： フォーマット、import の順番、未使用の変数など、機械的に判定できるもの。
• AGENTS.md： コーディング規約。コーディングエージェントも同じ規約に従います。
• REVIEW.md： レビューでだけ意味を持つ観点。何を確認し、何を見なくてよく、どの問題をどれくらい深刻に扱うか。
• リポジトリのチェック： 見落とすと影響が大きく、見逃しやすい要件。

REVIEW.md に観点を書く

HeyDeer はリポジトリ直下の REVIEW.md を読み、書かれた観点に沿ってレビューします。一般的なレビューの観点はすでに適用されるので、書くのはそのリポジトリ固有のことだけです。深刻度は HeyDeer の 4 段階（緊急・高・中・低）で指定できます。

# レビューの観点

## 必ず確認する
- ログにメールアドレス、アカウント ID、リクエスト本文を出さない。
- src/api/public/ に追加したエンドポイントは openapi.yaml に載せる。

## 見なくてよい
- フォーマットと lint の問題。CI で検出している。
- tests/fixtures/ のコードは意図的に本番のルールを破っている。

## 深刻度
- 後方互換でないマイグレーションは「高」。
- 命名やリファクタリングの提案は「低」。

ディレクトリごとに src/payments/REVIEW.md のようなファイルを置くと、そのディレクトリ以下の変更にだけ追加の観点が効きます。HeyDeer は REVIEW.md をプルリクエストから読むので、観点を追加するプルリクエスト自体でその効果を確かめられます。詳しくは REVIEW.md のドキュメントを参照してください。

重要な観点はリポジトリのチェックにする

「API ハンドラーのクエリは必ずワークスペースで絞り込む」のように、見落とすと事故になる要件は .agents/checks/ に Markdown ファイルとして書きます。フロントマターの files で対象ファイルを指定し、本文に何が違反で何が合格か、なぜ重要かを書きます。

---
files:
  - "src/api/**/*.ts"
  - "!**/*.test.ts"
---
# API ハンドラーは呼び出し元のワークスペースで絞り込む

workspace_id カラムを持つテーブルを読み書きするクエリは、
requireWorkspace() が返すワークスペースで絞り込むこと。
絞り込みがないと、ある顧客が別の顧客のデータを読めてしまう。

絞り込みのないクエリがあれば不合格。
すべてのクエリが絞り込まれていれば合格。

対象ファイルを変更するプルリクエストでは、チェックごとに専任のレビュアーが付いて要件を確認し、違反があればどのチェックに反したかを示して指摘します。「クエリは安全に」のような一般論ではなく、そのコードベースに固有の条件として書くのがコツです。ダッシュボードの「はじめに」から「リポジトリのチェックを設定」を選ぶと、HeyDeer がリポジトリと過去のプルリクエストを読んでチェックを書き、プルリクエストを開きます。書き方は リポジトリのチェックのドキュメントにあります。

レビューの観点は置き場所で効き方が変わります。機械的に判定できるものはリンターと CI、コーディング規約は AGENTS.md、レビューでだけ使う観点は REVIEW.md、見落とすと事故になる要件はリポジトリのチェックに書くと、人のレビューは設計や仕様の判断に集中できます。

AI レビューと人のレビューの分担

AI コードレビューは、セキュリティ、異常系、N+1 クエリのように、決まった観点を毎回同じ密度で確認する作業が得意です。一方、その変更がそもそも必要か、ユーザーにとって正しい仕様かといった判断は、背景を知る人のほうが確実です。

コーディングエージェントが書くコードが増えると、レビューに回ってくる量も増えます。観点を REVIEW.md とチェックに書いておけば、AI レビューが一次レビューでチェックリストの大半を確認し、人は設計と仕様に時間を使えます。AI レビューの仕組みと限界は AI コードレビューの仕組み、HeyDeer がルールをどう適用するかは コードレビューのルールで紹介しています。

参考資料

1. google-eng-practices-ja: コードレビューの観点
2. google-eng-practices-ja: CL の見方
3. google-eng-practices-ja: コードレビューのスピード
4. google-eng-practices-ja: コードレビューの基準
5. レバテックLAB: 伊藤淳一が考える「コードレビューの観点とアプローチ」