AI コードレビュープロセス with PR-Agent

はじめに

こんにちは！BABY JOB 開発部です！
以前の記事にて、AI コードレビューツール「PR-Agent（Qodo Merge）^[1]」の導入背景と選定理由についてご紹介しました。
https://zenn.dev/babyjob/articles/introduce-qodo-merge

今回はその続編として、導入後の私たちのレビュープロセスについてご紹介します。

コードレビュープロセス

おおまかには「実装完了 → AI レビュー → 指摘対応 → 人間レビュー」という流れにしています。

このプロセスの大きな特徴は、AI レビューの実行タイミングを、自前で用意した専用の GitHub アカウント（以下、AI アカウント）によって制御している点です。

具体的には、次のいずれかの条件を満たしたときに実行される形としています。

• AI アカウントをレビュアーにアサインしたとき
• AI アカウントがレビュアーにアサインされた状態で、追加の push を行ったとき

各ステップについて説明して行きます。

ステップ①：【レビューイ】実装完了

開発者はローカル環境での実装を完了します。

なお、プルリクエストの作成タイミングには、以下のようなパターンが考えられます。

• 実装完了後にプルリクエストを作成する場合
• WIP（作業途中）の状態で先にプルリクエストを作成しておく場合

いずれのケースにおいても「実装が完了し、AI レビューを受ける準備が整った」状態をこのステップとしています。

ステップ②：【レビューイ】AI アカウントをレビュアーにアサイン

AI アカウントをプルリクエストのレビュアーにアサインします。

このアクションがトリガーとなり、GitHub Actions 経由で PR-Agent によるコードレビューが実行されます。

ステップ③：【レビュアー（AI）】レビュー

AI がプルリクエストを解析し、行コメント形式で指摘を投稿します^[2]。

ステップ④：【レビューイ】AI アカウントをレビュアーから外す（任意）

AI アカウントがレビュアーにアサインされたまま追加の push を行うと再レビューが実行されます。
この挙動を避けたい場合は、push の前に AI アカウントをレビュアーから外しておきます。

ステップ⑤：【レビューイ】AI の指摘に対応

AI からのコメントを確認し、修正が必要かどうかを判断します。
修正が必要な場合は対応を行い、不要と判断した場合は、その理由をコメントで残します。
これは、指摘を取り込まなかったのが意図的なのか、単なる見落としなのかを、人間のレビュアーが判断できるようにするためです。

ステップ⑥：【レビューイ】人をレビュアーにアサイン

AI レビュー対応後、最終確認として人間のレビュアーをアサインします。

ステップ⑦：【レビュアー（人間）】最終レビュー

AI とレビューイのやり取りを参考にしながら、最終レビューを行います。

このプロセスに至った経緯

導入直後は、PR-Agent を既存のレビュープロセスにそのまま組み込んで運用していました。
しかし、継続的に利用していく中でいくつかの課題が見つかり、それに対応する形で、現在のプロセスを整備するに至りました。

背景：AI による再レビューの自動化

当初、私たちは PR-Agent で再レビューを実行する際、PR-Agent が提供するコマンドコメントを投稿する方法を用いていました^[3]。

具体的には以下のコマンドです。

• /describe：プルリクエストの要約を更新
• /review：レビューガイドの更新
• /improve：改善コメントの投稿

しかし、これらは 1 つずつ投稿する必要があるため、手間に感じる声がメンバーから上がるようになりました。
そのため、追加の push 時にこれら 3 つの機能が自動的に実行される方法を調査しました。

その結果、

• GitHub Actions のトリガー
• GITHUB_ACTION_CONFIG.PR_ACTIONS オプション

に synchronize を追加することで再レビューの自動実行が可能になることがわかりました。

on:
  pull_request:
    types: [opened, reopened, ready_for_review, synchronize]

      - name: Pull request analysis and feedback
        uses: qodo-ai/pr-agent@v0.29
        env:
          # ...（中略）
          GITHUB_ACTION_CONFIG.PR_ACTIONS: '["opened", "reopened", "ready_for_review", "synchronize"]'

しかし、再レビューの自動実行が可能になると、次第に別の問題が生じるようになりました。

問題 1：ノイズコメント

push のたびに、AI が同じ内容のコメントを繰り返し投稿してしまう問題が発生しました^[4]。

具体的には、以下のようなケースです。

• AI からの指摘について取り込まない判断をし、別の修正のために push した場合
• AI からの指摘の一部に対応し、未対応の指摘を残したまま push した場合

いずれのケースでも、初回レビューで指摘されたコードがそのまま残っているため、再レビュー時にも同じコメントが投稿されてしまっているものと考えられます。

指摘を取り込まない判断をした場合については、コードが変更されない以上、同じ内容の指摘が繰り返されることを避けるのは難しいと考えています。

一方で、一部対応の段階で再レビューが走ってしまう場合については、AI の実行を制御する仕組みを用意することで防ぐことができそうです。

問題 2：レビュープロセスの複雑化

push のたびに AI レビューが自動で実行される状態では、人間のレビュアーからの指摘に対応した際にも AI レビューが実行されてしまいます。

AI と人間のレビューが入り混じることでプロセスが複雑に感じられるようになり、「AI レビューを任意のタイミングで締め切りたい」といった要望が出てくるようになりました。

対策

上記の問題に対し、次のような対策を講じました。

• AI レビューの実行タイミングを開発者が制御できる仕組みを導入
• AI と人間のレビューフェーズを明確に分け、プロセスをシンプルにする

後者については冒頭に載せたレビュープロセスの定義で対応しました。
ここでは前者について説明します。

どのように AI レビューの実行タイミングを制御するか

はじめは、コミットログやプルリクエストのタイトルに特定の文字列を含め、それをもとにワークフローをスキップする方法を検討しました。
しかし、最終的には「専用の GitHub アカウントを使って制御する方法」に切り替えました。

その理由は次の通りです。

• 「レビュアーにアサインすればレビューしてもらえる」といったように、AI を人間のレビュアーと同様に扱えるため、既存の運用からスムーズに移行できる
• 一時的な方針を、永続的に残る情報（コミットログやプルリクエストのタイトル）に埋め込むことを避けたかった
  • これらの情報は将来的にも参照される可能性がある
  • 一方で、AI レビューの運用方針は変更される可能性があり、後の開発者にとってノイズとなり得る

このようにして、AI アカウントによる実行制御を採用するに至りました。

ここまでが現在のレビュープロセスに至った経緯です。
ここからは、このレビュープロセスを実現するために私たちが実際に行った準備や設定についてご紹介します。

実現に必要な準備と設定

このレビュープロセスを実現するためには、以下 2 点が必要です。

• GitHub アカウントの用意
• GitHub Actions ワークフローファイルの調整

GitHub アカウントの用意

AI レビューの実行制御に用いる GitHub アカウントを用意します。

詳細は公式ドキュメントを参照ください。
https://docs.github.com/ja/organizations/managing-membership-in-your-organization/inviting-users-to-join-your-organization

GitHub Actions ワークフローファイルの調整

以下のタイミングで AI レビューが実施されるようにワークフローのファイルを構成します。

• AI アカウントをレビュアーにアサインしたとき
• AI アカウントがレビュアーにアサインされた状態で、追加の push を行ったとき

on:
  pull_request:
    types: [review_requested, synchronize] # review_requested：レビュアーアサイン用、synchronize：追加 push 用
  issue_comment:
    types: [created]

jobs:
  execute_ai_code_review:
    # 【pull_request イベント】
    # - AI アカウントのレビュアーアサイン時にレビューを実施
    # - AI アカウントがレビュアーに含まれている状態での追加 push 時にレビューを実施
    # 【issue_comment イベント】
    # - プルリクエストに '/' から始まるコマンドコメントを投稿した時に PR-Agent の機能を実施
    if: >-
      github.event.sender.type != 'Bot' &&
      (
        (
          github.event_name == 'pull_request' &&
          (
            (github.event.action == 'review_requested' && github.event.requested_reviewer.login == '<AI アカウントの GitHub ユーザー名>')
            ||
            (github.event.action == 'synchronize' && contains(github.event.pull_request.requested_reviewers.*.login, '<AI アカウントの GitHub ユーザー名>'))
          )
        )
        ||
        (github.event_name == 'issue_comment' && github.event.issue.pull_request && startsWith(github.event.comment.body, '/'))
      )
    runs-on: ubuntu-latest
    timeout-minutes: 10
    permissions:
      id-token: write
      pull-requests: write
      contents: write
    steps:
      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AI_REVIEW_ROLE_ARN }}
          aws-region: ap-northeast-1
      - name: Pull request analysis and feedback
        uses: qodo-ai/pr-agent@v0.29
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          CONFIG.MODEL: "<モデルID>"
          CONFIG.FALLBACK_MODELS: '["<モデルID>"]'
          PR_CODE_SUGGESTIONS.COMMITABLE_CODE_SUGGESTIONS: true
          GITHUB_ACTION_CONFIG.PR_ACTIONS: '["review_requested", "synchronize"]'

設定は以上です。
ぜひ、自チームの状況にあわせて試してみてください。

さいごに

PR-Agent を活用したコードレビュープロセスと、その背景についてご紹介しました。
本記事が、AI レビュー導入やレビュープロセス設計の参考になれば幸いです。

脚注

1. 以前の記事では Qodo Merge という名称を使用していましたが、本記事では OSS 版の正式名称である PR-Agent を使用しています。

2. デフォルトでは行コメントでの投稿は行われません。詳細は前回の記事を参照ください。

3. GitHub Actions のワークフローファイルで issue_comment イベントがトリガーになるような設定が必要です。

4. PR_CODE_SUGGESTIONS.COMMITABLE_CODE_SUGGESTIONS オプションが無効の場合は、Conversation タブで確認できる通常コメントが上書きされる形となるため、本問題は発生しませんでした。行コメントを採用している状況下での問題と捉えています。