Claude Code に質の高いPRを書かせたい — まず Google Engineering Practices で予習する

最近、プルリクエストの粒度と説明文に困っている。実装を進めると、一つのコミットに機能追加もリファクタリングも設定変更も混ざって差分がふくらみ、説明文は後回しで薄くなる。自分で書いてもそうだし、Claude Code に任せても変更をまとめて一気に出してくる。レビューする側からすると、大きいPRも中身の薄い説明も等しくつらい。

これを気合いではなく仕組みで直したい。まず自分の Claude Code 運用に、ゆくゆくはチームのレビュー文化として、ちゃんとした規範を一本通したい。その教科書に選んだのが Google が公開している Google Engineering Practices のコードレビューガイドだ。「なんとなく小さく書こう」では定着しないので、まずガイド全体を一度見渡し、Claude Code と会社のPR運用に役立ちそうな章を深掘りする。この記事は導入を決める前の予習メモになる。

まず全体像：2つのガイドと緊急時の例外

Google Engineering Practices のコードレビュー部分は、立場の違う2つのガイドと、その外側の例外規定でできている。まず全体を一覧にしておく。

レビューする側：How To Do A Code Review（コードレビューの進め方）

章	何の話か
レビューの基準（The Standard of Code Review）	どこまで良ければ承認するか
何を見るか（What to look for）	設計・機能性・複雑性など10観点
CLの読み進め方（Navigating a CL）	どの順でファイルを見るか
レビューの速度（Speed of Code Reviews）	いつまでに返すか
コメントの書き方（Writing comments）	指摘をどう言葉にするか
反発への対処（Handling pushback）	著者が抵抗したとき

書く側：The CL Author’s Guide（変更を出す側のガイド）

章	何の話か
良いCL説明文（Good CL descriptions）	コミットメッセージの型
小さいCL（Small CLs）	1つの変更をどこまで小さく刻むか
レビューコメントへの対処（Handling comments）	指摘を受けたときの作法

その外側：緊急時（Emergencies） — 上の基準を一部緩めてよい例外と、その線引き。

CL（Changelist）は Google 社内でのプルリクエスト相当の単位だと思えばいい。ここから、気になった章を順に見ていく。

書く側①：小さいCL

いまの自分のPRが一番崩れているのがここなので、最初に読んだ。

ガイドは「単一の自己完結した変更を1つだけ実装するサイズ」をCLの基本とする。目安は100行が妥当、1000行は大きすぎる、行数だけでなくファイル数も込みで判断する。なぜそこまで小さくこだわるのか、理由がそろっている。

レビュアーは5分を数回割くほうが、30分まとめて確保するより楽
変更箇所が限定されていれば、影響範囲を追いやすくバグを見落としにくい
却下されたときの手戻りが小さく、マージ競合も減り、設計の見直しもしやすい

逆に、一つのCLに無関係な変更（ついでのリネーム、フォーマット直し、設定変更）を混ぜるのが典型的な悪手とされる。レビュアーは「大きすぎる」という理由だけでCLを突き返してよい。突き返されたら分割し直す手間が丸ごと無駄になる。

例外として大きくてよいのは、ファイル丸ごと削除（実質1行扱い）や、信頼できる自動リファクタリングツールが生成した変更くらい、と限定されている。

Claude Code は放っておくと、一つのタスクで触れた範囲を全部まとめて一気にコミットしようとする。だからここはAIへの最初の指示として渡す価値が大きい。

書く側②：説明文は「要約行は命令形、本文は理由」

説明文の型はシンプルだ。

要約行（1行目） は3つのルールに従う。

何が変わるかを具体的に要約し、それだけ読めば中身が伝わること
「〜を削除する」「〜を追加する」のように命令形で書く
要約行のあとに空行を1つ入れる

ガイドが挙げる良い例は「FizzBuzz RPC を削除し、新システムに置き換える」（Delete the FizzBuzz RPC and replace it with the new system.）のような形。逆に「バグ修正」（Fix bug）、「ビルド修正」（Fix build）、「パッチ追加」（Add patch）といった具体性のない一行は、悪い例として名指しされている。急いで書くと人でもAIでもここに落ちる。何も指示しなければ出てくる「Fix bug」は、ガイド的にはアウトの典型だ。

本文に書くのは、コードを見れば分かる「何をしたか」ではなく、コードからは読み取れない情報。

解決しようとしている問題
なぜこのアプローチを選んだのか
そのアプローチの限界や欠点
関連するバグ番号やベンチマーク結果

「なぜこの実装にしたか」は、まさにAIが頭の中では持っているのに出力では捨ててしまう情報だ。これを説明文に必ず残させれば、PRが「読んで意図が分かるもの」に近づくはずだ。

書く側③：レビューコメントへの対処

書く側のガイドには、指摘を受けたときの作法もある。怒りに任せて返信しない。レビュアーが理解できないなら、まずコード自体を分かりやすくする（コメントで言い訳するより、次の読み手のためにコードを直すほうが価値が高い）。納得できない指摘は対立的にならず、技術的な理由を添えて議論する。分からなければ説明を求める。

これはAIにレビューを受けさせる構成でもそのまま使える。指摘されたとき長文の弁明を返させるより、「コードにコメントを足して読み手に分かるようにする」ほうがガイドの方針に沿う。

レビューする側①：基準は「完璧」ではなく「前より良くなっているか」

ここから読む側のガイド。一番の軸が The Standard of Code Review（レビューの基準）だ。

レビュアーは完璧を待つのではなく、そのCLが全体としてコードの健全性を確実に改善している状態になったら承認すべき、とする。完璧なコードは存在せず、あるのは「より良いコード」だけ。だから細かい完璧主義でPRを止めない。

意見が割れたときの裁き方も明快だ。設計の良し悪しは個人の好みではなく原則やデータで判断する。著者が「複数のやり方が工学的に等価だ」と根拠を示せたら、レビュアーは著者の選択を受け入れる。必須ではない細かい指摘には「Nit:」と前置きして、対応するかは著者に委ねる。レビューは品質チェックであると同時にメンタリングの場でもある、という位置づけだ。

レビューする側②：何を見るか（設計が最優先）

見るべき観点は10項目に整理されている。並び順に意味がある。

設計（最優先）：この変更がシステム全体にうまく収まっているか。そもそも今このタイミングで入れるべきか
機能性：意図どおり動き、ユーザーにとって妥当か。UI変更や並行処理は特に慎重に
複雑性：「複雑すぎる」とは「読み手がすぐ理解できない」こと。最大の落とし穴は過剰な汎用化で、いま解くべき問題だけを解く。将来必要になりそうだという理由で作り込まない
テスト：適切なテストがあり、実際に壊れたとき検出できるか
命名：変数やメソッドの名前は意図が伝わるか
コメント：「何をしたか」ではなく「なぜそうしたか」。コードに書けない情報を残すのがコメント
スタイル・一貫性：スタイルガイド準拠、既存コードとの一貫性
ドキュメント：関連ドキュメントが更新されているか

そしてすべての行を見る。理解できないコードがあれば著者に説明を求め、分からないまま通さない。良い実装を見つけたら褒めるのもレビュアーの仕事に含まれる。

レビューする側③：CLの読み進め方

大きめのCLをどの順で読むか、という実務的な章。

まず全体像 — CLの説明を読み、この変更がそもそも意味を持つか判断する。根本から筋が悪ければ、細部を読む前にその場で代替案を返す
主要部分から — 論理的な変更が最も多いファイルを先に見る。ここで文脈がつかめる。大きな設計問題は早い段階で指摘して、著者の手戻りを減らす
残りを適切な順で — 主要ファイルのあと、ツールが並べる順で残りを見る。テストコードから読むと変更の意図が分かりやすい

「設計の問題は早く言え」が一貫している。終盤まで読んでからちゃぶ台返しをすると、著者の作業が丸ごと無駄になるからだ。

レビューする側④：速度（応答は1営業日以内）

ガイドは個人の速度よりチーム全体の生産性を最適化する立場で、レビューの応答は最大でも1営業日を目安にする。レビューが滞るとチーム全体の開発が遅れ、開発者がレビュー自体を嫌がり、結果としてコード品質も落ちる（「どうせ遅いなら大きくまとめて出そう」となり、また巨大CLに戻る）。

ただし「速度のために基準を妥協しない」とも明記される。速いことと甘いことは違う。早く返すのは応答であって、雑に通すことではない。

レビューする側⑤：コメントの書き方と反発への対処

コメントの作法はシンプルだ。コードについて述べて人を責めない。なぜを説明する。解決策を直接命じるより、問題を指摘して著者に考えさせる。Nit / Optional / FYI などで深刻度を分ける。

反発（Handling pushback）の章は、読んでおくと現場で助かる。著者が抵抗したら、まずその主張がコード健全性の観点で筋が通っているか考える。著者は実装に一番近いので、正しいこともある。一方で、丁寧に書かれた指摘に開発者が本気で腹を立てることはまずない、感情的な反発の多くは指摘の書き方の問題だ、とも言い切っている。

そして**「あとで直す」を許さない**。後で直す約束はだいたい果たされないから、新しい複雑性が入るなら、コードベースに入る前の今、直させる。緊急時を除いて例外を認めない。

例外：緊急時（Emergencies）

最後に、上の基準を緩めてよい唯一の場所。緊急CLとは、進行中の大きなローンチを止めないための修正、本番ユーザーに重大な影響が出ているバグ、法的問題、セキュリティホールへの対応など、小さくて急を要する変更を指す。このときだけレビュアーは速度と正しさを最優先し、通常の網羅的レビューより解決を急ぐ。

面白いのは「何が緊急でないか」を列挙しているところだ。今週中にローンチしたい、長く取り組んだ作業をようやく出せる、金曜の夜までに終わらせたい、上司がソフトな締切を口にした、テスト失敗やビルド破損のロールバック——どれも緊急ではない。本当のハード期限は、契約上の義務や年1回の出荷機会のように「逃すと破滅的なことが起きる」場合だけ。そして緊急で通したCLも、後から通常どおりのレビューにかける。

「急いでる」を言い訳にさせない線引きがはっきりしているので、これはチームのルールとして引用しやすい。

Claude Code と会社にどう落とすか

全体を読んで、導入の順番が見えた。書く側の2点をまず Claude Code に、レビューする側の観点を次にチームに、という二段で入れる。

最初に手を付けるのは、プロジェクトの CLAUDE.md（Claude Code が毎回読む指示ファイル）への規約。下書きはこうなる。

コミット・PRを作るときは Google Engineering Practices の CL Author’s Guide に従う。
1コミット＝1つの自己完結した変更。機能追加・リファクタリング・フォーマット変更は混ぜず別コミットに分ける。差分が大きくなりそうなら分割を提案する。
コミットメッセージの1行目は命令形で、何が変わるかを具体的に。「Fix bug」のような曖昧な要約は禁止。1行目のあとは空行を1つ。
本文には「何をしたか」ではなく「なぜこの変更が必要か」「なぜこのアプローチか」「既知の限界」を書く。関連 issue 番号があれば添える。

レビューする側は、上の10観点と「前より良くなっているか」という基準をレビュー用スキルの評価軸に移す。AIに一次レビューさせるなら、設計→複雑性→テスト→命名…の順で見させ、「Nit:」相当の軽い指摘と必須の指摘を分けて出させる。人間のレビュアーには速度（1営業日）と「あとで直すを許さない」をチームルールとして共有する。

人間のエンジニアが新人に渡す教科書を、そのままAIにも会社にも渡す——という絵だ。まずは自分のプロジェクトで CLAUDE.md に書く側の2点を入れ、コミットの粒度と説明文がどう変わるかを確かめる。そこで手応えがあれば会社のリポジトリに持ち込む。実際に運用した結果は、別記事にする。

参考

この記事は Claude Sonnet 4.6 が執筆しました。