AIコードレビューの導入と運用 ― 何を任せ、何を人に残すか

はじめに

プルリクエストにAIレビューを組み込むチームが増えている。LLMベースのレビューは「差分を読み、指摘を返す」までを自動化できるが、導入して満足度が高いチームと、ノイズに疲れて形骸化するチームがはっきり分かれる。

この記事は、AIコードレビューを「入れる」ではなく「運用に載せる」視点で、設計・失敗パターン・落としどころを整理した考察である。特定のツールに依存しない一般論として書く。

AIレビューが得意なこと・苦手なこと

まず期待値を揃える。LLMレビューの性質は、人間のシニアレビューアとは違う。

得意なこと:

• 差分単体で判断できる指摘（null未処理、例外の握り潰し、明らかな境界値ミス）
• 命名・可読性・コメント過不足など「読めばわかる」層
• 定型的な観点の網羅（大量PRでも疲れず均一に見る）

苦手なこと:

• リポジトリ全体の文脈・過去の設計判断を踏まえた指摘
• 「この抽象化はやりすぎ」といった設計の匙加減
• 仕様と実装のズレ（仕様書がプロンプトに入っていなければ判断不能）
• 事実確認が必要な指摘（実際に動くか、既存コードと矛盾しないか）

この非対称性が運用設計の出発点になる。AIには「差分で閉じる指摘」を任せ、文脈依存の判断は人間に残す。ここを曖昧にすると、AIが自信満々に的外れな設計指摘をして信頼を失う。

アーキテクチャ：どこに差し込むか

典型的な構成は3パターンある。

1. PRトリガーでボットがコメント（GitHub Actions / GitLab CI 等）
2. ローカルの pre-commit / エディタ拡張でコミット前に指摘
3. ローカルCLIで差分を渡し、人間がレビュー前の下読みに使う

チーム運用なら 1 が基本。個人の生産性なら 2・3 が効く。以下は 1 を前提にした最小構成の例。

# .github/workflows/ai-review.yml
name: ai-review
on:
  pull_request:
    types: [opened, synchronize, reopened]

concurrency:
  group: ai-review-${{ github.event.pull_request.number }}
  cancel-in-progress: true

jobs:
  review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write   # コメント投稿に必要。それ以上は付けない
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0      # base との差分を取るため履歴が要る
      - name: Get diff
        run: git diff --unified=3 "origin/${{ github.base_ref }}...HEAD" > pr.diff
      - name: Run AI review
        env:
          LLM_API_KEY: ${{ secrets.LLM_API_KEY }}
        run: node scripts/ai-review.mjs pr.diff

ポイントは concurrency と permissions の最小化、そして差分の取り方だ。フルリポではなく差分を渡すのが基本になる。

差分の渡し方 ― コスト・精度・ノイズを分ける鍵

素朴に「差分全部を1回のプロンプトに詰める」と3つの問題が出る。大きなPRでトークン上限に当たり、lockfileや自動生成物までレビューして無意味な指摘が増え、1回のレスポンスに指摘が詰め込まれて粒度がばらつく。

対策として、送る前にフィルタとチャンク分割を入れる。

// scripts/ai-review.mjs（抜粋）
import { readFileSync } from "node:fs";

// 生成物・ロック・スナップショットは指摘してもノイズ
const IGNORE = [
  /(^|\/)(package-lock\.json|pnpm-lock\.yaml|yarn\.lock)$/,
  /(^|\/)dist\//,
  /\.min\.(js|css)$/,
  /\.snap$/,
];

const splitByFile = (diff) =>
  diff.split(/^diff --git /m).filter(Boolean).map((c) => "diff --git " + c);

const pathOf = (fd) => (fd.match(/^\+\+\+ b\/(.+)$/m) || [])[1] || "";

const diff = readFileSync(process.argv[2], "utf8");
const targets = splitByFile(diff).filter((f) => {
  const p = pathOf(f);
  return p && !IGNORE.some((re) => re.test(p));
});

for (const fd of targets) {
  await reviewOneFile(pathOf(fd), fd); // ファイル単位で粒度を揃える
}

ファイル単位に割ると、指摘の粒度が揃い、どのファイルへのコメントか対応づけしやすくなる。大きなファイルはさらにハンク単位に割る。

プロンプト設計 ― 「観点」と「出力形式」を固定する

AIレビューの質はほぼプロンプトで決まる。効くのは、観点を明示的に列挙する・リポジトリの規約を渡す・出力を構造化する、の3点だ。

const SYSTEM = `
渡された diff だけを根拠に指摘してください。
diff に写っていない箇所の推測、全体設計の是非は指摘しないこと。

観点（この順で確認）:
1. バグ・境界値・null/例外の握り潰し
2. セキュリティ（入力検証・認可・秘密情報のハードコード）
3. 規約違反
4. 可読性・命名

規約:
- 例外は握り潰さずログして再送出する
- 認可判定はユースケース層で行う
- 秘密情報はコードに書かず環境変数から読む

出力は JSON 配列のみ。各要素:
{ "line": <行番号>, "severity": "high|medium|low",
  "title": "要約", "body": "なぜ問題か+修正案" }
確信が持てない指摘は出さない。指摘ゼロなら []。
`;

「diffだけを根拠に」「確信がなければ出すな」の2文が、的外れ指摘とハルシネーションをかなり減らす。severity を付けさせるのは、後段で重要度フィルタをかけるためだ。

ノイズ対策 ― これが運用の成否を決める

導入初期に必ず起きるのが「コメントが多すぎて誰も読まなくなる」問題。放置すると1〜2週間でボットがミュートされる。効いた対策を挙げる。

• severity で足切りする（初期は high のみ、慣らしてから medium 開放）
• 1PRあたりコメント上限を設ける（例：上位10件、残りは要約に集約）
• 前回コミットで出した指摘は再掲しない
• nit（好みレベル）はまとめて1コメントにする
• 人間が resolve した指摘は蒸し返さない

function postComments(findings) {
  const shown = findings.filter((f) => f.severity === "high").slice(0, 10);
  if (findings.length > shown.length) {
    postSummary(`他 ${findings.length - shown.length} 件は severity 低のため要約に集約`);
  }
  shown.forEach(postInline);
}

数を絞るほど、残った指摘の信頼度が上がる。「AIの指摘は読む価値がある」という状態を維持することが、機能を殺さない条件になる。

事実確認 ― AIの指摘を鵜呑みにしない仕組み

LLMは「それらしい嘘」を混ぜる。特に「この関数は存在しない」といった事実系の指摘は、周辺を見ていないため誤ることがある。対策は2段構えだ。プロンプトで「diffに写っていない前提の指摘は出すな」と縛り、出せる範囲で機械照合する（指摘行が実在するか、参照シンボルが同PR内に定義されているか）。

さらに厳しくやるなら、AIの指摘をもう一段のAIに「本当に問題か、反証してみろ」と当てる二重チェックも有効だ。片方が指摘し、もう片方が反証を試みて残ったものだけ出す。コストは上がるが、誤検知が目に見えて減る。

導入の進め方 ― いきなり全開にしない

1. サイレント運用：コメントは投稿せず、ログにだけ出して精度を観察する
2. high のみ投稿・非ブロッキング：CIは落とさない。あくまで参考
3. 観点を絞って medium 開放：セキュリティなど誤検知の少ない観点から
4. 一部をブロッキング化：秘密情報のハードコードなど「機械的に確実な」ものだけ必須化

いきなり 4 から入ると、誤検知でCIが落ちて開発が止まり、反発でロールバックされる。最初は必ず非ブロッキングが鉄則である。

費用と権限の注意点

• コスト：PR単位・ファイル単位で課金が積み上がる。差分フィルタと上限設定で制御し、大量PR連打の日に跳ねる分を月次で監視する
• 秘密情報：レビュー対象コードを外部LLMへ送る＝社外送信。会社のポリシー確認が必須。送信前のマスク、あるいは許容される基盤の選定を行う
• 権限：CIトークンは pull-requests: write 程度に絞る

効果の計測

導入効果は感覚で語らず、AI指摘の採用率、誤検知として無視された割合、人間レビューの1PRあたり所要時間の変化を計測すると判断できる。採用率が2〜3割を切り続けるなら、プロンプトか対象範囲の設計がずれている。

まとめ

AIコードレビューは「入れれば楽になる」道具ではなく、得意領域に絞り・ノイズを管理し・非ブロッキングから段階導入するという運用設計込みで初めて効く。差分で閉じる指摘をAIに任せ、文脈と責任を人間に残す。この線引きを最初に決めることが、機能を形骸化させない一番のポイントになる。