レビューアーが作る観点リストの構成・配布・改善サイクル
レビューアーが作る観点リストの構成・配布・改善サイクル
コードレビューにおいて「レビュー観点がぶれる」「人によってコメントの質に差がある」といった課題は非常に多くの現場で起きています。
その解決策の一つが「観点リスト」の導入です。
しかし、観点リストは作るだけでは機能しません。
構成・配布・改善のサイクルが回ってはじめて、チーム全体にレビュー力が定着します。
このマニュアルでは、レビューアーが主体となって観点リストを構築・展開・改善していく方法を、実務に即した視点で解説します。
観点リストとは何か？その目的は何か？
観点リストとは
コードレビュー時に確認すべきポイント（責務、可読性、拡張性、安全性など）を網羅的かつ構造的に列挙した一覧表。
レビュアーが「何を見落としてはならないか」「どこに注目するべきか」を明示する道具です。
観点リストは、単なるチェックリストではありません。
- 知見の蓄積
- レビュー設計の共通化
- 再現可能な判断基準
という3つの役割を持ちます。
なぜ観点リストが必要なのか？
レビュー観点の属人化を防ぐ
- 「そのレビューは○○さんだから気づいた」という状態では再現性がない
- チームで判断軸を共有することで教育と標準化が同時に実現する
コメント品質を構造化できる
- 「なんとなく変」ではなく、「責務が集中している」「拡張性がない」など観点に基づいた指摘ができる
フィードバックに対する納得度が高まる
- 開発者も「観点に基づいた指摘」として受け取りやすくなり、防衛的にならない
観点リストの基本構成：3層モデルで設計する
観点リストは以下の3層構造で設計することで、粒度の一貫性と運用の柔軟性を両立できます。
1. 観点カテゴリ（テーマ）
- 例：責務分離、命名、例外処理、状態管理、API設計
2. 具体観点（Whatを定義）
- 例：「関数の責務が1つに絞られているか」「変数名が用途を反映しているか」
3. 確認方法・判断材料（Howを補足）
- 例：「if文のネストレベルが3段以上かどうか」「catchブロックでログが出力されているか」
観点リスト設計の実務パターン
パターン1：チェックリスト形式（評価中心）
■ 例：命名に関する観点
- [ ] 変数名は意味のある単語で構成されているか
- [ ] boolean変数は `is/has/can` など状態を表しているかパターン2：診断形式（問いかけ中心）
■ 例：責務分離に関する観点
- この関数は「1つの責務」に絞られているか？
- 処理のステップが分離可能な状態か？運用設計
- 初学者向けには「チェックリスト形式」
- 中級者以上向けには「診断形式」がおすすめ
チームへの配布・展開方法
観点リストを「属人化されたドキュメント」にしないためには、配布と展開の設計が極めて重要です。
| 手段 | メリット | 運用上の工夫点 |
|---|---|---|
| Notion / Confluence | 柔軟な編集と履歴管理が可能 | カテゴリごとに章立てし、検索性を意識する |
| GitHub Wiki | レポジトリに近く、習慣的に見やすい | PR単位で改善のトリガーを設定すると有効 |
| Markdownファイル | 軽量で扱いやすい | リポジトリ直下や /docs 配下に配置 |
| CIチェック連携（Lintルール含む） | 自動化と併用可能 | 観点リストのうち形式的チェックを抽出 |
配布後の失敗例とその処方箋
| 失敗パターン | 問題点 | 改善案 |
|---|---|---|
| 「見るだけ」のドキュメント化 | 読まれない・更新されない | PRテンプレートやレビューガイドとリンクさせる |
| 抽象語の羅列 | 「読めるが使えない」状態 | 実例・NG例・補足を併記 |
| 範囲が広すぎる | 結局「全部見る」になってしまう | 役割別・技術レイヤ別に分離する |
| 誰が直すか不明 | 責任が曖昧になり腐る | メンテナ担当 or 改善サイクルルールを定義 |
改善サイクルの設計と回し方
観点リストは静的なチェックリストではなく、動的に育てるガイドです。
継続改善のサイクル設計
トリガーイベントの設定例
- 月次レビュー振り返り会で1件は観点を見直す
- NGコードが検出されたら再発防止策として観点を1件追加
- 初学者からの質問があれば、その観点を「表現強化」
実務で使用される観点カテゴリ例（参考）
| カテゴリ | 説明 |
|---|---|
| 命名規則 | 可読性・検索性・ドメイン表現力の担保 |
| 責務分離 | 関数・クラスが1つの役割に絞られているか |
| エラー処理 | try-catchの設計、ログ出力有無、フォールバック戦略 |
| 可変性 | 状態の変更箇所が明示的か、バグリスクはないか |
| テスト観点 | 境界値、異常系、網羅性、意図テストかどうか |
| セキュリティ | データ検証、CSRF/XSS対策、認可設計の妥当性 |
コードレビュー中に観点リストを活用する方法
1. PRテンプレートに観点セクションを設ける
.github/PULL_REQUEST_TEMPLATE.md
## チェック観点
- [ ] 命名がドメインを反映している
- [ ] 責務が単一で分離されている
- [ ] 例外時の動作が明確である2. コメントに観点を明示して使う
Comment
@Reviewer: このロジックは「責務分離」の観点で見たときに、条件分岐とリソース操作が混在しているように感じました。関数の分割をご検討いただけますか。まとめ：観点リストをレビュー文化の中心に据える
- 観点リストはレビュー品質の「共通語」である
- 3層構造（カテゴリ→具体→判断材料）で設計する
- ドキュメントではなく「使われるツール」に昇華させる
- 運用は静的でなく動的に。改善サイクルが生きてこそ意味がある
観点リストは「守るべきルール」ではなく、「レビューという設計行為のための道具」です。
レビューアー自身が設計し、育て、展開する文化が、チームの設計力を底上げしていきます。