AIコードレビューを仕組み化する技術

「テストを書いてからPRを出してください」

AGENTS.mdにこう書いた。でも、テストなしのPRが出てきた。

「Conventional Commentsのラベルを付けてください」

チームに共有した。1週間後、ラベルを付けているのは自分だけだった。

お願いは忘れられます。ルールは破られます。

でも 仕組み は動き続けます。

---

私はレビュー文化の浸透に何度も失敗しています。

ドキュメントを書いた。読まれなかった。勉強会を開いた。翌週には忘れられた。Slackにリマインドを流した。ミュートされた。

それでも毎週月曜日、「フォーマット直してください」「importの順番変えてください」というレビューコメントを書き続けていました。30分かけて。

やっている側は正しいことをしている気でいた。でも、レビューされる側はどうだったか。

「また指摘された」「また直すのか」。フォーマットの指摘は、受け取る側にとっては純粋なストレスです。設計の議論なら学びがある。でも「インデントが2スペースじゃない」に学びはありません。直すだけ。指摘する側も疲れる。される側も疲れる。

そうやって両方が疲弊した結果、どうなったか。

レビュー自体が放置されるようになりました。

PRが3日開きっぱなし。誰もコメントしない。Approve だけ押してマージ。形だけのレビュー。これが多くのチームの現実です。

転機は、AIレビューツールを導入したときです。

CodeRabbitがフォーマットとリンター違反を全部拾ってくれた瞬間、レビュー欄の景色が変わりました。「インデント直して」の代わりに、「この設計どうする？」「この方向で増やしていいの？」という議論が始まった。

信号機を設置したら、交通整理の警察官が本来の仕事に戻れた。そんな感覚です。

---

本書は、コードレビューを「お願い」から「仕組み」に変える本です。

hooksでリンターを強制する。AIに一次レビューを任せる。人間は設計と方向性に集中する。

やることは明快です。ファイル構成、設定、パイプラインを、コピペできる粒度で解説します。

前提知識として、ハーネスエンジニアリングの基本(AGENTS.md、hooks、フィードバックループ)とコードレビューの基礎を理解していると読みやすいです。

コードレビューはハーネスの心臓部です。心臓が止まれば、全身に影響が出ます。

この続きはKindleで →

ハーネスの6層モデル

ハーネスエンジニアリングは、AIエージェントの動作環境を6つの層で設計します。

コードレビューは ③品質検証層 の中核です。

家に例えると、①が設計図、②が施工手順、③が建築検査。検査なしで建てた家に住みたい人はいません。

品質検証層の3つのサブレイヤー

品質検証層をさらに分解すると、3つのサブレイヤーに分かれます。

サブレイヤー	担当	速度	精度
自動ゲート	hooks / CI	秒単位	機械的な正確さ
AIレビュー	CodeRabbit / Copilot	分単位	パターン認識
人間レビュー	チームメンバー	時間単位	設計判断・方向性

下から上に向かって、速度は遅くなるが、判断の質は上がる。レストランの厨房と同じです。皿洗い機(自動ゲート)が最も速く、スーシェフ(AI)が品質チェックし、ヘッドシェフ(人間)が味の方向性を決める。

「ほぼ毎回」vs「例外なく毎回」

SmartScopeの記事が核心を突いています。

CLAUDE.mdに「リンターを実行せよ」と書くのと、Hookでリンター実行を強制するのは、「ほぼ毎回」と「例外なく毎回」の違い。

「ほぼ毎回」と「例外なく毎回」の間には、見た目以上の溝があります。90%の遵守率は「10回に1回は壊れたコードが通る」ということ。月に100PRあれば10本が検査なしで本番に行きます。

コードレビューでも同じです。

方法	実行率
AGENTS.mdに「テストを書いてからPR」と記載	80-90%
pre-commitフックでテスト実行を強制	100%
AGENTS.mdに「Conventional Commentsを使う」と記載	50-70%
PRテンプレートにラベルのリマインドを記載	70-80%

お願い → テンプレート → フック → CIの順で強制力が上がります。本書では、それぞれのレイヤーで何を強制し、何を任意にするかを設計します。

なぜ全部を強制しないのか

「全部CIで強制すればいいのでは？」と思うかもしれません。しかし、全部を強制すると開発のスピードが著しく落ちます。

セキュリティの世界に「利便性とセキュリティのトレードオフ」があるように、レビューにも「強制力と開発速度のトレードオフ」があります。大切なのは、何を強制し何を推奨に留めるかの線引きです。

本書のアプローチ:

• 強制: フォーマット、リンター、型チェック、テスト → 機械的に判断できるもの
• 推奨: Conventional Commentsのラベル、PRサイズ制限 → 人間の判断が関わるもの

ファイル構成の全体像

本書で構築するハーネスレビューシステムのファイル構成:

次章から、3つのサブレイヤーを順に設計していきます。

この続きはKindleで →

前章で、コードレビューがハーネスの③品質検証層に位置することがわかりました。この章では、その品質検証層を 3つのサブレイヤーに分解 します。これが本書の背骨になる構造です。

3層で役割を分ける

コードレビューの最大の問題は、すべてを人間がやろうとすることです。

スタイルチェック、リンター違反、型エラー、テストの有無、セキュリティ脆弱性、設計判断、方向性の議論。これを1人のレビュアーが1つのPRで全部やると、レビュー疲れが起きて当然です。

3層モデルはこれを分業します。

第1層: 自動ゲート(人間が関与しない)

ここで弾かれるものは、PRにすら到達しません。レビュアーの目に触れる前に解決される。

原則: 機械的に判断できるものは機械に任せる。

第2層: AIレビュー(パターン認識)

AIが見つけられるもの:

• N+1問題
• SQLインジェクションリスク
• 未使用のインポート/変数
• テストカバレッジの不足
• 命名規則の違反

原則: パターンで検出できるものはAIに任せる。

第3層: 人間レビュー(判断と方向性)

原則: 判断が必要なものだけ人間がやる。

3層の効果

人間は判断に集中できるから、品質も上がります。

各層の責任境界

問題の種類	第1層(自動)	第2層(AI)	第3層(人間)
フォーマット	○
リンター違反	○
型エラー	○
テスト失敗	○
N+1問題		○
セキュリティ脆弱性		○
命名の改善		○
設計判断			○
ビジネスロジック			○
方向性の編集			○

境界が明確だと、各層が自分の仕事に集中できます。

人間レビューが不要なケース

ここで重要な点があります。 すべてのPRが第3層まで到達する必要はありません。

バグ修正、依存関係の更新、シンプルなチケット対応など、設計判断やビジネスロジックの確認が不要なPRは、第1層(自動ゲート)と第2層(AIレビュー)だけで完結できます。

PRの種類	必要な層
フォーマット修正	第1層のみ
依存関係の更新(Dependabot)	第1層 + 第2層
バグ修正(原因が明確)	第1層 + 第2層
リファクタリング(小規模)	第1層 + 第2層
新機能追加	第1層 + 第2層 + 第3層
アーキテクチャ変更	第1層 + 第2層 + 第3層
新しいパターンの導入	第1層 + 第2層 + 第3層

人間のレビューが必要なのは「判断」が伴うPRだけです。これを明確にしておかないと、全PRに人間レビューを要求して、結局レビューがボトルネックに戻ります。

この続きはKindleで →