AI コードレビュアーを"育てる"。GitHub で作るナレッジベース

はじめに

こんにちは！
レバテックでリードエンジニアを務める山川です。

私たちの開発部では、AI エージェントによるコードレビューを導入し、開発の品質とスピードの両立を目指しています。

AI のレビューは非常に強力ですが、次のような課題を感じることはないでしょうか？

• 「もっと私たちのチーム独自のルールを反映させたい」
• 「新しい知見が溜まるたびに、長大なプロンプトを更新するのが大変…」

本記事では、こうした課題を解決するために私たちが実践している 「プロンプトとルールを分離して運用する」 AI コードレビューの手法 をご紹介します。

設計思想： プロンプトはシンプルに、ルールは Git で管理する

私たちの手法の核となる考え方は、「プロンプトは AI への命令書に徹し、変化しやすいルールや観点は外部ファイルで管理する」 というものです。これにより、ルールや観点の追加や変更が Git ベースで管理可能になり、メンテナンス性が向上します。

実際の運用で使っているプロンプトとリポジトリ構成を見ていきましょう。

指示の起点となる「基本プロンプト」

まず、AI エージェントに与えるプロンプトです。ここでは「何を参照して、何をするか」という最低限の指示に留めています。

# コードレビュー
次のレビュールールに従って、PR_URL の PR レビューを行い、
PR_URL にレビューコメントを必ず投稿してください。

# レビュールール
* リポジトリへのコミットやプッシュは絶対にしないでください。
  レビューとコメントのみが許可されています。
* ユーザーに確認を求めたり、返信を待ったりしてはいけません。
* 追加のレビュールールは
  https://github.com/{{ リポジトリ名 }}/blob/main/review-rules.md
  を参照してください。
  このファイルが参照できない場合は、その旨をユーザに報告し、レビューを中止してください。
* https://github.com/{{ リポジトリ名 }}/tree/main/perspectives
  にある全てのファイルを参照し、レビュー観点に加えてください。
  1つでもファイルが参照できない場合は、その旨をユーザに報告し、レビューを中止してください。

# 変数
PR_URL: プルリクエストの URL

変化に対応する「GitHub リポジトリ」

ルールやレビュー観点は、すべて GitHub リポジトリに集約しています。

tree
.
├── perspectives/   # レビュー観点を格納している
│   ├── general-perspectives.md
│   ├── organization-dedicated-perspectives.md
│   ├── awaiting-async-processing.md
│   └── (etc...)
└── review-rules.md # AIの挙動を制御するルールを記載している

レビュールール (review-rules.md)

次のような、コメントの形式や言語など、AIの挙動を制御するための普遍的なルールを記載しています:

# レビュールール
* リポジトリへのコミットやプッシュは絶対にしないでください。
  レビューとコメントのみが許可されています。
* ユーザーに確認を求めたり、返信を待ったりしてはいけません。
* PR へのコメントは日本語で行ってください。
* 一般的に広く使用されているコードレビュー観点を活用してください。
* 必ず具体的な行を指定したインラインコメントを使用してください。
  具体的な行を指定できない場合のみ、PR 全体に対するコメントを使用してください。
* 問題を指摘する際は、Markdown 形式のコードスニペットを含めてください。
* コメントは、該当箇所の前後の文脈が分かるように複数行で記述してください。
* コメントは、内容に応じて
  [must], [should], [nits], [ask], [imo]
  などの適切なラベルを、コメントの先頭に記載してください。
* 指摘しようとしている改善点がすでに PR で対応されていないか、変更前後を比較して確認してください。
* 必ず gh api コマンドを使用してコードを埋め込んだコメントを投稿してください。
  これに失敗した場合のみ、通常のコメントとコードブロックを使用してください 
  (「コードを埋め込んだコメントの投稿方法」を参照してください)。
* コメントを投稿する前に、PR のディスカッションを確認し、
  同じ内容の指摘が既に行われていないか確認してください。
* コメントを投稿する前に、PR のディスカッションを確認し、
  以前のレビューで既に対応されていないかも確認してください。
* 同じ問題が複数回出てくる場合は、必ず1つのコメントにまとめ、
  全ての該当箇所を参照してください（絶対に個別コメントに分けないでください）。
* コメントをする前に、このルール一覧を再確認してください。

## コードを埋め込んだコメントの投稿方法
(略 コメントをAPIで投稿する手順を記載しています)

私たちは「絶対に」「必ず」といった強い言葉を意図的に使用しています。これにより、AI が指示を破る確率を下げ、期待通りの挙動をさせやすくなります。

レビュー観点 (perspectives/)

perspectives ディレクトリには、具体的なレビュー観点をファイル単位で格納します。

• general-perspectives.md: SOLID 原則など、あらゆるコードに適用できる一般的な観点。
• organization-dedicated-perspectives.md: 私たちの開発部独自の命名規則や設計ルール。
• awaiting-async-processing.md など: 非同期処理の考慮漏れなど、特定技術領域の専門的な観点。

このように観点を分離しておくことで、プロジェクトの特性に合わせて読み込ませる観点を柔軟に選択することも可能です。

導入効果と今後の展望

この仕組みを導入したことで、2つの大きなメリットが生まれました。

• AIレビューの継続的な成長: レビューで指摘漏れがあった際、その観点をファイルとしてリポジトリに追加するだけで、AIの知識をアップデートできます。
• 開発者の学習教材として機能: リポジトリ自体が、チームが重視するレビュー観点の生きたナレッジベースとなり、チームメンバーのスキルアップにも繋がっています。

おわりに

AI との協業が当たり前になる中で、AI をいかに「育てる」かという視点が重要になります。この記事でご紹介した手法が、皆さんの開発現場をより良くするための一助となれば幸いです。

それでは！