プロジェクトの知見で育てる！ 不具合検出特化型AIコードレビューSkillsとその運用

みなさん、AI時代でもコードレビューはしていますか？

わざわざ「AI時代でも」と頭につけたのは、AI駆動開発が一般的になった今、コードレビュー不要論が出てきていまして、社内でも話題に上がることが多いからです。

コードレビュー必要派は「最終判断は人間であるべき/コードレビューはコミュニケーションの場でもある」という趣旨のことを主張することが多いようです。

不要派は、「その人間の目こそ信用ならない/人間の判断は遅すぎる/AIと会話したほうが有益で楽しい」というニュアンスのことを仰っているようです。

AIの登場によって、自動テスト導入のコストなども下がりましたし、AIエージェントにテストをさせたりもできるので、コードレビューの位置づけが変わるのは確かだと思います。

今回は「人力コードレビューの要/不要」について結論を出さないのですが、この記事では私たちのチームで行っている、AIによるコードレビューやその他レビューサポートの取り組みを紹介したいと思います。

このプロジェクトではCursorを利用していますが、Claudeでも、GeminiのGemsでも似たような事はできます。

目次

• AIコードレビューの課題
  • AIのレビューの指摘内容が安定しない/出力が毎回変わる
  • AIの指摘内容に対する対応方針がチームで統一されていない
  • チーム独自のナレッジが反映されていない
• 私たちチームの解決策~バグチェック特化型Skillsの作成~
• 不具合検出特化コードレビュー用Skillsの具体的な中身
  • プロンプト（外部公開版）
  • 結果サンプル
• 工夫ポイント
  • 過去プロジェクトで発生した不具合/事象をベースにチェックリストを作成する
  • チェックリストに記載のない観点も明示的に分析をしてもらう
  • 作成と実行はフロンティアモデルで行う
  • AIの指摘の対応有無を記録しておき、改善に活かす
• コードレビューの外にも広げていく
• 感想
  • 今後の課題

AIコードレビューの課題

「人間のレビューが追いつかないならAIにやらせよう」というのは普通の発想だと思います。
AIに「レビューして！」と言うだけでやってくれますし、専用のSkillsも公開されているので、特別な手順を踏まなくてもそれなりのレビューはしてくれます。

ただ、私たちのチームにおいては、AIによるコードレビューを行う上で以下3つの課題がありました。

AIのレビューの指摘内容が安定しない/出力が毎回変わる

AIは与えられたプロンプト/コンテキスト/モデルに応じてアウトプットが大きく変わります。
重要な不具合を見つけてくれることもあれば、不具合をスルーしておだててくることもあります。同じプロンプトを打ち込んでもOK/NGが変わることがあります。

A「AIコードレビューで問題があったよ！」

B「え、同じプロンプト打ち込んだけど、俺のAIは問題なしと言ってたよ？」

ということも珍しくありません。

AIの指摘内容に対する対応方針がチームで統一されていない

AIの指摘内容は、致命的な不具合もあれば、可読性/保守性等の割と好み問題のようなものまで多岐に及びます。

そのような性質を持つので、レビュー対応要否の判断コストが高くなり、属人性も出てきてしまいます。

チーム開発においては、統一的な基準があるレビュープロセスが存在しないと安心感が生まれません。

この課題は「アウトプットが安定しない」という話にも通じるものがあります。

同じコードをレビューさせたとき、AさんとBさんで、違うアウトプットを受け取って、対応基準も異なってしまった場合、品質のばらつきが出てしまいます。

チーム独自のナレッジが反映されていない

チームには過去の学びの蓄積があります。

過去発生した不具合、レビューでよく話題になる観点、見逃しがちな点、ドメイン固有の仕様等のナレッジがあるわけです。

このような観点が反映されていないレビューは痒い所に手が届かないものになります。

私たちチームの解決策~バグチェック特化型Skillsの作成~

その課題を解決すべく、AIコードレビュー用のオリジナルのプロンプトを作り、AIが明示的に不具合と判定したものに限り、対応することにしました。

具体的には、コードレビュー用のSkills（Gems）を作りました。
その中で、チェックリスト形式でAIにレビューをさせ、「〇（不具合なし）、△（要確認）、×（明確に不具合）」で結果を返すようにし、×のみ対応を必須とすることをチームのルールとしています。

「修正ブランチとmainブランチとの差分」を自動抽出してくれるスクリプトをAIで作成し、それを活用してレビューさせることでレビュー範囲が不必要に広がることを防いでいます。

GeminiのGemsでもこちらは実行できるのですが、CursorなどのAIエージェントを活用すると、周辺コードも含め、立体的にレビューをしてくれます。

肝心の不具合チェックリストの中身は、過去発生した不具合や見逃しがちだった点をベースに作成し、過去の学びの蓄積を活かした形になっています。
チェックリストという方式は、人間がやるにはいろいろヘビーですが、AIは文句を言わずにやってくれます。

ちなみにこのプロセスを通すことで不具合がないことを完全に証明できるのかと言われれば、それは「できません」。
そのため、手動テスト、E2Eテスト、目視でのコードレビューも開発プロセス内には残してあります。

不具合検出特化コードレビュー用Skillsの具体的な中身

それで、できあがったプロンプト（Skills）の短縮版が以下です。

実際は300行以上あり、全文掲載はセキュリティ的にも問題がありますので、外部公開できる形にだいぶ加工はしました。
本来はファイルが分かれていたりする部分もまとめちゃっています。

ただ、テスト実行をしたところ、この短縮版でも不具合を抽出してくれたため、使える形にはなっていると思います。

プロンプト（外部公開版）

かなり長いので、下の「プロンプト全文（外部公開用抜粋版）」の行をクリックすると折りたためます。読み飛ばしたい方はご利用ください。

📊 チェック結果サマリ
合計: N項目
  ✅ 〇: XX件
  ⚠️ △: XX件（致命的: X / 重大: X / 軽微: X）
  ❌ ×: XX件（致命的: X / 重大: X / 軽微: X）
  ⏭️ 対象外: #…（理由）

プロンプトはここまでです。上の「プロンプト全文（外部公開用抜粋版）」の行をクリックすると折りたためます。

結果サンプル

上のプロンプトを流したときの出力例です。こちらも下の「AIの出力例」の行をクリックすると折りたためます。

📊 チェック結果サマリ
━━━━━━━━━━━━━━━━━━━━
合計: 27項目
  ✅ 〇: 20件
  ⚠️ △: 2件（致命的: 0 / 重大: 1 / 軽微: 1）
  ❌ ×: 1件（致命的: 0 / 重大: 1 / 軽微: 0）
  ⏭️ 対象外: #1, #11, #18, #19 など（理由: 今回の差分は「水やりリマインダーのまとめて送信」のみ。画像アップロード・課金・地図等の変更は含まない）

// Before（イメージ）
->leftJoin('pots', 'pots.shelf_id', '=', 'shelves.id')
->where('pots.status', '!=', 'archived')

// After（イメージ）
->leftJoin('pots', function ($join) {
    $join->on('pots.shelf_id', '=', 'shelves.id')
         ->where('pots.status', '!=', 'archived');
})

$days = max(1, min((int) $request->input('days', 7), 60));

出力例はここまでです。上の「AIの出力例」の行をクリックすると折りたためます。

工夫ポイント

過去プロジェクトで発生した不具合/事象をベースにチェックリストを作成する

チェックリスト候補は以下のようにして広範囲から抽出して作成をしました。

抽出後はAIにテキストで渡して「誤字脱字を修正して、分類して、チェックリストにして！」と頼むだけです。

AIに整形してもらえるので、抽出時の形式や文章の誤字脱字等は気にしなくても良いです。CSVとテキストなど、形式が混ざっていても問題ありません。
そのため、抽出の形式より中身が圧倒的にポイントになります。良質な観点をいかに抽出できるかが勝負どころです。

チェックリストに記載のない観点も明示的に分析をしてもらう

チェックリストの弱点のひとつに「チェックリストにはない項目の確認が甘くなる」ことがあげられると思います。
また、チェックリスト方式にすることで、AIのパフォーマンスを制限しているのではないかという懸念もありました。
ガチガチにチェックリストを組むのはいいですが、それだとAIの自由な推論能力を阻害してしまいかねません。
そこで、このプロンプトにはチェックリストにはない観点を敢えて積極的にレビューするような箇所（その他）を組み込んでいます。

例えば、以下のような指示です。

このような指示を与えることで、AIが自分で考える余地も残してあります。

「人間の指示を厳密に守らせる部分」「AIの知能の自由な発想を活かす部分」を分けている点がポイントです。

作成と実行はフロンティアモデルで行う

モデルの性能でバグの検出力が大きく変動するので、できるだけ高性能モデルを使うようにしています。
安価なモデルでNGなしだった場合でも、フロンティアモデルに変えたらNGだったことが何度もあります。
また、プロンプトの調整もフロンティアモデルを利用します。繰り返し使うものなので、レバレッジが効きます。

AIの指摘の対応有無を記録しておき、改善に活かす

AIコードレビューの出力とそれぞれの実際の対応有無はスプレッドシートに記録しています。
実績が一定以上溜まった後にそれをAIに分析させ、検出力の高い項目を特定したり、抜けている観点を洗い出したりしました。
作りっぱなしにならないようにし、実態に合わせて、より精度が高いものを作れるようにしてあります。

コードレビューの外にも広げていく

上記の通り、コードレビューから手を付け始めたのですが、この「過去の対応例等をAIに読み込ませ修正/レビューをさせる」という発想で、Skillsは複数作ってあります。

すべてに共通しているのはAIに一般的な指摘をさせるだけではなく、プロジェクトで蓄積した過去の実例を読み込ませている点です。
ちなみに効果の傾向としては、チェックリスト方式のコードレビューやクエリチューニングといった正解不正解がはっきりしているものはAIがやはり得意で、要件定義のような抽象度が高いものは人間の判断がまだだいぶ必要になっています。

感想

このチェックリストに記載がある観点で、すり抜けてリリースされてしまった商用バグ等はありません。
本来手動でやらなければならない数十項目をAIのコマンド一発で流せるので工数削減効果も大きいです。
手動だと、チェックリストに1つ項目を追加する度に、工数も心理的負荷も跳ね上がってしまうものですが、AIだと気にならないです。
開発プロセス全体の定量的な分析はまだできていないのですが、これらの取り組みを始めてから工数削減/品質の向上ができている実感はあります。

個人的に気に入っているのが、プロセス自体がプロジェクトの経験に応じて賢くなっていく点です。
AIにチェック観点や出力例を追加するだけで進化するわけです。
AIがなかった時代だと、ナレッジなどがあっても、それを人間に共有し、継続して普段の業務に活かすのは至難の業でした。
しかし、この方式が洗練されれば、AIが学びを吸収していき、人間が意識せずとも過去の経験がアウトプットに反映されるので、学びの循環の難易度が激減するはずです。

今後の課題

今後の課題は自動化です。

現状は、過去の事例の抽出～Skillsに反映等はほぼ手動になっています。

これだと手間ですし、人間が気づいていない、捨てられていってしまっている学びもあるはずです。
人間が意識をしなくてもAIが自律的に判断し、自動でプロセスを進化させられるようにしたいです。
ナレッジの保管場所や実行結果等の配置場所を工夫してMCPで繋ぐことでうまいことできないかと日々夢想しています。

今後、AI駆動開発の進化によっておそらくこの形式もどんどん古くなって、新しいプロセスの構築が必要になってくると思います。
ただ、「人間の学びをAIにFBする」という大きい抽象的な流れが消えることはなかなかないと思いますので、考え方等を参考にしていただければ幸いです。