レビューの傾向分析から、PR 前の仕組み化へ

担当しているプロジェクトでは、PR を出すたびに似たようなレビュー指摘が返ってきていました。そこで過去の PR とレビューコメントを AI で横断的に読み、繰り返し出てくる指摘を、PR を出す前に見つけて直せる仕組みへ変えています。この記事では、レビューの分析方法、そこから実装したチェック、次に取り組むことを順に紹介します。

---

手順書に書いてあるルールが、PR の前に読まれない

このプロジェクトは、エンジニア以外のメンバーもモック（画面）の実装を回せるようにすることを目指しています。その中で、次のような指摘が別々の PR で何度も出ていました。

• 画面の見出しに使う部品を変更したのに、画面説明書には古い部品名が残っている
• レイアウトを直したのに、別のフェーズの画面説明書だけ更新されていない

実は、ルール自体は手順書に書いてあります。「モックを直したら、画面説明書も合わせて直す」という一文です。それでも手順書は PR の前に読まれず、人も AI も気づかないまま PR が出ていました。

この状況を見て、「手順書に書いてあるから大丈夫」で済ませるのをやめ、読まなくても効く仕組みにしようと考えました。変更の影響範囲や検証項目の確認を仕組み側で引き受け、自動で確認できるものは修正する場所まで案内します。人の判断が必要なものは、相談する内容を整理して渡します。こうした支援を PR の前に入れるのが目標です。

過去の PR とレビューを集めて AI で分類する

何を仕組みに組み込むかを決めるために、まず過去のレビューで繰り返されている確認を洗い出しました。GitHub から次のデータを集めています。

• PR 本文
• 変更ファイル
• レビューコメント
• 実装者の返信
• 承認状態

集計した実装 PR は 181 本、本文付きの非作者コメントは 454 件です。このコメントには指摘のほかに承認・補足・bot の投稿も含まれるため、454 件がそのまま不具合の数というわけではありません。

AI には、コメントを内容ごとに分類してもらいました。分類の例は「文書と実装の追随漏れ」「文書どうしの整合」「アクセシビリティ」「SP 幅」などです。複数の PR を横断して同じ種類の指摘をまとめ、指摘と返信を対応付けて、それぞれがどう対応されたかまで追いました。

指摘を防ぎ方で分ける

分類ができたら、次は分類ごとに「どうすれば提出前に防げるか」を整理しました。防ぎ方で分けると、次の 3 種類に収まりました。

機械で照合できるものはチェックとして自動化し、動作確認が要るものは確認手順に入れます。要件の意味のように人が判断するものは、レビューで原典を参照してもらう形に寄せます。この表で、仕組みにする候補を決めました。

画面の変更とブランチ名を push 前にチェックする

分析で見つけた問題の一部は、すでに提出前のチェックとして実装しています。ここでは一例として、ブランチ名とプレビューの食い違いを防ぐチェックを紹介します。これはコメントの分類とは別に、ブランチ名とプレビューの実態を集計していて見つかった問題です。

このプロジェクトでは、feature/ ブランチを AWS Amplify にデプロイして、レビュー用のプレビュー URL を発行しています。ところが過去の PR には、画面を修正しているのに fix/ ブランチで提出しているケースがありました。fix/ ブランチではプレビューが出ないので、レビュワーが画面を確認できません。これも手順書に書いてあるルールでしたが、読まれないまま同じブランチの切り直しが何度も繰り返されていました。

そこで、モック（画面）に差分があるかどうかという判定を 1 つ決め、そこからブランチ名・プレビュー URL・デザインレビュワーの 3 つが同時に決まる形にしました。

push 前チェックは、組み合わせが合っていればそのまま進み、食い違っていればその場で案内を出します。使う人は案内に沿って修正すればよく、Amplify のデプロイ条件を各自が覚えておく必要がなくなりました。

CI 側をあえて通知だけにしているのは、役割を分けるためです。手戻りを減らすのは手前の push 前チェックが担い、CI はそれをすり抜けたものを見える状態にする役に絞っています。過去の PR で見つかった問題を、次の PR を出す前のチェックに変える。これが、今回の分析から仕組み化までの具体例です。

レビュー履歴を材料に選んだ理由

1 本の PR だけを見ると、その場の問題を直してレビューが終わります。ところが複数の PR を横断して読むと、同じ確認が別の PR でも必要になっていたことが分かります。

レビューの往復には、何を確認すればよかったか、どう対応したかが具体例つきで残っています。規範や手順書に書かれていない確認も、実際のやり取りとしてここに残っています。ただし、そのやり取りは PR ごとに散らばっていて、人が一つずつ読んで集めるのは現実的ではありません。そこで、まとめて読む作業を AI に任せました。そこから提出前にできる確認を選んで、手順やチェックに組み込んでいます。

分析してみて意外だったのは、PRD の要件・画面の実装・画面説明書の 3 者の間で、画面説明書と実装の食い違いが想像以上に多かったことです。画面説明書は「このボタンを押すとこうなる」といった画面の振る舞いを説明する文書です。ここを見直せれば、レビューと修正にかかる工数を減らせると考えています。

残った問題への対応と、効果の測り方

紹介したチェックを含め、一部の仕組みは実装済みです。現在の進み具合は次のとおりです。

画面説明書の更新漏れは、冒頭で挙げた「繰り返す指摘」そのものです。画面を修正したときに、対応する画面説明書が更新されていなければ PR の前に気づける形を提案しています。

あわせて、仕組みを入れた効果も確認していきます。測りたいのは次の項目です。

• PR 前に見つけられた不備の数
• レビューまで流出した不備の数
• 誤検知・判定不能の件数と、対応にかかった手間

誤検知や判定不能も測るのは、チェックが使う人の手間を増やしていないかを確かめるためです。同じ指摘がレビューで繰り返されなくなったか、使う人が案内だけで自分で対処できたかを見て、仕組みの良し悪しを判断します。

まとめ

レビューの指摘は、その PR を直したら終わりになりがちです。同じ指摘が繰り返されているなら、それは次の PR を助ける材料になります。今回の取り組みを振り返ると、やったことは次の流れでした。

指摘が繰り返されると、レビュワーの負担になるだけでなく、毎回同じ指摘を受ける実装者にとっても良いことがありません。実装者がやることを覚えるのではなく、仕組みで解決する方向を目指しています。担当プロジェクトでは、これがエンジニア以外のメンバーもモック実装を回すための土台になると考えています。

取り組みはまだ途中ですが、過去の PR を横断して読むだけでも、提出前に防げる指摘が見えてきました。AI コーディングエージェントを前提に、ミスを「気をつける」のではなく構造で防ぐ考え方は、AI コーディングエージェントで間違えられない構造をつくる実践でも紹介しています。AI が作ったモックを UI の観点でレビューするときの判断基準については、AI に UI を任せる前に決めておく「操作の重み」もあわせてご覧ください。

KDDIアイレットでは、AI 駆動開発の実践を通じて、開発プロセスそのものの改善を社内で継続的に進めています。AI 駆動開発の導入や開発プロセスの見直しについて、お気軽にご相談ください。