はじめに
先日、AIコーディングエージェント向けのコードレビューSkill「code-review-skills」をリリースしました。Xで予想以上に反響をいただき、ありがとうございます。
この記事では、Skillを作った背景と設計、レビューの振る舞いをどう確かめているかを紹介します。
コードレビューの判断基準をAIにも伝える
私はレビューを受ける側として、指摘の意図がわからず手戻りする経験を何度もしました。レビュアーになってからは、何をどこまで見るべきか、どう伝えるべきかに悩みました。チーム内で判断基準が共有されていないと、人によって指摘が異なり、レビューが開発のボトルネックになることもあります。
こうした経験から、レビューを個人の経験や感覚だけに任せず、観点や判断基準を言葉にして共有することが大切だと考えるようになりました。その考えをまとめたのが、私の著書『コードレビューの教科書』です。
レビュー改善に取り組んだ経緯や、書籍の出版に至るまでの話は、以前の記事「『コードレビューの教科書』を出版します」でも紹介しています。
code-review-skillsも、この考え方を土台にしています。AIにコードを渡すだけではなく、次のような手順を伝えます。
- 変更行だけでなく、影響を受ける処理も追う
- 指摘には、発生条件と具体的な影響を含める
- 好みだけのコメントや、根拠のない推測は指摘にしない
- 情報が足りないときは、断定せず質問する
指摘の重さと観点を明示する
必ず直すべき問題と、任意の改善案が同じ調子で書かれていたら、読み手は優先度を判断しにくくなります。そこで、各コメントに対応レベルとレビュー観点を付けています。
| 例 | 意味 |
|---|---|
MUST(Functionality): |
機能上の問題など、マージ前に解決が必要 |
SHOULD(Test): |
通常は解決したい、具体的な品質上のリスク |
BETTER(Simplicity): |
現状も許容できるが、利点のある改善案 |
NITS(Style): |
軽微な修正。自動化できるフォーマット指摘には使わない |
指摘では、コードから確認できる振る舞いと、発生条件・影響を結び付けます。書き手を評価するのではなく、変更をよくするために次の行動がわかるコメントを目指します。
共通の手法からエージェント別のSkillを生成する
リポジトリは、レビュー手法の正本と、エージェントに配るファイルを分けています。
code-review-skills/
├── src/
│ ├── core/ # エージェントに依存しない共通のレビュー手法
│ └── technologies/ # 技術スタックに応じたレビュー知識
├── dist/
│ ├── codex/evidence-code-review/
│ └── claude-code/evidence-code-review/
├── docs/ # コメント規約、導入・評価ガイドなど
└── tests/ # 振る舞いを確認する評価ケース
src/core/には、エージェントや特定の技術に依存しないレビューの進め方を置いています。一方、src/technologies/では、よりプロジェクトに関わりの深い技術別の情報を管理します。
プロジェクトによって、使っている言語やフレームワーク、バージョン、設計上の前提は異なります。共通のレビュー手法だけですべてを判断するのではなく、対象プロジェクトの技術構成に合った情報を参照できるようにすることで、確認する観点を具体化し、レビューの精度を高める狙いがあります。
この共通手法と技術別の知識をもとに、CodexとClaude Code向けのパッケージを生成します。dist/以下は生成物なので、直接編集しません。こうすることで、エージェントごとに手法がずれていくのを防ぎながら、対象プロジェクトの技術に合わせたレビューを行えるようにしています。
開発時に使うコマンドも役割を分けています。
make build # エージェント向けパッケージを生成
make check # frontmatter、リンク、生成物の鮮度を確認
make test # 評価ケースなどを検証（AIサービスは呼び出さない）
アーキテクチャ上の決まりや独自の実装ルール、検証コマンドなど、個々のリポジトリに固有の情報は、そのプロジェクトのAGENTS.mdやCLAUDE.mdなどで伝えます。technologies/の技術別知識と、リポジトリ固有のルールを組み合わせることで、共通の手順を保ちながらプロジェクトに合わせてレビューできる設計です。
複雑なレビューでは、環境が対応していれば作業をサブエージェントに分けられます。その場合も、最後に結果を統合し、重複や見落としを確認します。
複数のOSSで過去のPRをレビューする
検証には、7つのOSSリポジトリから各10件、合計70件の過去PRを使用しました。各リポジトリの10件には、正常な差分も1件含めています。
正常な変更も評価に含めるのは、問題のあるPRだけを見せると、AIが毎回何かを指摘することを正解だと捉えかねないからです。「問題を見つける」と「問題がなければ指摘しない」の両方を確認します。
問題のあるPRは、次の条件で選びました。
- 変更量は20〜300行程度、変更ファイルは2〜8個程度
- 後続の修正PRまたはrevertがある
- 問題をコードから推論できる
- 大量の生成物や依存関係更新ではない
- 特定のIssue本文を知らなくてもレビューできる
- 修正前後のテストをローカルで実行できる
検証の流れは次の通りです。
- 親コミットのファイルを、別の一時ディレクトリへコピーする
-
.gitを含めずに、対象PRの差分だけを適用する - PRタイトルやIssue番号を渡さず、ネット検索も使わずにレビューさせる
- 実際のレビュアーコメントと突き合わせ、重要な漏れや不要な指摘を確認する
- 結果をもとに手法を改善し、再度レビューする
公開OSSのPRはモデルがすでに知っている可能性があります。比較的新しいPRを選び、PRや不具合に関するヒントを渡さないのは、その影響をできるだけ小さくするためです。
評価の限界も把握する
この検証で、あらゆるプロジェクトやPRに対する性能を保証できるわけではありません。対象の選び方に偏りがあり得ますし、公開情報をモデルが学習している可能性も完全には除けません。
そのため、文章の完全一致ではなく、期待する振る舞いを確認します。リポジトリの評価用fixtureでは、報告すべき項目、報告してはいけない項目、出力形式などをチェックします。自動チェックはケースや生成物の整合性を検証し、実際のエージェントでの振る舞いはCodexとClaude Codeを使って個別に評価します。
評価結果から手法を改善し、改めて重要な指摘の漏れや不要な指摘がないかを確かめる。検証を繰り返せる形にしておくことを重視しています。
code-review-skillsは現在ベータ版として公開しており、これからも検証と改善を続けていきます。実際に使ってみた感想や気づいた点など、利用者の皆さまからフィードバックをいただけると嬉しいです。
さいごに
AIによってコードレビューの一部を効率化できても、指摘を採用するか、変更が適切かを判断する責任までAIに委ねられるわけではありません。最終的なアウトプットに責任を持つのは人間です。
code-review-skillsは、レビューの考え方をAIエージェントが使える手順にしたものです。詳しくはGitHubリポジトリをご覧ください。
コードレビューの観点や判断基準に興味があれば、『コードレビューの教科書』もご覧ください。