| name | google-code-review |
| description | Google のコードレビュー基準でコードをレビューする。設計・機能・複雑さ・テスト・命名・コメント・スタイル・一貫性・ドキュメント・全行確認の10観点を網羅し、「完璧でなくてもコードの健全性を確実に向上させるなら承認に傾ける」という判断基準で承認可否を示し、建設的で敬意あるコメント作法（Nit:/Optional:/FYI ラベル、コードについて述べ作成者を責めない）に従う。「レビューして」「このdiff/PR/CLを見て」「コードレビュー」「マージしていい？」「承認していい？」「変更内容を確認して」と言われたとき、また diff・PR・コミットの良し悪しを判断したいときに使う。Google と明示されなくても、単なるバグ探しではなく観点を網羅した原則ベースのレビューや建設的なフィードバックがほしい場面で積極的に使う。review the diff / review this PR / code review のような英語の依頼でも同様に使う。 |
Google コードレビュー基準
このスキルは、Google のエンジニアリングプラクティスに基づくコードレビューの「観点・判断基準・コメント作法」を提供する。
単にバグを探すのではなく、コードの健全性を時間とともに向上させることを目的としたレビューを行うためのものである。
詳細な原典は references/ 配下に日本語訳で同梱している。本ファイルは要約とワークフローを示し、判断に迷ったら該当の参照ファイルを読むこと。
最上位の原則
レビュアーは、CL（変更）がシステム全体のコードの健全性を確実に向上させる状態に達したら、たとえ完璧でなくても承認に傾けるべきである。
これがすべての判断の起点になる。完璧なコードは存在しない。あるのはより良いコードだけである。
求めるのは完璧ではなく継続的な改善であり、保守性・可読性・理解しやすさを向上させる変更を、些細な不満のために何日も止めてはならない。
ただし、システムのコードの健全性を確実に悪化させる変更を通してはならない（緊急事態を除く）。
判断基準の詳細・原則・対立の解消は references/standard.md を読むこと。
レビューのワークフロー
- 変更を把握する — 何を解決する変更かを理解する。差分が大きい場合の読み進め方は
references/navigate.md を参照する。
- 観点で見る — 下記10観点を順に確認する。詳細は
references/looking-for.md。
- 承認可否を判断する — 最上位の原則と
references/standard.md の原則に照らして、承認・条件付き承認・要修正のいずれかを決める。
- コメントを書く — 下記のコメント作法に従い、重要度ラベルを付けて指摘する。
参照ファイルの読み方
小さな単一 diff で対立もない通常のレビューは、この SKILL.md 本体だけで完結してよい。判断の根拠が必要なときだけ、下表に従って該当ファイルを読む。読みすぎ・読み不足の両方を避けるための指針である。
| 参照 | 読む状況 |
|---|
references/standard.md | コア参照。承認可否・原則の適用・対立解消の根拠が必要なとき |
references/looking-for.md | コア参照。観点ごとの具体例・判断根拠が必要なとき |
references/comments.md | コア参照。コメントの言い回しや重要度ラベルの選び方に迷うとき |
references/navigate.md | 状況限定。差分が大きく、どこから読むか困るときのみ |
references/speed.md | 状況限定。レビューの優先度や応答速度（原則1営業日以内）を判断するときのみ |
references/pushback.md | 状況限定。作成者と意見が対立し、解消の進め方が必要なときのみ |
何を見るか（10観点）
各観点で問うべきことの要約。網羅的な解説と例は references/looking-for.md にある。
- 設計 — コード同士の相互作用は理にかなっているか。この変更はこのコードベース／ライブラリに属すべきか。今入れるべきタイミングか。
- 機能性 — 作成者の意図どおり動くか。その意図は利用者（エンドユーザー・将来の開発者）にとって良いか。エッジケース・並行処理の問題はないか。
- 複雑さ — 必要以上に複雑でないか。オーバーエンジニアリング（今不要な汎用化・将来の推測に基づく機能）はないか。
- テスト — 変更に応じたユニット／結合／E2E テストがあるか。テストは正しく、壊れたときに失敗し、誤検出を出さないか。
- 命名 — 対象が何であり何をするかを十分伝え、かつ冗長でない名前か。
- コメント — なぜ存在するかを説明しているか（何をするかではなく）。本当に必要なコメントか。
- スタイル — スタイルガイドに従っているか。ガイド外の好みは
Nit: を付ける。大きな再フォーマットは別 CL に分けてもらう。
- 一貫性 — 既存コードと一貫しているか。スタイルガイドが絶対的権威で、それ以外は既存に合わせる。
- ドキュメント — ビルド・テスト・操作手順などの関連ドキュメントも更新されたか。
- 全行を見る — 自分が理解できる範囲は1行ずつ目を通したか。データファイルや自動生成物は流し読みでよいが、人が書いたコードは確認する。理解できないコードは作成者に説明を求める。
加えて、良い点も指摘する（文脈の把握・優れた設計判断・きれいな解法など）。
承認可否の判断
- 技術的な事実とデータは、意見や個人的な好みに優先する。
- ソフトウェア設計は単なる好みではなく、原則に基づいて判断する。複数の手法が同等に妥当だと作成者が示せるなら、作成者の選好を受け入れる。
- それ以外で規則が当てはまらない場合は、既存コードベースとの一貫性を求めてよい。
- 改善提案はいつでも自由に残してよいが、重要でないものは重要度ラベルを付けて作成者の判断に委ねる。
対立が解消しない場合の進め方（合意形成 → 対面議論 → エスカレーション）は references/standard.md と references/pushback.md を参照する。作成者とレビュアーが合意できないからといって変更を放置してはならない。
コメントの書き方
references/comments.md の作法に従う。要点は4つ。
- 親切であること — コメントは常にコードについて述べ、作成者については述べない。対立を招きうる指摘では必ずこの形にする。
- 悪い例: 「なぜあなたはここでスレッドを使ったのか？」
- 良い例: 「ここの並行性モデルは、パフォーマンス上の利点がないまま複雑さを加えているように見える。利点がないなら、シングルスレッドにするのが良い。」
- 理由を説明する — なぜその指摘をするのか、どうコードの健全性が改善するのかを添える。
- 指摘と指示のバランスを取る — 直すのは作成者の責任。問題を指摘して判断を委ねるほうが学びになり、より良い解決につながることも多い。ただし直接的な提案やコード例が役立つ場面もある。
- 複雑さは説明させるのではなく単純化させる — 理解できないコードは、説明を求めるのではなくコードの単純化かコード内コメントの追加に向かわせる。レビューツール上だけの説明は将来の読み手に残らない。
重要度ラベル
必須の変更と提案を区別するため、コメントの重要度を示す。ラベルがないと作成者はすべてを必須と受け取りやすい。
Nit: — 些細な磨き上げ。対応は任意で、無視してよい。Optional:（または Consider:） — 良い案だと思うが必須ではない。FYI: — この変更で対応してほしいわけではないが、今後のために共有する。
出力フォーマット
レビュー結果は次の構造で示す。指摘には必ず重要度ラベルを付け、可能な箇所にファイルパスと行番号を添える。
## 総評
（承認に傾けられる状態か／要修正か。最上位の原則に照らした全体判断を1〜3行で。
「承認可否」「マージしてよいか」「LGTM か」はすべて同じ判断を指す）
## 指摘事項
- [必須] path/to/file.ext:42 — 問題の内容と、なぜ直すべきかの理由
- [Optional] path/to/file.ext:88 — 提案と理由
- [Nit] path/to/file.ext:120 — 些細な磨き上げ
- [FYI] path/to/file.ext:64 — 今回の対応は求めないが共有したい点
## 良い点
- 補強したい良い判断・実装（理由を添える）
ラベル
重要度ラベルは「コメントの書き方」の Nit / Optional / FYI に加え、対応が必須の指摘には 必須 を使う。
1件もないラベルの行は省略してよい（例: 必須指摘がなければ [必須] 行は出さない）。
行番号の付け方
- 変更後（new file 側）の行番号を基準にする。新規ファイルの diff（
@@ -0,0 +N,M @@）では、追加行のファイル内行番号（1始まり）を使う。
- テスト不在・ファイルやディレクトリの未作成のように、対応する行が存在しない「欠落」の指摘は、行番号を擬製せず
path/to/file（テスト不在） のように対象を明示する。
- 関数やファイル全体に及ぶ構造的な指摘は、最も関連の深い行に紐づけ、本文で範囲を補足する。
指摘が多い場合は観点ごとにまとめると作成者が対応しやすい。
