この記事は、特定の理由でうまくいっていなかった AI コードレビューの導入と、それを解決した変更についての実務者による報告である。チームは 2025 年の春ごろから Claude Code を通じてレビューを実行していた。人間によるレビューが同じ観点を繰り返し見落としていたため導入したものである。問題は、一般的な設定しかされていないレビュアーには的を射た指摘をするだけのコンテキストが欠けていたことであり、的外れなコメントが積み重なった結果、チームメンバーはその出力をまったく無視するようになった。
記事が説明する対応策は、レビュアーに単一責任の原則を適用することである。すべてをレビューするよう求められた 1 つのエージェントではなく、レビューの観点ごとに 1 つのエージェントを置き、それぞれに絞り込まれたコンテキストを持たせる。記事はこれをツールを越えて持ち運ぶ価値のある設計思想として提示しており、個々のエージェントは社内のものであって、転用できるのは中身ではなく形のほうだと明言している。
これは 1 つのチームによる直接の報告であり、このアプローチが機能していることの根拠は測定ではなくチーム自身の経験である。
要点
- 的外れなレビューコメントは中立的なコストではない。記事によれば、それが十分に積み重なった時点でチームメンバーは AI レビュアーを完全に無視し始めた。これは個々のコメントの品質不足ではなく、導入全体の失敗である。
- 提示される解決策は、レビュアーを観点ごとに分割し、レビューの次元ごとに 1 つのエージェントを置くことである。その根拠は、汎用的な設定ではどの 1 つの次元をうまくレビューするにも十分なコンテキストを持てないという点にある。記事はこれを、AI エージェントに適用された単一責任の原則として明示的に位置づけている。
- エージェントは YAML フロントマターを持つ Markdown ファイルとして定義される。フロントマターには名前、
description、モデル設定を、本文にはシステムプロンプトを記述する。エージェントはプラグインにまとめられ、1 つはチームの Rails 固有のレビュアー用、もう 1 つはスタックに依存しないレビュアー用である。 - ディスパッチに個別のトリガー設定は不要である。記事によれば、オーケストレーションを担うエージェントが各サブエージェントの
descriptionフィールドを読み、そこから 1 つを選択する。そのため、どのファイルに適用され、何を探すのかという説明を具体的に書くことが、呼び出しを確実にする鍵となる。抽象的な説明は、呼び出し漏れと不要な呼び出しの両方の原因として挙げられている。 - 記事は、各エージェントの
descriptionをシステムプロンプトから AI に書かせていると報告する一方で、それが実際に意図どおりに呼び出されるかは別の問題だとも指摘している。明確なファイルパターンのトリガーはモデルにとって判断しやすく、それがない場合、チームはテスト用のプルリクエストを作成して挙動を確認している。 - 知識はチューニングではなく、意図的なループによって蓄積される。フレーキーなテストを修正し、そのパターンが他の場所でも再発しそうだとチームが判断した場合、その検出パターンをレビュアーに追加する。つまり、障害の修正とエージェントの育成が同じ行為になる。
- 記事は、このアプローチがツールに依存しないと主張しており、同じ役割分割を表現できる場所として Cursor のルールファイルや GitHub Copilot の指示ファイルを挙げ、重要なのは各レビュアーのコンテキストを絞り込むことだと述べている。
- 締めくくりの主張として、AI レビュアーのためにルールを書き出すことには、レビューとは独立した第 2 の見返りがあるとする。それはチームの暗黙知を明示的な形に変換し、チームの手元に残るものにするという点である。
背景
記事は、この変更を、チームがすでに試していた 2 つの代替手段と対比して位置づけている。最初に使われたのはチェックリストであり、手間がかかるうえに依然として漏れがあったと報告されている。フレーキーなテストという観点については、エージェントの前にカスタムの静的解析ルールが試みられたが、パターンが複雑すぎてその方法では表現できず断念された。これが、その種の欠陥に対しては lint ルールではなく LLM レビュアーが適切なツールだとする記事の論拠となっている。
著者はまた、チームが使っているツールに 2026 年 3 月に公式のコードレビュー機能がリリースされたこと、そしてチームがそのコストを見積もったうえで乗り換えず、自分たちが構築したものを使い続けていることにも触れている。