AIレビューの指摘、そのあとどうしてる?
AIにコードレビューをさせるのは、もう珍しい話ではない。リポジトリを読ませて「レビューして」と言えば、それらしい指摘リストが返ってくる。
問題はそのあとだ。
返ってくるのは「16件の指摘事項」のようなフラットなリストで、そこから先は人間の仕事になる。どれから直すか優先度を決め、関連する指摘をまとめ、修正の単位を切り、作業に着手する——この「指摘リストを作業計画に翻訳するコスト」が、地味に重い。
しかも翻訳をサボって指摘リストのまま上から潰していくと、1つのブランチにバグ修正とリファクタと表示調整が混ざった、レビュー不能の巨大な差分ができあがる。AIレビューで楽をしたはずが、その後工程で負債を作っている。
そこで私は運用を変えた。AIには指摘リストではなく、**「PR単位のハンドオフプロンプト」**を最終成果物として出させる。この記事はその具体的なやり方の共有だ。
ワークフロー全体像
やることは3ステップ。
- レビューさせる:リポジトリを読ませて、指摘を洗い出させる
- PR単位に分割させる:指摘を「1PR=1関心事」でグルーピングし、着手すべき依存順に並べさせる
- 各PRの「ハンドオフプロンプト」を書かせる:それぞれのPRについて、別のAIセッション(またはClaude Codeなどのコーディングエージェント)にそのまま渡せる自己完結の実装指示書を生成させる
ポイントは、レビューしたセッションと実装するセッションを分離すること。レビューセッションは文脈をたっぷり抱えた「設計者」、実装セッションは1つのPRだけに集中する「実装者」という分業にする。ハンドオフプロンプトは、その間をつなぐ引き継ぎ書だ。
実例:個人開発アプリのレビューを3PRに分割した
私の個人開発アプリ(Next.js + Supabase)で実際にやった例を出す。
まずレビューを依頼すると、middlewareの配置ミス(認証が機能していない)、壊れた画面遷移、タイムゾーンの扱いの不整合、型定義の重複など、大小さまざまな指摘が出てきた。
これをそのまま直し始めるのではなく、次のように依頼する。
この指摘を「1PR=1関心事」の原則でPR単位にグルーピングしてください。
- 動作に影響するバグ修正を最優先
- リファクタリングはバグ修正と混ぜない
- PR間に依存関係がある場合は着手順を明示
結果、こう分割された。
- PR1:バグ修正(middleware配置の修正、壊れた遷移の修正)——動作の正しさを最優先
- PR2:構造の整理(型定義の重複解消、タイムゾーン処理の一元化)——PR1がマージされた土台の上で
- PR3:表示の改善(UI調整系)——機能に影響しない変更を最後に
この時点で「レビュー不能な巨大差分」問題は消える。各PRの差分は1つの関心事しか含まないので、後から自分でレビューするのも楽だ。
ハンドオフプロンプトのテンプレート
次に、各PRについてハンドオフプロンプトを書かせる。私が使っている構造はこれだ。
# PR1: 認証middlewareの修正
## コンテキスト
- リポジトリ: Next.js 16 (App Router) + Supabase
- このPRはレビューで検出されたバグ修正のみを扱う
## 問題
- `src/middleware.ts` が誤った階層に配置されており、
認証チェックが一切実行されていない
- (以下、問題ごとに再現条件と影響範囲)
## 修正方針
- middleware.ts をプロジェクトルート直下に移動
- matcher設定で保護対象ルートを明示
- (具体的な方針を問題ごとに)
## やらないこと(重要)
- 型定義の重複解消には触れない(PR2で対応)
- UIの調整はしない(PR3で対応)
- 修正対象ファイル以外のリファクタリングをしない
## 受け入れ条件
- [ ] 未ログイン状態で保護ルートにアクセスするとリダイレクトされる
- [ ] `pnpm build` が通る
- [ ] 既存のテストが全件パスする
各セクションの意図を説明する。
**「コンテキスト」**は、実装セッションがゼロから読む前提で書かせる。レビューセッションの脳内にある文脈は、明示しない限り引き継がれない。
「やらないこと」が一番重要だ。コーディングエージェントは放っておくと「ついでに」周辺コードを直したがる。善意のスコープ逸脱がPR分割を台無しにするので、他のPRで扱う内容を明示的に禁止する。体感では、このセクションの有無でPRの純度が最も変わる。
**「受け入れ条件」**はチェックボックス形式で、検証コマンドを含めて書かせる。実装セッションが自己検証できるし、人間が最後に確認する項目リストにもそのまま使える。
なぜこの運用が効くのか
やってみて感じている効果は3つ。
1. コンテキストの引き継ぎコストが消える。 新しいセッションを開いて「さっきの続きで…」と説明し直す必要がない。ハンドオフプロンプトを貼るだけで実装が始まる。レビューから数日空いても、未来の自分への引き継ぎ書としてそのまま機能する。
2. 差分がレビュー可能な粒度に保たれる。 AIに書かせたコードこそ、人間のレビューが必要だ。1PR=1関心事なら、AIの出力を自分の目で検証するのが現実的な負荷で済む。
3. 修正の「順番」をAIに設計させられる。 バグ修正→構造整理→表示改善という依存順は、フラットな指摘リストには含まれない情報だ。分割を依頼することで、この暗黙知が明文化される。
限界と注意点
いいことばかり書いたので、正直な注意点も。
- レビューの網羅性はAI任せにしない。 AIレビューは「よく見るパターンの問題」に強く、ドメイン固有のロジックバグには弱い。検出器のひとつとして扱い、最終判断は自分でする
- 小さすぎる修正にはオーバーキル。 typo修正1件にハンドオフプロンプトは要らない。指摘が5件を超えて関心事が混ざり始めたあたりから効いてくる
- ハンドオフプロンプト自体もレビューする。 たまに「やらないこと」に入れたはずの内容が「修正方針」に紛れ込む。貼る前に30秒だけ目を通す
おわりに
AIコードレビューの価値は、指摘の量ではなく**「指摘を作業可能な形に整形できること」**にあると思っている。指摘リストを受け取って終わりにするのは、せっかくの整形能力を使い残している。
「レビューさせる」の次の一歩として、「PR単位のハンドオフプロンプトまで書かせる」——同じような運用をしている方がいたら、工夫をコメントで教えてほしい。テンプレートはこの記事のものを自由に使ってもらって構いません。