Google が公開してるGoogle Engineering Practices Documentation。これは Google 社内のコードレビュー基準を一般公開したドキュメント群で、CL を書く側と、レビューする側の両方の作法がまとまってる
CL（changelist）っていうのは Google 社内語で、要するに GitHub でいう PR のことだね
良いドキュメントを見つけたら「紹介する」より「AI の参照辞書に組み込む」方が資産になる。読むのは一回やけど、スキルにすれば毎回効く
X で毎日 Claude Code 情報を配信してるコムテです。Claude Code 実践テクニックを配信しています
完成したスキルの中身を全部置いとく
スキルのディレクトリ構成。SKILL.md と、Google の原文を丸ごと同梱した references/ の2階建てや
distill は作らず、Google の原文をそっくりそのまま references/eng-practices-master/ に置いてるだけ。で、入口の SKILL.md がこれ。そのままコピペで動くよ
肝はステップ3のセルフレビュー10項目で、各項目に「迷ったらこの原文を読め」のポインタを添えてること。チェックリストで当たりをつけて、迷ったら原文1枚で深掘りする二段構えやな。全ファイルを一度に読ませないから、コンテキストも食わない
同じものを作る手順
そのまま真似できるように手順を置いとく
- eng-practices のリポジトリを丸ごと落として、スキルの references/ 配下に置く。LICENSE も一緒に置いて CC BY 3.0 の帰属表示にする
- SKILL.md のワークフローを4ステップで組む。変更を小さく分ける → 説明文を書く → submit 前セルフレビュー → 結果提示
- 上の10項目チェックリストを SKILL.md に inline で書く
- 各ステップに「迷ったらこの原文1ファイル」のポインタを添える。全ファイルを一度に読ませない、が肝
- CL = PR の用語読み替え表を入れて、Google 社内語が出力に漏れんようにする
あとは「自分の git diff を eng-practices の基準でセルフレビューして」って言うだけ。コピペで自分のリポジトリの .claude/skills/ に置けば、そのまま動く
スキルの設計
ここからは、なんでこの形に落ち着いたかの話。Claude Code のスキルは SKILL.md っていう入口ファイルと、references/ 配下の知識ファイルで構成できる。ここで自分が最初に決めた設計方針はこれ
- instructions（手順）は薄く SKILL.md に inline で書く
- knowledge（厚い知識）は外部ファイルに出して、必要なときだけ読ませる
なんでこう分けるかというと、SKILL.md は発動するたびに毎回読み込まれるからやな。ここに全知識を詰めるとコンテキストを食いまくる
一方で判断の根拠になる詳細な基準は、毎回いらん。迷ったときだけ該当する1枚を開けばいい。つまり「いつもの薄い手順」と「困ったときの厚い辞書」を物理的に分ける、って感じです
eng-practices の review/ 配下はこういう構成になってる
書く側（developer）が3枚、見る側（reviewer）が6枚、それと全体に効く emergencies.md。役割がきれいに割れてるから、スキルの各ステップから「この判断なら small-cls.md を読め」って指し示しやすい。設計としては仕込みやすい素材だった
最初の失敗
ここで自分は欲を出した。原文は全部英語やし、せっかくなら日本語に要約（distill）して、読みやすい知識ファイルに作り直そうと思ったわけ。各ファイルの要点を抜き出して、日本語のチェックリストにまとめ直す作業をやった
これが盛大に失敗
要約版を後から原文と突き合わせたら、reviewer/ の6ファイルのうち、pushback.md と speed.md を丸ごと落としてた。レビュアーが反論を受けたときの対処と、レビューの速さの話が、要約の過程でまるっと消えてた
さらにマズかったのが comments.md で、これは指摘コメントの書き方を扱うファイルなんやけど、自分は原文をちゃんと読まずに「コメントの書き方ってこんな感じやろ」っていう一般知識で書いてた。当然、原文の主張からズレる
要約は必ずドリフトする。元の文書から何が落ちて何が歪んだか、要約した本人ですら把握できない。AI に渡す知識を人間が（あるいは AI が）要約した時点で、原文との乖離が静かに入り込む
方針転換
そこで結論をひっくり返した。反直感的やけど、こうした
要約するな。原文を丸ごと積んで、必要な1ファイルだけを on-demand で読ませろ
日本語に作り直した distill 版は削除した。代わりに eng-practices のリポジトリを references/ 配下にそのまま同梱して、SKILL.md には「判断に迷ったら該当する原文1ファイルだけを読め。全ファイルを一度に読むな」と書いた
この設計の良いところは、知識が劣化しないこと。AI が読むのは Google が書いた原文そのものやから、要約によるドリフトが原理的に起きん。コンテキスト効率も悪くならない
なぜなら全部を読ませるんやなくて、その判断に必要な1枚だけをピンポイントで開かせるから。「薄い入口 + 厚い辞書」の方針はそのままに、辞書の中身を自作要約から原文に差し替えただけ、って整理やな
OSS を同梱するときは license を守る必要がある。eng-practices は CC BY 3.0（表示すれば再配布・改変 OK のクリエイティブコモンズライセンス）やったので、リポジトリの LICENSE ファイルもそのまま references/ に同梱して、SKILL.md にも出典と CC BY 3.0 を明記した。冒頭で見せた CL = PR の用語読み替え表も、社内語が出力に漏れて読み手が混乱せんように入れたやつやな
テストしてみた
実際の diff を流して、AI がちゃんとアラを出すか試した。Python と TypeScript の壊れた diff を用意して、submit 前セルフレビューを回した
結果、AI が自分でアラを3つ出してきた。しかも blocking（直すまで submit すべきでない）と nit（任意の磨き）を分けて報告してきたのが良かった
1. 空の catch によるサイレント障害（Python）
カートの送料計算まわりの diff やった。だいたいこんな感じのコード
AI の指摘はこう。「except で握りつぶしてるので、fetch_rate が失敗したときに rate が未定義になり、後続で参照してクラッシュする。さらに失敗がログにも出ないからサイレント障害になる。これは blocking」。例外パスを頭の中で一度通せ、っていう eng-practices の looking-for.md の観点が効いてる
2. null 未チェックのクラッシュ（TypeScript）
ユーザー作成の createUser まわり。ざっくりこんなノリ
指摘は「profile が optional なのに null チェックなしで displayName を辿ってる。profile が無いリクエストでランタイムクラッシュする。これも blocking」。エッジケースを通せ、の観点やな
3. 関心事の混在 = CL を分割すべき
3つ目はバグやなくて構成の問題。1つの diff に機能追加とリファクタリングが混ざってた。AI は「これは small-cls.md の観点で、リファクタと機能変更は別 PR に分けるべき。レビュアーが何を見ればいいか分からなくなる。blocking」と判断した
そして最後に、AI 自身がこう締めた。「blocking が3件残ってるので submit すべきでない」。レビュー基準を食わせた AI が、自分の書いたコードを見て自分で submit を止めた
nit と blocking を AI が自分で振り分けて「完璧は求めないが、これは直すまで出すな」と判断する。レビュー基準を渡すと、AI のセルフレビューが「指摘の羅列」から「出荷判断」に進化する
横展開
ここで気づいたことがある。eng-practices のレビュー哲学って、よく見ると2層に分解できる
- 哲学（領域非依存）nit と blocking の規律 / 全体から読んで致命傷を先に見る / 完璧を求めない
- 観点（領域固有）空 catch・null・テストの有無みたいなコード特有のチェックリスト
哲学の方はコードに限った話やない。文章レビューにもそのまま効く。「全体の論旨を先に見て、致命的に崩れてたらそこで止める」「直すまで出すべきでない指摘と、任意の磨きを分ける」「完璧を求めず、全体の質を確実に上げる状態なら publish する」。これ、記事のセルフレビューでも全く同じことが言える
なので、同じ型からコード固有の観点だけを外して、文章レビュー用のスキル（writing-review）も作った。哲学の根拠になる原文は standard.md / navigate.md / comments.md / pushback.md の4枚だけ references/ に切り出して同梱した（コード特有の looking-for.md や small-cls.md は外した）
CL = 記事 or ポスト、code health = 記事全体の質、submit = publish、っていう読み替えを足せば、izanami 記事や X ポストを publish 前にレビューするスキルになる
レビューは「哲学（領域非依存）」と「観点（領域固有）」に分解できる。哲学を残して観点を差し替えれば、コードレビューのスキルが文章レビューのスキルに転用できる。writing-review がその証拠だね
まとめ
今日やったことを整理するとこうなる
- Google の eng-practices をスキルに食わせた
- 最初は日本語に要約したが、原文からドリフトして失敗した
- 要約をやめて、リポジトリを丸ごと同梱し、必要な1ファイルだけ on-demand で読ませる設計に変えた
- 実 diff を流したら、AI が空 catch・null クラッシュ・CL 分割を blocking として自分で出し、submit を止めた
- 同じ型から観点を差し替えて、文章レビュー用スキルも作れた
一番言いたいのは、AI に渡すレビュー基準は自分で選んで丸ごと渡せる時代になった、ってこと。汎用の AI は「それっぽい」レビューはしてくれるけど、どの基準で見るかは曖昧やった。そこに Google の基準を原文のまま積めば、AI のレビューがその基準で揃う。要約して劣化させるより、信頼できる原文を選んで丸ごと食わせる方が強い
出典は google/eng-practices（CC BY 3.0）。良いレビュー基準を持ってる人は、それを AI の辞書にしてみると地味に効く
